Numeric.Units.Dimensional.Prelude

A KnownVariant is one whose term-level Dimensional values we can represent with an associated data family instance and manipulate with certain functions, not all of which are exported from the package.

Each validly constructed type of kind Variant has a KnownVariant instance.

A dimensional value, either a Quantity or a Unit, parameterized by its Dimension and representation.

A unit of measurement.

A dimensional quantity.

Encodes whether a unit is a metric unit, that is, whether it can be combined with a metric prefix to form a related unit.

Subtracts one Quantity from another.

Multiplication of dimensions corresponds to addition of the base dimensions' exponents.

Multiplies two Quantitys or two Units.

The intimidating type signature captures the similarity between these operations and ensures that composite Units are NonMetric.

Represents a physical dimension in the basis of the 7 SI base dimensions, where the respective dimensions are represented by type variables using the following convention:

• l: Length

• m: Mass

• t: Time

• i: Electric current

• th: Thermodynamic temperature

• n: Amount of substance

• j: Luminous intensity

For the equivalent term-level representation, see Dimension'

Division of dimensions corresponds to subtraction of the base dimensions' exponents.

Divides one Quantity by another or one Unit by another.

The intimidating type signature captures the similarity between these operations and ensures that composite Units are NonMetric.

Powers of dimensions correspond to multiplication of the base dimensions' exponents by the exponent.

We limit ourselves to integer powers of Dimensionals as fractional powers make little physical sense.

Raises a Quantity or Unit to an integer power.

Because the power chosen impacts the Dimension of the result, it is necessary to supply a type-level representation of the exponent in the form of a Proxy to some TypeInt. Convenience values pos1, pos2, neg1, ... are supplied by the Numeric.NumType.DK.Integers module. The most commonly used ones are also reexported by Numeric.Units.Dimensional.Prelude.

The intimidating type signature captures the similarity between these operations and ensures that composite Units are NonMetric.

Roots of dimensions correspond to division of the base dimensions' exponents by the order of the root.

Square root is a special case of NRoot with order 2.

Cube root is a special case of NRoot with order 3.

The reciprocal of a dimension is defined as the result of dividing DOne by it, or of negating each of the base dimensions' exponents.

A physical dimension, encoded as 7 integers, representing a factorization of the dimension into the 7 SI base dimensions. By convention they are stored in the same order as in the Dimension data kind.

Dimensional values inhabit this class, which allows access to a term-level representation of their dimension.

A KnownDimension is one for which we can construct a term-level representation. Each validly constructed type of kind Dimension has a KnownDimension instance.

While KnownDimension is a constraint synonym, the presence of KnownDimension d in a context allows use of dimension :: Proxy d -> Dimension'.

Forms a Quantity by multipliying a number and a unit.

Divides a Quantity by a Unit of the same physical dimension, obtaining the numerical value of the quantity expressed in that unit.

Computes the nth root of a Quantity using **.

The NRoot type family will prevent application of this operator where the result would have a fractional dimension or where n is zero.

Because the root chosen impacts the Dimension of the result, it is necessary to supply a type-level representation of the root in the form of a Proxy to some TypeInt. Convenience values pos1, pos2, neg1, ... are supplied by the Numeric.NumType.DK.Integers module. The most commonly used ones are also reexported by Numeric.Units.Dimensional.Prelude.

Also available in prefix form, see nroot.

Raises a dimensionless quantity to a dimensionless power.

Adds two Quantitys.

Negates the value of a Quantity.

Takes the absolute value of a Quantity.

Takes the sign of a Quantity. The functions abs and signum satisy the law that:

abs x * signum x == x

The sign is either negate _1 (negative), _0 (zero), or _1 (positive).

Forms the reciprocal of a Quantity, which has the reciprocal dimension.

>>> recip $ 47 *~ hertz2.127659574468085e-2 s

Computes the nth root of a Quantity using **.

The NRoot type family will prevent application of this operator where the result would have a fractional dimension or where n is zero.

Because the root chosen impacts the Dimension of the result, it is necessary to supply a type-level representation of the root in the form of a Proxy to some TypeInt. Convenience values pos1, pos2, neg1, ... are supplied by the Numeric.NumType.DK.Integers module. The most commonly used ones are also reexported by Numeric.Units.Dimensional.Prelude.

n must not be zero. Negative roots are defined such that nroot (Proxy :: Proxy (Negate n)) x == nroot (Proxy :: Proxy n) (recip x).

