Merge pull request #171 from SymbolicML/MilesCranmer/issue170

Add `ustrip(unit, quantity)`

Author: MilesCranmer

README.md

@@ -163,12 +163,25 @@ julia> ulength(x)
 ```
 
 Finally, you can strip units with `ustrip`:
-    
+
 ```julia
 julia> ustrip(x)
 0.2
 ```
 
+You can also convert a quantity to a desired unit and *then* strip the units
+using a two-argument version of `ustrip`:
+
+```julia
+julia> ustrip(u"km", 1000u"m")
+1.0
+
+julia> ustrip(u"minute", 60u"s")
+1.0
+```
+
+This is equivalent to `ustrip(quantity / unit)` but performs dimension checks first.
+
 ### Constants
 
 There are a variety of physical constants accessible
@@ -298,6 +311,16 @@ julia> freezing = 32ua"degF"
 273.15 K
 ```
 
+These are regular `Quantity{Float64,Dimensions{...}}` objects, meaning that you
+can use them in the same way as regular quantities, including taking differences.
+
+To convert back, you can use the two-argument `ustrip` with the particular affine unit:
+
+```julia
+julia> ustrip(ua"degC", 295.15u"K")
+22.0
+```
+
 ### Arrays
 
 For working with an array of quantities that have the same dimensions,
