# Units

The Units submodule is concerned with defining and storing physical units, and defines the arithmetic operations available for constructing and combining units.

Unless stated otherwise, all types, functions, and constants defined in the submodule are exported by Alicorn.

## Overview

#### How units are represented

To understand how Alicorn handles physical units, let us consider the unit

$$$\mathrm{kg} \, \mathrm{nm}^2 \, \mathrm{ps}^{-2}.$$$

In Alicorn, this unit is represented by a Unit object. The Unit contains three UnitFactor objects, representing

1. UnitFactor: $\mathrm{kg}$
2. UnitFactor: $\mathrm{nm}^2$
3. UnitFactor: $\mathrm{ps}^2$

respectively. A UnitFactor in turn consists of three elements: a UnitPrefix, a BaseUnit, and a real-valued exponent. The first unit factor, for instance, is assembled from

• UnitPrefix: $\mathrm{k}$ (kilo)
• BaseUnit: $\mathrm{g}$ (gram)
• exponent::Real: $1$

while for the third

• UnitPrefix: $\mathrm{p}$ (pico)
• BaseUnit: $\mathrm{s}$ (second)
• exponent::Real: $-2$

Each BaseUnit represents one of the seven basic units (kilogram, meter, second, ampere, kelvin, mol, and candela) of the International System of Units, or a derived unit bearing a special name, such as the joule. A BaseUnit is characterized through a prefactor and the corresponding powers of the basic units, represented as a BaseUnitExponents object.

#### Types representing units

There are three types that represent valid physical units: BaseUnit, UnitFactor, and Unit, in order of increasing complexity. These types are concrete realizations of the abstract type AbstractUnit which provides an interface defining a set of methods for physical units.

The complete type graph for constituents of physical units is

AbstractUnitElement
├─ UnitPrefix
├─ BaseUnitExponents
└─ AbstractUnit
├─ BaseUnit
├─ UnitFactor
└─ Unit

The types UnitPrefix and BaseUnit making up a UnitFactor are collected in the type union UnitFactorElement.

#### How units can be constructed

Definitions of UnitPrefix and BaseUnit objects are collected in a UnitCatalogue. Alicorn provides a default catalogue constructed by UnitCatalogue() that contains the most important prefixes and named units. A natural way to construct composite units like $\mathrm{kg} \, \mathrm{nm}^2 \, \mathrm{ps}^{-2}$ is by arithmetically combining unit prefixes and base units:

julia> ucat = UnitCatalogue() ;

julia> kg = ucat.kilo * ucat.gram
UnitFactor kg

julia> nm2 = (ucat.nano * ucat.meter)^2
UnitFactor nm^2

julia> ps_2 = (ucat.pico * ucat.second)^-2
UnitFactor ps^-2

julia> kg * nm2 * ps_2
Unit kg nm^2 ps^-2

## AbstractUnit

#### Interface of AbstractUnit

Alicorn extends the following functions from the Base module for AbstractUnit types:

Base.:*Method
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.:/Method
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>

The following functions are considered part of the interface of AbstractUnit and need to be extended for all concrete subtypes of AbstractUnit:

Alicorn.Units.convertToUnitMethod
convertToUnit(abstractUnit::AbstractUnit)::Unit

Convert any object of type AbstractUnit to the Unit subtype.

Base.:*Method
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.invMethod
Base.inv(abstractUnit::AbstractUnit)

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

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

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

Base.sqrtMethod
Base.:sqrt(abstractUnit::AbstractUnit)

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

Base.Math.cbrtMethod
Base.:cbrt(abstractUnit::AbstractUnit)

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

Alicorn.Units.convertToBasicSIMethod
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.

Alicorn.Units.convertToBasicSIAsExponentsMethod
 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.

Alicorn.Dimensions.dimensionOfMethod
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

Alicorn.Units.UnitPrefixType
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

#### Constants of type UnitPrefix

Alicorn.Units.emptyUnitPrefixConstant

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

Alicorn.Units.kiloConstant

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

Alicorn.Units.BaseUnitType
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)

#### Methods implementing the AbstractUnit interface

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

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

Base.invMethod
Base.inv(baseUnit::BaseUnit)

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

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

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

Base.sqrtMethod
Base.sqrt(baseUnit::BaseUnit)

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

Base.Math.cbrtMethod
Base.cbrt(baseUnit::BaseUnit)

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

#### Constants of type BaseUnit

Alicorn.Units.unitlessBaseUnitConstant

Constant of type BaseUnit indicating the absence of a unit.

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

Alicorn.Units.gramConstant

Constant of type BaseUnit representing the gram.

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

Alicorn.Units.meterConstant

Constant of type BaseUnit representing the meter.

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

Alicorn.Units.secondConstant

