Merge tag 'v0.4.0' into abstract-types-2

Author: MilesCranmer

Project.toml

@@ -1,7 +1,7 @@
 name = "DynamicQuantities"
 uuid = "06fc5a27-2a28-4c7c-a15d-362465fb6821"
 authors = ["MilesCranmer <[email protected]> and contributors"]
-version = "0.3.0"
+version = "0.4.0"
 
 [deps]
 Requires = "ae029012-a4dd-5104-9daa-d747884805df"

docs/Project.toml

@@ -1,3 +1,2 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-DynamicQuantities = "06fc5a27-2a28-4c7c-a15d-362465fb6821"

docs/make.jl

@@ -1,4 +1,5 @@
 using DynamicQuantities
+import DynamicQuantities.Units
 using Documenter
 
 DocMeta.setdocmeta!(DynamicQuantities, :DocTestSetup, :(using DynamicQuantities); recursive=true)
@@ -26,7 +27,7 @@ open(dirname(@__FILE__) * "/src/index.md", "w") do io
 end
 
 makedocs(;
-    modules=[DynamicQuantities],
+    modules=[DynamicQuantities, DynamicQuantities.Units],
     authors="MilesCranmer <[email protected]> and contributors",
     repo="https://github.com/SymbolicML/DynamicQuantities.jl/blob/{commit}{path}#{line}",
     sitename="DynamicQuantities.jl",

docs/src/api.md

@@ -1,15 +1,91 @@
-```@meta
-CurrentModule = DynamicQuantities
+# Usage
+
+## Types
+
+```@docs
+Quantity
+Dimensions
+```
+
+## Utilities
+
+The two main general utilities for working
+with quantities are `ustrip` and `dimension`:
+
+```@docs
+ustrip
+dimension
 ```
 
-# API Reference
+### Accessing dimensions
 
-API Reference for [DynamicQuantities](https://github.com/SymbolicML/DynamicQuantities.jl).
+Utility functions to extract specific dimensions are as follows:
 
-```@index
+```@docs
+ulength
+umass
+utime
+ucurrent
+utemperature
+uluminosity
+uamount
 ```
 
 ```@autodocs
 Modules = [DynamicQuantities]
-Order   = [:type, :function]
-```
+Pages   = ["utils.jl"]
+Filter  = t -> !(t in [ustrip, dimension, ulength, umass, utime, ucurrent, utemperature, uluminosity, uamount])
+```
+
+## Units
+
+The two main functions for working with units are `uparse` and `u_str`:
+
+```@docs
+@u_str
+uparse
+```
+
+### Available units
+
+The base SI units are as follows.
+Instead of calling directly, it is recommended to access them via
+the `@u_str` macro, which evaluates the expression
+in a namespace with all the units available.
+
+```@docs
+Units.m
+Units.g
+Units.s
+Units.A
+Units.K
+Units.cd
+Units.mol
+```
+
+Several derived SI units are available as well:
+
+```@docs
+Units.Hz
+Units.N
+Units.Pa
+Units.J
+Units.W
+Units.C
+Units.V
+Units.F
+Units.Ω
+Units.T
+Units.L
+Units.bar
+```
+
+## Internals
+
+### FixedRational
+
+```@docs
+DynamicQuantities.FixedRational
+DynamicQuantities.denom
+```
+

ext/DynamicQuantitiesUnitfulExt.jl

@@ -13,7 +13,12 @@ end
 # This lets the user override the preferred units:
 function unitful_equivalences()
     si_units = (length=u"m", mass=u"kg", time=u"s", current=u"A", temperature=u"K", luminosity=u"cd", amount=u"mol")
-    return NamedTuple((k => Unitful.upreferred(si_units[k]) for k in keys(si_units)))
+    for k in keys(si_units)
+        if Unitful.upreferred(si_units[k]) !== si_units[k]
+            error("Found custom `Unitful.preferunits`. This is not supported when interfacing Unitful and DynamicQuantities: you must leave the default `Unitful.upreferred`, which is the SI base units.")
+        end
+    end
+    return NamedTuple((k => si_units[k] for k in keys(si_units)))
 end
 
 Base.convert(::Type{Unitful.Quantity}, x::DynamicQuantities.Quantity) =

src/fixed_rational.jl

@@ -4,6 +4,11 @@
 A rational number with a fixed denominator. Significantly
 faster than `Rational{T}`, as it never needs to compute
 the `gcd` apart from when printing.
+Access the denominator with `denom(F)` (which converts to `T`).
+
+# Fields
+
+- `num`: numerator of type `T`. The denominator is fixed to the type parameter `den`.
 """
 struct FixedRational{T<:Integer,den} <: Real
     num::T
@@ -44,9 +49,9 @@ Base.convert(::Type{Rational}, x::F) where {F<:FixedRational} = Rational{eltype(
 Base.convert(::Type{AF}, x::F) where {AF<:AbstractFloat,F<:FixedRational} = convert(AF, x.num) / convert(AF, denom(F))
 Base.round(::Type{T}, x::F) where {T,F<:FixedRational} = div(convert(T, x.num), convert(T, denom(F)), RoundNearest)
 Base.promote(x::Integer, y::F) where {F<:FixedRational} = (F(x), y)
-Base.promote(x::F, y::Integer) where {F<:FixedRational} = (x, F(y))
+Base.promote(x::F, y::Integer) where {F<:FixedRational} = reverse(promote(y, x))
 Base.promote(x, y::F) where {F<:FixedRational} = promote(x, convert(Rational, y))
-Base.promote(x::F, y) where {F<:FixedRational} = promote(convert(Rational, x), y)
+Base.promote(x::F, y) where {F<:FixedRational} = reverse(promote(y, x))
 Base.show(io::IO, x::F) where {F<:FixedRational} = show(io, convert(Rational, x))
 Base.zero(::Type{F}) where {F<:FixedRational} = unsafe_fixed_rational(0, eltype(F), val_denom(F))
 

src/types.jl

@@ -11,11 +11,13 @@ constructor_of(::Type{Q}) where {T,Q<:AbstractQuantity{T}} = Q.body.name.wrapper
 constructor_of(::Type{Q}) where {T,R,Q<:AbstractQuantity{T,R}} = Q.name.wrapper
 
 """
-    Dimensions
+    Dimensions{R}
 
 A type representing the dimensions of a quantity, with each
 field giving the power of the corresponding dimension. For
 example, the dimensions of velocity are `Dimensions(length=1, time=-1)`.
+Each of the 7 dimensions are stored using the type `R`,
+which is by default a rational number.
 
 # Fields
 
@@ -26,6 +28,15 @@ example, the dimensions of velocity are `Dimensions(length=1, time=-1)`.
 - `temperature`: temperature dimension (i.e., K^(temperature))
 - `luminosity`: luminosity dimension (i.e., cd^(luminosity))
 - `amount`: amount dimension (i.e., mol^(amount))
+
+# Constructors
+
+- `Dimensions(args...)`: Pass all the dimensions as arguments. `R` is set to `DEFAULT_DIM_TYPE`.
+- `Dimensions(; kws...)`: Pass a subset of dimensions as keyword arguments. `R` is set to `DEFAULT_DIM_TYPE`.
+- `Dimensions(::Type{R}; kws...)` or `Dimensions{R}(; kws...)`: Pass a subset of dimensions as keyword arguments, with the output type set to `Dimensions{R}`.
+- `Dimensions{R}(args...)`: Pass all the dimensions as arguments, with the output type set to `Dimensions{R}`.
+- `Dimensions{R}(d::Dimensions)`: Copy the dimensions from another `Dimensions` object, with the output type set to `Dimensions{R}`.
+
 """
 struct Dimensions{R<:Real} <: AbstractDimensions{R}
     length::R
@@ -46,22 +57,31 @@ end
 
 
 """
-    Quantity{T}
+    Quantity{T,R}
 
-Physical quantity with value `value` of type `T` and dimensions `dimensions`.
+Physical quantity with value `value` of type `T` and dimensions `dimensions` of type `Dimensions{R}`.
 For example, the velocity of an object with mass 1 kg and velocity
 2 m/s is `Quantity(2, mass=1, length=1, time=-1)`.
 You should access these fields with `ustrip(q)`, and `dimensions(q)`.
 You can access specific dimensions with `ulength(q)`, `umass(q)`, `utime(q)`,
 `ucurrent(q)`, `utemperature(q)`, `uluminosity(q)`, and `uamount(q)`.
 
 Severals operators in `Base` are extended to work with `Quantity` objects,
-including `*`, `+`, `-`, `/`, `^`, `sqrt`, and `cbrt`.
+including `*`, `+`, `-`, `/`, `abs`, `^`, `sqrt`, and `cbrt`, which manipulate
+dimensions according to the operation.
 
 # Fields
 
-- `value::T`: value of the quantity of some type `T`
-- `dimensions::Dimensions`: dimensions of the quantity
+- `value::T`: value of the quantity of some type `T`. Access with `ustrip(::Quantity)`
+- `dimensions::Dimensions{R}`: dimensions of the quantity with dimension type `R`. Access with `dimension(::Quantity)`
+
+# Constructors
+
+- `Quantity(x; kws...)`: Construct a quantity with value `x` and dimensions given by the keyword arguments. The value type is inferred from `x`. `R` is set to `DEFAULT_DIM_TYPE`.
+- `Quantity(x, ::Type{R}; kws...)`: Construct a quantity with value `x`. The dimensions parametric type is set to `R`.
+- `Quantity(x, d::Dimensions{R})`: Construct a quantity with value `x` and dimensions `d`.
+- `Quantity{T}(q::Quantity)`: Construct a quantity with value `q.value` and dimensions `q.dimensions`, but with value type converted to `T`.
+- `Quantity{T,R}(q::Quantity)`: Construct a quantity with value `q.value` and dimensions `q.dimensions`, but with value type converted to `T` and dimensions parametric type set to `R`.
 """
 struct Quantity{T,R} <: AbstractQuantity{T,R}
     value::T

src/units.jl

@@ -1,5 +1,7 @@
 module Units
 
+export uparse, @u_str
+
 import ..DEFAULT_DIM_TYPE
 import ..DEFAULT_VALUE_TYPE
 import ..Quantity
@@ -27,12 +29,19 @@ function _add_prefixes(base_unit::Symbol, prefixes)
 end
 
 # SI base units
+"Length in meters. Available variants: `fm`, `pm`, `nm`, `μm` (/`um`), `cm`, `dm`, `mm`, `km`, `Mm`, `Gm`."
 const m = Quantity(1.0, length=1)
+"Mass in grams. Available variants: `μg` (/`ug`), `mg`, `kg`."
 const g = Quantity(1e-3, mass=1)
+"Time in seconds. Available variants: `fs`, `ps`, `ns`, `μs` (/`us`), `ms`, `min`, `h` (/`hr`), `day`, `yr`, `kyr`, `Myr`, `Gyr`."
 const s = Quantity(1.0, time=1)
+"Current in Amperes. Available variants: `nA`, `μA` (/`uA`), `mA`, `kA`."
 const A = Quantity(1.0, current=1)
+"Temperature in Kelvin. Available variant: `mK`."
 const K = Quantity(1.0, temperature=1)
+"Luminosity in candela. Available variant: `mcd`."
 const cd = Quantity(1.0, luminosity=1)
+"Amount in moles. Available variant: `mmol`."
 const mol = Quantity(1.0, amount=1)
 
 @add_prefixes m (f, p, n, μ, u, c, d, m, k, M, G)
@@ -44,15 +53,26 @@ const mol = Quantity(1.0, amount=1)
 @add_prefixes mol (m,)
 
 # SI derived units
+"Frequency in Hertz. Available variants: `kHz`, `MHz`, `GHz`."
 const Hz = inv(s)
+"Force in Newtons."
 const N = kg * m / s^2
+"Pressure in Pascals. Available variant: `kPa`."
 const Pa = N / m^2
+"Energy in Joules. Available variant: `kJ`."
 const J = N * m
+"Power in Watts. Available variants: `kW`, `MW`, `GW`."
 const W = J / s
+"Charge in Coulombs."
 const C = A * s
+"Voltage in Volts. Available variants: `kV`, `MV`, `GV`."
 const V = W / A
+"Capacitance in Farads."
 const F = C / V
+"Resistance in Ohms. Available variant: `mΩ`. Also available is ASCII `ohm` (with variant `mohm`)."
 const Ω = V / A
+const ohm = Ω
+"Magnetic flux density in Teslas."
 const T = N / (A * m)
 
 @add_prefixes Hz (k, M, G)
@@ -64,6 +84,7 @@ const T = N / (A * m)
 @add_prefixes V (m, k, M, G)
 @add_prefixes F ()
 @add_prefixes Ω (m,)
+@add_prefixes ohm (m,)
 @add_prefixes T ()
 
 # Common assorted units
@@ -81,11 +102,13 @@ const yr = 365.25 * day
 @add_prefixes yr (k, M, G)
 
 ## Volume
+"Volume in liters. Available variants: `mL`, `dL`."
 const L = dm^3
 
 @add_prefixes L (m, d)
 
 ## Pressure
+"Pressure in bars."
 const bar = 100 * kPa
 
 @add_prefixes bar ()
@@ -100,8 +123,8 @@ const bar = 100 * kPa
     uparse(s::AbstractString)
 
 Parse a string containing an expression of units and return the
-corresponding `Quantity` object. For example, `uparse("m/s")`
-would be parsed to `Quantity(1.0, length=1, time=-1)`.
+corresponding `Quantity` object with `Float64` value. For example,
+`uparse("m/s")` would be parsed to `Quantity(1.0, length=1, time=-1)`.
 """
 function uparse(s::AbstractString)
     return as_quantity(eval(Meta.parse(s)))::Quantity{DEFAULT_VALUE_TYPE,DEFAULT_DIM_TYPE}
@@ -112,14 +135,14 @@ as_quantity(x::Number) = Quantity(convert(DEFAULT_VALUE_TYPE, x), DEFAULT_DIM_TY
 as_quantity(x) = error("Unexpected type evaluated: $(typeof(x))")
 
 """
-    @u_str(s::AbstractString)
+    u"[unit expression]"
 
 Parse a string containing an expression of units and return the
-corresponding `Quantity` object. For example, `u"km/s^2"`
-would be parsed to `Quantity(1000.0, length=1, time=-2)`.
+corresponding `Quantity` object with `Float64` value. For example,
+`u"km/s^2"` would be parsed to `Quantity(1000.0, length=1, time=-2)`.
 """
 macro u_str(s)
     return esc(uparse(s))
 end
 
-end
+end

test/test_unitful.jl

@@ -6,18 +6,13 @@ import Ratios: SimpleRatio
 import SaferIntegers: SafeInt16
 using Test
 
-# Try to work with different preferred units:
-Unitful.preferunits(u"km")
-
 risapprox(x::Unitful.Quantity, y::Unitful.Quantity; kws...) =
     let (xfloat, yfloat) = (Unitful.ustrip ∘ Unitful.upreferred).((x, y))
         return isapprox(xfloat, yfloat; kws...)
     end
 
-factor_for_preferred_units = 1e-3
-
 for T in [DEFAULT_VALUE_TYPE, Float16, Float32, Float64], R in [DEFAULT_DIM_TYPE, Rational{Int16}, Rational{Int32}, SimpleRatio{Int}, SimpleRatio{SafeInt16}]
-    x = DynamicQuantities.Quantity(T(0.2*factor_for_preferred_units), R, length=1, amount=2, current=-1 // 2, luminosity=2 // 5)
+    x = DynamicQuantities.Quantity(T(0.2), R, length=1, amount=2, current=-1 // 2, luminosity=2 // 5)
     x_unitful = T(0.2)u"m*mol^2*A^(-1//2)*cd^(2//5)"
 
     @test risapprox(convert(Unitful.Quantity, x), x_unitful; atol=1e-6)