feat: add ustripexpand (#162)

* Add `sibasevalue` function

* Define uexpand for quantities with Dimensions
* Define `sibasevalue(q)=ustrip(uexpand(q))

When obtaining the numerical value of a quantity (e.g. for computations
with sparse direct solvers implemented in other languages) via `ustrip`,
there is danger of mixing up the right values when quantities with
symbolic dimensions come into play.

By adding a `uexpand` method for quantities with dimensions,
which just passes through the value one can write code consistent
for both flavors of quantities.

`sibasevalue` shall help to remove a little bit of boilerplate
and explicitely hint at the characteristics of the returned value.

* Update format in test/unittests.jl

Co-authored-by: Miles Cranmer <[email protected]>

* remove unintended dependency in docs/Project.toml

* sibasevalue -> ustripexpand

* fix missing export of ustripexpand

* implement suggested changes

* define ustripexpand for UnionAbstractQuantity

* docs: improve docstring

* docs: clean up

* style: sort exports

* test: tweak tests

Author: MilesCranmer

docs/src/symbolic_units.md

@@ -24,6 +24,7 @@ To convert a quantity to its regular base SI units, use `uexpand`:
 
 ```@docs
 uexpand
+ustripexpand
 ```
 
 To convert a quantity in regular base SI units to corresponding symbolic units, use `uconvert`:

src/DynamicQuantities.jl

@@ -8,9 +8,9 @@ export AbstractDimensions, Dimensions, NoDims
 export AbstractSymbolicDimensions, SymbolicDimensions, SymbolicDimensionsSingleton
 export QuantityArray
 export DimensionError
-export ustrip, dimension
+export ustrip, dimension, uexpand, uconvert, ustripexpand
 export ulength, umass, utime, ucurrent, utemperature, uluminosity, uamount
-export uparse, @u_str, sym_uparse, @us_str, uexpand, uconvert, @register_unit
+export uparse, @u_str, sym_uparse, @us_str, @register_unit
 
 # Deprecated:
 export expand_units

src/symbolic_dimensions.jl

@@ -34,7 +34,7 @@ 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`.
+with [`uexpand`](@ref).
 """
 struct SymbolicDimensions{R} <: AbstractSymbolicDimensions{R}
     nzdims::Vector{INDEX_TYPE}
@@ -147,18 +147,23 @@ end
 
 
 """
-    uexpand(q::UnionAbstractQuantity{<:Any,<:AbstractSymbolicDimensions})
+    uexpand(q::UnionAbstractQuantity)
+    uexpand(q::QuantityArray)
 
-Expand the symbolic units in a quantity to their base SI form.
+Expand  the symbolic units in a quantity with symbolic dimensions to their base SI form.
 In other words, this converts a quantity with `AbstractSymbolicDimensions`
 to one with `Dimensions`. The opposite of this function is `uconvert`,
 for converting to specific symbolic units, or, e.g., `convert(Quantity{<:Any,<:AbstractSymbolicDimensions}, q)`,
 for assuming SI units as the output symbols.
+
+For quantities with `Dimensions`, this function just passes through the value `q`.
 """
+uexpand(q::Q) where {T,R,D<:AbstractDimensions{R},Q<:UnionAbstractQuantity{T,D}} = q
+uexpand(q::QuantityArray{T,N,D}) where {T,N,D} = q
 function uexpand(q::Q) where {T,R,D<:AbstractSymbolicDimensions{R},Q<:UnionAbstractQuantity{T,D}}
     return convert(with_type_parameters(Q, T, Dimensions{R}), q)
 end
-uexpand(q::QuantityArray) = uexpand.(q)
+uexpand(q::QuantityArray{T,N,D}) where {T,N,D<:AbstractSymbolicDimensions} = uexpand.(q)
 # TODO: Make the array-based one more efficient
 
 """
@@ -251,6 +256,15 @@ function Base.:(|>)(
     return uconvert(qout, q)
 end
 
+"""
+    ustripexpand(q::AbstractQuantity)
+    ustripexpand(q::QuantityArray)
+
+Return the value of `q` in SI base units. This is equivalent with `ustrip(uexpand(q))`.
+"""
+ustripexpand(q::UnionAbstractQuantity) = ustrip(uexpand(q))
+ustripexpand(q::QuantityArray) = ustrip(uexpand(q))
+
 
 Base.copy(d::SymbolicDimensions) = SymbolicDimensions(copy(nzdims(d)), copy(nzvals(d)))
 Base.copy(d::SymbolicDimensionsSingleton) = constructorof(typeof(d))(getfield(d, :dim))

src/utils.jl

@@ -379,6 +379,10 @@ Base.copy(q::Q) where {Q<:UnionAbstractQuantity} = new_quantity(Q, copy(ustrip(q
     ustrip(q::AbstractGenericQuantity)
 
 Remove the units from a quantity.
+
+!!! note
+
+    If using symbolic dimensions, you might also consider using [`ustripexpand`](@ref) to first convert to SI base units before stripping.
 """
 @inline ustrip(q::UnionAbstractQuantity) = q.value
 ustrip(::AbstractDimensions) = error("Cannot remove units from an `AbstractDimensions` object.")

test/unittests.jl

@@ -855,7 +855,16 @@ end
     @test dimension(inv(us"s") * us"km") == dimension(us"km/s")
     @test dimension(inv(us"s") * us"m") != dimension(us"km/s")
     @test dimension(uexpand(inv(us"s") * us"m")) == dimension(uexpand(us"km/s"))
+    
+    @test ustripexpand(u"h") == 3600.0
+    @test ustripexpand(us"h") == 3600.0
+    # Different behavior than ustrip alone:
+    @test ustrip(us"h") == 1.0
+
+    @test ustripexpand(QuantityArray(fill(1.0,5), u"h")) == fill(3600.0, 5)
+    @test ustripexpand(QuantityArray(fill(1.0,5), us"h")) == fill(3600.0, 5)
 
+    
     f2(i::Int) = us"s"^i
     @inferred f2(5)
     @test uexpand(f2(5)) == u"s"^5