docs menu

Module Ymir_units.Constant

Measured constants.

A constant is a measured value: a published decimal, its standard uncertainty, a unit and a name. Its value and uncertainty are kept exact, so a constant rounds once, from the published decimal, to the dtype a program asks for: a float32 program gets G with no detour through float64.

ocaml

let g = Codata.newtonian_gravitation Codata.v2022
let gm = Quantity.mul (Constant.quantity Nx.float64 g) mass

#type t

The type for measured constants.

#val v : name:string -> string -> Unit.t -> t

v ~name text u is the constant text in u, named name. text is

["-"] digits ["." digits] ["(" digits ")"] ["e" ["-"] digits]

the parenthesised digits counting units of the mantissa's last digit: "6.67430(15)e-11" is (6.67430 ± 0.00015)·10^-11. Text without parentheses is exact.

Raises Invalid_argument if text is outside this grammar, as in {|Constant.v: "6.67430(15" is not a constant's value|}; if its value is zero or its mantissa, its digits read as one integer, is 2⁶² or more; if its uncertainty is zero, since an exact value has no parentheses, or its digits are 2⁶² or more; or as Unit.decimal does when the value or the uncertainty is past the coefficient's bound, as in "Constant.v: the coefficient's numerator is past 4096 bits". When text breaks several of these, the first in this order is raised: the grammar, the value, the uncertainty, the coefficient's bound.

#val name : t -> string

name k is k's name.

#val unit : t -> Unit.t

unit k is k's unit.

#val quantity : ('a, 'b) Nx.dtype -> t -> ('a, 'b, Nx.host) Nx.t Quantity.t

quantity d k is k's value as a host scalar of d in unit k: its magnitude rounded once to d as Unit.ratio rounds, then its sign. A complex dtype has a zero imaginary part. An integer dtype holds k only if it holds k's magnitude, so -128 is refused in int8, and an unsigned dtype holds no negative constant.

Raises Invalid_argument when d holds no rounding of k's magnitude, for the reasons Unit.ratio gives, its message naming Constant.quantity, k and k's text, as in "Constant.quantity: Newtonian constant of gravitation: 6.67430(15)e-11 is 0 in float8_e4m3fn" and "Constant.quantity: k: -128 has a magnitude int8 does not hold"; or, for a negative k and an unsigned dtype, before any rounding, as in "Constant.quantity: electron g factor: -2.00231930436092(36) is negative, which uint8 does not hold".

#val uncertainty : ('a, 'b) Nx.dtype -> t -> ('a, 'b, Nx.host) Nx.t Quantity.t

uncertainty d k is k's standard uncertainty, which is never negative, as a scalar of d in unit k: zero for an exact constant, otherwise rounded once as quantity rounds. Raises Invalid_argument as quantity does, its message naming Constant.uncertainty, k and the uncertainty of k's text, as in "Constant.uncertainty: k: the uncertainty of 42.0(5) is not an integer".

#val pp : Stdlib.Format.formatter -> t -> unit

pp ppf k formats k's name, its text and its unit's canonical text, as in Newtonian constant of gravitation = 6.67430(15)e-11 kg^-1 m^3 s^-2. The unit is left out when it is Unit.one, as in fine-structure constant = 7.2973525643(11)e-3.