Constant of type BaseUnit representing the second.

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

Alicorn.Units.ampereConstant

Constant of type BaseUnit representing the ampere.

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

Alicorn.Units.kelvinConstant

Constant of type BaseUnit representing the kelvin.

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

Alicorn.Units.molConstant

Constant of type BaseUnit representing the mol.

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

Alicorn.Units.candelaConstant

Constant of type BaseUnit representing the candela.

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

## BaseUnitExponents

Alicorn.Units.BaseUnitExponentsType
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
Alicorn.Units.convertToUnitMethod
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.:*Method
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.:+Method
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

Alicorn.Units.UnitFactorType
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

#### Methods implementing the AbstractUnit interface

Base.:*Method
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.invMethod
Base.inv(unitFactor::UnitFactor)

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

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

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

Base.sqrtMethod
Base.sqrt(unitFactor::UnitFactor)

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

Base.Math.cbrtMethod
Base.cbrt(unitFactor::UnitFactor)

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

#### Constants of type UnitFactor

Alicorn.Units.unitlessUnitFactorConstant

Constant of type UnitFactor indicating the absence of a unit.

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

Alicorn.Units.kilogramConstant

Constant of type UnitFactor representing the kilogram.

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

## Unit

Alicorn.Units.UnitType
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

#### Methods implementing the AbstractUnit interface

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

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

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

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

Base.:*Method
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.invMethod
Base.inv(unit::Unit)

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

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

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

Base.sqrtMethod
Base.sqrt(unit::Unit)

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

Base.Math.cbrtMethod
Base.cbrt(unit::Unit)

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

#### Constants of type Unit

Alicorn.Units.unitlessUnitConstant

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

Alicorn.Units.UnitCatalogueType
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:

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

UnitCatalogue providing
1 unit prefixes
0 base units

julia> ucat.nano
UnitPrefix nano (n) of value 1e-9

#### Methods

Base.getpropertyMethod
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)
Alicorn.Units.listUnitPrefixesMethod
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
Alicorn.Units.listBaseUnitsMethod
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)
Alicorn.Units.add!Method
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.

#### Default UnitCatalogue

Calling the UnitCatalogue constructor without arguments returns a catalogue that contains a default set of common units and prefixes used with the SI system:

julia> ucat = UnitCatalogue()
UnitCatalogue providing
21 unit prefixes
43 base units

#### Default unit prefixes

The default prefixes are listed in the following table. The corresponding UnitPrefix objects are constructed as

julia> yotta = UnitPrefix( name="yotta", symbol="Y", value=1e+24 )
UnitPrefix yotta (Y) of value 1e+24

and can be selected from the default UnitCatalogue by

julia> ucat.yotta
UnitPrefix yotta (Y) of value 1e+24

and so on.

namesymbolvalue
"yotta""Y"1e+24
"zetta""Z"1e+21
"exa""E"1e+18
"peta""P"1e+15
"tera""T"1e+12
"giga""G"1e+9
"mega""M"1e+6
"kilo""k"1e+3
"hecto""h"1e+2
"deca""da"1e+1
"deci""d"1e-1
"centi""c"1e-2
"milli""m"1e-3
"micro""μ"1e-6
"nano""n"1e-9
"pico""p"1e-12
"femto""f"1e-15
"atto""a"1e-18
"zepto""z"1e-21
"yocto""y"1e-24
"empty""<empty>"1

#### Default named units

The default named units are listed in the following table. The corresponding BaseUnit objects are constructed as

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

and can be selected from the default UnitCatalogue by

julia> ucat.gram
BaseUnit gram (1 g = 1e-3 kg)

and so on.

