

Manipulating units

Unitful string macro

# Unitful.@u_str — Macro.

@u_str(unit)

String macro to easily recall units, dimensions, or quantities defined in unit modules that have been registered with Unitful.register.

If the same symbol is used for a Unitful.Units object defined in different modules, then the symbol found in the most recently registered module will be used.

Note that what goes inside must be parsable as a valid Julia expression. In other words, u"N m" will fail if you intended to write u"N*m".

Examples:

julia> 1.0u"m/s"
1.0 m s^-1

julia> 1.0u"N*m"
1.0 m N

julia> u"m,kg,s"
(m, kg, s)

julia> typeof(1.0u"m/s")
Quantity{Float64,𝐋*𝐓^-1,Unitful.FreeUnits{(m, s^-1),𝐋*𝐓^-1,nothing}}

julia> u"ħ"
1.0545718001391127e-34 J s

source

# Unitful.register — Function.

register(unit_module::Module)

Makes the @u_str macro aware of units defined in new unit modules. By default, Unitful is itself a registered module. Note that Main is not, so if you define new units at the REPL, you will probably want to do Unitful.register(Main).

Example:

# somewhere in a custom units package...
module MyUnitsPackage
using Unitful

function __init__()
    ...
    Unitful.register(MyUnitsPackage)
end
end #module

source

Dimension and unit inspection

We define a function dimension that turns, for example, acre^2 or 1*acre^2 into 𝐋^4. We can usually add quantities with the same dimension, regardless of specific units (FixedUnits cannot be automatically converted, however). Note that dimensions cannot be determined by powers of the units: ft^2 is an area, but so is ac^1 (an acre).

There is also a function unit that turns, for example, 1*acre^2 into acre^2. You can then query whether the units are FreeUnits, FixedUnits, etc.

# Unitful.unit — Function.

unit(x::Quantity{T,D,U}) where {T,D,U}
unit(x::Type{Quantity{T,D,U}}) where {T,D,U}

Returns the units associated with a Quantity or Quantity type.

Examples:

julia> unit(1.0u"m") == u"m"
true

julia> unit(typeof(1.0u"m")) == u"m"
true

source

unit(x::Number)

Returns a Unitful.FreeUnits{(), NoDims} object to indicate that ordinary numbers have no units. This is a singleton, which we export as NoUnits. The unit is displayed as an empty string.

Examples:

julia> typeof(unit(1.0))
Unitful.FreeUnits{(),NoDims,nothing}

julia> typeof(unit(Float64))
Unitful.FreeUnits{(),NoDims,nothing}

julia> unit(1.0) == NoUnits
true

source

# Unitful.dimension — Method.

dimension(x::Number)
dimension(x::Type{T}) where {T<:Number}

Returns a Unitful.Dimensions{()} object to indicate that ordinary numbers are dimensionless. This is a singleton, which we export as NoDims. The dimension is displayed as an empty string.

Examples:

julia> typeof(dimension(1.0))
Unitful.Dimensions{()}
julia> typeof(dimension(Float64))
Unitful.Dimensions{()}
julia> dimension(1.0) == NoDims
true

source

# Unitful.dimension — Method.

dimension(u::Units{U,D}) where {U,D}

Returns a Unitful.Dimensions object corresponding to the dimensions of the units, D. For a dimensionless combination of units, a Unitful.Dimensions{()} object is returned (NoDims).

Examples:

julia> dimension(u"m")
𝐋

