Affine Units Functionality

Project.toml

@@ -1,7 +1,7 @@
 name = "DynamicQuantities"
 uuid = "06fc5a27-2a28-4c7c-a15d-362465fb6821"
 authors = ["MilesCranmer <[email protected]> and contributors"]
-version = "1.5.1"
+version = "1.6.0"
 
 [deps]
 DispatchDoctor = "8d63f2c5-f18a-4cf2-ba9d-b3f60fc568c8"

README.md

@@ -284,6 +284,21 @@ julia> 3us"V" |> us"OneFiveV"
 2.0 OneFiveV
 ```
 
+#### Affine Units
+
+You can also use "*affine*" units such as Celsius or Fahrenheit,
+using the `ua"..."` string macro:
+
+```julia
+julia> room_temp = 22ua"degC"
+22.0 °C
+
+julia> room_temp |> ua"degF" |> round
+72.0 °F
+
+julia> room_temp |> uexpand |> round
+295.0 K
+```
 
 ### Arrays
 

docs/make.jl

@@ -46,6 +46,7 @@ makedocs(;
         "Units" => "units.md",
         "Constants" => "constants.md",
         "Symbolic Units" => "symbolic_units.md",
+        "Affine Units" => "affine_units.md",
         "Types" => "types.md",
     ],
     warnonly = [:missing_docs]

docs/src/affine_units.md

@@ -0,0 +1,53 @@
+# Affine Dimensions
+Units that have an offset (such as °C = K + 273.15) are an unfortunate fact of life: they are used extensively but often result in ambiguous mathematical operations (many other packages, such as Unitful.jl only support limited operations for affine dimensions). `AffineDimensions` seeks to extend DynamicQuantities.jl to reduce dependence on Unitful.jl, and enable handling/converting such units in a flexible, type-stable manner.
+
+`AffineDimensions` are a generalization of `Dimensions` and `SymbolicDimensions`. While SymbolicDimensions essentially add a scale to Dimensions, AffineDimensions will add both a scale and an offset. Verious constructors can be used to construct `AffineDimensions` from other dimensions.
+```
+kelvin  = AffineDimensions(basedim=u"K") #Assumes a scale of 1 and offset 0
+rankine = AffineDimensions(scale=5/9, offset=0.0, basedim=dimension(u"K")) #Rankine is a scaled version of Kelvin, offset is assumed to be of units 'basedim'
+fahrenheit = AffineDimensions(scale=1.0, offset=Quantity(459.67, rankine), basedim=rankine) #Its best to make offset a `Quantity` to be explicit
+celsius = AffineDimensions(scale=9/5, offset=Quantity(32.0, rankine), basedim=fahrenheit) #When AffineDimensiosn are used, offset starts with basedim's offset
+```
+## Registration and parsing
+To access units from the affine unit registry, the string macro `ua"..."` can be used. This macro will always return quantities with AffineDimensions, even if a non-affine unit is called (it will simply have an offset of 0). Because AffineDimensions are a generalization of SymbolicDimensions, the affine unit registry will mirror the symbolic unit registry.
+```
+@register_unit psi 6.89476us"kPa"
+u"psi"
+>> 6894.76 m⁻¹ kg s⁻²
+us"psi"
+>> 1.0 psi
+ua"psi"
+>> 1.0 psi
+```
+However, strictly affine units cannot belong to the symbolic registry, so a different macro must be used on an AffineDimension (or quantity thereof)
+```
+@register_affine_unit psig AffineDimensions(offset=u"Constants.atm", basedim=u"psi") #Gauge pressure implies atmospheric offset
+ua"psig"
+>> 1.0 psig
+us"psig"
+>> ERROR: LoadError: ArgumentError: Symbol psig not found in `Units` or `Constants`.
+```
+Affine unit parsing can also be done outside of a macro using `aff_uparse(str::AbstractString)`
+```
+aff_uparse("°C")
+>> 1.0 °C
+```
+```@docs
+@ua_str
+@register_affine_unit
+aff_uparse
+```
+## Operations
+In Unitful.jl, multiplication of affine quantities is not supported for affine dimensions:
+```
+using Unitful
+u"R"*0u"°C"
+>> ERROR: AffineError: an invalid operation was attempted with affine units: °C
+```
+This behaviour is mimicked in DynamicQuantities:
+```
+using DynamicQuantities
+u"Constants.R"*(0ua"°C")
+>> AssertionError: AffineDimensions °C has a non-zero offset, implicit conversion is not allowed due to ambiguity. Use uexpand(x) to explicitly convert 
+```
+In general, it's best to treat quantities with AffineDimensions as placeholders and use `uexpand(q)` or `uconvert(units, q)` as soon as possible. The main objective of AffineDimesnions is to provide you with convenient, type-stable tools to do this conversion before applying mathematical operations.

src/DynamicQuantities.jl

@@ -6,11 +6,12 @@ export Quantity, GenericQuantity, RealQuantity
 export FixedRational
 export AbstractDimensions, Dimensions, NoDims
 export AbstractSymbolicDimensions, SymbolicDimensions, SymbolicDimensionsSingleton
+export AbstractAffineDimensions, AffineDimensions
 export QuantityArray
 export DimensionError
 export ustrip, dimension, uexpand, uconvert, ustripexpand
 export ulength, umass, utime, ucurrent, utemperature, uluminosity, uamount
-export uparse, @u_str, sym_uparse, @us_str, @register_unit
+export uparse, @u_str, sym_uparse, @us_str, @register_unit, aff_uparse, @ua_str, @register_affine_unit
 
 # Deprecated:
 export expand_units
@@ -29,9 +30,11 @@ using DispatchDoctor: @stable
     include("constants.jl")
     include("uparse.jl")
     include("symbolic_dimensions.jl")
+    include("affine_dimensions.jl")
     include("complex.jl")
     include("register_units.jl")
     include("disambiguities.jl")
+
 
     include("deprecated.jl")
 end