Merge tag 'v0.7.4' into weak-floats-2

[Diff since v0.7.3](v0.7.3...v0.7.4)

**Merged pull requests:**
- Add `uconvert` and chemistry example (#48) (@gaurav-arya)
- Add `uconvert` method for `QuantityArray` (#61) (@MilesCranmer)
- Deprecate `expand_units` -> `uexpand` (#62) (@MilesCranmer)

Author: MilesCranmer

.github/workflows/CI.yml

@@ -35,10 +35,10 @@ jobs:
       - name: "Run tests"
         shell: bash
         run: |
-          julia --color=yes --project=. -e 'import Pkg; Pkg.add("Coverage")'
-          julia --color=yes --threads=auto --check-bounds=yes --depwarn=yes --code-coverage=user --project=. -e 'import Pkg; Pkg.test(coverage=true)'
-          DQ_TEST_UPREFERRED=true julia --color=yes --threads=auto --check-bounds=yes --depwarn=yes --code-coverage=user --project=. -e 'import Pkg; Pkg.test(coverage=true)'
-          julia --color=yes --project=. coverage.jl
+          julia --color=yes -e 'import Pkg; Pkg.add("Coverage")'
+          julia --color=yes --threads=auto --check-bounds=yes --depwarn=yes --code-coverage=user -e 'import Coverage; import Pkg; Pkg.activate("."); Pkg.test(coverage=true)'
+          DQ_TEST_UPREFERRED=true julia --color=yes --threads=auto --check-bounds=yes --depwarn=yes --code-coverage=user -e 'import Coverage; import Pkg; Pkg.activate("."); Pkg.test(coverage=true)'
+          julia --color=yes coverage.jl
       - name: "Coveralls"
         uses: coverallsapp/github-action@v2
         if: matrix.version == '1'

Project.toml

@@ -1,31 +1,45 @@
 name = "DynamicQuantities"
 uuid = "06fc5a27-2a28-4c7c-a15d-362465fb6821"
 authors = ["MilesCranmer <miles.cranmer@gmail.com> and contributors"]
-version = "0.6.0"
+version = "0.7.4"
 
 [deps]
-Requires = "ae029012-a4dd-5104-9daa-d747884805df"
-SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+Compat = "34da2185-b29b-5c13-b0c7-acf172513d20"
+PackageExtensionCompat = "65ce6f38-6b18-4e1d-a461-8949797d7930"
 Tricks = "410a4b4d-49e4-4fbc-ab6d-cb71b17b3775"
 
 [weakdeps]
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Measurements = "eff96d63-e80a-5855-80a2-b1b0885c5ab7"
+ScientificTypes = "321657f4-b219-11e9-178b-2701a2544e81"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
 
 [extensions]
+DynamicQuantitiesLinearAlgebraExt = "LinearAlgebra"
+DynamicQuantitiesMeasurementsExt = "Measurements"
+DynamicQuantitiesScientificTypesExt = "ScientificTypes"
 DynamicQuantitiesUnitfulExt = "Unitful"
 
 [compat]
-Requires = "1"
+Compat = "3.42, 4"
+Measurements = "2"
+PackageExtensionCompat = "1.0.2"
+ScientificTypes = "3"
 Tricks = "0.1"
 Unitful = "1"
 julia = "1.6"
 
 [extras]
+Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Measurements = "eff96d63-e80a-5855-80a2-b1b0885c5ab7"
 Ratios = "c84ed2f1-dad5-54f0-aa8e-dbefe2724439"
 SafeTestsets = "1bc83da4-3b8d-516f-aca4-4fe02f6d838f"
 SaferIntegers = "88634af6-177f-5301-88b8-7819386cfa38"
+ScientificTypes = "321657f4-b219-11e9-178b-2701a2544e81"
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
 
 [targets]
-test = ["Test", "Ratios", "SaferIntegers", "SafeTestsets", "Unitful"]
+test = ["Aqua", "LinearAlgebra", "Measurements", "Ratios", "SaferIntegers", "SafeTestsets", "ScientificTypes", "StaticArrays", "Test", "Unitful"]

README.md

@@ -5,15 +5,20 @@
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://symbolicml.org/DynamicQuantities.jl/dev/)
 [![Build Status](https://github.com/SymbolicML/DynamicQuantities.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/SymbolicML/DynamicQuantities.jl/actions/workflows/CI.yml?query=branch%3Amain)
 [![Coverage](https://coveralls.io/repos/github/SymbolicML/DynamicQuantities.jl/badge.svg?branch=main)](https://coveralls.io/github/SymbolicML/DynamicQuantities.jl?branch=main)
+[![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
 
 </div>
 
 DynamicQuantities defines a simple statically-typed `Quantity` type for Julia.
 Physical dimensions are stored as a *value*, as opposed to a parametric type, as in [Unitful.jl](https://github.com/PainterQubits/Unitful.jl).
-This is done to allow for calculations where physical dimensions are not known at compile time.
+This can greatly improve both runtime performance, by avoiding type instabilities, and startup time, as it avoids overspecializing methods.
 
 - [Performance](#performance)
 - [Usage](#usage)
+  - [Constants](#constants)
+  - [Symbolic Units](#symbolic-units)
+  - [Arrays](#arrays)
+  - [Unitful](#unitful)
 - [Types](#types)
 - [Vectors](#vectors)
 
@@ -25,22 +30,22 @@ when the compiler cannot infer dimensions in a function:
 ```julia
 julia> using BenchmarkTools, DynamicQuantities; import Unitful
 
-julia> dyn_uni = 0.2u"m^0.5 * kg * mol^3"
-0.2 m¹ᐟ² kg mol³
+julia> dyn_uni = 0.2u"m/s"
+0.2 m s⁻¹
 
 julia> unitful = convert(Unitful.Quantity, dyn_uni)
-0.2 kg m¹ᐟ² mol³
+0.2 m s⁻¹
 
 julia> f(x, i) = x ^ i * 0.3;
 
 julia> @btime f($dyn_uni, 1);
-  8.759 ns (0 allocations: 0 bytes)
+  2.708 ns (0 allocations: 0 bytes)
 
 julia> @btime f($unitful, 1);
-  30.083 μs (42 allocations: 1.91 KiB)
+  2.597 μs (30 allocations: 1.33 KiB)
 ```
 
-**(Note the μ and n.)**
+**Note the μ and n: this is a 1000x speedup!**
 Here, the DynamicQuantities quantity object allows the compiler to build a function that is type stable,
 while the Unitful quantity object, which stores its dimensions in the type, requires type inference at runtime.
 
@@ -51,10 +56,10 @@ then you can get better speeds with Unitful:
 julia> g(x) = x ^ 2 * 0.3;
 
 julia> @btime g($dyn_uni);
-  10.051 ns (0 allocations: 0 bytes)
+  1.791 ns (0 allocations: 0 bytes)
 
 julia> @btime g($unitful);
-  2.000 ns (0 allocations: 0 bytes)
+  1.500 ns (0 allocations: 0 bytes)
 ```
 
 While both of these are type stable,
@@ -147,16 +152,113 @@ julia> ustrip(x)
 0.2
 ```
 
-### Unitful
+### Constants
+
+There are a variety of physical constants accessible
+via the `Constants` submodule:
+
+```julia
+julia> Constants.c
+2.99792458e8 m s⁻¹
+```
+
+These can also be used inside the `u"..."` macro:
+
+```julia
+julia> u"Constants.c * Hz"
+2.99792458e8 m s⁻²
+```
+
+For the full list, see the [docs](https://symbolicml.org/DynamicQuantities.jl/dev/constants/).
+
+
+### Symbolic Units
+
+You can also choose to not eagerly convert to SI base units,
+instead leaving the units as the user had written them.
+For example:
+
+```julia
+julia> q = 100us"cm * kPa"
+100.0 cm kPa
+
+julia> q^2
+10000.0 cm² kPa²
+```
+
+You can convert to regular SI base units with
+`uexpand`:
+
+```julia
+julia> uexpand(q^2)
+1.0e6 kg² s⁻⁴
+```
+
+This also works with constants:
+
+```julia
+julia> x = us"Constants.c * Hz"
+1.0 Hz c
+
+julia> x^2
+1.0 Hz² c²
+
+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
 
-DynamicQuantities works with quantities that are exclusively
-represented by their SI base units. This gives us type stability
-and greatly improves performance.
+For working with an array of quantities that have the same dimensions,
+you can use a `QuantityArray`:
+
+```julia
+julia> ar = QuantityArray(rand(3), u"m/s")
+3-element QuantityArray(::Vector{Float64}, ::Quantity{Float64, Dimensions{DynamicQuantities.FixedRational{Int32, 25200}}}):
+ 0.2729202669351497 m s⁻¹
+ 0.992546340360901 m s⁻¹
+ 0.16863543422972482 m s⁻¹
+```
 
-However, performing calculations with physical dimensions
-is actually equivalent to working with a standardized unit system.
-Thus, you can use Unitful to parse units,
-and then use the DynamicQuantities->Unitful extension for conversion:
+This `QuantityArray` is a subtype `<:AbstractArray{Quantity{Float64,Dimensions{...}},1}`,
+meaning that indexing a specific element will return a `Quantity`:
+
+```julia
+julia> ar[2]
+0.992546340360901 m s⁻¹
+
+julia> ar[2] *= 2
+1.985092680721802 m s⁻¹
+
+julia> ar[2] += 0.5u"m/s"
+2.485092680721802 m s⁻¹
+```
+
+This also has a custom broadcasting interface which
+allows the compiler to avoid redundant dimension calculations,
+relative to if you had simply used an array of quantities:
+
+```julia
+julia> f(v) = v^2 * 1.5;
+
+julia> @btime $f.(xa) setup=(xa = randn(100000) .* u"km/s");
+  109.500 μs (2 allocations: 3.81 MiB)
+
+julia> @btime $f.(qa) setup=(xa = randn(100000) .* u"km/s"; qa = QuantityArray(xa));
+  50.917 μs (3 allocations: 781.34 KiB)
+```
+
+So we can see the `QuantityArray` version saves on both time and memory.
+
+### Unitful
+
+DynamicQuantities allows you to convert back and forth from Unitful.jl:
 
 ```julia
 julia> using Unitful: Unitful, @u_str; import DynamicQuantities
@@ -180,28 +282,28 @@ true
 ## Types
 
 Both a `Quantity`'s values and dimensions are of arbitrary type.
-By default, dimensions are stored as a `DynamicQuantities.FixedRational{Int32,C}`
-object, which represents a rational number
+By default, dimensions are stored as a `Dimensions{FixedRational{Int32,C}}`
+object, whose exponents are stored as rational numbers
 with a fixed denominator `C`. This is much faster than `Rational`.
 
 ```julia
 julia> typeof(0.5u"kg")
-Quantity{Float64, FixedRational{Int32, 25200}
+Quantity{Float64, Dimensions{FixedRational{Int32, 25200}}}
 ```
 
 You can change the type of the value field by initializing with a value
 explicitly of the desired type.
 
 ```julia
 julia> typeof(Quantity(Float16(0.5), mass=1, length=1))
-Quantity{Float16, FixedRational{Int32, 25200}}
+Quantity{Float16, Dimensions{FixedRational{Int32, 25200}}}
 ```
 
 or by conversion:
 
 ```julia
 julia> typeof(convert(Quantity{Float16}, 0.5u"m/s"))
-Quantity{Float16, DynamicQuantities.FixedRational{Int32, 25200}}
+Quantity{Float16, Dimensions{FixedRational{Int32, 25200}}}
 ```
 
 For many applications, `FixedRational{Int8,6}` will suffice,
@@ -213,9 +315,9 @@ the type you wish to use as the second argument to `Quantity`:
 ```julia
 julia> using DynamicQuantities
 
-julia> R8 = DynamicQuantities.FixedRational{Int8,6};
+julia> R8 = Dimensions{DynamicQuantities.FixedRational{Int8,6}};
 
-julia> R32 = DynamicQuantities.FixedRational{Int32,2^4 * 3^2 * 5^2 * 7};  # Default
+julia> R32 = Dimensions{DynamicQuantities.FixedRational{Int32,2^4 * 3^2 * 5^2 * 7}};  # Default
 
 julia> q8 = [Quantity(randn(), R8, length=rand(-2:2)) for i in 1:1000];
 
@@ -229,30 +331,3 @@ julia> @btime f($q8);
 julia> @btime f($q32);
   8.417 μs (2 allocations: 39.11 KiB)
 ```
-
-## Vectors
-
-There is not a separate class for vectors, but you can create units
-like so:
-
-```julia
-julia> randn(5) .* u"m/s"
-5-element Vector{Quantity{Float64, DynamicQuantities.FixedRational{Int32, 25200}}}:
- 1.1762086954956399 m s⁻¹
- 1.320811324040591 m s⁻¹
- 0.6519033652437799 m s⁻¹
- 0.7424822374423569 m s⁻¹
- 0.33536928068133726 m s⁻¹
-```
-
-Because it is type stable, you can have mixed units in a vector too:
-
-```julia
-julia> v = [Quantity(randn(), mass=rand(0:5), length=rand(0:5)) for _=1:5]
-5-element Vector{Quantity{Float64, DynamicQuantities.FixedRational{Int32, 25200}}}:
- 0.4309293892461158 kg⁵
- 1.415520139801276
- 1.2179414706524276 m³ kg⁴
- -0.18804207255117408 m³ kg⁵
- 0.52123911329638 m³ kg²
-```

benchmark/benchmarks.jl

@@ -3,15 +3,17 @@ using DynamicQuantities
 
 const SUITE = BenchmarkGroup()
 
-SUITE["creation"] = let s = BenchmarkGroup()
+SUITE["Quantity"] = BenchmarkGroup()
+
+SUITE["Quantity"]["creation"] = let s = BenchmarkGroup()
     s["Quantity(x)"] = @benchmarkable Quantity(x) setup = (x = randn()) evals = 1000
     s["Quantity(x, length=y)"] = @benchmarkable Quantity(x, length=y) setup = (x = randn(); y = rand(1:5)) evals = 1000
     s
 end
 
 default() = Quantity(rand(), length=rand(1:5), mass=rand(1:5) // 2)
 
-SUITE["with_numbers"] = let s = BenchmarkGroup()
+SUITE["Quantity"]["with_numbers"] = let s = BenchmarkGroup()
     f1(x, i) = x^i
     s["^int"] = @benchmarkable $f1(x, i) setup = (x = default(); i = rand(1:5)) evals = 1000
     f2(x, y) = x * y
@@ -21,7 +23,7 @@ SUITE["with_numbers"] = let s = BenchmarkGroup()
     s
 end
 
-SUITE["with_self"] = let s = BenchmarkGroup()
+SUITE["Quantity"]["with_self"] = let s = BenchmarkGroup()
     f4(x) = inv(x)
     s["inv"] = @benchmarkable $f4(x) setup = (x = default()) evals = 1000
     f7(x) = ustrip(x)
@@ -31,10 +33,31 @@ SUITE["with_self"] = let s = BenchmarkGroup()
     s
 end
 
-SUITE["with_quantity"] = let s = BenchmarkGroup()
+SUITE["Quantity"]["with_quantity"] = let s = BenchmarkGroup()
     f5(x, y) = x / y
     s["/y"] = @benchmarkable $f5(x, y) setup = (x = default(); y = default()) evals = 1000
     f6(x, y) = x + y
     s["+y"] = @benchmarkable $f6(x, y) setup = (x = default(); y = x + rand() * x) evals = 1000
     s
 end
+
+if @isdefined QuantityArray
+    SUITE["QuantityArray"] = BenchmarkGroup()
+
+    SUITE["QuantityArray"]["broadcasting"] = let s = BenchmarkGroup()
+        N = 10000
+        f9(x) = x^2
+        s["x^2_normal_array"] = @benchmarkable $f9.(arr) setup = (arr = randn($N))
+        s["x^2_quantity_array"] = @benchmarkable $f9.(arr) setup = (arr = QuantityArray(randn($N), u"km/s"))
+        s["x^2_array_of_quantities"] = @benchmarkable $f9.(arr) setup = (arr = randn($N) .* u"km/s")
+        f10(x) = x^4
+        s["x^4_normal_array"] = @benchmarkable $f10.(arr) setup = (arr = randn($N))
+        s["x^4_quantity_array"] = @benchmarkable $f10.(arr) setup = (arr = QuantityArray(randn($N), u"km/s"))
+        s["x^4_array_of_quantities"] = @benchmarkable $f10.(arr) setup = (arr = randn($N) .* u"km/s")
+        f11(x) = x^4 * 0.9 - x * x / 0.3 * x * 0.9 * x
+        s["multi_normal_array"] = @benchmarkable $f11.(arr) setup = (arr = randn($N))
+        s["multi_quantity_array"] = @benchmarkable $f11.(arr) setup = (arr = QuantityArray(randn($N), u"km/s"))
+        s["multi_array_of_quantities"] = @benchmarkable $f11.(arr) setup = (arr = randn($N) .* u"km/s")
+        s
+    end
+end