ABSTRACT_QUANTITY_TYPES

A constant tuple of the existing abstract quantity types, each as a tuple with (1) the abstract type, (2) the base type, and (3) the default exported concrete type.

UnionAbstractQuantity{T,D}

This is a union of both AbstractQuantity{T,D} and AbstractGenericQuantity{T,D}. It is used throughout the library to declare methods which can take both types. You should generally specialize on this type, rather than its constituents, as it will also include future abstract quantity types.

AbstractDimensions{R}

An abstract type for dimension types. R is the type of the exponents of the dimensions, and by default is set to DynamicQuantities.DEFAULT_DIM_BASE_TYPE. AbstractDimensions are used to store the dimensions of UnionAbstractQuantity objects. Together these enable many operators in Base to manipulate dimensions. This type has generic constructors for creating dimension objects, so user-defined dimension types can be created by simply subtyping AbstractDimensions, without the need to define many other functions.

The key function that one could wish to overload is DynamicQuantities.dimension_name(::AbstractDimensions, k::Symbol) for mapping from a field name to a base unit (e.g., length by default maps to m). You may also need to overload constructorof(::Type{T}) in case of non-standard construction.

AbstractGenericQuantity{T,D} <: Any

This has the same behavior as AbstractQuantity but is subtyped to Any rather than Number.

Note: In general, you should probably specialize on UnionAbstractQuantity which is the union of both AbstractQuantity and AbstractGenericQuantity, as well as any other future abstract quantity types,

AbstractQuantity{T,D} <: Number

An abstract type for quantities. T is the type of the value of the quantity, which should be <:Number. D is the type of the dimensions of the quantity. By default, D is set to DynamicQuantities.DEFAULT_DIM_TYPE. T is inferred from the value in a calculation, but in other cases is defaulted to DynamicQuantities.DEFAULT_VALUE_TYPE. It is assumed that the value is stored in the :value field, and the dimensions object is stored in the :dimensions field. These fields can be accessed with ustrip and dimension, respectively. Many operators in Base are defined on AbstractQuantity objects, including +, -, *, /, ^, sqrt, cbrt, abs.

See also AbstractGenericQuantity for creating quantities subtyped to Any.

Note: In general, you should probably specialize on UnionAbstractQuantity which is the union of both AbstractQuantity and AbstractGenericQuantity, as well as any other future abstract quantity types,

AbstractRealQuantity{T,D} <: Real

This has the same behavior as AbstractQuantity but is subtyped to Real rather than Number.

AbstractSymbolicDimensions{R} <: AbstractDimensions{R}

Abstract type to allow for custom types of symbolic dimensions. In defining this abstract type we allow for units to declare themselves as a special type of symbolic dimensions which are immutable, whereas the regular SymbolicDimensions type has mutable storage.

Dimensions{R<:Real} <: AbstractDimensions{R}

A type representing the dimensions of a quantity, with each field giving the power of the corresponding dimension. For example, the dimensions of velocity are Dimensions(length=1, time=-1). Each of the 7 dimensions are stored using the type R, which is by default a rational number.

Fields

• length: length dimension (i.e., meters^(length))
• mass: mass dimension (i.e., kg^(mass))
• time: time dimension (i.e., s^(time))
• current: current dimension (i.e., A^(current))
• temperature: temperature dimension (i.e., K^(temperature))
• luminosity: luminosity dimension (i.e., cd^(luminosity))
• amount: amount dimension (i.e., mol^(amount))

Constructors

• Dimensions(args...): Pass all the dimensions as arguments.
• Dimensions(; kws...): Pass a subset of dimensions as keyword arguments. R is set to DEFAULT_DIM_BASE_TYPE.
• Dimensions(::Type{R}; kws...) or Dimensions{R}(; kws...): Pass a subset of dimensions as keyword arguments, with the output type set to Dimensions{R}.
• Dimensions{R}(): Create a dimensionless object typed as Dimensions{R}.
• Dimensions{R}(d::Dimensions): Copy the dimensions from another Dimensions object, with the output type set to Dimensions{R}.

FixedRational{T,den}

