Merge branch 'main' into safe-precompile

Author: MilesCranmer

Project.toml

@@ -1,7 +1,7 @@
 name = "DynamicQuantities"
 uuid = "06fc5a27-2a28-4c7c-a15d-362465fb6821"
 authors = ["MilesCranmer <[email protected]> and contributors"]
-version = "0.7.3"
+version = "0.7.5"
 
 [deps]
 Compat = "34da2185-b29b-5c13-b0c7-acf172513d20"

README.md

@@ -187,10 +187,10 @@ julia> q^2
 ```
 
 You can convert to regular SI base units with
-`expand_units`:
+`uexpand`:
 
 ```julia
-julia> expand_units(q^2)
+julia> uexpand(q^2)
 1.0e6 kg² s⁻⁴
 ```
 
@@ -203,10 +203,16 @@ julia> x = us"Constants.c * Hz"
 julia> x^2
 1.0 Hz² c²
 
-julia> expand_units(x^2)
+julia> uexpand(x^2)
 8.987551787368176e16 m² s⁻⁴
 ```
 
+You can also convert a quantity in regular base SI units to symbolic units with `uconvert`:
+```julia
+julia> uconvert(us"nm", 5e-9u"m") # can also write 5e-9u"m" |> uconvert(us"nm")
+5.0 nm
+```
+
 ### Arrays
 
 For working with an array of quantities that have the same dimensions,

docs/make.jl

