Units

AbstractUnitElement

Abstract supertype for all types used in constructing a physical unit.

All AbstractUnit types are subtypes of AbstractUnitElement. The only concrete subtype of AbstractUnitElement is UnitPrefix.

UnitFactorElement = Union{UnitPrefix, BaseUnit}

Type union that encompasses the types UnitPrefix and BaseUnit which are used to construct objects of type UnitFactor.

AbstractUnit <: AbstractUnitElement

Abstract supertype for all types that represent a physical unit.

The concrete subtypes of AbstractUnit are BaseUnit, UnitFactor, and Unit.

Base.:*(abstractUnit1::AbstractUnit, abstractUnit2::AbstractUnit)

Multiply two objects of type AbstractUnit and return the result as a Unit.

The method ultimately calls Base.:*(::Unit, ::Unit).

Examples

julia> kilogram = Alicorn.kilogram
UnitFactor kg

julia> kilogram * kilogram
Unit kg^2

Base.:/(abstractUnit1::AbstractUnit, abstractUnit2::AbstractUnit)

Divide two objects of type AbstractUnits and return the result as a Unit.

The method ultimately calls Base.:/(::Unit, ::Unit).

Examples

julia> kilogram = Alicorn.kilogram
UnitFactor kg

julia> kilogram / kilogram
Unit <unitless>

convertToUnit(abstractUnit::AbstractUnit)::Unit

Convert any object of type AbstractUnit to the Unit subtype.

Base.:*(unitPrefix::UnitPrefix, abstractUnit::AbstractUnit)

Combine a unit prefix with a unit. The behavior of this function depends on the concrete subtype of abstractUnit.

Base.inv(abstractUnit::AbstractUnit)

Return the (multiplicative) inverse of a unit. The behavior of this function depends on the concrete subtype of abstractUnit.

Base.:^(abstractUnit::AbstractUnit, exponent::Real)

Exponentiate a unit. The behavior of this function depends on the concrete subtype of abstractUnit.

Base.:sqrt(abstractUnit::AbstractUnit)

Take the square root of a unit. The behavior of this function depends on the concrete subtype of abstractUnit.

Base.:cbrt(abstractUnit::AbstractUnit)

Take the cubic root of a unit. The behavior of this function depends on the concrete subtype of abstractUnit.

convertToBasicSI(abstractUnit::AbstractUnit)

Express a unit in terms of the seven basic SI units.

Output

(prefactor::Real, basicUnit::Unit)

The return variable basicUnit only contains powers of the seven basic SI units (kg, m, s, A, K, mol, cd). The return variable prefactor is the numerical prefactor relating the original unit to the returned unit.

 convertToBasicSIAsExponents(abstractUnit::AbstractUnit)

Express a unit in terms of the seven basic SI units.

Output

(prefactor::Real, basicUnitAsExponents::BaseUnitExponents)

The return variable basicUnitAsExponents indicates the powers of the seven basic SI units (kg, m, s, A, K, mol, cd) needed to represent the original unit. The return variable prefactor is the numerical prefactor relating the original unit to the returned unit.

dimensionOf(abstractUnit::AbstractUnit)

Returns the dimension of a physical unit of type AbstractUnit.

Example

One siemens is defined as $1\,\mathrm{S} = 1\,\mathrm{kg}^{-1}\,\mathrm{m}^{-2}\,\mathrm{s}^3\,\mathrm{A}^2$. The unit is hence of dimension $\mathrm{M}^{-1}\,\mathrm{L}^{-2}\,\mathrm{T}^3\,\mathrm{I}^2$:

julia> ucat = UnitCatalogue() ;

julia> siemens = ucat.siemens
BaseUnit siemens (1 S = 1 kg^-1 m^-2 s^3 A^2)
julia> dimensionOf(siemens)
Dimension M^-1 L^-2 T^3 I^2

UnitPrefix  <: AbstractUnitElement

Metric prefix that can precede a base unit. The prefix indicates that the unit is scaled by a corresponding factor.

Fields

• name::String: long form name of the prefix
• symbol::String: short symbol used to denote the prefix in a composite unit
• value: numerical value of the prefix