A rational number with a fixed denominator. Significantly faster than Rational{T}, as it never needs to compute the gcd apart from when printing. Access the denominator with denom(F) (which converts to T).

Fields

• num: numerator of type T. The denominator is fixed to the type parameter den.

GenericQuantity{T<:Any,D<:AbstractDimensions} <: AbstractGenericQuantity{T,D} <: Any

This has the same behavior as Quantity but is subtyped to AbstractGenericQuantity <: Any rather than AbstractQuantity <: Number.

NoDims{R}

A type representing the dimensions of a non-quantity.

For any getproperty call on this type, the result is zero(R).

Quantity{T<:Number,D<:AbstractDimensions} <: AbstractQuantity{T,D} <: Number

Physical quantity with value value of type T and dimensions dimensions of type D. For example, the velocity of an object with mass 1 kg and velocity 2 m/s is Quantity(2, mass=1, length=1, time=-1). You should access these fields with ustrip(q), and dimension(q). You can access specific dimensions with ulength(q), umass(q), utime(q), ucurrent(q), utemperature(q), uluminosity(q), and uamount(q).

Severals operators in Base are extended to work with Quantity objects, including *, +, -, /, abs, ^, sqrt, and cbrt, which manipulate dimensions according to the operation.

Fields

• value::T: value of the quantity of some type T. Access with ustrip(::Quantity)
• dimensions::D: dimensions of the quantity. Access with dimension(::Quantity)

Constructors

• Quantity(x; kws...): Construct a quantity with value x and dimensions given by the keyword arguments. The value type is inferred from x. R is set to DEFAULT_DIM_TYPE.
• Quantity(x, ::Type{D}; kws...): Construct a quantity with value x with dimensions given by the keyword arguments, and the dimensions type set to D.
• Quantity(x, d::D): Construct a quantity with value x and dimensions d of type D.
• Quantity{T}(...): As above, but converting the value to type T. You may also pass a Quantity as input.
• Quantity{T,D}(...): As above, but converting the value to type T and dimensions to D. You may also pass a Quantity as input.

QuantityArray{T,N,D<:AbstractDimensions,Q<:UnionAbstractQuantity,V<:AbstractArray}

An array of quantities with value value of type V and dimensions dimensions of type D (which are shared across all elements of the array). This is a subtype of AbstractArray{Q,N}, and so can be used in most places where a normal array would be used, including broadcasting operations.

Fields

• value: The underlying array of values. Access with ustrip(a).
• dimensions: The dimensions of the array. Access with dimension(a).

Constructors

• QuantityArray(v::AbstractArray, d::AbstractDimensions): Create a QuantityArray with value v and dimensions d, using Quantity if the eltype of v is numeric, and GenericQuantity otherwise.
• QuantityArray(v::AbstractArray{<:Number}, q::AbstractQuantity): Create a QuantityArray with value v and dimensions inferred with dimension(q). This is so that you can easily create an array with the units module, like so: julia julia> A = QuantityArray(randn(32), 1u"m")
• QuantityArray(v::AbstractArray{<:Any}, q::AbstractGenericQuantity): Create a QuantityArray with value v and dimensions inferred with dimension(q). This is so that you can easily create quantity arrays of non-numeric eltypes, like so: julia julia> A = QuantityArray([[1.0], [2.0, 3.0]], GenericQuantity(1u"m"))
• QuantityArray(v::AbstractArray{<:UnionAbstractQuantity}): Create a QuantityArray from an array of quantities. This means the following syntax works:

  julia> A = QuantityArray(randn(32) .* 1u"km/s")

• QuantityArray(v::AbstractArray; kws...): Create a QuantityArray with dimensions inferred from the keyword arguments. For example:

  julia> A = QuantityArray(randn(32); length=1)

  is equivalent to

  julia> A = QuantityArray(randn(32), u"m")

  The keyword arguments are passed to DEFAULT_DIM_TYPE.

RealQuantity{T<:Real,D<:AbstractDimensions} <: AbstractRealQuantity{T,D} <: Real

This has the same behavior as Quantity but is subtyped to AbstractRealQuantity <: Real.

SymbolicDimensions{R} <: AbstractDimensions{R}