julia> typeof(dimension(u"m"))
Unitful.Dimensions{(Unitful.Dimension{:Length}(1//1),)}

julia> dimension(u"m/km")
NoDims

source

dimension(x::Quantity{T,D}) where {T,D}
dimension(::Type{Quantity{T,D,U}}) where {T,D,U}

Returns a Unitful.Dimensions object D corresponding to the dimensions of quantity x. For a dimensionless Unitful.Quantity, a Unitful.Dimensions{()} object is returned (NoDims).

Examples:

julia> dimension(1.0u"m")
𝐋

julia> typeof(dimension(1.0u"m/μm"))
Unitful.Dimensions{()}

source

# Unitful.dimension — Method.

dimension(u::Units{U,D}) where {U,D}

Returns a Unitful.Dimensions object corresponding to the dimensions of the units, D. For a dimensionless combination of units, a Unitful.Dimensions{()} object is returned (NoDims).

Examples:

julia> dimension(u"m")
𝐋

julia> typeof(dimension(u"m"))
Unitful.Dimensions{(Unitful.Dimension{:Length}(1//1),)}

julia> dimension(u"m/km")
NoDims

source

dimension(x::Quantity{T,D}) where {T,D}
dimension(::Type{Quantity{T,D,U}}) where {T,D,U}

Returns a Unitful.Dimensions object D corresponding to the dimensions of quantity x. For a dimensionless Unitful.Quantity, a Unitful.Dimensions{()} object is returned (NoDims).

Examples:

julia> dimension(1.0u"m")
𝐋

julia> typeof(dimension(1.0u"m/μm"))
Unitful.Dimensions{()}

source

# Unitful.dimension — Method.

dimension(u::Units{U,D}) where {U,D}

Returns a Unitful.Dimensions object corresponding to the dimensions of the units, D. For a dimensionless combination of units, a Unitful.Dimensions{()} object is returned (NoDims).

Examples:

julia> dimension(u"m")
𝐋

julia> typeof(dimension(u"m"))
Unitful.Dimensions{(Unitful.Dimension{:Length}(1//1),)}

julia> dimension(u"m/km")
NoDims

source

dimension(x::Quantity{T,D}) where {T,D}
dimension(::Type{Quantity{T,D,U}}) where {T,D,U}

Returns a Unitful.Dimensions object D corresponding to the dimensions of quantity x. For a dimensionless Unitful.Quantity, a Unitful.Dimensions{()} object is returned (NoDims).

Examples:

julia> dimension(1.0u"m")
𝐋

julia> typeof(dimension(1.0u"m/μm"))
Unitful.Dimensions{()}

source

Unit stripping

# Unitful.ustrip — Function.

ustrip(u::Units, x::Quantity)
ustrip(T::Type, u::Units, x::Quantity)

Convert x to units u using uconvert and return the number out the front of the resulting quantity. If T is supplied, also convert the resulting number into type T.

This function is mainly intended for compatibility with packages that don't know how to handle quantities.

julia> ustrip(u"m", 1u"mm") == 1//1000
true

julia> ustrip(Float64, u"m", 2u"mm") == 0.002
true

source

ustrip(x::Number)
ustrip(x::Quantity)

Returns the number out in front of any units. The value of x may differ from the number out front of the units in the case of dimensionless quantities, e.g. 1m/mm != 1. See uconvert and the example below. Because the units are removed, information may be lost and this should be used with some care — see ustrip(u,x) for a safer alternative.

julia> ustrip(2u"μm/m") == 2
true

julia> uconvert(NoUnits, 2u"μm/m") == 2//1000000
true

source

ustrip(x::Array{Q}) where {Q <: Quantity}

Strip units from an Array by reinterpreting to type T. The resulting Array is a not a copy, but rather a unit-stripped view into array x. Because the units are removed, information may be lost and this should be used with some care.

This function is provided primarily for compatibility purposes; you could pass the result to PyPlot, for example.

julia> a = [1u"m", 2u"m"]
2-element Array{Quantity{Int64,𝐋,Unitful.FreeUnits{(m,),𝐋,nothing}},1}:
 1 m
 2 m

julia> b = ustrip(a)
2-element reinterpret(Int64, ::Array{Quantity{Int64,𝐋,Unitful.FreeUnits{(m,),𝐋,nothing}},1}):
 1
 2

julia> a[1] = 3u"m"; b
2-element reinterpret(Int64, ::Array{Quantity{Int64,𝐋,Unitful.FreeUnits{(m,),𝐋,nothing}},1}):
 3
 2

source

ustrip(A::Diagonal)
ustrip(A::Bidiagonal)
ustrip(A::Tridiagonal)
ustrip(A::SymTridiagonal)

Strip units from various kinds of matrices by calling ustrip on the underlying vectors.

source

Unit multiplication

# Base.:* — Method.

*(a0::Units, a::Units...)

Given however many units, multiply them together. This is actually handled by a few different methods, since we have FreeUnits, ContextUnits, and FixedUnits.

Collect Unitful.Unit objects from the type parameter of the Unitful.Units objects. For identical units including SI prefixes (i.e. cm ≠ m), collect powers and sort uniquely by the name of the Unit. The unique sorting permits easy unit comparisons.

Examples:

julia> u"kg*m/s^2"
kg m s^-2

julia> u"m/s*kg/s"
kg m s^-2

julia> typeof(u"m/s*kg/s") == typeof(u"kg*m/s^2")
true

source

# Base.:* — Method.

*(a0::Dimensions, a::Dimensions...)

Given however many dimensions, multiply them together.

Collect Unitful.Dimension objects from the type parameter of the Unitful.Dimensions objects. For identical dimensions, collect powers and sort uniquely by the name of the Dimension.

Examples:

julia> u"𝐌*𝐋/𝐓^2"
𝐋 𝐌 𝐓^-2

julia> u"𝐋*𝐌/𝐓^2"
𝐋 𝐌 𝐓^-2

julia> typeof(u"𝐋*𝐌/𝐓^2") == typeof(u"𝐌*𝐋/𝐓^2")
true

source