Constructor

UnitPrefix(;name::String, symbol::String, value::Real)

The string name needs to be valid as an identifier. The number value needs to be finite.

Raises Exceptions

• Core.ArgumentError: if attempting to initialize the name field with a string that is not valid as an identifier
• Core.DomainError: if attempting to initialize the value field with an infinite number

Examples

The prefix "milli" for the International System of Units is by default defined in Alicorn as

julia> UnitPrefix(name="milli", symbol="m", value=1e-3)
UnitPrefix milli (m) of value 1e-3

Constant of type UnitPrefix that indicates the absence of a unit prefix.

The prefix emptyUnitPrefix is used to construct UnitFactor objects without a unit prefix. The constant is not exported by Alicorn but can be accessed as Alicorn.emptyUnitPrefix

Constant of type UnitPrefix that represents the SI prefix "kilo".

The prefix kilo is used to define the basic SI unit kilogram. The constant is not exported by Alicorn but can be accessed as Alicorn.kilo

BaseUnit <: AbstractUnit

A named unit derived from the seven basic SI units.

Fields

• name::String: long form name of the unit
• symbol::String: short symbol used to denote the named unit in a composite unit
• prefactor::Real: numerical prefactor multiplying the polynomial of basic SI units corresponding to the named unit.
• exponents::BaseUnitExponents: collection of the powers in the polynomial of basic SI units corresponding to the named unit.

Constructor

BaseUnit(; name::String, symbol::String, prefactor::Real, exponents::BaseUnitExponents)

Raises Exceptions

• Core.ArgumentError: if attempting to initialize the name field with a string that is not valid as an identifier
• Core.DomainError: if attempting to initialize the prefactor field with an infinite number

Examples

1. The meter can be represented by

   julia> BaseUnit( name="meter",
                    symbol="m",
                    prefactor=1,
                    exponents=BaseUnitExponents(m=1) )
   BaseUnit meter (1 m = 1 m)

2. The gram can be represented by

   julia> BaseUnit( name="gram",
                    symbol="g",
                    prefactor=1e-3,
                    exponents=BaseUnitExponents(kg=1) )
   BaseUnit gram (1 g = 1e-3 kg)

3. The joule is defined as

   \[1\,\mathrm{J} = 1\,\mathrm{kg}\,\mathrm{m^2}\,\mathrm{s^{-2}}.\]

   and can be represents by

   julia> BaseUnit( name="joule",
                    symbol="J",
                    prefactor=1,
                    exponents=BaseUnitExponents(kg=1, m=2, s=-2) )
   BaseUnit joule (1 J = 1 kg m^2 s^-2)

Base.:*(unitPrefix::UnitPrefix, baseUnit::BaseUnit)

Combine unitPrefix and baseUnit to form a unit of type UnitFactor.

Base.inv(baseUnit::BaseUnit)

Return the (multiplicative) inverse of baseUnit as a unit of type UnitFactor.

Base.:^(baseUnit::BaseUnit, exponent::Real)

Raise baseUnit to the power of exponent and return the result as a unit of type UnitFactor.

Base.sqrt(baseUnit::BaseUnit)

Take the square root of baseUnit and return it as unit of type UnitFactor.

Base.cbrt(baseUnit::BaseUnit)

Take the cubic root of baseUnit and return it as unit of type UnitFactor.

Constant of type BaseUnit indicating the absence of a unit.

The constant is not exported by Alicorn but can be accessed as Alicorn.unitlessBaseUnit.

Constant of type BaseUnit representing the gram.

The constant is not exported by Alicorn but can be accessed as Alicorn.gram.

Constant of type BaseUnit representing the meter.

The constant is not exported by Alicorn but can be accessed as Alicorn.meter.

Constant of type BaseUnit representing the second.

The constant is not exported by Alicorn but can be accessed as Alicorn.second.

Constant of type BaseUnit representing the ampere.

The constant is not exported by Alicorn but can be accessed as Alicorn.ampere.

Constant of type BaseUnit representing the kelvin.