An AbstractDimensions with one dimension for every unit and constant symbol. This is to allow for lazily reducing to SI base units, whereas Dimensions is always in SI base units. Furthermore, SymbolicDimensions stores dimensions using a sparse vector for efficiency (since there are so many unit symbols).

You can convert a quantity using SymbolicDimensions as its dimensions to one which uses Dimensions as its dimensions (i.e., base SI units) uexpand.

SymbolicDimensionsSingleton{R} <: AbstractSymbolicDimensions{R}

This special symbolic dimensions types stores a single unit or constant, and can be used for constructing symbolic units and constants without needing to allocate mutable storage.

WriteOnceReadMany{V}(container::V)

A wrapper type for container that only defines methods for appending to and reading to, but not modifying the container.

This is so that we can safely define a @register_unit interface without needing to worry about the user overwriting previously defined units and voiding the indexing of symbolic dimensions.

|>(q::Union{UnionAbstractQuantity,QuantityArray,Number}, qout::UnionAbstractQuantity)

Using q |> qout is an alias for uconvert(qout, q).

constructorof(::Type{<:AbstractDimensions})
constructorof(::Type{<:UnionAbstractQuantity})

Return the constructor of the given type. This is used to create new objects of the same type as the input. Overload a method for a new type, especially if you need custom behavior.

denom(F::FixedRational)

Since den can be a different type than T, this function is used to get the denominator as a T.

dimension(q::AbstractQuantity)
dimension(q::AbstractGenericQuantity)
dimension(x)

Get the dimensions of a quantity, returning an AbstractDimensions object.

dimension_names(::Type{<:AbstractDimensions})

Return a tuple of symbols with the names of the dimensions of the given type. This should be static so that it can be hardcoded during compilation. The default is to use fieldnames, but you can overload this for custom behavior.

promote_except_value(q1::UnionAbstractQuantity, q2::UnionAbstractQuantity)

This applies a promotion to the quantity type, and the dimension type, but not the value type. This is necessary because sometimes we would want to multiply a quantity array with a scalar quantity, and wish to use promotion on the quantity type itself, but don't want to promote to a single value type.

promote_quantity_on_quantity(Q1, Q2)

Defines the type hierarchy for quantities, returning the most specific type that is compatible with both input quantity types. For example, promote_quantity_on_quantity(Quantity, GenericQuantity) would return GenericQuantity, as it can store both Quantity and GenericQuantity values. Similarly, promote_quantity_on_quantity(RealQuantity, RealQuantity) would return RealQuantity, as that is the most specific type.

Also see promote_quantity_on_value.

promote_quantity_on_value(Q::Type, T::Type)

Find the next quantity type in the hierarchy that can accommodate the type T. If the current quantity type can already accommodate T, then the current type is returned. For example, promote_quantity_on_value(Quantity, Float64) would return Quantity, and promote_quantity_on_value(RealQuantity, String) would return GenericQuantity. The user should overload this function to define a custom type hierarchy.

Also see promote_quantity_on_quantity.

uamount(q::AbstractQuantity)
uamount(q::AbstractGenericQuantity)
uamount(d::AbstractDimensions)

Get the amount dimension of a quantity (e.g., mol^(uamount)).

uconvert(qout::UnionAbstractQuantity{<:Any, <:AbstractSymbolicDimensions}, q::UnionAbstractQuantity{<:Any, <:Dimensions})

Convert a quantity q with base SI units to the symbolic units of qout, for q and qout with compatible units. Mathematically, the result has value q / uexpand(qout) and units dimension(qout).

You can also use |> as a shorthand for uconvert:

julia> q = 1u"m/s^2" |> us"km/h^2"
12960.0 km h⁻²

uconvert(qout::UnionAbstractQuantity{<:Any, <:AbstractSymbolicDimensions})

Create a function that converts an input quantity q with base SI units to the symbolic units of qout, i.e a function equivalent to q -> uconvert(qout, q).

ucurrent(q::AbstractQuantity)
ucurrent(q::AbstractGenericQuantity)
ucurrent(d::AbstractDimensions)

Get the current dimension of a quantity (e.g., A^(ucurrent)).

