Skip to content

About

CODATA fundamental physical constants as typed, dimensioned quantities in pure Standard ML, built on sml-units (MLton + Poly/ML).

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

sml-constants

CI

CODATA fundamental physical constants as typed, dimensioned quantities in pure Standard ML. Every constant is a Units.quantity — a real magnitude in SI base units tagged with its physical dimension — so the relations between constants (hbar = h/(2 pi), R = N_A k, c = 1/sqrt(mu0 eps0)) check out dimensionally as well as numerically, and adding a length to a time is a runtime error rather than silent nonsense.

This library builds on, and vendors, sml-units (see Relationship to sml-units below). No dependencies to fetch, no FFI, no threads, no clock, no randomness: the same inputs always produce the same outputs under MLton and Poly/ML.

  • The seven constants fixed exactly by the 2019 SI redefinition (speedOfLight, planck, elementaryCharge, boltzmann, avogadro, plus the conventional standardGravity) carry their exact defining values.
  • The measured constants (gravitational, electronMass, protonMass, vacuumPermeability, vacuumPermittivity, gasConstant, stefanBoltzmann, fineStructure) use the CODATA 2018 recommended values.
  • Derived helpers: photonEnergy (E = h f), photonMomentum (p = h f / c), deBroglie (lambda = h / m v).

Relationship to sml-units

sml-constants does not reimplement dimensional analysis. It vendors sml-units verbatim under lib/github.com/sjqtentacles/sml-units/ (the copy is byte-for-byte identical to the upstream library, verified with diff -rq) and loads those sources before constants.sml in sources.mlb. Each constant is then defined as a genuine Units.quantity, built compositionally from the sml-units catalogue of named SI units (so the dimensions are computed by sml-units, not asserted by hand). The vendored structure is re-exported as Constants.Units, so callers get the full dimensional-arithmetic API for free.

This is the true integration path described in the build plan (not the real-valued fallback): constants are quantities, dimensions are tracked at runtime, and unit conversions go through Units. CI uses Variant A — the apt Poly/ML builds the vendored sml-units + sml-constants without trouble.

API

structure Constants : sig
  structure Units : UNITS                 (* the vendored dimensional library *)

  (* exact 2019-SI defining constants *)
  val speedOfLight     : Units.quantity   (* c   = 299792458 m/s       *)
  val planck           : Units.quantity   (* h   = 6.62607015e-34 J s  *)
  val elementaryCharge : Units.quantity   (* e   = 1.602176634e-19 C   *)
  val boltzmann        : Units.quantity   (* k   = 1.380649e-23 J/K    *)
  val avogadro         : Units.quantity   (* N_A = 6.02214076e23 /mol  *)

  (* derived / CODATA-2018 measured constants *)
  val reducedPlanck      : Units.quantity (* hbar = h/(2 pi)           *)
  val gravitational      : Units.quantity (* G    = 6.67430e-11        *)
  val electronMass       : Units.quantity
  val protonMass         : Units.quantity
  val vacuumPermeability : Units.quantity (* mu_0                      *)
  val vacuumPermittivity : Units.quantity (* eps_0                     *)
  val gasConstant        : Units.quantity (* R = N_A k                 *)
  val stefanBoltzmann    : Units.quantity
  val fineStructure      : Units.quantity (* alpha (dimensionless)     *)
  val standardGravity    : Units.quantity (* g_0 = 9.80665 m/s^2       *)

  val value          : Units.quantity -> real                      (* SI magnitude   *)
  val valueIn        : Units.quantity * Units.quantity -> real      (* magnitude in u *)
  val photonEnergy   : real -> Units.quantity                       (* E = h f        *)
  val photonMomentum : real -> Units.quantity                       (* p = h f / c    *)
  val deBroglie      : real * real -> Units.quantity                (* h / (m v)      *)
end

Example