The constant is not exported by Alicorn but can be accessed as Alicorn.kelvin.

Constant of type BaseUnit representing the mol.

The constant is not exported by Alicorn but can be accessed as Alicorn.mol.

Constant of type BaseUnit representing the candela.

The constant is not exported by Alicorn but can be accessed as Alicorn.candela.

BaseUnitExponents

Collection of powers exponentiating each of the seven SI basic units.

The exponents $(a, b, c, d, e, f, g)$ are interpreted as the powers to which the seven SI basic units are raised:

\[\mathrm{kg}^a \, \mathrm{m}^b \, \mathrm{s}^c \, \mathrm{A}^d \, \mathrm{K}^e \, \mathrm{mol}^f \, \mathrm{cd}^g.\]

The BaseUnit type uses BaseUnitExponents to define named units in terms of the basic units.

Fields

• kilogramExponent::Real: power $a$ of kilogram
• meterExponent::Real: power $b$ of meter
• secondExponent::Real: power $c$ of second
• ampereExponent::Real: power $d$ of ampere
• kelvinExponent::Real: power $e$ of kelvin
• molExponent::Real: power $f$ of mol
• candelaExponent::Real: power $g$ of candela

Constructor

BaseUnitExponents(; kg::Real=0, m::Real=0, s::Real=0, A::Real=0, K::Real=0, mol::Real=0, cd::Real=0)

Raises Exceptions

• Core.DomainError: if attempting to initialize any field with an infinite number

Remarks

The constructor converts any exponent to Int if possible.

Examples

The joule is defined as

\[ 1\,\mathrm{J} = 1\,\mathrm{kg}\,\mathrm{m^2}\,\mathrm{s^{-2}}.\]

The corresponding BaseUnitExponents object is:

julia> BaseUnitExponents(kg=1, m=2, s=-2)
BaseUnitExponents kg^1 m^2 s^-2 A^0 K^0 mol^0 cd^0

Calling the constructor without any keyword arguments returns exponents that correspond to a dimensionless unit:

julia> BaseUnitExponents()
BaseUnitExponents kg^0 m^0 s^0 A^0 K^0 mol^0 cd^0

convertToUnit(baseUnitExponents::BaseUnitExponents)

Return the Unit corresponding to a BaseUnitExponents object.

Example

julia> jouleExponents = BaseUnitExponents(kg=1, m=2, s=-2)
BaseUnitExponents kg^1 m^2 s^-2 A^0 K^0 mol^0 cd^0

julia> convertToUnit(jouleExponents)
Unit kg m^2 s^-2

Base.:*(number::Number, baseUnitExponents::BaseUnitExponents)
Base.:*(baseUnitExponents::BaseUnitExponents, number::Number)

Multiply each exponent in baseUnitExponents by number. This operation corresponds to exponentiating the corresponding unit with number.

Example

julia> meterExps = BaseUnitExponents(m=1)
BaseUnitExponents kg^0 m^1 s^0 A^0 K^0 mol^0 cd^0

julia> convertToUnit(meterExps)
Unit m

julia> meterSqrdExps = 2 * meterExps
BaseUnitExponents kg^0 m^2 s^0 A^0 K^0 mol^0 cd^0

julia> convertToUnit(meterSqrdExps)
Unit m^2

Base.:+(baseUnitExponents1::BaseUnitExponents, baseUnitExponents2::BaseUnitExponents)

Add each exponent in baseUnitExponents1 to its counterpart in baseUnitExponents2. This operation corresponds to multiplying the two corresponding units.

Example

julia> newtonExps = BaseUnitExponents(kg=1, m=1, s=-2)
BaseUnitExponents kg^1 m^1 s^-2 A^0 K^0 mol^0 cd^0

julia> convertToUnit(newtonExps)
Unit kg m s^-2

julia> meterExps = BaseUnitExponents(m=1)
BaseUnitExponents kg^0 m^1 s^0 A^0 K^0 mol^0 cd^0

julia> convertToUnit(meterExps)
Unit m

