Merge tag 'v0.6.0' into weak-floats

[Diff since v0.5.0](v0.5.0...v0.6.0)

**Closed issues:**
- Physical constants (#26)

**Merged pull requests:**
- Create (1) physical constants, and (2) symbolic dimensions object (#32) (@MilesCranmer)

Author: MilesCranmer

.github/workflows/CI.yml

@@ -33,13 +33,15 @@ jobs:
       - uses: julia-actions/cache@v1
       - uses: julia-actions/julia-buildpkg@v1
       - 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
       - name: "Coveralls"
         uses: coverallsapp/github-action@v2
+        if: matrix.version == '1'
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           file: lcov.info

Project.toml

@@ -1,10 +1,11 @@
 name = "DynamicQuantities"
 uuid = "06fc5a27-2a28-4c7c-a15d-362465fb6821"
 authors = ["MilesCranmer <[email protected]> and contributors"]
-version = "0.5.0"
+version = "0.6.0"
 
 [deps]
 Requires = "ae029012-a4dd-5104-9daa-d747884805df"
+SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 Tricks = "410a4b4d-49e4-4fbc-ab6d-cb71b17b3775"
 
 [weakdeps]

docs/make.jl

@@ -41,6 +41,8 @@ makedocs(;
         "Home" => "index.md",
         "Utilities" => "api.md",
         "Units" => "units.md",
+        "Constants" => "constants.md",
+        "Symbolic Units" => "symbolic_units.md",
         "Types" => "types.md",
     ]
 )

docs/src/constants.md

@@ -0,0 +1,46 @@
+
+# Units
+
+Many common physical constants are available as well:
+
+```@docs
+Constants.c
+Constants.h
+Constants.hbar
+Constants.e
+Constants.k_B
+Constants.N_A
+Constants.eV
+Constants.R
+Constants.F
+Constants.sigma_sb
+Constants.alpha
+Constants.u
+Constants.G
+Constants.mu_0
+Constants.eps_0
+Constants.m_e
+Constants.m_p
+Constants.m_n
+Constants.a_0
+Constants.k_e
+Constants.Ryd
+```
+
+## Astronomical constants
+
+```@docs
+Constants.M_earth
+Constants.M_sun
+Constants.M_jup
+Constants.R_earth
+Constants.R_jup
+Constants.R_sun
+Constants.L_sun
+Constants.L_bol0
+Constants.sigma_T
+Constants.au
+Constants.pc
+Constants.ly
+Constants.atm
+```

docs/src/symbolic_units.md

@@ -0,0 +1,21 @@
+# Symbolic Dimensions
+
+Whereas `u"..."` will automatically convert all units to the same
+base SI units, `us"..."` will not. This uses the `SymbolicDimensions`
+type, which is a subtype of `AbstractDimensions` that stores the
+dimensions symbolically. This is useful for keeping track of the
+original units and constants in a user-entered expression.
+
+The two main functions for working with symbolic
+units are `sym_uparse` and `us_str`:
+
+```@docs
+@us_str
+sym_uparse
+```
+
+To convert a quantity to its regular base SI units, use `expand_units`:
+
+```@docs
+expand_units
+```

docs/src/types.md

@@ -15,4 +15,10 @@ AbstractQuantity
 ```
 
 Note also that the `Quantity` object can take a custom `AbstractDimensions`
-as input, so there is often no need to subtype `AbstractQuantity` separately.
+as input, so there is often no need to subtype `AbstractQuantity` separately.
+
+Another type which subtypes `AbstractDimensions` is `SymbolicDimensions`:
+
+```@docs
+SymbolicDimensions
+```

docs/src/units.md

@@ -16,14 +16,16 @@ in a namespace with all the units available.
 
 ```@docs
 Units.m
-Units.g
+Units.kg
 Units.s
 Units.A
 Units.K
 Units.cd
 Units.mol
 ```
 
+### Derived units
+
 Several derived SI units are available as well:
 
 ```@docs
@@ -39,4 +41,4 @@ Units.Ω
 Units.T
 Units.L
 Units.bar
-```
+```

src/DynamicQuantities.jl

@@ -1,9 +1,11 @@
 module DynamicQuantities
 
+export Units, Constants
 export AbstractQuantity, AbstractDimensions
-export Quantity, Dimensions, DimensionError, ustrip, dimension, valid
+export Quantity, Dimensions, SymbolicDimensions, DimensionError
+export ustrip, dimension, valid
 export ulength, umass, utime, ucurrent, utemperature, uluminosity, uamount
-export uparse, @u_str
+export uparse, @u_str, sym_uparse, @us_str, expand_units
 
 include("fixed_rational.jl")
 include("lazy_float.jl")
@@ -12,9 +14,14 @@ include("types.jl")
 include("utils.jl")
 include("math.jl")
 include("units.jl")
+include("constants.jl")
+include("uparse.jl")
+include("symbolic_dimensions.jl")
 
 import Requires: @init, @require
-import .Units: uparse, @u_str, DEFAULT_UNIT_TYPE
+import .Units: DEFAULT_UNIT_TYPE
+import .Constants
+import .UnitsParse: uparse, @u_str
 
 if !isdefined(Base, :get_extension)
     @init @require Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d" include("../ext/DynamicQuantitiesUnitfulExt.jl")

src/constants.jl

@@ -0,0 +1,224 @@
+module Constants
+
+import ..DEFAULT_QUANTITY_TYPE
+import ..Quantity
+import ..Units as U
+import ..Units: _add_prefixes
+
+const _CONSTANT_SYMBOLS = Symbol[]
+const _CONSTANT_VALUES = DEFAULT_QUANTITY_TYPE[]
+
+macro register_constant(name, value)
+    return esc(_register_constant(name, value))
+end
+
+macro add_prefixes(base_unit, prefixes)
+    @assert prefixes.head == :tuple
+    return esc(_add_prefixes(base_unit, prefixes.args, _register_constant))
+end
+
+function _register_constant(name::Symbol, value)
+    s = string(name)
+    return quote
+        const $name = $value
+        push!(_CONSTANT_SYMBOLS, Symbol($s))
+        push!(_CONSTANT_VALUES, $name)
+    end
+end
+
+# Source: http://physics.nist.gov/constants (2018)
+
+# Exact, base:
+@register_constant c 299792458 * U.m/U.s
+@register_constant h 6.62607015e-34 * U.J/U.Hz
+@register_constant hbar h / (2π)
+@register_constant e 1.602176634e-19 * U.C
+@register_constant k_B 1.380649e-23 * U.J/U.K
+@register_constant N_A 6.02214076e+23 / U.mol
+
+@doc(
+    "Speed of light in a vacuum. Standard.",
+    c,
+)
+@doc(
+    "Planck constant. Standard.",
+    h,
+)
+@doc(
+    "Reduced Planck constant (h/2π). Standard.",
+    hbar,
+)
+@doc(
+    "Elementary charge. Standard.",
+    e,
+)
+@doc(
+    "Boltzmann constant. Standard.",
+    k_B,
+)
+@doc(
+    "Avogadro constant. Standard.",
+    N_A,
+)
+
+# Exact, derived:
+@register_constant eV e * U.J/U.C
+@register_constant R N_A * k_B
+@register_constant F N_A * e
+@register_constant sigma_sb (π^2/60) * k_B^4/(hbar^3 * c^2)
+
+@add_prefixes eV (m, k, M, G, T)
+
+@doc(
+    "Electron volt. Standard.",
+    eV,
+)
+@doc(
+    "Molar gas constant. Standard.",
+    R,
+)
+@doc(
+    "Faraday constant. Standard.",
+    F,
+)
+@doc(
+    "Stefan-Boltzmann constant. Standard.",
+    sigma_sb,
+)
+
+# Measured
+@register_constant alpha DEFAULT_QUANTITY_TYPE(7.2973525693e-3)
+@register_constant u 1.66053906660e-27 * U.kg
+@register_constant G 6.67430e-11 * U.m^3 / (U.kg * U.s^2)
+@register_constant mu_0 4π * alpha * hbar / (e^2 * c)
+@register_constant eps_0 8.8541878128e-12 * U.F/U.m
+@register_constant m_e 9.1093837015e-31 * U.kg
+@register_constant m_p 1.67262192369e-27 * U.kg
+@register_constant m_n 1.67492749804e-27 * U.kg
+@register_constant a_0 hbar/(m_e * c * alpha)
+@register_constant k_e 1/(4π * eps_0)
+@register_constant Ryd alpha^2 * m_e * c^2 / (2 * h)
+
+@doc(
+    "Fine-structure constant. Measured.",
+    alpha,
+)
+@doc(
+    "Atomic mass unit (1/12th the mass of Carbon-12). Measured.",
+    u,
+)
+@doc(
+    "Newtonian constant of gravitation. Measured.",
+    G,
+)
+@doc(
+    "Vacuum magnetic permeability. Measured.",
+    mu_0,
+)
+@doc(
+    "Vacuum electric permittivity. Measured.",
+    eps_0,
+)
+@doc(
+    "Electron mass. Measured.",
+    m_e,
+)
+@doc(
+    "Proton mass. Measured.",
+    m_p,
+)
+@doc(
+    "Neutron mass. Measured.",
+    m_n,
+)
+@doc(
+    "Bohr radius. Measured.",
+    a_0,
+)
+@doc(
+    "Coulomb constant (Note: SI units only!). Measured.",
+    k_e,
+)
+@doc(
+    "Rydberg frequency. Measured.",
+    Ryd,
+)
+
+# Astro constants.
+# Source: https://arxiv.org/abs/1510.07674
+
+@register_constant M_earth 5.97216787e+24 * U.kg
+@register_constant M_sun 1.98840987e+30 * U.kg
+@register_constant M_jup 1.8981246e+27 * U.kg
+@register_constant R_earth 6.3781e+6 * U.m
+@register_constant R_jup 7.1492e+7 * U.m
+@register_constant R_sun 6.957e+8 * U.m
+@register_constant L_sun 3.828e+26 * U.W
+@register_constant L_bol0 3.0128e+28 * U.W
+@register_constant sigma_T 6.6524587321e-29 * U.m^2
+@register_constant au 149597870700 * U.m
+@register_constant pc (648000/π) * au
+@register_constant ly c * U.yr
+@register_constant atm 101325 * U.Pa
+
+@add_prefixes pc (k, M, G)
+
+@doc(
+    "Earth mass. Measured.",
+    M_earth,
+)
+@doc(
+    "Solar mass. Measured.",
+    M_sun,
+)
+@doc(
+    "Jupiter mass. Measured.",
+    M_jup,
+)
+@doc(
+    "Nominal Earth equatorial radius. Standard.",
+    R_earth,
+)
+@doc(
+    "Nominal Jupiter equatorial radius. Standard.",
+    R_jup,
+)
+@doc(
+    "Nominal solar radius. Standard.",
+    R_sun,
+)
+@doc(
+    "Nominal solar luminosity. Standard.",
+    L_sun,
+)
+@doc(
+    "Standard luminosity at absolute bolometric magnitude 0. Standard.",
+    L_bol0,
+)
+@doc(
+    "Thomson scattering cross-section. Measured.",
+    sigma_T,
+)
+@doc(
+    "Astronomical unit. Standard.",
+    au,
+)
+@doc(
+    "Parsec. Standard.",
+    pc,
+)
+@doc(
+    "Light year. Standard.",
+    ly,
+)
+@doc(
+    "Standard atmosphere. Standard.",
+    atm,
+)
+
+"""A tuple of all possible constants."""
+const CONSTANT_SYMBOLS = Tuple(_CONSTANT_SYMBOLS)
+const CONSTANT_VALUES = Tuple(_CONSTANT_VALUES)
+const CONSTANT_MAPPING = NamedTuple([s => i for (i, s) in enumerate(CONSTANT_SYMBOLS)])
+
+end