Awesome
This package may be unsupported
We recommend Unitful.jl, which provides greater functionality and was written more recently, allowing it to take advantage of modern features of julia.
SIUnits
This package provides efficient unit-checked computations based for units in the
SIUnits systems. To use this package use (after installing it using Pkg.add
)
using SIUnits
optionally, you may also use
using SIUnits
using SIUnits.ShortUnits
instead, to load a number of abbreviations into the current namespace
(e.g. kg
instead of KiloGram
). These abbreviations are not loaded
by default to avoid flooding the namespace where this is not desired.
Note that all examples in this README assume that the second form was
used. To make the examples work with the first form, just substitute the
written out names, e.g. Volt
for V
and Nano*Meter
for nm
.
Usage
SIUnits.jl
integrates into the number promotion system and all the usual
arithmetic operations (+
,-
,*
,/
,^
,sqrt
) work as one would expect.
In particular, addition and subtraction is allowed between two quantities with
the same units:
julia> 1V + 2V
3 kg m²s⁻³A⁻¹
julia> (1//2)s - 1s
-1//2 s
However, you may not add or subtract quantities whose units differ:
julia> 1s + 2V
ERROR: Unit mismatch. Got (s ) + (kg m²s⁻³A⁻¹)
Consistently, multiplication and division increase or decrease the exponents of the base units, e.g.:
julia> 1N
1 kg m s⁻²
julia> 1N/m
1 kg s⁻²
julia> 1N*s^2
1 kg m
You may also take square roots of quantities with units:
julia> sqrt(1s^2)
1.0 s
However, currently, the result must have integral exponents. Support for fractional exponents may be added in the future:
julia> sqrt(1m)
ERROR: InexactError()
Converting between unitful and unitless quantities
SIUnits.jl
does not define implicit convert
methods to avoid silently losing
unit information where this may be undesirable. Instead, SIUnits.jl
extends
the various forced type conversions e.g. float
, float64
and int
. Packages
writing generic code should use these where a specific unitless value is
required.
Implementation details
Where possible (i.e. where the compiler can reason about the type of a variable), there is no runtime overhead. For example:
julia> [1V, 2V, 3V]
3-element Array{SIQuantity{Int64,2,1,-3,-1,0,0,0},1}:
1 kg m²s⁻³A⁻¹
2 kg m²s⁻³A⁻¹
3 kg m²s⁻³A⁻¹
julia> sizeof(ans)
24
this is the same amount of storage as that taken up by a simple array of three 64bit integers:
julia> sizeof([1 2 3])
24
This shows that there is no runtime memory overhead. Similarly, the code generated to add two 64bit integers:
julia> code_native(+,(Uint64,Uint64))
.section __TEXT,__text,regular,pure_instructions
Filename: int.jl
Source line: 42
push RBP
mov RBP, RSP
Source line: 42
add RDI, RSI
mov RAX, RDI
pop RBP
ret
is exactly the same as the code two add two 64bit integer quantities with units:
julia> code_native(+,typeof((1V,2V)))
.section __TEXT,__text,regular,pure_instructions
Filename: /Users/kfischer/.julia/SIUnits/src/SIUnits.jl
Source line: 122
push RBP
mov RBP, RSP
Source line: 122
add RDI, RSI
Source line: 123
mov RAX, RDI
pop RBP
ret
This is achieved by keeping track of the exponents as part of the type rather than of the value. An SIQuantity is defined as
immutable SIQuantity{T<:Number,m,kg,s,A,K,mol,cd} <: Number
val::T
end
where the m,kg,s,A,K,mol,cd
type parameters keep track of the exponents of
the respective base units. This definition is the core of the package. The
rest makes it play nicely with the numeric promotion sytem to make sure that
generic code will work just fine on SIQuantities
.