@@ -39,6 +39,7 @@ makedocs(;
     ),
     pages=[
         "Home" => "index.md",
+        "Examples" => "examples.md",
         "Utilities" => "api.md",
         "Units" => "units.md",
         "Constants" => "constants.md",

docs/src/examples.md

@@ -0,0 +1,35 @@
+# Toy Examples with Code
+
+## 1. Solving a Chemistry Homework Problem
+
+On your chemistry homework, you are faced with the following problem on the photoelectric effect[^1]:
+
+[^1]: Attribution: [MIT OCW](https://ocw.mit.edu/courses/5-111sc-principles-of-chemical-science-fall-2014/resources/mit5_111f14_lec04soln/)
+
+> In a photoelectric effect experiment, electrons are ejected from a titanium surface (work function ``\Phi = 4.33\mathrm{eV}``) following irradition with UV light.
+> The energy of the incident UV light is ``7.2 \cdot 10^{-19} \mathrm{J}`` per photon. Calculate the wavelength of the ejected electrons, in nanometers.
+
+Let's solve this problem with `DynamicQuantities.jl`!
+```jldoctest examples
+julia> using DynamicQuantities
+
+julia> using DynamicQuantities.Constants: h, m_e
+
+julia> Φ = 4.33u"Constants.eV" # work function
+6.93742482522e-19 m² kg s⁻²
+
+julia> E = 7.2e-19u"J" # incident energy
+7.2e-19 m² kg s⁻²
+
+julia> p = sqrt(2 * m_e * (E - Φ)) # momentum of ejected electrons
+2.1871890716439906e-25 m kg s⁻¹
+
+julia> λ = h / p # wavelength of ejected electrons
+3.029491247878056e-9 m
+
+julia> uconvert(us"nm", λ) # return answer in nanometers
+3.0294912478780556 nm
+```
+Since units are automatically propagated, we can verify the dimension of our answer and all intermediates.
+Also, using `DynamicQuantities.Constants`, we were able to obtain the (dimensionful!) values of all necessary constants without typing them ourselves.
+

docs/src/symbolic_units.md

@@ -14,8 +14,14 @@ units are `sym_uparse` and `us_str`:
 sym_uparse
 ```
 
-To convert a quantity to its regular base SI units, use `expand_units`:
+To convert a quantity to its regular base SI units, use `uexpand`:
 
 ```@docs
-expand_units
+uexpand
+```
+
+To convert a quantity in regular base SI units to corresponding symbolic units, use `uconvert`:
+
+```@docs
+uconvert
 ```

src/DynamicQuantities.jl

@@ -5,7 +5,7 @@ export AbstractQuantity, AbstractDimensions
 export Quantity, Dimensions, SymbolicDimensions, QuantityArray, DimensionError
 export ustrip, dimension
 export ulength, umass, utime, ucurrent, utemperature, uluminosity, uamount
-export uparse, @u_str, sym_uparse, @us_str, expand_units
+export uparse, @u_str, sym_uparse, @us_str, uexpand, uconvert
 
 include("fixed_rational.jl")
 include("types.jl")
@@ -17,6 +17,9 @@ include("constants.jl")
 include("uparse.jl")
 include("symbolic_dimensions.jl")
 
+include("deprecated.jl")
+export expand_units
+
 import PackageExtensionCompat: @require_extensions
 import .Units
 import .Constants

src/deprecated.jl

@@ -0,0 +1 @@
+Base.@deprecate expand_units(q) uexpand(q)

src/symbolic_dimensions.jl

@@ -32,7 +32,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)
-`expand_units`.
+`uexpand`.
 """
 struct SymbolicDimensions{R} <: AbstractDimensions{R}
     nzdims::Vector{INDEX_TYPE}
@@ -94,17 +94,51 @@ function Base.convert(::Type{Quantity{T,D}}, q::Quantity{<:Any,<:SymbolicDimensi
 end
 
 """
-    expand_units(q::Quantity{<:Any,<:SymbolicDimensions})
+    uexpand(q::Quantity{<:Any,<:SymbolicDimensions})
 
 Expand the symbolic units in a quantity to their base SI form.
 In other words, this converts a `Quantity` with `SymbolicDimensions`
-to one with `Dimensions`.
+to one with `Dimensions`. The opposite of this function is `uconvert`,
+for converting to specific symbolic units, or `convert(Quantity{<:Any,<:SymbolicDimensions}, q)`,
+for assuming SI units as the output symbols.
 """
-function expand_units(q::Q) where {T,R,D<:SymbolicDimensions{R},Q<:AbstractQuantity{T,D}}
+function uexpand(q::Q) where {T,R,D<:SymbolicDimensions{R},Q<:AbstractQuantity{T,D}}
     return convert(constructor_of(Q){T,Dimensions{R}}, q)
 end
-expand_units(q::QuantityArray) = expand_units.(q)
+uexpand(q::QuantityArray) = uexpand.(q)
+# TODO: Make the array-based one more efficient
 
+"""
+    uconvert(qout::AbstractQuantity{<:Any, <:SymbolicDimensions}, q::AbstractQuantity{<:Any, <:Dimensions})
+
+Convert a quantity `q` with base SI units to the symbolic units of `qout`, for `q` and `qout` with compatible units.
+Mathematically, the result has value `q / uexpand(qout)` and units `dimension(qout)`. 
+"""
+function uconvert(qout::AbstractQuantity{<:Any, <:SymbolicDimensions}, q::AbstractQuantity{<:Any, <:Dimensions})
+    @assert isone(ustrip(qout)) "You passed a quantity with a non-unit value to uconvert."
+    qout_expanded = uexpand(qout)
+    dimension(q) == dimension(qout_expanded) || throw(DimensionError(q, qout_expanded))
+    new_val = ustrip(q) / ustrip(qout_expanded)
+    new_dim = dimension(qout)
+    return new_quantity(typeof(q), new_val, new_dim)
+end
+function uconvert(qout::AbstractQuantity{<:Any,<:SymbolicDimensions}, q::QuantityArray{<:Any,<:Any,<:Dimensions})
+    @assert isone(ustrip(qout)) "You passed a quantity with a non-unit value to uconvert."
+    qout_expanded = uexpand(qout)
+    dimension(q) == dimension(qout_expanded) || throw(DimensionError(q, qout_expanded))
+    new_array = ustrip(q) ./ ustrip(qout_expanded)
+    new_dim = dimension(qout)
+    return QuantityArray(new_array, new_dim, quantity_type(q))
+end
+# TODO: Method for converting SymbolicDimensions -> SymbolicDimensions
+
+"""
+    uconvert(qout::AbstractQuantity{<:Any, <:SymbolicDimensions})
+
+Create a function that converts an input quantity `q` with base SI units to the symbolic units of `qout`, i.e 
+a function equivalent to `q -> uconvert(qout, q)`.
+"""
+uconvert(qout::AbstractQuantity{<:Any, <:SymbolicDimensions}) = Base.Fix1(uconvert, qout)
 
 Base.copy(d::SymbolicDimensions) = SymbolicDimensions(copy(getfield(d, :nzdims)), copy(getfield(d, :nzvals)))
 function Base.:(==)(l::SymbolicDimensions, r::SymbolicDimensions)

src/units.jl

@@ -52,7 +52,7 @@ end
 @register_unit mol DEFAULT_QUANTITY_TYPE(1.0, amount=1)
 
 @add_prefixes m (f, p, n, μ, u, c, d, m, k, M, G)
-@add_prefixes g (μ, u, m, k)
+@add_prefixes g (p, n, μ, u, m, k)
 @add_prefixes s (f, p, n, μ, u, m)
 @add_prefixes A (n, μ, u, m, k)
 @add_prefixes K (m,)
@@ -64,7 +64,7 @@ end
     m,
 )
 @doc(
-    "Mass in kilograms. Available variants: `μg` (/`ug`), `mg`, `g`.",
+    "Mass in kilograms. Available variants: `pg`, `ng`, `μg` (/`ug`), `mg`, `g`.",
     kg,
 )
 @doc(

test/unittests.jl

@@ -545,19 +545,19 @@ end
     @test q == 1.5 * us"km" / us"s"
     @test typeof(q) <: Quantity{Float64,<:SymbolicDimensions}
     @test string(dimension(q)) == "s⁻¹ km"
-    @test expand_units(q) == 1.5u"km/s"
+    @test uexpand(q) == 1.5u"km/s"
     @test string(dimension(us"Constants.au^1.5")) == "au³ᐟ²"
-    @test string(dimension(expand_units(us"Constants.au^1.5"))) == "m³ᐟ²"
-    @test expand_units(2.3us"Constants.au^1.5") ≈ 2.3u"Constants.au^1.5"
+    @test string(dimension(uexpand(us"Constants.au^1.5"))) == "m³ᐟ²"
+    @test uexpand(2.3us"Constants.au^1.5") ≈ 2.3u"Constants.au^1.5"
     @test iszero(dimension(us"1.0")) == true
-    @test expand_units(inv(us"Constants.au")) ≈ 1/u"Constants.au"
+    @test uexpand(inv(us"Constants.au")) ≈ 1/u"Constants.au"
     @test dimension(inv(us"s") * us"km") == dimension(us"km/s")
     @test dimension(inv(us"s") * us"m") != dimension(us"km/s")
-    @test dimension(expand_units(inv(us"s") * us"m")) == dimension(expand_units(us"km/s"))
+    @test dimension(uexpand(inv(us"s") * us"m")) == dimension(uexpand(us"km/s"))
 
     f2(i::Int) = us"s"^i
     @inferred f2(5)
-    @test expand_units(f2(5)) == u"s"^5
+    @test uexpand(f2(5)) == u"s"^5
 
     @test_throws ErrorException sym_uparse("'c'")
 
@@ -567,7 +567,7 @@ end
     @test dimension(us"h")[:h] == 1
 
     @test us"Constants.h" != us"h"
-    @test expand_units(us"Constants.h") == u"Constants.h"
+    @test uexpand(us"Constants.h") == u"Constants.h"
 
     # Actually expands to:
     @test dimension(us"Constants.h")[:m] == 2
@@ -597,6 +597,50 @@ end
             testing=Val(true)
         )
     )
+
+    # Test deprecated method
+    q = 1.5us"km/s"
+    @test expand_units(q) == uexpand(q)
+end
+
+@testset "uconvert" begin
+    @test uconvert(us"nm", 5e-9u"m") ≈ (5e-9u"m" |> uconvert(us"nm")) ≈ 5us"nm"
+    @test_throws DimensionError uconvert(us"nm * J", 5e-9u"m")
+
+    q = 1.5u"Constants.M_sun"
+    qs = uconvert(us"Constants.M_sun", 5.0 * q)
+    @test qs ≈ 7.5us"Constants.M_sun"
+    @test dimension(qs)[:kg] == 0
+    @test dimension(qs)[:g] == 0
+    @test dimension(qs)[:M_sun] == 1
+    @test uexpand(qs) ≈ 5.0 * q
+
+    # Refuses to convert to non-unit quantities:
+    @test_throws AssertionError uconvert(1.2us"m", 1.0u"m")
+    VERSION >= v"1.8" &&
+        @test_throws "You passed a quantity" uconvert(1.2us"m", 1.0u"m")
+
+    # Different types require converting both arguments:
+    q = convert(Quantity{Float16}, 1.5u"g")
+    qs = uconvert(convert(Quantity{Float16}, us"g"), 5 * q)
+    @test typeof(qs) <: Quantity{Float16,<:SymbolicDimensions{<:Any}}
+    @test qs ≈ 7.5us"g"
+
+    # Arrays
+    x = [1.0, 2.0, 3.0] .* u"kg"
+    xs = x .|> uconvert(us"g")
+    @test typeof(xs) <: Vector{<:Quantity{Float64,<:SymbolicDimensions{<:Any}}}
+    @test xs[2] ≈ 2000us"g"
+
+    x_qa = QuantityArray(x)
+    xs_qa = x_qa .|> uconvert(us"g")
+    @test typeof(xs_qa) <: QuantityArray{Float64,1,<:SymbolicDimensions{<:Any}}
+    @test xs_qa[2] ≈ 2000us"g"
+
+    # Without vectorized call:
+    xs_qa2 = x_qa |> uconvert(us"g")
+    @test typeof(xs_qa2) <: QuantityArray{Float64,1,<:SymbolicDimensions{<:Any}}
+    @test xs_qa2[2] ≈ 2000us"g"
 end
 
 @testset "Test ambiguities" begin
@@ -854,8 +898,8 @@ end
         z_ar = randn(32)
         z = QuantityArray(z_ar, us"Constants.h * km/s")
         z_expanded = QuantityArray(z_ar .* u"Constants.h * km/s")
-        @test typeof(expand_units(z)) == typeof(z_expanded)
-        @test all(expand_units(z) .≈ z_expanded)
+        @test typeof(uexpand(z)) == typeof(z_expanded)
+        @test all(uexpand(z) .≈ z_expanded)
         io = IOBuffer()
         Base.showarg(io, z, true)
         msg = String(take!(io))