Also available in operator form, see ^/.

Computes the square root of a Quantity using **.

The NRoot type family will prevent application where the supplied quantity does not have a square dimension.

prop> (x :: Area Double) >= _0 ==> sqrt x == nroot pos2 x

Computes the cube root of a Quantity using **.

The NRoot type family will prevent application where the supplied quantity does not have a cubic dimension.

prop> (x :: Volume Double) >= _0 ==> cbrt x == nroot pos3 x

Takes the logarithm of the second argument in the base of the first.

>>> logBase _2 _83.0

The standard two argument arctangent function. Since it interprets its two arguments in comparison with one another, the input may have any dimension.

>>> atan2 _0 _10.0

>>> atan2 _1 _01.5707963267948966

>>> atan2 _0 (negate _1)3.141592653589793

>>> atan2 (negate _1) _0-1.5707963267948966

Applies *~ to all values in a functor.

Applies /~ to all values in a functor.

The sum of all elements in a foldable structure.

>>> sum ([] :: [Mass Double])0.0 kg

>>> sum [12.4 *~ meter, 1 *~ foot]12.7048 m

The arithmetic mean of all elements in a foldable structure.

>>> mean [pi, _7]5.070796326794897

The product of all elements in a foldable structure.

>>> product ([] :: [Dimensionless Double])1.0

>>> product [pi, _4, 0.36 *~ one]4.523893421169302

The length of the foldable data structure as a Dimensionless. This can be useful for purposes of e.g. calculating averages.

>>> dimensionlessLength ["foo", "bar"]2

Returns a list of quantities between given bounds.

prop> n <= 0 ==> nFromTo (x :: Mass Double) (y :: Mass Double) n == [x, y]

prop> (x :: Length Double) <= (y :: Length Double) ==> all (\z -> x <= z && z <= y) (nFromTo x y n)

>>> nFromTo _0 _3 2[0.0,1.0,2.0,3.0]

>>> nFromTo _1 _0 7[1.0,0.875,0.75,0.625,0.5,0.375,0.25,0.125,0.0]

>>> nFromTo _0 _1 (-5)[0.0,1.0]

The type-level dimension of dimensionless values.

The constant for zero is polymorphic, allowing it to express zero Length or Capacitance or Velocity etc, in addition to the Dimensionless value zero.

Twice pi.

For background on tau see https://tauday.com/tau-manifesto (but also feel free to review https://web.archive.org/web/20200926221249/http://www.thepimanifesto.com/).

A polymorphic Unit which can be used in place of the coherent SI base unit of any dimension. This allows polymorphic quantity creation and destruction without exposing the Dimensional constructor.

The unit one has dimension DOne and is the base unit of dimensionless values.

As detailed in 7.10 "Values of quantities expressed simply as numbers: the unit one, symbol 1" of [1], the unit one generally does not appear in expressions. However, for us it is necessary to use one as we would any other unit to perform the "wrapping" of dimensionless values.

Forms a new atomic Unit by specifying its UnitName and its definition as a multiple of another Unit.

Use this variant when the scale factor of the resulting unit is irrational or Approximate. See mkUnitQ for when it is rational and mkUnitZ for when it is an integer.

Note that supplying zero as a definining quantity is invalid, as the library relies upon units forming a group under multiplication.

Supplying negative defining quantities is allowed and handled gracefully, but is discouraged on the grounds that it may be unexpected by other readers.

Forms a new atomic Unit by specifying its UnitName and its definition as a multiple of another Unit.

Use this variant when the scale factor of the resulting unit is rational. See mkUnitZ for when it is an integer and mkUnitR for the general case.

For more information see mkUnitR.

Forms a new atomic Unit by specifying its UnitName and its definition as a multiple of another Unit.

Use this variant when the scale factor of the resulting unit is an integer. See mkUnitQ for when it is rational and mkUnitR for the general case.

For more information see mkUnitR.

Extracts the UnitName of a Unit.

Extracts the exact value of a Unit, expressed in terms of the SI coherent derived unit (see siUnit) of the same Dimension.

Note that the actual value may in some cases be approximate, for example if the unit is defined by experiment.

Discards potentially unwanted type level information about a Unit.

Attempts to convert a Unit which may or may not be Metric to one which is certainly Metric.

Forms the exact version of a Unit.

Shows the value of a Quantity expressed in a specified Unit of the same Dimension.