uexpand(q::UnionAbstractQuantity{<:Any,<:AbstractSymbolicDimensions})

Expand the symbolic units in a quantity to their base SI form. In other words, this converts a quantity with AbstractSymbolicDimensions to one with Dimensions. The opposite of this function is uconvert, for converting to specific symbolic units, or, e.g., convert(Quantity{<:Any,<:AbstractSymbolicDimensions}, q), for assuming SI units as the output symbols.

ulength(q::AbstractQuantity)
ulength(q::AbstractGenericQuantity)
ulength(d::AbstractDimensions)

Get the length dimension of a quantity (e.g., meters^(ulength)).

uluminosity(q::AbstractQuantity)
uluminosity(q::AbstractGenericQuantity)
uluminosity(d::AbstractDimensions)

Get the luminosity dimension of a quantity (e.g., cd^(uluminosity)).

umass(q::AbstractQuantity)
umass(q::AbstractGenericQuantity)
umass(d::AbstractDimensions)

Get the mass dimension of a quantity (e.g., kg^(umass)).

ustrip(q::AbstractQuantity)
ustrip(q::AbstractGenericQuantity)

Remove the units from a quantity.

utemperature(q::AbstractQuantity)
utemperature(q::AbstractGenericQuantity)
utemperature(d::AbstractDimensions)

Get the temperature dimension of a quantity (e.g., K^(utemperature)).

utime(q::AbstractQuantity)
utime(q::AbstractGenericQuantity)
utime(d::AbstractDimensions)

Get the time dimension of a quantity (e.g., s^(utime))

with_type_parameters(::Type{<:AbstractDimensions}, ::Type{R})
with_type_parameters(::Type{<:UnionAbstractQuantity}, ::Type{T}, ::Type{D})

Return the type with the given type parameters instead of the ones in the input type. This is used to get Dimensions{R} from input (Dimensions{R1}, R), for example. Overload a method for a new type, especially if you need custom behavior.

@register_unit symbol value

Register a new unit under the given symbol to have a particular value.

Example

julia> @register_unit MyVolt 1.5u"V"

This will register a new unit MyVolt with a value of 1.5u"V". You can then use this unit in your calculations:

julia> x = 20us"MyVolt^2"
20.0 MyVolt²

julia> y = 2.5us"A"
2.5 A

julia> x * y^2 |> us"W^2"
281.25 W²

julia> x * y^2 |> us"W^2" |> sqrt |> uexpand
16.77050983124842 m² kg s⁻³

us"[unit expression]"

Parse a string containing an expression of units and return the corresponding Quantity object with Float64 value. However, unlike the regular u"..." macro, this macro uses SymbolicDimensions for the dimension type, which means that all units and constants are stored symbolically and will not automatically expand to SI units. For example, us"km/s^2" would be parsed to Quantity(1.0, SymbolicDimensions, km=1, s=-2).

Note that inside this expression, you also have access to the Constants module. So, for example, us"Constants.c^2 * Hz^2" would evaluate to Quantity(1.0, SymbolicDimensions, c=2, Hz=2). However, note that due to namespace collisions, a few physical constants are automatically converted.

A tuple of all possible constants.

Faraday constant. Standard.

Newtonian constant of gravitation. Measured.

Standard luminosity at absolute bolometric magnitude 0. Standard.

Nominal solar luminosity. Standard.

Earth mass. Measured.

Jupiter mass. Measured.

Solar mass. Measured.

Avogadro constant. Standard.

Molar gas constant. Standard.

Nominal Earth equatorial radius. Standard.

Nominal Jupiter equatorial radius. Standard.

Nominal solar radius. Standard.

Rydberg frequency. Measured.

Bohr radius. Measured.

Fine-structure constant. Measured.

Standard atmosphere. Standard.

Astronomical unit. Standard.

Speed of light in a vacuum. Standard.

Elementary charge. Standard.

Electron volt. Standard.

Vacuum electric permittivity. Measured.

Planck constant. Standard.

Reduced Planck constant (h/2π). Standard.

Boltzmann constant. Standard.

Coulomb constant (Note: SI units only!). Measured.

Light year. Standard.