@@ -439,3 +462,4 @@ julia> @btime f($q8);
 julia> @btime f($q32);
   1.883 μs (4 allocations: 39.12 KiB)
 ```
+

src/affine_dimensions.jl

@@ -114,3 +114,23 @@ function aff_uparse(s::AbstractString)
     ex = AffineUnits.map_to_scope(Meta.parse(s))
     return eval(ex)::AffineUnit{DEFAULT_DIM_BASE_TYPE}
 end
+
+"""
+    ustrip(unit::AffineUnit, q::UnionAbstractQuantity)
+
+Convert a quantity `q` to the numerical value in terms of affine units specified by `unit`,
+then strip the units. This allows getting the numerical value in terms of degrees Celsius or Fahrenheit.
+
+# Examples
+```julia
+julia> ustrip(ua"degC", 27ua"degC")
+27.0
+
+julia> ustrip(ua"degF", 300u"K")
+80.33000000000003
+```
+"""
+function ustrip(unit::AffineUnit, q::UnionAbstractQuantity)
+    unit.basedim == dimension(q) || throw(DimensionError(unit, q))
+    return (ustrip(q) - unit.offset) / unit.scale
+end

src/arrays.jl

@@ -108,6 +108,33 @@ end
     )
 end
 
+@inline function promote_except_value(q1::Q1, q2::QA2) where {
+    T1,D1,T2,D2,Q1<:UnionAbstractQuantity{T1,D1},Q2,
+    QA2<:QuantityArray{T2,N2,D2,Q2} where N2,
+}
+    if D1 == D2 && constructorof(Q1) == constructorof(Q2)
+        return (q1, q2)
+    end
+    Q = promote_type(Q1, Q2)
+    D = promote_type(D1, D2)
+
+    # Create quantity with the properly promoted dimension type
+    q1_converted = convert(with_type_parameters(Q, T1, D), q1)
+    # Create a promoted QuantityArray
+    d2 = convert(with_type_parameters(Q, T2, D), new_quantity(Q, one(T2), dimension(q2)))
+    q2_converted = QuantityArray(ustrip(q2), d2)
+
+    return (q1_converted, q2_converted)
+end
+
+@inline function promote_except_value(q1::QA1, q2::Q2) where {
+    T1,D1,T2,D2,Q1,Q2<:UnionAbstractQuantity{T2,D2},
+    QA1<:QuantityArray{T1,N1,D1,Q1} where N1,
+}
+    q2_converted, q1_converted = promote_except_value(q2, q1)
+    return (q1_converted, q2_converted)
+end
+
 function Base.convert(::Type{QA}, A::QA) where {QA<:QuantityArray}
     return A
 end
@@ -125,6 +152,11 @@ end
 
 @inline ustrip(A::QuantityArray) = A.value
 @inline ustrip(A::AbstractArray{<:UnionAbstractQuantity}) = ustrip.(A)
+@inline function ustrip(unit::UnionAbstractQuantity, q::QuantityArray)
+    unit, q = promote_except_value(unit, q)
+    dimension(unit) == dimension(q) || throw(DimensionError(unit, q))
+    return ustrip(q) ./ ustrip(unit)
+end
 @inline dimension(A::QuantityArray) = A.dimensions
 
 array_type(::Type{<:QuantityArray{T,N,D,Q,V}}) where {T,N,D,Q,V} = V

src/utils.jl

@@ -388,6 +388,32 @@ Remove the units from a quantity.
 ustrip(::AbstractDimensions) = error("Cannot remove units from an `AbstractDimensions` object.")
 @inline ustrip(q) = q
 
+"""
+    ustrip(unit::UnionAbstractQuantity, q::UnionAbstractQuantity)
+
+Convert quantity `q` to the units specified by `unit`, then strip the units.
+This is equivalent to `ustrip(q / unit)`, but also verifies the dimensions are compatible.
+
+# Examples
+```julia
+julia> ustrip(u"km", 1000u"m")
+1.0
+
+julia> ustrip(u"s", 1u"minute")
+60.0
+
+julia> ustrip(u"km", [1000u"m", 2000u"m"])
+2-element Vector{Float64}:
+ 1.0
+ 2.0
+```
+"""
+@inline function ustrip(unit::UnionAbstractQuantity, q::UnionAbstractQuantity)
+    unit, q = promote_except_value(unit, q)
+    dimension(unit) == dimension(q) || throw(DimensionError(unit, q))
+    return ustrip(q) / ustrip(unit)
+end
+
 """
     dimension(q::AbstractQuantity)
     dimension(q::AbstractGenericQuantity)

test/unittests.jl

@@ -1017,6 +1017,41 @@ end
     end
 end
 
+@testset "ustrip with unit conversion" begin
+    # Test Dimension/Dimension conversions
+    # Basic
+    @test ustrip(u"km", 1000u"m") == 1.0
+    @test ustrip(u"mm", 1000u"m") == 1000000.0
+    @test ustrip(u"s", 1u"minute") == 60.0
+    @test ustrip(u"minute", 60u"s") == 1.0
+
+    # Arrays
+    m_qarray = QuantityArray([1000.0, 2000.0], u"m")
+    @test ustrip(u"km", m_qarray) == [1.0, 2.0]
+    @test ustrip(u"mm", m_qarray) == [1000000.0, 2000000.0]
+
+    # Mixed dimensions
+    @test_throws DimensionError ustrip(u"m", u"K")
+    @test_throws DimensionError ustrip(u"K", u"m")
+    @test_throws DimensionError ustrip(u"K", u"m")
+
+    # Test with SymbolicDimensions
+    @test ustrip(u"km", us"m") == 0.001
+    @test ustrip(us"km", u"m") == 0.001
+    @test ustrip(us"mm", u"km") == 1000000.0
+    @test ustrip(us"km", 500us"km") == 500.0
+
+    # But, if no promotion, we still check dimensions symbolically!
+    @test_throws DimensionError ustrip(us"km", us"m")
+    @test_throws DimensionError ustrip(us"km", us"m")
+
+    # SymbolicDimensions arrays
+    m_sym_qarray = QuantityArray([1000us"km", 2000us"km"])
+    @test ustrip(u"m", m_sym_qarray) == [1000000.0, 2000000.0]
+    @test ustrip(us"km", m_sym_qarray) == [1000.0, 2000.0]
+    @test_throws DimensionError ustrip(us"cm", m_sym_qarray)
+end
+
 @testset "Test missing" begin
     x = 1.0u"m"
     @test round(Union{Int32,Missing}, FixedRational{Int32,100}(1)) isa Int32
@@ -2054,6 +2089,15 @@ end
     @test sprint(show, °C) == "°C"
 
     @test sprint(show, °F) == "°F"
+    
+    # Test the two-argument ustrip method with AffineUnit
+    @test ustrip(ua"degC", 273.15u"K") ≈ 0.0
+    @test ustrip(ua"degC", 300.15u"K") ≈ 27.0
+    @test ustrip(ua"degF", 273.15u"K") ≈ 32.0
+    @test ustrip(ua"degF", 300.15u"K") ≈ 80.6
+    @test ustrip(ua"degC", 22ua"degC") ≈ 22.0
+    @test ustrip(ua"degF", 22ua"degC") ≈ 71.6
+    @test_throws DimensionError ustrip(ua"degC", 1.0u"m")
 end
 
 @testset "Test div" begin