julia> jouleExps = newtonExps + meterExps
BaseUnitExponents kg^1 m^2 s^-2 A^0 K^0 mol^0 cd^0

julia> convertToUnit(jouleExps)
Unit kg m^2 s^-2

UnitFactor <: AbstractUnit

A composite unit formed by a named unit of type BaseUnit, a prefix of type UnitPrefix modifying it, and an exponent indicating to which power the pair is raised.

Fields

• unitPrefix::UnitPrefix
• baseUnit::BaseUnit
• exponent::Real

Constructors

UnitFactor(unitPrefix::UnitPrefix, baseUnit::BaseUnit, exponent::Real)
UnitFactor(baseUnit::BaseUnit, exponent::Real)
UnitFactor(unitPrefix::UnitPrefix, baseUnit::BaseUnit)
UnitFactor(baseUnit::BaseUnit)
UnitFactor()

If any of the three fields are omitted from the constructor call, that field is initialized using the corresponding default value:

• unitPrefix = unitPrefix=Alicorn.emptyUnitPrefix
• baseUnit = Alicorn.unitlessBaseUnit
• exponent = 1

Raises Exceptions

• Core.DomainError: if attempting to initialize the exponent field with an infinite number

Remarks

The constructor converts the exponent to Int if possible. If baseUnit=Alicorn.unitlessBaseUnit, the prefix is always set to unitPrefix=Alicorn.emptyUnitPrefix and the exponent to exponent=1.

Examples

1. The unit $\mathrm{km}^2$ (square kilometer) can be represented by a UnitFactor that can be constructed using the type constructor method as follows:

   julia> ucat = UnitCatalogue();
   
   julia> UnitFactor(ucat.kilo, ucat.meter, 2)
   UnitFactor km^2

2. Alternatively, $\mathrm{km}^2$ can be constructed arithmetically:

   julia> ucat = UnitCatalogue();
   
   julia> (ucat.kilo * ucat.meter)^2
   UnitFactor km^2

Base.:*(unitPrefix::UnitPrefix, unitFactor::UnitFactor)

Combine unitPrefix and unitFactor to form a unit of type UnitFactor.

The operation is only permitted if

1. unitFactor does not already contain a unit prefix, and
2. the exponent of unitFactor is 1.

Raises Exceptions

• Base.ArgumentError: if unitFactor.unitPrefix != Alicorn.emptyUnitPrefix
• Base.ArgumentError: if unitFactor.exponent != 1

Base.inv(unitFactor::UnitFactor)

Return the (multiplicative) inverse of unitFactor as a unit of type UnitFactor.

Base.:^(unitFactor::UnitFactor, exponent::Real)

Raise unitFactor to the power of exponent and return the result as a unit of type UnitFactor.

Base.sqrt(unitFactor::UnitFactor)

Take the square root of unitFactor and return it as unit of type UnitFactor.

Base.cbrt(unitFactor::UnitFactor)

Take the cubic root of unitFactor and return it as unit of type UnitFactor.

Constant of type UnitFactor indicating the absence of a unit.

The constant is not exported by Alicorn but can be accessed as Alicorn.unitlessUnitFactor.

Constant of type UnitFactor representing the kilogram.

The constant is not exported by Alicorn but can be accessed as Alicorn.kilogram.

Unit <: AbstractUnit

A composite unit formed by several UnitFactor objects.

Fields

• unitFactors::Vector{UnitFactor}: ordered list of UnitFactor objects that form the Unit through multiplication (concatenation).

Constructors

Unit(unitFactors::Vector{UnitFactor})
Unit(abstractUnit::AbstractUnit)
Unit()

Remarks

The constructor Unit(abstractUnit::AbstractUnit) is equivalent to convertToUnit(abstractUnit::AbstractUnit). The constructor Unit() returns the constant unitlessUnit.

When a Unit is initialized, UnitFactor objects are added to the unitFactors field in order of appearance. UnitFactor objects with the same base (UnitPrefix and BaseUnit) are merged.

Examples