val c = Constants.value Constants.speedOfLight       (* 299792458.0 *)
val () = print (Units.Dim.toString (Units.dim Constants.planck))  (* "kg m^2 s^-1" *)

(* derived relations, checked within epsilon *)
val hbar = Constants.value Constants.reducedPlanck
val ok   = Real.abs (hbar - Constants.value Constants.planck / 6.283185307) < 1e~15

(* photon energy of green light *)
val e = Constants.value (Constants.photonEnergy 5.45e14)          (* ~3.61e-19 J *)

Running examples/demo.sml with make example prints:

CODATA fundamental constants (SI base units):
  c   (speed of light)      = 2.99792458E8  m s^-1
  h   (Planck)              = 6.62607015E-34  kg m^2 s^-1
  hbar(reduced Planck)      = 1.05457182E-34  kg m^2 s^-1
  e   (elementary charge)   = 1.60217663E-19  s A
  k   (Boltzmann)           = 1.38064900E-23  kg m^2 s^-2 K^-1
  NA  (Avogadro)            = 6.02214076E23  mol^-1
  G   (gravitational)       = 6.67430000E-11  kg^-1 m^3 s^-2
  R   (molar gas)           = 8.31446262E0  kg m^2 s^-2 K^-1 mol^-1

Derived relations hold:
  h / (2 pi)      = 1.05457182E-34   vs hbar = 1.05457182E-34
  NA * k          = 8.31446262E0   vs R    = 8.31446262E0
  1/sqrt(mu0 eps0)= 2.99792458E8   vs c    = 2.99792458E8

Applications:
  photon energy at 5.45E14 Hz = 3.611208E-19 J
  electron de Broglie wavelength at 1.0e6 m/s = 7.273895E-10 m
  speed of light = 299792.458 km/s

Build & test

Requires MLton and/or Poly/ML.

make test        # build + run the suite under MLton
make test-poly   # run the suite under Poly/ML
make all-tests   # both
make example     # build + run the demo
make clean

Installing with smlpkg

smlpkg add github.com/sjqtentacles/sml-constants
smlpkg sync

Reference lib/github.com/sjqtentacles/sml-constants/constants.mlb from your own .mlb (it pulls in the vendored sml-units first), or feed sources.mlb to tools/polybuild (Poly/ML).

Layout

sml.pkg                                       smlpkg manifest
Makefile                                      MLton + Poly/ML targets
.github/workflows/ci.yml                      CI: MLton + Poly/ML (Variant A)
lib/github.com/sjqtentacles/
  sml-units/                                  VENDORED verbatim from sml-units
    units.sig  units.sml  units.mlb
  sml-constants/
    constants.sig   CONSTANTS signature
    constants.sml   Constants implementation (built on Units)
    sources.mlb     loads ../sml-units/units.mlb, then constants
    constants.mlb   public basis
examples/
  demo.sml       constant tour + derived relations + conversions
test/
  harness.sml    shared assertion harness
  test.sml       exact values, derived relations, dimensions (44 checks)
  entry.sml / main.sml
tools/polybuild  Poly/ML build wrapper

Tests

44 deterministic checks: the five 2019-SI defining constants matched to full Real.== precision; CODATA-2018 measured constants to a tight relative tolerance; the derived relations hbar = h/(2 pi), R = N_A k, and c = 1/sqrt(mu0 eps0) within epsilon; the runtime dimension of every constant (e.g. c : m s^-1, eps_0 : kg^-1 m^-3 s^4 A^2); photonEnergy, photonMomentum, and deBroglie values and dimensions; unit conversions; and dimensional-safety checks (adding mismatched dimensions raises Units.Dimension). Reals are compared with epsilon/relative tolerances and printed with a forced-decimal/--sign formatter, so output is byte-identical under both compilers. Run make all-tests to verify.

License

MIT. See LICENSE.

About

CODATA fundamental physical constants as typed, dimensioned quantities in pure Standard ML, built on sml-units (MLton + Poly/ML).

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages