Quantities

The Quantities submodule is concerned with defining and manipulating physical quantities.

Unless stated otherwise, all types, functions, and constants defined in the submodule are exported to the global scope.

Contents

Overview

Alicorn distinguishes scalar (number-valued) and array (vector-, matrix-, or tensor-valued) quantities. The abstract supertype for all scalar quantities is AbstractQuantity, while the abstract supertype for all array quantities is AbstractQuantityArray. AbstractQuantityArray is a subtype of Base.AbstractArray and implements its interface.

Types Representing Quantities

There are two concrete implementations of each supertype:

The type graph for physical quantities is

AbstractQuantity{T}
├─ SimpleQuantity{T}
└─ Quantity{T}

AbstractQuantityArray{T,N} <: AbstractArray{T,N}
├─ SimpleQuantityArray{T,N}
└─ QuantityArray{T,N}

The SimpleQuantity and SimpleQuantityArray types store their numerical values expressed directly with respect to their unit.

The Quantity and QuantityArray types store their numerical values expressed with respect to a shared set of internal units for the seven basic physical dimensions of the SI system. These internal units are represented by a InternalUnits object. Instead of a concrete units for each quantity, only their physical dimension is retained. This approach can reduce the need for unit conversions during calculations. Moreover, it facilitates the use of a global set of internal units adapted to the magnitudes of the quantities appearing in a given calculation.

Type Aliases

Alicorn defines the following aliases for one- and two-dimensional arrays:

Type nameMathematical dimensionRoleAlias forCarries physical dimension
AbstractQuantity{T}N=0abstract supertype-yes
AbstractQuantityVector{T}N=1abstract supertypeAbstractQuantityArray{T,1}yes
AbstractQuantityMatrix{T}N=2abstract supertypeAbstractQuantityArray{T,2}yes
AbstractQuantityArray{T,N}Nabstract supertype-yes
SimpleQuantity{T}N=0concrete type-yes
SimpleQuantityVector{T}N=1concrete typeSimpleQuantityArray{T,1}yes
SimpleQuantityMatrix{T}N=2concrete typeSimpleQuantityArray{T,2}yes
SimpleQuantityArray{T,N}Nconcrete type-yes
Quantity{T}N=0concrete type-yes
QuantityVector{T}N=1concrete typeQuantityArray{T,1}yes
QuantityMatrix{T}N=2concrete typeQuantityArray{T,2}yes
QuantityArray{T,N}Nconcrete type-yes

Type unions for scalar and array quantities of the same kind:

Type nameRoleAlias forCarries physical dimension
AbstractQuantityType{T}type unionUnion{AbstractQuantity{T}, AbstractQuantityArray{T}} where T<:Numberyes
SimpleQuantityType{T}type unionUnion{SimpleQuantity{T}, SimpleQuantityArray{T}} where T<:Numberyes
QuantityType{T}type unionUnion{Quantity{T}, QuantityArray{T}} where T<:Numberyes
DimensionlessType{T}type unionUnion{Number, AbstractArray{<:Number}} where T<:Numberno

Type unions for scalar and array quantities:

Type nameMathematical dimensionRoleAlias forCarries physical dimension
ScalarQuantity{T}N=0type unionUnion{T, AbstractQuantity{T}} where T<:Numbereither yes or no
VectorQuantity{T}N=1type unionUnion{T, AbstractQuantityVector{T}} where T<:Numbereither yes or no
MatrixQuantity{T}N=2type unionUnion{T, AbstractQuantityMatrix{T}} where T<:Numbereither yes or no
ArrayQuantity{T,N}Ntype unionUnion{Array{T,N}, AbstractQuantityArray{T,N}} where {T<:Number, N}either yes or no

InternalUnits

Alicorn.Quantities.InternalUnitsType
InternalUnits

A set of seven SimpleQuantity objects which represent a choice of units with respect to which the seven basic physical dimensions of the SI system are measured.

Fields

  • mass::SimpleQuantity: unit of mass
  • length::SimpleQuantity: unit of length
  • time::SimpleQuantity: unit of time
  • current::SimpleQuantity: unit of current
  • temperature::SimpleQuantity: unit of temperature
  • amount::SimpleQuantity: unit of amount
  • luminousIntensity::SimpleQuantity: unit of luminousIntensity

Constructors

InternalUnits(::SimpleQuantity, ::SimpleQuantity, ::SimpleQuantity, ::SimpleQuantity, ::SimpleQuantity, ::SimpleQuantity, ::SimpleQuantity)
InternalUnits(; mass = 1*kilogram, length = 1*meter, time = 1*second, current = 1*ampere,temperature = 1*kelvin, amount = 1*mol, luminousIntensity = 1*candela)

