Why this package ?

We demonstrate this with an example. Assume we have a nice function which calculates with unitful values:

julia> using Unitful

julia> unitful_lsum(a::Unitful.Length, b::Unitful.Length) = a+b;

julia> unitful_lsum(10.0u"cm",1.0u"m")
1.1 m

Now we assume that there is a faster way to calculate the same sum with the caveat that the implementation does not support unitful values, e.g. because it uses a binary package written in C. (here, we just use a mock example, in reality, think about sparse linear algebra)

julia> fast_lsum(a::Real, b::Real)=a+b;

If we want to use this method in a faster implementation of unitful_area, we might try to use Unitful.ustrip to strip the units and to attach them back somehow afterwards. However, before stripping the arguments need to be brought to a common unit. Canonically, this is the preferred unit of the corresponding dimension provided by Unitful (SI base unit by default).

julia> function fast_unitful_lsum(a::Unitful.Length, b::Unitful.Length)
           a_stripped=a |> upreferred |> ustrip
           b_stripped=b |> upreferred |> ustrip
           fast_lsum(a_stripped, b_stripped)* unit(upreferred(a))
       end;

julia> fast_unitful_lsum(10.0u"cm",1.0u"m")
1.1 m

LessUnitful.jl provides

julia> using LessUnitful, LessUnitful.MoreUnitful

julia> function fast_lessunitful_lsum(a::Unitful.Length, b::Unitful.Length)
           a_stripped=a |> unitfactor
           b_stripped=b |> unitfactor
           fast_lsum(a_stripped, b_stripped) |> u"m"
       end;

julia> fast_lessunitful_lsum(10.0u"cm",1.0u"m")
1.1 m

Also it helps to support a complete "less unitful" workflow:

julia> fast_lsum(10.0ufac"cm",1.0ufac"m")
1.1

It is also possible to attach arbitrary units back in a way consistent to the preferred units:

julia> fast_lsum(10.0ufac"cm",1.0ufac"m") |> u"cm"
110.00000000000001 cm

Notations

The package provides tools to access Unitful.jl to define floating point constants for units like cm, kPa, mV etc. called unit factors. These unit factors relate units to their corresponding products of powers of unitful preferred units in the sense of Unitful.jl.

By default the unitful preferred units are synonymous with the SI base units.

Example: Unit: kN $\to$ representation in powers of SI base units: $1000\cdot kg\cdot m\cdot s^{-2}$ $\to$ unit factor: 1000.0

julia> using LessUnitful

julia> @unitfactors kN
1000.0

The unit factor of a quantity like 5cm, 10kPa, 3mV is its numerical value after conversion to products of powers of unitful preferred units.

Example: Quantity: 3kN $\to$ representation in powers of SI base units: $3000\cdot kg\cdot m\cdot s^{-2}$ $\to$ unit factor: 3000.0

julia> using LessUnitful

julia> ufac"3kN"
3000.0

The unitfactor represents the numerical value of a unit/quatity expressed in preferred units:

julia> using LessUnitful, Unitful

julia> unitfactor(u"cm")==Unitful.ustrip(Unitful.upreferred(u"1.0cm"))
true

Reciprocally, one can make a number "unitful", assuming it corresponds to one of the preferred units. Assume x represents an unit factor of a quantity with respect to the corresponding products of powers of unitful preferred units. Create this quantity and convert it to unit:

julia> using LessUnitful, Unitful

julia> unitful(0.03,u"cm")==u"cm"(Unitful.float(0.03*Unitful.upreferred(u"cm")))
true

Providing these unit factors allows a "unitless" workflow with physical data which is characterized by the following aspects:

• All calculations are done in numerical values corresponding to unitful preferred units (SI base units by default)
• Data input can be performed in at least two different ways:
  • Declare @unitfactors cm and enter e.g. length=10*cm
  • Enter "unitful" length=10u"cm" and actually provide unitfactor(length) to the "unitless" code
• Data output can go as follows - assume result p is a pressure:
  • Declare @unitfactors kPa and do println("p= ",p/kPa,"kPa")
  • Alternatively, do println(unitful(p,u"kPa")), or (with LessUnitful.MoreUnitful): println(p|> u"kPa")

Obtaining unit factors

unitfactor(x)

julia> unitfactor(u"3mV")
0.003
julia> u"3mV"|> unitfactor
0.003

julia> unitfactor(u"mV")
0.001
julia> u"mV"|> unitfactor
0.001

julia> u"1mV" |> u"V" |> Unitful.float
0.001 V

julia> u"1cm" |> unitfactor |> u"cm"
1.0 cm

@ufac_str

julia> ufac"1mV"
0.001

@unitfactors

julia> @unitfactors cm;

julia> 3cm
0.03

@unitfactors mm cm km A V

julia> @unitfactors cm mm;

julia> cm+mm
0.011

julia> u"1cm"+u"1mm"|> float
0.011 m

@local_unitfactors

function f()
    @local_unitfactors cm
    3cm
end
f()
# output
0.03

Creating unitful values

unitful(x,unit)

julia> unitful(200,u"kPa")
0.2 kPa

    MoreUnitful

(unit)(x::Real)

julia> u"kPa"(200)
0.2 kPa

julia> 200 |> u"kPa"
0.2 kPa

ERROR: DimensionError: kPa and 200 are not dimensionally compatible.

@unitfactors μA mA;
x = 15mA
println(x/μA," μA")
# output
15000.0 μA

@unitfactors  μA mA
x = 15mA
println(x|>u"μA")  
# output
15000.0 μA

julia>  0.05|> u"cm" |> unitfactor
0.05

Physical constants

As already described above, the @ufac_str macro can be used to extract the values of physical constants from PhysicalConstants.CODATA2018.

@ph_str

julia> ph"N_A"
6.02214076e23

@phconstants

julia> @phconstants N_A
6.02214076e23

const N_A = ustrip(upreferred(PhysicalConstants.CODATA2018.N_A))

@phconstants AvogadroConstant c_0

@local_phconstants

function f()
    @local_phconstants N_A
    N_A
end
f()
# output
6.02214076e23

Ensuring consistency with SI Base units

ensureSIBase()

julia> ensureSIBase()
true

Changing preferred units

By calling Unitful.preferunits the preferred units can be changed from SI base units to e.g. g for mass and cm for length.

In order to be effective, this needs to be called before any invocation of Unitful.upreferred, and as a consequence, before any invocation of macros or functions from the LessUnitful package.

Due to this issue for Julia 1.8 it is advised to evaluate at least one of the unit factors from LessUnitful immediately after calling preferunits.

Moreover, while it is convenient to use e.g. @unitfactors in the global scope of a package, it is important to understand that values in global scope are evaluated during precompilation and cannot be influenced by Unitful.upreferred. Therefore it appears that packages which are designed to work consistently with other defaults than SI base units should avoid the use of @unitfactors and @phconstants. The use of @local_unitfactors and @local_phconstants, and of @ufac_str, unitfactor, unitful does not suffer from this problem, though.