Types
DynamicQuantities.Quantity
— TypeQuantity{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 typeT
. Access withustrip(::Quantity)
dimensions::D
: dimensions of the quantity. Access withdimension(::Quantity)
Constructors
Quantity(x; kws...)
: Construct a quantity with valuex
and dimensions given by the keyword arguments. The value type is inferred fromx
.R
is set toDEFAULT_DIM_TYPE
.Quantity(x, ::Type{D}; kws...)
: Construct a quantity with valuex
with dimensions given by the keyword arguments, and the dimensions type set toD
.Quantity(x, d::D)
: Construct a quantity with valuex
and dimensionsd
of typeD
.Quantity{T}(...)
: As above, but converting the value to typeT
. You may also pass aQuantity
as input.Quantity{T,D}(...)
: As above, but converting the value to typeT
and dimensions toD
. You may also pass aQuantity
as input.
DynamicQuantities.Dimensions
— TypeDimensions{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 toDEFAULT_DIM_BASE_TYPE
.Dimensions(::Type{R}; kws...)
orDimensions{R}(; kws...)
: Pass a subset of dimensions as keyword arguments, with the output type set toDimensions{R}
.Dimensions{R}()
: Create a dimensionless object typed asDimensions{R}
.Dimensions{R}(d::Dimensions)
: Copy the dimensions from anotherDimensions
object, with the output type set toDimensions{R}
.
There are also abstract types available. There are no required functions to build an interface, most relevant functions are defined on the abstract functions (including constructors).
DynamicQuantities.AbstractDimensions
— TypeAbstractDimensions{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.
DynamicQuantities.AbstractQuantity
— TypeAbstractQuantity{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,
Note also that the Quantity
object can take a custom AbstractDimensions
as input, so there is often no need to subtype AbstractQuantity
separately.
Symbolic dimensions
Another type which subtypes AbstractDimensions
is SymbolicDimensions
:
DynamicQuantities.SymbolicDimensions
— TypeSymbolicDimensions{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
.
Just note that all of the symbolic units and constants are stored using the immutable SymbolicDimensionsSingleton
, which shares the same supertype AbstractSymbolicDimensions <: AbstractDimensions
. These get immediately converted to the mutable SymbolicDimensions
when used in any calculation.
DynamicQuantities.SymbolicDimensionsSingleton
— TypeSymbolicDimensionsSingleton{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.
DynamicQuantities.AbstractSymbolicDimensions
— TypeAbstractSymbolicDimensions{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.
Arrays
DynamicQuantities.QuantityArray
— TypeQuantityArray{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 withustrip(a)
.dimensions
: The dimensions of the array. Access withdimension(a)
.
Constructors
QuantityArray(v::AbstractArray, d::AbstractDimensions)
: Create aQuantityArray
with valuev
and dimensionsd
, usingQuantity
if the eltype ofv
is numeric, andGenericQuantity
otherwise.QuantityArray(v::AbstractArray{<:Number}, q::AbstractQuantity)
: Create aQuantityArray
with valuev
and dimensions inferred withdimension(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 aQuantityArray
with valuev
and dimensions inferred withdimension(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 aQuantityArray
from an array of quantities. This means the following syntax works:julia> A = QuantityArray(randn(32) .* 1u"km/s")
QuantityArray(v::AbstractArray; kws...)
: Create aQuantityArray
with dimensions inferred from the keyword arguments. For example:
is equivalent tojulia> A = QuantityArray(randn(32); length=1)
The keyword arguments are passed tojulia> A = QuantityArray(randn(32), u"m")
DEFAULT_DIM_TYPE
.
Generic quantities
Whereas Quantity
is subtyped to Number
, a more general type of quantity is GenericQuantity
, which is subtyped to Any
.
DynamicQuantities.GenericQuantity
— TypeGenericQuantity{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
.
DynamicQuantities.AbstractGenericQuantity
— TypeAbstractGenericQuantity{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,
In the other direction, there is also RealQuantity
, which is subtyped to Real
.
DynamicQuantities.RealQuantity
— TypeRealQuantity{T<:Real,D<:AbstractDimensions} <: AbstractRealQuantity{T,D} <: Real
This has the same behavior as Quantity
but is subtyped to AbstractRealQuantity <: Real
.
DynamicQuantities.AbstractRealQuantity
— TypeAbstractRealQuantity{T,D} <: Real
This has the same behavior as AbstractQuantity
but is subtyped to Real
rather than Number
.
More general, these are each contained in the following:
DynamicQuantities.UnionAbstractQuantity
— TypeUnionAbstractQuantity{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.
DynamicQuantities.ABSTRACT_QUANTITY_TYPES
— ConstantABSTRACT_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.
Custom behavior in abstract quantities
There are a few functions you may need to overload when subtyping AbstractDimensions
, AbstractQuantity
, or AbstractGenericQuantity
.
DynamicQuantities.constructorof
— Functionconstructorof(::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.
DynamicQuantities.with_type_parameters
— Functionwith_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.
DynamicQuantities.dimension_names
— Functiondimension_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.