# Raises Exceptions
- `Core.DomainError`: if attempting to initialize any field with a quantity
of a value that is zero, infinite, or not real
- `Exceptions.DimensionMismatchError`: if attempting to initialize any field
with a quantity whose dimension does not match the physical dimension the field
represents

# Examples
The following `InternalUnits` measure lengths in units of ``3 cm`` and uses
the basic SI units for all other dimensions:

jldoctest julia> ucat = UnitCatalogue(); cm = ucat.centi * ucat.meter ;

julia> InternalUnits(length = 3cm) InternalUnits mass unit: 1 kg length unit: 3 cm time unit: 1 s current unit: 1 A temperature unit: 1 K amount unit: 1 mol luminous intensity unit: 1 cd ```

source
Base.:==Method
Base.:(==)(internalUnits1::InternalUnits, internalUnits2::InternalUnits)

Compare two InternalUnits objects.

Two InternalUnits objects are equal if the SimpleQuantity objects representing the unit for each of the seven physical dimensions are equal.

source
Alicorn.Quantities.internalUnitForMethod
internalUnitFor(dimension::Dimension, internalUnits::InternalUnits)

Returns a SimpleQuantity representing the unit in which quantities of physical dimension dimension are measured according to internalUnits.

source
Alicorn.Quantities.conversionFactorMethod
conversionFactor(dimension::Dimension, currentIntU::InternalUnits, targetIntU::InternalUnits)

Returns the factor with which a value of physical dimension dimension expressed in units of currentIntU needs to be mutliplied in order to express it in units of targetIntU.

source

Scalar Quantities

Types

Alicorn.Quantities.SimpleQuantityType
SimpleQuantity{T<:Number} <: AbstractQuantity{T}

A physical quantity consisting of a scalar value and a physical unit.

Fields

  • value::T: value of the quantity
  • unit::Unit: unit of the quantity

Constructors

SimpleQuantity(::Number, ::AbstractUnit)
SimpleQuantity(::Number)
SimpleQuantity(::AbstractUnit)

If no unit is passed to the constructor, unitlessUnit is used by default. If no value is passed to the constructor, the value is set to 1 by default.

If called with a Quantity as argument, the Quantity is expressed in terms of the units used to store its value internally, see InternalUnits.

SimpleQuantity(::Quantity)

If the type T is specified explicitly, Alicorn attempts to convert the value accordingly:

SimpleQuantity{T}(::Number, ::AbstractUnit) where {T<:Number}
SimpleQuantity{T}(::Number) where {T<:Number}
SimpleQuantity{T}(::AbstractUnit) where {T<:Number}

Examples

  1. The quantity $7\,\mathrm{nm}$ (seven nanometers) can be constructed using the constructor method as follows:

    julia> ucat = UnitCatalogue() ;
    
    julia> nanometer = ucat.nano * ucat.meter
    UnitFactor nm
    
    julia> quantity = SimpleQuantity(7, nanometer)
    7 nm
  2. Alternatively, $7\,\mathrm{nm}$ can be constructed arithmetically:

    julia> ucat = UnitCatalogue() ;
    
    julia> nm = ucat.nano * ucat.meter
    UnitFactor nm
    
    julia> quantity = 7nm
    7 nm
source
Alicorn.Quantities.QuantityType
Quantity{T<:Number} <: AbstractQuantity{T}

A physical quantity consisting of a number, a Dimension object representing the physical dimension, and an InternalUnits object representing the units with respect to which the seven basic dimensions of the SI system are measured.

The value field of a Quantity{T} is of type T, which needs to be a subtype of Number.

Fields

  • value::T: value of the quantity
  • dimension::Dimension: physical dimension of the quantity
  • internalUnits::InternalUnits: set of units with respect to which the seven

basic dimensions of the SI system are measured.

Constructors

The constructors preserve the type T of the value upon conversion to the internal units whenever possible. If no InternalUnits are passed to the constructor, the basic SI units are used by default.

Construction from value and dimension; if no dimension is passed to the constructor, a dimensionless quantity is constructed by default.

Quantity(::Number, ::Dimension, ::InternalUnits)
Quantity(::Number, ::Dimension)
Quantity(::Number, ::InternalUnits)
Quantity(::Number)

If the type T is specified explicitly, Alicorn attempts to convert the value accordingly:

Quantity{T}(::Number, ::Dimension, ::InternalUnits) where {T<:Number}
Quantity{T}(::Number, ::Dimension) where {T<:Number}
Quantity{T}(::Number, ::InternalUnits) where {T<:Number}
Quantity{T}(::Number) where {T<:Number}

Construction from value and unit; if no unit is passed to the constructor, a dimensionless quantity is constructed by default.

Quantity(::Number, ::AbstractUnit, ::InternalUnits)
Quantity(::Number, ::AbstractUnit)
Quantity(::AbstractUnit, ::InternalUnits)
Quantity(::AbstractUnit)

Examples

  1. The quantity $7\,\mathrm{nm}$ (seven nanometers) can for instance be constructed as follows:

    julia> ucat = UnitCatalogue() ;
           nm = ucat.nano*ucat.meter;
           intu = InternalUnits(length=1nm) ;
    
    julia> Quantity(7nm, intu)
    Quantity{Int64} of dimension L^1 in units of (1 nm):
     7

    Note that the original type Int64 of the value is preserved.

  2. If we use $2\,\mathrm{nm}$ as internal unit for length, the value can no longer be represented as type Int64 internally:

    julia> ucat = UnitCatalogue() ;
           nm = ucat.nano*ucat.meter;
           intu = InternalUnits(length=2nm) ;
    
    julia> Quantity(7nm, intu)
    Quantity{Float64} of dimension L^1 in units of (2 nm):
     3.5
source
Alicorn.Quantities.ScalarQuantityType
ScalarQuantity{T}

Type union representing a scalar (number) of type T, with or without a unit.

Alias for Union{T, AbstractQuantity{T}} where T<:Number.

source

Construction

Base.:*Method
Base.:*(value::Number, abstractUnit::AbstractUnit)

Combine value and abstractUnit to form a physical quantity of type SimpleQuantity.

If abstractUnit is a product of a UnitPrefix and BaseUnit, they are first combined into a SimpleQuantity, which is then in turn combined with value.

Example

julia> ucat = UnitCatalogue() ;

julia> 3.5 * ucat.milli * ucat.tesla
3.5 mT
source
Base.:/Method
Base.:/(value::Number, abstractUnit::AbstractUnit)

Combine value and abstractUnit to form a physical quantity of type SimpleQuantity.

If abstractUnit is a product of a UnitPrefix and BaseUnit, they are first combined into a SimpleQuantity, which is then in turn combined with value.

Example

julia> ucat = UnitCatalogue() ;

julia> 3.5 / ucat.nano * ucat.second
3.5 ns^-1
source

Dimension

Alicorn.Dimensions.dimensionOfMethod
dimensionOf(quantity::AbstractQuantity)

Returns the dimension of a physical quantity of type AbstractQuantity.

Example

One henry is defined as $1\,\mathrm{H} = 1\,\mathrm{kg}^{1}\,\mathrm{m}^{2}\,\mathrm{s}^{-2}\,\mathrm{A}^{-2}$ and is hence of dimension $\mathrm{M}^{1}\,\mathrm{L}^{2}\,\mathrm{T}^{-2}\,\mathrm{I}^{-2}$:

julia> ucat = UnitCatalogue() ;

julia> oneHenry = 1 * ucat.henry
1 H
julia> dimensionOf(oneHenry)
Dimension M^1 L^2 T^-2 I^-2
source

Type conversion

Alicorn.Quantities.SimpleQuantityMethod
SimpleQuantity(quantity::AbstractQuantity)

Construct a SimpleQuantity from a physical quantity of any implementation of AbstractQuantity.

If quantity is of type SimpleQuantity, it is returned unchanged. If quantity is of type Quantity, it is expressed in terms of the SI units specified by quantity.InternalUnits.

Example

julia> ucat = UnitCatalogue() ; intu = InternalUnits(length=2*ucat.milli*ucat.meter) ;

julia> q = Quantity(4, Dimension(L=1), intu)
Quantity{Int64} of dimension L^1 in units of (2 mm):
 4
julia> sq = SimpleQuantity(q)
8 mm
source
Alicorn.Quantities.SimpleQuantityMethod
SimpleQuantity{T}(::AbstractQuantity) where {T<:Number}

Construct a SimpleQuantity{T} with specified type T from a physical quantity of any implementation of AbstractQuantity.

See SimpleQuantity(::AbstractQuantity) for details.

source
Alicorn.Quantities.QuantityMethod
Quantity(::AbstractQuantity, ::InternalUnits)
Quantity(::AbstractQuantity)

Construct a Quantity from a physical quantity of any implementation of AbstractQuantity.

If no InternalUnits are specified, they are constructed using basic SI units.

source
Alicorn.Quantities.QuantityMethod
Quantity{T}(::AbstractQuantity, ::InternalUnits) where {T<:Number}
Quantity{T}(::AbstractQuantity) where {T<:Number}

Construct a Quantity{T} with specified type T from a physical quantity of any implementation of AbstractQuantity.

See Quantity(::AbstractQuantity, ::InternalUnits) for details.

Raises Exceptions

  • InexactError: if the internal value of AbstractQuantity cannot be

represented as type T.

source
Base.convertMethod
Base.convert(::Type{T}, simpleQuantity::SimpleQuantity) where {T<:SimpleQuantity}

Convert simpleQuantity from type SimpleQuantity{S} where S to any subtype T of SimpleQuantity

Allows to convert, for instance, from SimpleQuantity{Float64} to SimpleQuantity{UInt8}.

source
Base.convertMethod
Base.convert(::Type{T}, quantity::Quantity) where {T<:Quantity}

Convert quantity from type Quantity{S} where S to any type T of Quantity.

Allows to convert, for instance, from Quantity{Float64} to Quantity{UInt8}.

source

Unit Conversion

Alicorn.Quantities.inUnitsOfMethod
inUnitsOf(quantity::AbstractQuantity, unit::AbstractUnit)::SimpleQuantity

Express quantity as an object of type SimpleQuantity in terms of the unit specified by unit.

Raises Exceptions

  • Alicorn.Exceptions.DimensionMismatchError: if the dimensions of quantity and unit do not agree
source
Alicorn.Quantities.valueInUnitsOfMethod
valueInUnitsOf(quantity::AbstractQuantity, unit::AbstractUnit)

Returns the numerical value of quantity expressed in units of unit.

Raises Exceptions

  • Alicorn.Exceptions.DimensionMismatchError: if the dimensions of quantity and unit do not agree
source
Alicorn.Quantities.valueInUnitsOfMethod
valueInUnitsOf(quantity::AbstractQuantity, simpleQuantity::SimpleQuantity)

Returns the numerical value of quantity expressed in units of simpleQuantity.

The result is equivalent to valueOfDimensionless(quantity / simpleQuantity).

Raises Exceptions

  • Alicorn.Exceptions.DimensionMismatchError: if the dimensions of quantity and simpleQuantity do not agree
source
Alicorn.Quantities.valueOfDimensionlessMethod
valueOfDimensionless(quantity::AbstractQuantity)

Strips the unit from a dimensionless quantity and returns its bare value.

Raises Exceptions

  • Alicorn.Exceptions.DimensionMismatchError: if quantity is not dimensionless
source
Base.:*Method
Base.:*(quantity::AbstractQuantity, unit::AbstractUnit)
Base.:*(unit::AbstractUnit, quantity::AbstractQuantity)

Modify the unit of quantity by multiplying it with unit.

source
Base.:/Method
Base.:/(quantity::AbstractQuantity, unit::AbstractUnit)
Base.:/(unit::AbstractUnit, quantity::AbstractQuantity)

Modify the unit of quantity by dividing it by unit, or vice versa.

source
Alicorn.Quantities.inInternalUnitsOfMethod
inInternalUnitsOf(qArray::QuantityArray{T}, targetIntU::InternalUnits) where T

Returns a new QuantityArray corresponding to qArray, but stored using targetIntU as new internal units.

The value type S of the returned quantity array is identical to T, if possible.

source

Array Quantities

Types

Alicorn.Quantities.SimpleQuantityArrayType
SimpleQuantityArray{T<:Number,N} <: AbstractQuantityArray{T,N}

A physical quantity consisting of a number array and a physical unit.

The value field of a SimpleQuantityArray{T,N} is of type Array{T,N}. T needs to be a subtype of Number.

Fields

  • value::Array{T,N}: value of the quantity
  • unit::Unit: unit of the quantity

Constructors

SimpleQuantityArray(::AbstractArray, ::AbstractUnit)
SimpleQuantityArray(::AbstractArray)

If no unit is passed to the constructor, unitlessUnit is used by default.

SimpleQuantityArray{T}(::AbstractArray, ::AbstractUnit) where {T<:Number}
SimpleQuantityArray{T}(::AbstractArray) where {T<:Number}

If the type T is specified explicitly, Alicorn attempts to convert the value accordingly.

source
Alicorn.Quantities.QuantityArrayType
QuantityArray{T<:Number,N} <: AbstractQuantityArray{T,N}

A physical quantity consisting of an array, a Dimension object representing the physical dimension, and an InternalUnits object representing the units with respect to which the seven basic dimensions of the SI system are measured.

The value field of a QuantityArray{T,N} is of type Array{T,N}. T needs to be a subtype of Number.

Fields

  • value::Array{T,N}: value of the quantity
  • dimension::Dimension: physical dimension of the quantity
  • internalUnits::InternalUnits: set of units with respect to which the seven

basic dimensions of the SI system are measured.

Constructors

QuantityArray(::AbstractArray, ::Dimension, ::InternalUnits)
QuantityArray(::AbstractArray, ::Dimension)
QuantityArray(::AbstractArray, ::InternalUnits)
QuantityArray(::AbstractArray)

If no InternalUnits are passed to the constructor, the basic SI units are used. If no Dimension is passed to the constructor, a dimensionless quantity is constructed.

QuantityArray{T}(::AbstractArray, ::Dimension, ::InternalUnits) where {T<:Number}
QuantityArray{T}(::AbstractArray, ::Dimension) where {T<:Number}
QuantityArray{T}(::AbstractArray, ::InternalUnits) where {T<:Number}
QuantityArray{T}(::AbstractArray) where {T<:Number}

If the type T is specified explicitly, Alicorn attempts to convert the provided AbstractArray to Array{T}.

source
Alicorn.Quantities.VectorQuantityType
VectorQuantity{T}

Type union representing one-dimensional arrays with elements of type T, with or without a physical unit.

Alias for Union{Vector{T}, AbstractQuantityArray{T, 1}} where T<:Number.

source
Alicorn.Quantities.MatrixQuantityType
MatrixQuantity{T}

Type union representing two-dimensional arrays with elements of type T, with or without a physical unit.

Alias for Union{Matrix{T}, AbstractQuantityArray{T, 2}} where T<:Number.

source
Alicorn.Quantities.ArrayQuantityType
ArrayQuantity{T,N}

Type union representing N-dimensional arrays with elements of type T, with or without a physical unit.

Alias for Union{Array{T,N}, AbstractQuantityArray{T,N}} where {T<:Number, N}.

source

Construction

Base.:*Method
Base.:*(value::AbstractArray{T}, abstractUnit::AbstractUnit) where {T<:Number}

Combine the array value and abstractUnit to form a physical quantity of type SimpleQuantityArray.

If abstractUnit is a product of a UnitPrefix and BaseUnit, they are first combined into a SimpleQuantity, which is then in turn combined with value.

Example

julia> ucat = UnitCatalogue() ;

julia> [3.5, 4.6] * ucat.milli * ucat.tesla
2-element SimpleQuantityVector{Float64} of unit mT:
 3.5
 4.6
source
Base.:/Method
Base.:/(value::AbstractArray{T}, abstractUnit::AbstractUnit) where {T<:Number}

Combine the array value and abstractUnit to form a physical quantity of type SimpleQuantityArray.

If abstractUnit is a product of a UnitPrefix and BaseUnit, they are first combined into a SimpleQuantity, which is then in turn combined with value.

Example

julia> ucat = UnitCatalogue() ;

julia> [3.5, 4.6] / ucat.nano * ucat.second
2-element SimpleQuantityVector{Float64} of unit ns^-1:
 3.5
 4.6
source

Dimension

Type Conversion

Alicorn.Quantities.SimpleQuantityArrayMethod
SimpleQuantityArray(quantityArray::AbstractQuantityArray)

Construct a SimpleQuantityArray from a physical quantity of any implementation of AbstractQuantityArray.

If quantityArray is of type SimpleQuantityArray, it is returned unchanged. If quantityArray is of type QuantityArray, it is expressed in terms of the SI units specified by quantityArray.InternalUnits.

source
Alicorn.Quantities.SimpleQuantityArrayMethod
SimpleQuantityArray{T}(::AbstractQuantityArray) where {T<:Number}

Construct a SimpleQuantityArray{T} with specified type T from a physical quantity of any implementation of AbstractQuantityArray.

See SimpleQuantityArray(::AbstractQuantityArray) for details.

Raises Exceptions

  • InexactError: if the value of AbstractQuantityArray cannot be

represented as type Array{T}.

source
Alicorn.Quantities.SimpleQuantityArrayMethod
SimpleQuantityArray(quantity::AbstractQuantity)

Construct a 1x1 SimpleQuantityArray from a physical quantity of any implementation of AbstractQuantity.

See SimpleQuantityArray(::AbstractQuantityArray) for details.

source
Alicorn.Quantities.SimpleQuantityArrayMethod
SimpleQuantityArray{T}(quantity::AbstractQuantity) where {T<:Number}

Construct a 1x1 SimpleQuantityArray{T} with specified type T from a physical quantity of any implementation of AbstractQuantity.

See SimpleQuantityArray(::AbstractQuantity) for details.

Raises Exceptions

  • InexactError: if the value of AbstractQuantity cannot be

represented as type Array{T}.

source
Alicorn.Quantities.QuantityArrayMethod
QuantityArray(::AbstractQuantityArray, ::InternalUnits)
QuantityArray(::AbstractQuantityArray)

Construct a QuantityArray from a physical quantity of any implementation of AbstractQuantityArray.

If no InternalUnits are specified, they are inferred from the AbstractQuantityArray if possible. Else, basic SI units are used.

source
Alicorn.Quantities.QuantityArrayMethod
QuantityArray{T}(::AbstractQuantityArray, ::InternalUnits) where {T<:Number}
QuantityArray{T}(::AbstractQuantityArray) where {T<:Number}

Construct a QuantityArray{T} with specified type T from a physical quantity of any implementation of AbstractQuantityArray.

See QuantityArray(::AbstractQuantityArray, ::InternalUnits) for details.

Raises Exceptions

  • InexactError: if the internal value of AbstractQuantityArray cannot be

represented as type Array{T}.

source
Alicorn.Quantities.QuantityArrayMethod
QuantityArray(quantity::AbstractQuantity, ::InternalUnits)
QuantityArray(quantity::AbstractQuantity)

Construct a 1x1 QuantityArray from a physical quantity of any implementation of AbstractQuantity.

See QuantityArray(::AbstractQuantityArray) for details.

source
Alicorn.Quantities.QuantityArrayMethod
QuantityArray{T}(::AbstractQuantity, ::InternalUnits) where {T<:Number}
QuantityArray{T}(::AbstractQuantity) where {T<:Number}

Construct a QuantityArray{T} with specified type T from a physical quantity of any implementation of AbstractQuantity.

See QuantityArray(::AbstractQuantity, ::InternalUnits) for details.

Raises Exceptions

  • InexactError: if the internal value of AbstractQuantityArray cannot be

represented as type Array{T}.

source
Base.convertMethod
Base.convert(::Type{T}, sqArray::SimpleQuantityArray) where {T<:SimpleQuantityArray}

Convert sqArray from type SimpleQuantityArray{S} where S to any subtype T of SimpleQuantityArray.

Allows to convert, for instance, from SimpleQuantityArray{Float64} to SimpleQuantityVector{UInt8}.

source
Base.convertMethod
Base.convert(::Type{T}, qArray::QuantityArray) where {T<:QuantityArray}

Convert qArray from type QuantityArray{S} where S to any subtype T of QuantityArray.

Allows to convert, for instance, from QuantityArray{Float64} to QuantityVector{UInt8}.

source

Unit Conversion

Alicorn.Quantities.inUnitsOfMethod
inUnitsOf(qArray::AbstractQuantityArray, unit::AbstractUnit)::SimpleQuantityArray

Express qArray as an object of type SimpleQuantityArray in terms of the unit specified by unit.

Raises Exceptions

  • Alicorn.Exceptions.DimensionMismatchError: if the dimensions of qArray and unit do not agree
source
Alicorn.Quantities.inBasicSIUnitsMethod
inBasicSIUnits(qArray::AbstractQuantity)::SimpleQuantityArray

Express qArray as an object of type SimpleQuantityArray using the seven basic SI units.

source
Alicorn.Quantities.valueInUnitsOfMethod
valueInUnitsOf(qArray::AbstractQuantityArray, unit::AbstractUnit)

Returns the numerical value of qArray expressed in units of unit.

Raises Exceptions

  • Alicorn.Exceptions.DimensionMismatchError: if the dimensions of quantity and unit do not agree
source
Alicorn.Quantities.valueInUnitsOfMethod
valueInUnitsOf(quantityArray::AbstractQuantityArray, simpleQuantity::SimpleQuantity)

Returns the numerical value of quantityArray expressed in units of simpleQuantity.

The result is equivalent to valueOfDimensionless(quantityArray / simpleQuantity).

Raises Exceptions

  • Alicorn.Exceptions.DimensionMismatchError: if the dimensions of quantityArray and simpleQuantity do not agree
source
Alicorn.Quantities.valueOfDimensionlessMethod
valueOfDimensionless(qArray::AbstractQuantityArray)

Strips the unit from a dimensionless quantity array and returns its bare value.

Raises Exceptions

  • Alicorn.Exceptions.DimensionMismatchError: if qArray is not dimensionless
source
Base.:*Method
Base.:*(qArray::AbstractQuantityArray, unit::AbstractUnit)
Base.:*(unit::AbstractUnit, qArray::AbstractQuantityArray)

Modify the unit of qArray by multiplying it with unit.

source
Base.:/Method
Base.:/(qArray::AbstractQuantityArray, unit::AbstractUnit)
Base.:/(unit::AbstractUnit, qArray::AbstractQuantityArray)

Modify the unit of qArray by dividing it by unit, or vice versa.

source
Alicorn.Quantities.inInternalUnitsOfMethod
inInternalUnitsOf(quantity::Quantity{T}, targetIntU::InternalUnits) where T

Returns a new Quantity{S} corresponding to quantity, but stored using targetIntU as new internal units.

The value type S of the returned quantity is identical to T, if possible.

source

Array Methods

AbstractQuantityArray and (where applicable) AbstractQuantity extend the interface of AbstractArray from Julia base.

MethodImplemented forRemak
Base.sizeAbstractQuantityType
Base.IndexStyleAbstractQuantityTypereturns IndexLinear()
Base.getindexAbstractQuantityTypereturns SimpleQuantity or Quantity if a single element is indexed
Base.setindex!AbstractQuantityTypethe assigned values have to be of matching type, e.g., SimpleQuantity or SimpleQuantityArray when assigning to a SimpleQuantityArray

Alicorn also extends the following methods for handling arrays from Julia base:

MethodImplemented for
Base.eltypeAbstractQuantityType
Base.copyAbstractQuantityType
Base.deepcopyAbstractQuantityType
Base.axesAbstractQuantityType
Base.ndimsAbstractQuantityType
Base.lengthAbstractQuantityType
Base.firstindexAbstractQuantityType
Base.lastindexAbstractQuantityType
Base.IteratorSizeAbstractQuantity
Base.keysAbstractQuantityType
Base.getAbstractQuantityType
Base.firstAbstractQuantityType
Base.lastAbstractQuantityType
Base.deleteat!AbstractQuantityVector
Base.repeatAbstractQuantityArray
Base.iterateScalarQuantity

Mathematics

Alicorn extends the following basic mathematical functions from Julia base to operate on AbstractQuantity and AbstractQuantityArray types.

Arithmetics

Binary operations involving two quantities generally show the followig behavior:

MethodSupports broadcasting
unary plus Base.:+(::AbstractQuantityType)yes
unary minus Base.:-(::AbstractQuantityType)yes
addition Base.:+yes
subtraction Base.:-yes
multiplication Base.:*yes
division Base.:*yes
power Base.:^yes
inverse Base.invyes
Base.:+Method
Base.:+(q1::SimpleQuantity, q2::SimpleQuantity)
Base.:+(q1::SimpleQuantityArray, q2::SimpleQuantityArray)

Add two objects of type SimpleQuantity or SimpleQuantityArray.

The resulting quantity is expressed in units of q1.

Raises Exceptions

  • Alicorn.Exceptions.DimensionMismatchError: if q1 and q2 are of different dimensions
source
Base.:+Method
Base.:+(q1::Quantity, q2::Quantity)
Base.:+(q1::QuantityArray, q2::QuantityArray)

Add two objects of type Quantity or QuantityArray.

The resulting quantity is expressed in internal units of q1.

Raises Exceptions

  • Alicorn.Exceptions.DimensionMismatchError: if q1 and q2 are of different dimensions
source
Base.:+Method
Base.:+(q1::SimpleQuantity, q2::Quantity)
Base.:+(q1::Quantity, q2::SimpleQuantity)
Base.:+(q1::SimpleQuantityArray, q2::QuantityArray)
Base.:+(q1::QuantityArray, q2::SimpleQuantityArray)

Add two objects of type SimpleQuantity and Quantity, or SimpleQuantityArray and QuantityArray.

Returns a quantity of type Quantity or QuantityArray.

Raises Exceptions

  • Alicorn.Exceptions.DimensionMismatchError: if q1 and q2 are of different dimensions
source
Base.:-Method
Base.:-(q1::SimpleQuantity, q2::SimpleQuantity)
Base.:-(q1::SimpleQuantityArray, q2::SimpleQuantityArray)

Subtract two objects of type SimpleQuantity or SimpleQuantityArray.

The resulting quantity is expressed in units of q1.

Raises Exceptions

  • Alicorn.Exceptions.DimensionMismatchError: if q1 and q2 are of different dimensions
source
Base.:-Method
Base.:-(q1::Quantity, q2::Quantity)
Base.:-(q1::QuantityArray, q2::QuantityArray)

Subtract two objects of type Quantity or QuantityArray.

The resulting quantity is expressed in internal units of q1.

Raises Exceptions

  • Alicorn.Exceptions.DimensionMismatchError: if q1 and q2 are of different dimensions
source
Base.:-Method
Base.:-(q1::SimpleQuantity, q2::Quantity)
Base.:-(q1::Quantity, q2::SimpleQuantity)
Base.:-(q1::SimpleQuantityArray, q2::QuantityArray)
Base.:-(q1::QuantityArray, q2::SimpleQuantityArray)

Subtract two objects of type SimpleQuantity and Quantity, or SimpleQuantityArray and QuantityArray.

Returns a quantity of type Quantity or QuantityArray.

Raises Exceptions

  • Alicorn.Exceptions.DimensionMismatchError: if q1 and q2 are of different dimensions
source

Numeric Comparison

Numeric comparison is only possible between

In particular, comparison with == fails if this is not the case.

MethodSupports broadcastingRemarks
Base.(==)yes
Base.<yes
Base.(<=)yes
Base.>yes
Base.(>=)yes
Base.isapproxyes
Base.isfinitenoonly for AbstractQuantity
Base.isinfnoonly for AbstractQuantity
Base.isnannoonly for AbstractQuantity
Base.:==Method
Base.:(==)(q1::SimpleQuantity, q2::SimpleQuantity)
Base.:(==)(q1::SimpleQuantityArray, q2::SimpleQuantityArray)

Returns true if q1 and q2 are of equal value and unit.

Note that the units are not converted during the comparison.

Examples

julia> ucat = UnitCatalogue() ;

julia> q1 = 7 * ucat.meter
7 m

julia> q2 = 700 * (ucat.centi * ucat.meter)
700 cm

julia> q1 == q1
true

julia> q1 == q2
false
source
Base.:==Method
Base.:(==)(q1::Quantity, q2::Quantity)
Base.:(==)(q1::QuantityArray, q2::QuantityArray)

Compare two Quantity or QuantityArray objects.

The two quantities are equal if their values, their dimensions, and their internal units are equal. Note that the internal units are not converted during the comparison.

source
Base.islessMethod
Base.isless(q1::SimpleQuantity, q2::SimpleQuantity)

Returns true if q1 is of lesser value than q2.

Note that units are not converted during the comparison.

Raises Exceptions

  • Alicorn.Exceptions.UnitMismatchError: if q1 and

q2 are not of the same unit

source
Base.islessMethod
Base.isless(q1::Quantity, q2::Quantity)

Returns true if q1 is of lesser value than q2.

Note that internal units are not converted during the comparison.

Raises Exceptions

  • Alicorn.Exceptions.DimensionMismatchError: if q1 and q2 are not of the same dimension
  • Alicorn.Exceptions.UnitMismatchError: if q1 and q2 are not using the same internal units
source
Base.isapproxMethod
Base.isapprox(q1::SimpleQuantity, q2::SimpleQuantity; rtol::Real = sqrt(eps()) )
Base.isapprox(q1::SimpleQuantityArray, q2::SimpleQuantityArray; rtol::Real = sqrt(eps()) )

Returns isapprox(q1.value, q2.value, rtol=rtol).

Note that units are not converted during the comparison. Returns false if the two quantities are not of equal physical dimension.

source
Base.isapproxMethod
Base.isapprox(q1::Quantity, q2::Quantity; rtol::Real = sqrt(eps()) )
Base.isapprox(q1::QuantityArray, q2::QuantityArray; rtol::Real = sqrt(eps()) )

Returns isapprox(q1.value, q2.value, rtol=rtol).

Note that internal units are not converted during the comparison.

Raises Exceptions

  • Alicorn.Exceptions.DimensionMismatchError: if q1 and q2 are not of the same dimension
  • Alicorn.Exceptions.UnitMismatchError: if q1 and q2 are not using the same internal units
source

Sign and Absolute Value

MethodSupports broadcastingRemarks
Base.absyesonly for AbstractQuantity
Base.abs2yesonly for AbstractQuantity
Base.signyesonly for AbstractQuantity
Base.signbitnoonly for AbstractQuantity
Base.copysignnoonly for AbstractQuantity
Base.flipsignnoonly for AbstractQuantity

Roots

MethodSupports broadcastingRemarks
Base.sqrtyesonly for AbstractQuantity
Base.cbrtyesonly for AbstractQuantity

Complex Numbers

MethodSupports broadcastingRemarks
Base.realyes
Base.imagyes
Base.angleyesonly for AbstractQuantity
Base.conjyes

Broadcasting

Alicorn offers broadcasting for most mathematical functions available for quantities. For example:

julia> ucat = UnitCatalogue() ;

julia> M = [2 3; 4 5] * ucat.meter ;

julia> q = Quantity(2 * ucat.meter) ;

julia> M .+ q
2×2 QuantityMatrix{Int64} of dimension L^1 in units of (1 m):
 4  5
 6  7

The tables in the previous section indicate which functions support broadcasting.