Electron mass. Measured.

Neutron mass. Measured.

Proton mass. Measured.

Vacuum magnetic permeability. Measured.

Parsec. Standard.

Thomson scattering cross-section. Measured.

Stefan-Boltzmann constant. Standard.

Atomic mass unit (1/12th the mass of Carbon-12). Measured.

SymbolicUnits

A separate module where each unit is treated as a separate dimension, to enable pretty-printing of units.

sym_uparse(raw_string::AbstractString)

Parse a string containing an expression of units and return the corresponding Quantity object with Float64 value. However, that unlike the regular u"..." macro, this macro uses SymbolicDimensions for the dimension type, which means that all units and constants are stored symbolically and will not automatically expand to SI units. For example, sym_uparse("km/s^2") would be parsed to Quantity(1.0, SymbolicDimensions, km=1, s=-2).

Note that inside this expression, you also have access to the Constants module. So, for example, sym_uparse("Constants.c^2 * Hz^2") would evaluate to Quantity(1.0, SymbolicDimensions, c=2, Hz=2). However, note that due to namespace collisions, a few physical constants are automatically converted.

uparse(s::AbstractString)

Parse a string containing an expression of units and return the corresponding Quantity object with Float64 value. For example, uparse("m/s") would be parsed to Quantity(1.0, length=1, time=-1).

Note that inside this expression, you also have access to the Constants module. So, for example, uparse("Constants.c^2 * Hz^2") would evaluate to the quantity corresponding to the speed of light multiplied by Hertz, squared.

u"[unit expression]"

Parse a string containing an expression of units and return the corresponding Quantity object with Float64 value. For example, u"km/s^2" would be parsed to Quantity(1000.0, length=1, time=-2).

Note that inside this expression, you also have access to the Constants module. So, for example, u"Constants.c^2 * Hz^2" would evaluate to the quantity corresponding to the speed of light multiplied by Hertz, squared.

Current in Amperes. Available variants: nA, μA (/uA), mA, kA.

Charge in Coulombs.

Capacitance in Farads. Available variants: fF, pF, nF, μF (/uF), mF.

Electrical inductance in henries.

Frequency in Hertz. Available variants: nHz, μHz (/uHz), mHz, kHz, MHz, GHz.

Energy in Joules. Available variant: kJ.

Temperature in Kelvin. Available variant: mK.

Volume in liters. Available variants: μL (/uL), mL, cL, dL.

Molar concentration in molar. Available variants: pM, nM, μM (/uM), mM.

Force in Newtons.

Pressure in Pascals. Available variant: kPa.

Electrical conductance, electric susceptance, and electric admittance in siemens. Available variants: nS, μS (/uS), mS, kS, MS, GS.

Magnetic flux density in Teslas.

Voltage in Volts. Available variants: pV, nV, μV (/uV), mV, kV,MV,GV`.

Power in Watts. Available variants: mW, kW, MW, GW.

Magnetic flux in webers. Available variants: nWb, μWb (/uWb), mWb.

Pressure in bars. Available variants: mbar.

Luminosity in candela. Available variant: mcd.

Mass in kilograms. Available variants: pg, ng, μg (/ug), mg, g.

Length in meters. Available variants: fm, pm, nm, μm (/um), cm, inch, dm, mm, ft, km, mi, Mm, Gm.

Amount in moles. Available variant: pmol, nmol, μmol (/umol), mmol.

Angle in radians. Note that the SI definition is simply 1 rad = 1, so use symbolic units to avoid this. Available variants: nrad, μrad (/urad), mrad, deg, arcmin, arcsec, μarcsec (/uarcsec), marcsec.

Time in seconds. Available variants: fs, ps, ns, μs (/us), ms, min (/minute), h (/hr), day (/d), wk, yr, kyr, Myr, Gyr.

Solid angle in steradians. Note that the SI definition is simply 1 sr = 1, so use symbolic units to avoid this.

Resistance in Ohms. Available variant: nΩ, μΩ (/uΩ), mΩ, kΩ, MΩ, GΩ. Also available is ASCII ohm (with variants nohm, μohm (/uohm), mohm, kohm, Mohm, Gohm).