namesymbolprefactorexponentscorresponding basic unit
"gram""g"1e-3BaseUnitExponents(kg=1)$10^{-3}\,\mathrm{kg}$
"meter""m"1BaseUnitExponents(m=1)$1\,\mathrm{m}$
"second""s"1BaseUnitExponents(s=1)$1\,\mathrm{s}$
"ampere""A"1BaseUnitExponents(A=1)$1\,\mathrm{A}$
"kelvin""K"1BaseUnitExponents(K=1)$1\,\mathrm{K}$
"mol""mol"1BaseUnitExponents(mol=1)$1\,\mathrm{mol}$
"candela""cd"1BaseUnitExponents(cd=1)$1\,\mathrm{cd}$
"hertz""Hz"1BaseUnitExponents(s=-1)$1\,\mathrm{s}^{-1}$
"radian""rad"1BaseUnitExponents()$1$
"steradian""sr"1BaseUnitExponents()$1$
"newton""N"1BaseUnitExponents(kg=1, m=1, s=-2)$1\,\mathrm{kg}\,\mathrm{m}\,\mathrm{s}^{-2}$
"pascal""Pa"1BaseUnitExponents(kg=1, m=-1, s=-2)$1\,\mathrm{kg}\,\mathrm{m}^{-1}\,\mathrm{s}^{-2}$
"joule""J"1BaseUnitExponents(kg=1, m=2, s=-2)$1\,\mathrm{kg}\,\mathrm{m}^2\,\mathrm{s}^{-2}$
"watt""W"1BaseUnitExponents(kg=1, m=2, s=-3)$1\,\mathrm{kg}\,\mathrm{m}^2\,\mathrm{s}^{-3}$
"coulomb""C"1BaseUnitExponents(s=1, A=1)$1\,\mathrm{s}\,\mathrm{A}$
"volt""V"1BaseUnitExponents(kg=1, m=2, s=-3, A=-1)$1\,\mathrm{kg}\,\mathrm{m}^2\,\mathrm{s}^{-3}\,\mathrm{A}^{-1}$
"farad""F"1BaseUnitExponents(kg=-1, m=-2, s=4, A=2)$1\,\mathrm{kg}^{-1}\,\mathrm{m}^{-2}\,\mathrm{s}^4\,\mathrm{A}^2$
"ohm""Ω"1BaseUnitExponents(kg=1, m=2, s=-3, A=-2)$1\,\mathrm{kg}\,\mathrm{m}^2\,\mathrm{s}^{-3}\,\mathrm{A}^{-2}$
"siemens""S"1BaseUnitExponents(kg=-1, m=-2, s=3, A=2)$1\,\mathrm{kg}^{-1}\,\mathrm{m}^{-2}\,\mathrm{s}^3\,\mathrm{A}^2$
"weber""W"1BaseUnitExponents(kg=1, m=2, s=-2, A=-1)$1\,\mathrm{kg}\,\mathrm{m}^2\,\mathrm{s}^{-2}\,\mathrm{A}^{-1}$
"tesla""T"1BaseUnitExponents(kg=1, s=-2, A=-1)$1\,\mathrm{kg}\,\mathrm{s}^{-2}\,\mathrm{A}^{-1}$
"henry""H"1BaseUnitExponents(kg=1, m=2, s=-2, A=-2)$1\,\mathrm{kg}\,\mathrm{m}^2\,\mathrm{s}^{-2}\,\mathrm{A}^{-2}$
"degreeCelsius""°C"1BaseUnitExponents(K=1)$1\,\mathrm{K}$
"lumen""lm"1BaseUnitExponents(cd=1)$1\,\mathrm{cd}$
"lux""lx"1BaseUnitExponents(m=-2, cd=1)$1\,\mathrm{m}^{-2}\,\mathrm{cd}$
"becquerel""Bq"1BaseUnitExponents(s=-1)$1\,\mathrm{s}^{-1}$
"gray""Gy"1BaseUnitExponents(m=2, s=-2)$1\,\mathrm{m}^2\,\mathrm{s}^{-2}$
"sievert""Sv"1BaseUnitExponents(m=2, s=-2)$1\,\mathrm{m}^2\,\mathrm{s}^{-2}$
"katal""kat"1BaseUnitExponents(s=-1, mol=1)$1\,\mathrm{s}^{-1}\,\mathrm{mol}$
"minute""min"60BaseUnitExponents(s=1)$60\,\mathrm{s}$
"hour""h"3600BaseUnitExponents(s=1)$3600\,\mathrm{s}$
"day""d"86400BaseUnitExponents(s=1)$86400\,\mathrm{s}$
"astronomicalUnit""au"149597870700BaseUnitExponents(m=1)$149597870700\,\mathrm{m}$
"degree""°"pi/180BaseUnitExponents()$\pi/180$
"arcminute""'"pi/10800BaseUnitExponents()$\pi/10800$
"arcsecond""\""pi/648000BaseUnitExponents()$\pi/648000$
"hectare""ha"1e4BaseUnitExponents(m=2)$10^4\,\mathrm{m}^2$
"liter""l"1e-3BaseUnitExponents(m=3)$10^{-3}\,\mathrm{m}^3$
"tonne""t"1e3BaseUnitExponents(kg=1)$10^3\,\mathrm{kg}$
"dalton""Da"1.66053906660e-27BaseUnitExponents(kg=1)$1.66053906660 \times 10^{-27}\,\mathrm{kg}$
"electronvolt""eV"1.602176634e-19BaseUnitExponents(kg=1, m=2, s=-2)$1.602176634 \times 10^{-19}\,\mathrm{kg}\,\mathrm{m}^2\,\mathrm{s}^{-2}$
"angstrom""Å"1e-10BaseUnitExponents(m=1)$10^{-10}\,\mathrm{m}$
"unitless""<unitless>"1BaseUnitExponents()$1$