1. The unit $\sqrt{\mathrm{Hz}}/\mathrm{nm}$ (square root of hertz per nanometer) can be constructed using the constructor method as follows:

   julia> ucat = UnitCatalogue();
   
   julia> sqrtHz = UnitFactor(ucat.hertz, 1/2)
   UnitFactor Hz^5e-1
   
   julia> per_nm = UnitFactor(ucat.nano, ucat.meter, -1)
   UnitFactor nm^-1
   
   julia> sqrtHz_per_nm = Unit([sqrtHz, per_nm])
   Unit Hz^5e-1 nm^-1

2. Alternatively, $\sqrt{\mathrm{Hz}}/\mathrm{nm}$ can also be constructed arithmetically:

   julia> ucat = UnitCatalogue();
   
   julia> sqrtHz_per_nm = sqrt(ucat.hertz) / ( ucat.nano * ucat.meter )
   Unit Hz^5e-1 nm^-1

Base.:*(unit1::Unit, unit2::Unit)

Multiply unit1 with unit2 and return the result as a unit of type Unit.

Base.:/(unit1::Unit, unit2::Unit)

Divide unit1 by unit2 and return the result as a unit of type Unit.

Base.:*(unitPrefix::UnitPrefix, unit::Unit)

Combine unitPrefix and unit to form a unit of type Unit.

The operation is only permitted if

1. unit contains a single unit factor unitFactor::UnitFactor,
2. unitFactor does not already contain a unit prefix, and
3. the exponent of unitFactor is 1.

Raises Exceptions

• Base.ArgumentError: if unit.unitFactors contains more than one element unitFactor::UnitFactor
• Base.ArgumentError: if unitFactor.unitPrefix != Alicorn.emptyUnitPrefix
• Base.ArgumentError: if unitFactor.exponent != 1

Base.inv(unit::Unit)

Return the (multiplicative) inverse of unit as a unit of type Unit.

Base.:^(unit::Unit, exponent::Real)

Raise unit to the power of exponent and return the result as a unit of type Unit.

Base.sqrt(unit::Unit)

Take the square root of unit and return it as unit of type Unit.

Base.cbrt(unit::Unit)

Take the cubic root of unit and return it as unit of type Unit.

Constant of type Unit indicating the absence of a unit.

The constant is not exported by Alicorn but can be accessed as Alicorn.unitlessUnit.

UnitCatalogue

Collection of UnitFactorElement objects. These include unit prefixes of type UnitPrefix and named units of type BaseUnit.

A single UnitCatalogue object serves as a consistent library of unit elements. Users can construct composite units based on the prefix and unit definitions stored in the unit catalogue. In most use cases, it is sufficient to initialize a single unit catalogue using UnitCatalogue(). The returned catalogue contains the unit prefixes and named units accepted for use with the International System of Units.

Unit prefixes and base units stored in a unit catalogue can be accessed using dot notation through Base.getproperty using their name field. In consequence, the names of elements stored in the unit catalogue have to be unique.

Fields

The fields of UnitCatalogue are not considered part of the public interface and cannot be accessed using the dot notation. The stored UnitFactorElement objects can be accessed through the following methods:

• Base.getproperty(unitCatalogue::UnitCatalogue, symbol::Symbol)
• listUnitPrefixes(unitCatalogue::UnitCatalogue)
• listBaseUnits(unitCatalogue::UnitCatalogue)
• listUnitPrefixNames(unitCatalogue::UnitCatalogue)
• listBaseUnitNames(unitCatalogue::UnitCatalogue)
• providesUnitPrefix(unitCatalogue::UnitCatalogue, symbol::String)
• providesBaseUnit(unitCatalogue::UnitCatalogue, symbol::String)
• add!(unitCatalogue::UnitCatalogue, unitPrefix::UnitPrefix)
• add!(unitCatalogue::UnitCatalogue, baseUnit::BaseUnit)
• remove!(unitCatalogue::UnitCatalogue, elementName::String)

Constructors

UnitCatalogue(unitPrefixes::Vector{UnitPrefix}, baseUnits::Vector{BaseUnit})
UnitCatalogue(unitPrefixes::Vector, baseUnits::Vector)
UnitCatalogue()

Raises exceptions