Uses non-breaking spaces between the value and the unit, and within the unit name.

>>> putStrLn $ showIn watt $ (37 *~ volt) * (4 *~ ampere)148.0 W

Convenient conversion between numerical types while retaining dimensional information.

>>> let x = (37 :: Rational) *~ poundMass>>> changeRep x :: Mass Double16.78291769 kg

Convenient conversion from exactly represented values while retaining dimensional information.

Converts a Unit into a lens from Quantitys to values.

A class for categories. Instances should satisfy the laws

Right identity

f . id = f

Left identity

id . f = f

Associativity

f . (g . h) = (f . g) . h

The least element of a non-empty structure.

This function is non-total and will raise a runtime exception if the structure happens to be empty. A structure that supports random access and maintains its elements in order should provide a specialised implementation to return the minimum in faster than linear time.

Examples

Basic usage:

>>> minimum [1..10]1

>>> minimum []*** Exception: Prelude.minimum: empty list

>>> minimum Nothing*** Exception: minimum: empty structure

WARNING: This function is partial for possibly-empty structures like lists.

The largest element of a non-empty structure.

This function is non-total and will raise a runtime exception if the structure happens to be empty. A structure that supports random access and maintains its elements in order should provide a specialised implementation to return the maximum in faster than linear time.

Examples

Basic usage:

>>> maximum [1..10]10

>>> maximum []*** Exception: Prelude.maximum: empty list

>>> maximum Nothing*** Exception: maximum: empty structure

WARNING: This function is partial for possibly-empty structures like lists.

The Eq class defines equality (==) and inequality (/=). All the basic datatypes exported by the Prelude are instances of Eq, and Eq may be derived for any datatype whose constituents are also instances of Eq.

The Haskell Report defines no laws for Eq. However, instances are encouraged to follow these properties:

Reflexivity

x == x

=

True

Symmetry

x == y

=

y == x

Transitivity

if

x == y && y == z

=

True

, then

x == z

=

True

Extensionality

if

x == y

=

True

and

f

is a function whose return type is an instance of

Eq

, then

f x == f y

=

True

Negation

x /= y

=

not (x == y)

Basic numeric class.

The Haskell Report defines no laws for Num. However, (+) and (*) are customarily expected to define a ring and have the following properties:

Associativity of (+)

(x + y) + z

=

x + (y + z)

Commutativity of (+)

x + y

=

y + x

fromInteger 0 is the additive identity

x + fromInteger 0

=

x

negate gives the additive inverse

x + negate x

=

fromInteger 0

Associativity of (*)

(x * y) * z

=

x * (y * z)

fromInteger 1 is the multiplicative identity

x * fromInteger 1

=

x

and

fromInteger 1 * x

=

x

Distributivity of (*) with respect to (+)

a * (b + c)

=

(a * b) + (a * c)

and

(b + c) * a

=

(b * a) + (c * a)

Coherence with toInteger

if the type also implements

GHC.Real.Integral

, then

fromInteger

is a left inverse for

toInteger

, i.e.

fromInteger (toInteger i) == i

Note that it isn't customarily expected that a type instance of both Num and Ord implement an ordered ring. Indeed, in base only Integer and Rational do.

Fractional numbers, supporting real division.

The Haskell Report defines no laws for Fractional. However, (+) and (*) are customarily expected to define a division ring and have the following properties:

recip gives the multiplicative inverse

x * recip x

=

recip x * x

=

fromInteger 1

Totality of toRational

toRational

is total

Coherence with toRational

if the type also implements

Real

, then

fromRational

is a left inverse for

toRational

, i.e.

fromRational (toRational i) = i

Note that it isn't customarily expected that a type instance of Fractional implement a field. However, all instances in base do.

Trigonometric and hyperbolic functions and related functions.

The Haskell Report defines no laws for Floating. However, (+), (*) and exp are customarily expected to define an exponential field and have the following properties:

• exp (a + b) = exp a * exp b

• exp (fromInteger 0) = fromInteger 1

Real numbers.

The Haskell report defines no laws for Real, however Real instances are customarily expected to adhere to the following law:

Coherence with fromRational

if the type also implements

Fractional

, then

fromRational

is a left inverse for

toRational

, i.e.

fromRational (toRational i) = i

The law does not hold for Float, Double, CFloat, CDouble, etc., because these types contain non-finite values, which cannot be roundtripped through Rational.