• Alicorn.Exceptions.DuplicationError: if attempting to add UnitFactorElement objects with identical name fields to the UnitCatalogue

Remarks

If vectors of types other than UnitPrefix and BaseUnit are provided, the constructor attempts to convert them to those types.

If the constructor is invoked without arguments, the default set of unit prefix and base unit definitions is added to the UnitCatalogue.

Examples

1. Initialize a default unit catalogue (containing the standard unit prefixes and named units accepted for use with the International System of Units) and use it to define the unit $\mathrm{nm}$ (nanometer):

   julia> ucat = UnitCatalogue()
   UnitCatalogue providing
    21 unit prefixes
    43 base units
   
   julia> nm = ucat.nano * ucat.meter
   UnitFactor nm

2. Initialize an empty unit catalogue (to be filled with custom prefix and unit definitions) and add new prefix with name nano:

   julia> ucat = UnitCatalogue([], [])
   UnitCatalogue providing
    0 unit prefixes
    0 base units
   
   julia> nano = UnitPrefix(name="nano", symbol="n", value=1e-9)
   UnitPrefix nano (n) of value 1e-9
   
   julia> add!(ucat, nano)
   UnitCatalogue providing
    1 unit prefixes
    0 base units
   
   julia> ucat.nano
   UnitPrefix nano (n) of value 1e-9

Base.getproperty(unitCatalogue::UnitCatalogue, symbol::Symbol)

Access a UnitFactorElement stored in unitCatalogue through its name using the dot notation.

Raises Exception

• Base.KeyError: if attempting to access a non-existent element

Examples

julia> ucat = UnitCatalogue() ;

julia> ucat.peta
UnitPrefix peta (P) of value 1e+15

julia> ucat.ohm
BaseUnit ohm (1 Ω = 1 kg m^2 s^-3 A^-2)

Base.propertynames(unitCatalogue::UnitCatalogue)

List the names of UnitFactorElement objects stored in unitCatalogue as Symbol objects.

This method is called to provide tab completion in the REPL.

listUnitPrefixes(unitCatalogue::UnitCatalogue)

Return a dictionary indexing the UnitPrefix objects stored in unitCatalogue by their name.

Example

julia> ucat = UnitCatalogue() ;

julia> prefixes = listUnitPrefixes(ucat) ;

julia> prefixes["micro"]
UnitPrefix micro (μ) of value 1e-6

listBaseUnits(unitCatalogue::UnitCatalogue)

Return a dictionary indexing the BaseUnit objects stored in unitCatalogue by their name.

Example

julia> ucat = UnitCatalogue() ;

julia> baseUnits = listBaseUnits(ucat) ;

julia> baseUnits["siemens"]
BaseUnit siemens (1 S = 1 kg^-1 m^-2 s^3 A^2)

listUnitPrefixNames(unitCatalogue::UnitCatalogue)

List the names of the UnitPrefix objects stored in unitCatalogue as a Vector{String}.

listBaseUnitNames(unitCatalogue::UnitCatalogue)

List the names of the BaseUnit objects stored in unitCatalogue as a Vector{String}.

providesUnitPrefix(unitCatalogue::UnitCatalogue, name::String)

Check if a UnitPrefix with name name is stored in unitCatalogue.

Output

::Bool

providesBaseUnit(unitCatalogue::UnitCatalogue, name::String)

Check if a BaseUnit with name name is stored in unitCatalogue.

Output

::Bool

add!(unitCatalogue::UnitCatalogue, unitPrefix::UnitPrefix)
add!(unitCatalogue::UnitCatalogue, baseUnit::BaseUnit)

Add a UnitFactorElement to unitCatalogue.

No element with the same name as the element to add may already exist in unitCatalogue.

Raises Exception

• Alicorn.Exceptions.DuplicationError: if a UnitFactorElement carrying the same name field as the element to add already exists in unitCatalogue.

remove!(unitCatalogue::UnitCatalogue, name::String)

Remove the UnitFactorElement object of name name from unitCatalogue.

Raises Exception

• Base.KeyError: if attempting to delete a non-existent element