dimensional-1.0.1.3: Statically checked physical dimensions, using Type Families and Data Kinds.

Copyright | Copyright (C) 2006-2015 Bjorn Buckwalter
License | BSD3
Maintainer | bjorn@buckwalter.se
Stability | Stable
Portability | GHC only
Safe Haskell | None
Language | Haskell2010

Extensions

- Cpp
- MonoLocalBinds
- ScopedTypeVariables
- TypeFamilies
- DataKinds
- StandaloneDeriving
- DeriveDataTypeable
- AutoDeriveTypeable
- DeriveGeneric
- TypeSynonymInstances
- FlexibleContexts
- FlexibleInstances
- ConstrainedClassMethods
- MultiParamTypeClasses
- KindSignatures
- RoleAnnotations
- GeneralizedNewtypeDeriving
- RankNTypes
- TypeOperators
- ExplicitNamespaces
- ExplicitForAll

Numeric.Units.Dimensional

Contents

- Types
- Physical Dimensions
  - Dimension Arithmetic
  - Term Level Representation of Dimensions
- Dimensional Arithmetic
  - Transcendental Functions
  - Operations on Collections
- Dimension Synonyms
- Quantity Synonyms
- Constants
- Constructing Units
- Unit Metadata
- Pretty Printing
- On `Functor`, and Conversion Between Number Representations

Description

# Summary

In this module we provide data types for performing arithmetic with physical quantities and units. Information about the physical dimensions of the quantities/units is embedded in their types and the validity of operations is verified by the type checker at compile time. The boxing and unboxing of numerical values as quantities is done by multiplication and division of units, of which an incomplete set is provided.

We limit ourselves to "Newtonian" physics. We do not attempt to accommodate relativistic physics in which e.g. addition of length and time would be valid.

As far as possible and/or practical the conventions and guidelines of NIST's "Guide for the Use of the International System of Units (SI)" [1] are followed. Occasionally we will reference specific sections from the guide and deviations will be explained.

## Disclaimer

Merely an engineer, the author doubtlessly uses a language and notation that makes mathematicians and physicist cringe. He does not mind constructive criticism (or pull requests).

The sets of functions and units defined herein are incomplete and reflect only the author's needs to date. Again, patches are welcome.

# Usage

## Preliminaries

This module requires GHC 7.8 or later. We utilize Data Kinds, TypeNats, Closed Type Families, etc. Clients of the module are generally not required to use these extensions.

Clients probably will want to use the NegativeLiterals extension.

## Examples

We have defined operators and units that allow us to define and work with physical quantities. A physical quantity is defined by multiplying a number with a unit (the type signature is optional).

    v :: Velocity Prelude.Double
    v = 90 *~ (kilo meter / hour)

It follows naturally that the numerical value of a quantity is obtained by division by a unit.

    numval :: Prelude.Double
    numval = v /~ (meter / second)

The notion of a quantity as the product of a numerical value and a unit is supported by 7.1 "Value and numerical value of a quantity" of [1]. While the above syntax is fairly natural it is unfortunate that it must violate a number of the guidelines in [1], in particular 9.3 "Spelling unit names with prefixes", 9.4 "Spelling unit names obtained by multiplication", 9.5 "Spelling unit names obtained by division".

As a more elaborate example of how to use the module we define a function for calculating the escape velocity of a celestial body [2].

    escapeVelocity :: (Floating a) => Mass a -> Length a -> Velocity a
    escapeVelocity m r = sqrt (two * g * m / r)
      where
          two = 2 *~ one
          g = 6.6720e-11 *~ (newton * meter ^ pos2 / kilo gram ^ pos2)

The following is an example GHC session where the above function is used to calculate the escape velocity of Earth in kilometer per second.

    >>> :set +t
    >>> let me = 5.9742e24 *~ kilo gram -- Mass of Earth.
    me :: Quantity DMass GHC.Float.Double
    >>> let re = 6372.792 *~ kilo meter -- Mean radius of Earth.
    re :: Quantity DLength GHC.Float.Double
    >>> let ve = escapeVelocity me re   -- Escape velocity of Earth.
    ve :: Velocity GHC.Float.Double
    >>> ve /~ (kilo meter / second)
    11.184537332296259
    it :: GHC.Float.Double

For completeness we should also show an example of the error messages we will get from GHC when performing invalid arithmetic. In the best case GHC will be able to use the type synonyms we have defined in its error messages.

    >>> x = 1 *~ meter + 1 *~ second
    Couldn't match type 'Numeric.NumType.DK.Integers.Zero
                   with 'Numeric.NumType.DK.Integers.Pos1
      Expected type: Unit 'Metric DLength a
        Actual type: Unit 'Metric DTime a
      In the second argument of `(*~)', namely `second'
      In the second argument of `(+)', namely `1 *~ second'

In other cases the error messages aren't very friendly.

    >>> x = 1 *~ meter / (1 *~ second) + 1 *~ kilo gram
    Couldn't match type 'Numeric.NumType.DK.Integers.Zero
                   with 'Numeric.NumType.DK.Integers.Neg1
      Expected type: Quantity DMass a
        Actual type: Dimensional
                       ('Numeric.Units.Dimensional.Variants.DQuantity
                        Numeric.Units.Dimensional.Variants.* 'Numeric.Units.Dimensional.Variants.DQuantity)
                       (DLength / DTime)
                       a
      In the first argument of `(+)', namely `1 *~ meter / (1 *~ second)'
      In the expression: 1 *~ meter / (1 *~ second) + 1 *~ kilo gram
      In an equation for `x':
          x = 1 *~ meter / (1 *~ second) + 1 *~ kilo gram

It is the author's experience that the usefullness of the compiler error messages is more often than not limited to pinpointing the location of errors.

# Notes

## Future work

While there is an insane amount of units in use around the world it is reasonable to provide at least all SI units. Units outside of SI will most likely be added on an as-needed basis.

There are also plenty of elementary functions to add. The `Floating` class can be used as reference.

Additional physics models could be implemented. See [3] for ideas.

## Related work

Henning Thielemann numeric prelude has a physical units library, however, checking of dimensions is dynamic rather than static. Aaron Denney has created a toy example of statically checked physical dimensions covering only length and time. HaskellWiki has pointers [4] to these.

Also see Samuel Hoffstaetter's blog post [5] which uses techniques similar to this library.

Libraries with similar functionality exist for other programming languages and may serve as inspiration. The author has found the Java library JScience [6] and the Fortress programming language [7] particularly noteworthy.

## References

1. http://physics.nist.gov/Pubs/SP811/
2. http://en.wikipedia.org/wiki/Escape_velocity
3. http://jscience.org/api/org/jscience/physics/models/package-summary.html
4. http://www.haskell.org/haskellwiki/Physical_units
5. http://liftm.wordpress.com/2007/06/03/scientificdimension-type-arithmetic-and-physical-units-in-haskell/
6. http://jscience.org/
7. http://research.sun.com/projects/plrg/fortress.pdf

Synopsis

- type Unit m = Dimensional (DUnit m)
- type Quantity = Dimensional DQuantity
- data Metricality
  - = Metric
  - | NonMetric
- data Dimension = Dim TypeInt TypeInt TypeInt TypeInt TypeInt TypeInt TypeInt
- type family (a :: Dimension) * (b :: Dimension) where ...
- type family (a :: Dimension) / (d :: Dimension) where ...
- type family (d :: Dimension) ^ (x :: TypeInt) where ...
- type family Root (d :: Dimension) (x :: TypeInt) where ...
- type Recip d = DOne / d
- data Dimension' = Dim' !Int !Int !Int !Int !Int !Int !Int
- class HasDimension a where
- type KnownDimension d = HasDimension (Proxy d)
- (*~) :: Num a => a -> Unit m d a -> Quantity d a
- (/~) :: Fractional a => Quantity d a -> Unit m d a -> a
- (^) :: (Fractional a, KnownTypeInt i, KnownVariant v, KnownVariant (Weaken v)) => Dimensional v d1 a -> Proxy i -> Dimensional (Weaken v) (d1 ^ i) a
- (^/) :: (KnownTypeInt n, Floating a) => Quantity d a -> Proxy n -> Quantity (Root d n) a
- (**) :: Floating a => Dimensionless a -> Dimensionless a -> Dimensionless a
- (*) :: (KnownVariant v1, KnownVariant v2, KnownVariant (v1 * v2), Num a) => Dimensional v1 d1 a -> Dimensional v2 d2 a -> Dimensional (v1 * v2) (d1 * d2) a
- (/) :: (KnownVariant v1, KnownVariant v2, KnownVariant (v1 * v2), Fractional a) => Dimensional v1 d1 a -> Dimensional v2 d2 a -> Dimensional (v1 * v2) (d1 / d2) a
- (+) :: Num a => Quantity d a -> Quantity d a -> Quantity d a
- (-) :: Num a => Quantity d a -> Quantity d a -> Quantity d a
- negate :: Num a => Quantity d a -> Quantity d a
- abs :: Num a => Quantity d a -> Quantity d a
- nroot :: (KnownTypeInt n, Floating a) => Proxy n -> Quantity d a -> Quantity (Root d n) a
- sqrt :: Floating a => Quantity d a -> Quantity (Root d Pos2) a
- cbrt :: Floating a => Quantity d a -> Quantity (Root d Pos3) a
- exp :: Floating a => Dimensionless a -> Dimensionless a
- log :: Floating a => Dimensionless a -> Dimensionless a
- sin :: Floating a => Dimensionless a -> Dimensionless a
- cos :: Floating a => Dimensionless a -> Dimensionless a
- tan :: Floating a => Dimensionless a -> Dimensionless a
- asin :: Floating a => Dimensionless a -> Dimensionless a
- acos :: Floating a => Dimensionless a -> Dimensionless a
- atan :: Floating a => Dimensionless a -> Dimensionless a
- sinh :: Floating a => Dimensionless a -> Dimensionless a
- cosh :: Floating a => Dimensionless a -> Dimensionless a
- tanh :: Floating a => Dimensionless a -> Dimensionless a
- asinh :: Floating a => Dimensionless a -> Dimensionless a
- acosh :: Floating a => Dimensionless a -> Dimensionless a
- atanh :: Floating a => Dimensionless a -> Dimensionless a
- atan2 :: RealFloat a => Quantity d a -> Quantity d a -> Dimensionless a
- (*~~) :: (Functor f, Num a) => f a -> Unit m d a -> f (Quantity d a)
- (/~~) :: (Functor f, Fractional a) => f (Quantity d a) -> Unit m d a -> f a
- sum :: (Num a, Foldable f) => f (Quantity d a) -> Quantity d a
- mean :: (Fractional a, Foldable f) => f (Quantity d a) -> Quantity d a
- dimensionlessLength :: (Num a, Foldable f) => f (Dimensional v d a) -> Dimensionless a
- nFromTo :: (Fractional a, Integral b) => Quantity d a -> Quantity d a -> b -> [Quantity d a]
- type DOne = Dim Zero Zero Zero Zero Zero Zero Zero
- type DLength = Dim Pos1 Zero Zero Zero Zero Zero Zero
- type DMass = Dim Zero Pos1 Zero Zero Zero Zero Zero
- type DTime = Dim Zero Zero Pos1 Zero Zero Zero Zero
- type DElectricCurrent = Dim Zero Zero Zero Pos1 Zero Zero Zero
- type DThermodynamicTemperature = Dim Zero Zero Zero Zero Pos1 Zero Zero
- type DAmountOfSubstance = Dim Zero Zero Zero Zero Zero Pos1 Zero
- type DLuminousIntensity = Dim Zero Zero Zero Zero Zero Zero Pos1
- type Dimensionless = Quantity DOne
- type Length = Quantity DLength
- type Mass = Quantity DMass
- type Time = Quantity DTime
- type ElectricCurrent = Quantity DElectricCurrent
- type ThermodynamicTemperature = Quantity DThermodynamicTemperature
- type AmountOfSubstance = Quantity DAmountOfSubstance
- type LuminousIntensity = Quantity DLuminousIntensity
- _0 :: Num a => Quantity d a
- _1 :: Num a => Dimensionless a
- _2 :: Num a => Dimensionless a
- _3 :: Num a => Dimensionless a
- _4 :: Num a => Dimensionless a
- _5 :: Num a => Dimensionless a
- _6 :: Num a => Dimensionless a
- _7 :: Num a => Dimensionless a
- _8 :: Num a => Dimensionless a
- _9 :: Num a => Dimensionless a
- pi :: Floating a => Dimensionless a
- tau :: Floating a => Dimensionless a
- siUnit :: forall d a. (KnownDimension d, Num a) => Unit NonMetric d a
- one :: Num a => Unit NonMetric DOne a
- mkUnitR :: Floating a => UnitName m -> ExactPi -> Unit m1 d a -> Unit m d a
- mkUnitQ :: Fractional a => UnitName m -> Rational -> Unit m1 d a -> Unit m d a
- mkUnitZ :: Num a => UnitName m -> Integer -> Unit m1 d a -> Unit m d a
- name :: Unit m d a -> UnitName m
- exactValue :: Unit m d a -> ExactPi
- weaken :: Unit m d a -> Unit NonMetric d a
- strengthen :: Unit m d a -> Maybe (Unit Metric d a)
- exactify :: Unit m d a -> Unit m d ExactPi
- showIn :: (KnownDimension d, Show a, Fractional a) => Unit m d a -> Quantity d a -> String
- class KnownVariant v where
  - data Dimensional v :: Dimension -> * -> *
- changeRep :: (KnownVariant v, Real a, Fractional b) => Dimensional v d a -> Dimensional v d b
- changeRepApproximate :: (KnownVariant v, Floating b) => Dimensional v d ExactPi -> Dimensional v d b

# Types

Our primary objective is to define a data type that can be used to represent (while still differentiating between) units and quantities. There are two reasons for consolidating units and quantities in one data type. The first being to allow code reuse as they are largely subject to the same operations. The second being that it allows reuse of operators (and functions) between the two without resorting to occasionally cumbersome type classes.

The relationship between (the value of) a `Quantity`, its numerical value and its `Unit` is described in 7.1 "Value and numerical value of a quantity" of [1]. In short a `Quantity` is the product of a number and a `Unit`. We define the `*~` operator as a convenient way to declare quantities as such a product.

type Unit m = Dimensional (DUnit m) Source #

A unit of measurement.

type Quantity = Dimensional DQuantity Source #

A dimensional quantity.

data Metricality Source #

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

Constructors

Metric | Capable of receiving a metric prefix.
NonMetric | Incapable of receiving a metric prefix.

Instances

Eq Metricality Source # |
Methods (==) :: Metricality -> Metricality -> Bool # (/=) :: Metricality -> Metricality -> Bool #
Data Metricality Source # |

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Metricality -> c Metricality #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Metricality #

toConstr :: Metricality -> Constr #

dataTypeOf :: Metricality -> DataType #

dataCast1 :: Typeable (* -> *) t => (forall d. Data d => c (t d)) -> Maybe (c Metricality) #

dataCast2 :: Typeable (* -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Metricality) #

gmapT :: (forall b. Data b => b -> b) -> Metricality -> Metricality #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Metricality -> r #

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Metricality -> r #

gmapQ :: (forall d. Data d => d -> u) -> Metricality -> [u] #

gmapQi :: Int -> (forall d. Data d => d -> u) -> Metricality -> u #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Metricality -> m Metricality #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Metricality -> m Metricality #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Metricality -> m Metricality #

Ord Metricality Source # |
Methods compare :: Metricality -> Metricality -> Ordering # (<) :: Metricality -> Metricality -> Bool # (<=) :: Metricality -> Metricality -> Bool # (>) :: Metricality -> Metricality -> Bool # (>=) :: Metricality -> Metricality -> Bool # max :: Metricality -> Metricality -> Metricality # min :: Metricality -> Metricality -> Metricality #
Generic Metricality Source # |
Associated Types type Rep Metricality :: * -> * # Methods from :: Metricality -> Rep Metricality x # to :: Rep Metricality x -> Metricality #
type Rep Metricality Source # |
type Rep Metricality = D1 (MetaData "Metricality" "Numeric.Units.Dimensional.Variants" "dimensional-1.0.1.3-J9LDKppAtjNKDu3TyelN12" False) ((:+:) (C1 (MetaCons "Metric" PrefixI False) U1) (C1 (MetaCons "NonMetric" PrefixI False) U1))

# Physical Dimensions

The phantom type variable d encompasses the physical dimension of a `Dimensional`. As detailed in [5] there are seven base dimensions, which can be combined in integer powers to a given physical dimension. We represent physical dimensions as the powers of the seven base dimensions that make up the given dimension. The powers are represented using NumTypes. For convenience we collect all seven base dimensions in a data kind `Dimension`.

We could have chosen to provide type variables for the seven base dimensions in `Dimensional` instead of creating a new data kind `Dimension`. However, that would have made any type signatures involving `Dimensional` very cumbersome. By encompassing the physical dimension in a single type variable we can "hide" the cumbersome type arithmetic behind convenient type classes as will be seen later.

data Dimension Source #

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'`

Constructors

Dim TypeInt TypeInt TypeInt TypeInt TypeInt TypeInt TypeInt |

Instances

(KnownTypeInt l, KnownTypeInt m, KnownTypeInt t, KnownTypeInt i, KnownTypeInt th, KnownTypeInt n, KnownTypeInt j) => HasDimension (Proxy Dimension (Dim l m t i th n j)) Source # |
Methods dimension :: Proxy Dimension (Dim l m t i th n j) -> Dimension' Source #

## Dimension Arithmetic

When performing arithmetic on units and quantities the arithmetics must be applied to both the numerical values of the Dimensionals but also to their physical dimensions. The type level arithmetic on physical dimensions is governed by closed type families expressed as type operators.

We could provide the `Mul` and `Div` classes with full functional dependencies but that would be of limited utility as there is no limited use for "backwards" type inference. Efforts are underway to develop a type-checker plugin that does enable these scenarios, e.g. for linear algebra.

type family (a :: Dimension) * (b :: Dimension) where ... infixl 7 Source #

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

Equations

DOne * d = d |
d * DOne = d |
(Dim l m t i th n j) * (Dim l' m' t' i' th' n' j') = Dim (l + l') (m + m') (t + t') (i + i') (th + th') (n + n') (j + j') |

type family (a :: Dimension) / (d :: Dimension) where ... infixl 7 Source #

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

Equations

d / DOne = d |
d / d = DOne |
(Dim l m t i th n j) / (Dim l' m' t' i' th' n' j') = Dim (l - l') (m - m') (t - t') (i - i') (th - th') (n - n') (j - j') |

type family (d :: Dimension) ^ (x :: TypeInt) where ... infixr 8 Source #

Powers of dimensions corresponds 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.

Equations

DOne ^ x = DOne |
d ^ Zero = DOne |
d ^ Pos1 = d |
(Dim l m t i th n j) ^ x = Dim (l * x) (m * x) (t * x) (i * x) (th * x) (n * x) (j * x) |

type family Root (d :: Dimension) (x :: TypeInt) where ... Source #

Roots of dimensions corresponds to division of the base dimensions' exponents by the order(?) of the root.

See `sqrt`, `cbrt`, and `nroot` for the corresponding term-level operations.

Equations

Root DOne x = DOne |
Root d Pos1 = d |
Root (Dim l m t i th n j) x = Dim (l / x) (m / x) (t / x) (i / x) (th / x) (n / x) (j / x) |

type Recip d = DOne / d Source #

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

## Term Level Representation of Dimensions

To facilitate parsing and pretty-printing functions that may wish to operate on term-level representations of dimension, we provide a means for converting from type-level dimensions to term-level dimensions.

data Dimension' Source #

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.

Constructors

Dim' !Int !Int !Int !Int !Int !Int !Int |

Instances

Eq Dimension' Source # |
Methods (==) :: Dimension' -> Dimension' -> Bool # (/=) :: Dimension' -> Dimension' -> Bool #
Ord Dimension' Source # |
Methods compare :: Dimension' -> Dimension' -> Ordering # (<) :: Dimension' -> Dimension' -> Bool # (<=) :: Dimension' -> Dimension' -> Bool # (>) :: Dimension' -> Dimension' -> Bool # (>=) :: Dimension' -> Dimension' -> Bool # max :: Dimension' -> Dimension' -> Dimension' # min :: Dimension' -> Dimension' -> Dimension' #
Show Dimension' Source # |
Methods showsPrec :: Int -> Dimension' -> ShowS # show :: Dimension' -> String # showList :: [Dimension'] -> ShowS #
Monoid Dimension' Source # | The monoid of dimensions under multiplication.
Methods mempty :: Dimension' # mappend :: Dimension' -> Dimension' -> Dimension' # mconcat :: [Dimension'] -> Dimension' #
HasDimension Dimension' Source # |
Methods dimension :: Dimension' -> Dimension' Source #

class HasDimension a where Source #

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

Minimal complete definition

dimension

Methods

dimension :: a -> Dimension' Source #

Obtains a term-level representation of a value's dimension.

Instances

HasDimension Dimension' Source # |
Methods dimension :: Dimension' -> Dimension' Source #
HasDimension AnyUnit Source # |
Methods dimension :: AnyUnit -> Dimension' Source #
HasDimension (AnyQuantity v) Source # |
Methods dimension :: AnyQuantity v -> Dimension' Source #
(KnownTypeInt l, KnownTypeInt m, KnownTypeInt t, KnownTypeInt i, KnownTypeInt th, KnownTypeInt n, KnownTypeInt j) => HasDimension (Proxy Dimension (Dim l m t i th n j)) Source # |
Methods dimension :: Proxy Dimension (Dim l m t i th n j) -> Dimension' Source #
KnownDimension d => HasDimension (Dimensional v d a) Source # |
Methods dimension :: Dimensional v d a -> Dimension' Source #

type KnownDimension d = HasDimension (Proxy d) Source #

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'``.

# Dimensional Arithmetic

(*~) :: Num a => a -> Unit m d a -> Quantity d a infixl 7 Source #

Forms a `Quantity` by multipliying a number and a unit.

(/~) :: Fractional a => Quantity d a -> Unit m d a -> a infixl 7 Source #

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

(^) :: (Fractional a, KnownTypeInt i, KnownVariant v, KnownVariant (Weaken v)) => Dimensional v d1 a -> Proxy i -> Dimensional (Weaken v) (d1 ^ i) a infixr 8 Source #

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 `Unit`s are `NotPrefixable`.

(^/) :: (KnownTypeInt n, Floating a) => Quantity d a -> Proxy n -> Quantity (Root d n) a infixr 8 Source #

Computes the nth root of a `Quantity` using `**`.

The `Root` 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`.

(**) :: Floating a => Dimensionless a -> Dimensionless a -> Dimensionless a infixr 8 Source #

Raises a dimensionless quantity to a floating power using `**`.

(*) :: (KnownVariant v1, KnownVariant v2, KnownVariant (v1 * v2), Num a) => Dimensional v1 d1 a -> Dimensional v2 d2 a -> Dimensional (v1 * v2) (d1 * d2) a infixl 7 Source #

Multiplies two `Quantity`s or two `Unit`s.

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

(/) :: (KnownVariant v1, KnownVariant v2, KnownVariant (v1 * v2), Fractional a) => Dimensional v1 d1 a -> Dimensional v2 d2 a -> Dimensional (v1 * v2) (d1 / d2) a infixl 7 Source #

Divides one `Quantity` by another or one `Unit` by another.

The intimidating type signature captures the similarity between these operations and ensures that composite `Unit`s are `NotPrefixable`.

(+) :: Num a => Quantity d a -> Quantity d a -> Quantity d a infixl 6 Source #

Adds two `Quantity`s.

(-) :: Num a => Quantity d a -> Quantity d a -> Quantity d a infixl 6 Source #

Subtracts one `Quantity` from another.

negate :: Num a => Quantity d a -> Quantity d a Source #

Negates the value of a `Quantity`.

abs :: Num a => Quantity d a -> Quantity d a Source #

Takes the absolute value of a `Quantity`.

nroot :: (KnownTypeInt n, Floating a) => Proxy n -> Quantity d a -> Quantity (Root d n) a Source #

Computes the nth root of a `Quantity` using `**`.

The `Root` 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 operator form, see `^/`.

sqrt :: Floating a => Quantity d a -> Quantity (Root d Pos2) a Source #

Computes the square root of a `Quantity` using `**`.

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

    sqrt x == nroot pos2 x

cbrt :: Floating a => Quantity d a -> Quantity (Root d Pos3) a Source #

Computes the cube root of a `Quantity` using `**`.

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

    cbrt x == nroot pos3 x

## Transcendental Functions

exp :: Floating a => Dimensionless a -> Dimensionless a Source #

log :: Floating a => Dimensionless a -> Dimensionless a Source #

sin :: Floating a => Dimensionless a -> Dimensionless a Source #

cos :: Floating a => Dimensionless a -> Dimensionless a Source #

tan :: Floating a => Dimensionless a -> Dimensionless a Source #

asin :: Floating a => Dimensionless a -> Dimensionless a Source #

acos :: Floating a => Dimensionless a -> Dimensionless a Source #

atan :: Floating a => Dimensionless a -> Dimensionless a Source #

sinh :: Floating a => Dimensionless a -> Dimensionless a Source #

cosh :: Floating a => Dimensionless a -> Dimensionless a Source #

tanh :: Floating a => Dimensionless a -> Dimensionless a Source #

asinh :: Floating a => Dimensionless a -> Dimensionless a Source #

acosh :: Floating a => Dimensionless a -> Dimensionless a Source #

atanh :: Floating a => Dimensionless a -> Dimensionless a Source #

atan2 :: RealFloat a => Quantity d a -> Quantity d a -> Dimensionless a Source #

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

## Operations on Collections

Here we define operators and functions to make working with homogenuous lists of dimensionals more convenient.

We define two convenience operators for applying units to all elements of a functor (e.g. a list).

(*~~) :: (Functor f, Num a) => f a -> Unit m d a -> f (Quantity d a) infixl 7 Source #

Applies `*~` to all values in a functor.

(/~~) :: (Functor f, Fractional a) => f (Quantity d a) -> Unit m d a -> f a infixl 7 Source #

Applies `/~` to all values in a functor.

sum :: (Num a, Foldable f) => f (Quantity d a) -> Quantity d a Source #

The sum of all elements in a list.

mean :: (Fractional a, Foldable f) => f (Quantity d a) -> Quantity d a Source #

The arithmetic mean of all elements in a list.

dimensionlessLength :: (Num a, Foldable f) => f (Dimensional v d a) -> Dimensionless a Source #

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

nFromTo Source #

Arguments

:: (Fractional a, Integral b) |
=> Quantity d a | The initial value.
-> Quantity d a | The final value.
-> b | The number of intermediate values. If less than one, no intermediate values will result.
-> [Quantity d a] |

Returns a list of quantities between given bounds.

# Dimension Synonyms

Using our `Dimension` data kind we define some type synonyms for convenience. We start with the base dimensions, others can be found in Numeric.Units.Dimensional.Quantities.

type DOne = Dim Zero Zero Zero Zero Zero Zero Zero Source #

The type-level dimensions of dimensionless values.

type DLength = Dim Pos1 Zero Zero Zero Zero Zero Zero Source #

type DMass = Dim Zero Pos1 Zero Zero Zero Zero Zero Source #

type DTime = Dim Zero Zero Pos1 Zero Zero Zero Zero Source #

type DElectricCurrent = Dim Zero Zero Zero Pos1 Zero Zero Zero Source #

type DThermodynamicTemperature = Dim Zero Zero Zero Zero Pos1 Zero Zero Source #

type DAmountOfSubstance = Dim Zero Zero Zero Zero Zero Pos1 Zero Source #

type DLuminousIntensity = Dim Zero Zero Zero Zero Zero Zero Pos1 Source #

# Quantity Synonyms

Using the above type synonyms we can define type synonyms for quantities of particular physical dimensions.

Again we limit ourselves to the base dimensions, others can be found in Numeric.Units.Dimensional.Quantities.

type Dimensionless = Quantity DOne Source #

type Length = Quantity DLength Source #

type Mass = Quantity DMass Source #

type Time = Quantity DTime Source #

type ElectricCurrent = Quantity DElectricCurrent Source #

type ThermodynamicTemperature = Quantity DThermodynamicTemperature Source #

type AmountOfSubstance = Quantity DAmountOfSubstance Source #

type LuminousIntensity = Quantity DLuminousIntensity Source #

# Constants

For convenience we define some constants for small integer values that often show up in formulae. We also throw in `pi` and `tau` for good measure.

_0 :: Num a => Quantity d a Source #

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

_1 :: Num a => Dimensionless a Source #

_2 :: Num a => Dimensionless a Source #

_3 :: Num a => Dimensionless a Source #

_4 :: Num a => Dimensionless a Source #

_5 :: Num a => Dimensionless a Source #

_6 :: Num a => Dimensionless a Source #

_7 :: Num a => Dimensionless a Source #

_8 :: Num a => Dimensionless a Source #

_9 :: Num a => Dimensionless a Source #

pi :: Floating a => Dimensionless a Source #

tau :: Floating a => Dimensionless a Source #

Twice `pi`.

For background on `tau` see http://tauday.com/tau-manifesto (but also feel free to review http://www.thepimanifesto.com).

# Constructing Units

siUnit :: forall d a. (KnownDimension d, Num a) => Unit NonMetric d a Source #

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.

one :: Num a => Unit NonMetric DOne a Source #

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 "boxing" of dimensionless values.

mkUnitR :: Floating a => UnitName m -> ExactPi -> Unit m1 d a -> Unit m d a Source #

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.

mkUnitQ :: Fractional a => UnitName m -> Rational -> Unit m1 d a -> Unit m d a Source #

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`.

mkUnitZ :: Num a => UnitName m -> Integer -> Unit m1 d a -> Unit m d a Source #

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`.

# Unit Metadata

name :: Unit m d a -> UnitName m Source #

Extracts the `UnitName` of a `Unit`.

exactValue :: Unit m d a -> ExactPi Source #

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.

weaken :: Unit m d a -> Unit NonMetric d a Source #

Discards potentially unwanted type level information about a `Unit`.

strengthen :: Unit m d a -> Maybe (Unit Metric d a) Source #

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

exactify :: Unit m d a -> Unit m d ExactPi Source #

Forms the exact version of a `Unit`.

# Pretty Printing

showIn :: (KnownDimension d, Show a, Fractional a) => Unit m d a -> Quantity d a -> String Source #

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

# On `Functor`, and Conversion Between Number Representations

We intentionally decline to provide a `Functor` instance for `Dimensional` because its use breaks the abstraction of physical dimensions.

If you feel your work requires this instance, it is provided as an orphan in Numeric.Units.Dimensional.Functor.

class KnownVariant v where Source #

A physical quantity or unit.

We call this data type `Dimensional` to capture the notion that the units and quantities it represents have physical dimensions.

The type variable `a` is the only non-phantom type variable and represents the numerical value of a quantity or the scale (w.r.t. SI units) of a unit. For SI units the scale will always be 1. For non-SI units the scale is the ratio of the unit to the SI unit with the same physical dimension.

Since `a` is the only non-phantom type we were able to define `Dimensional` as a newtype, avoiding boxing at runtime.

Minimal complete definition

extractValue, extractName, injectValue, dmap

Associated Types

data Dimensional v :: Dimension -> * -> * Source #

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

Methods

dmap :: (a1 -> a2) -> Dimensional v d a1 -> Dimensional v d a2 Source #

Maps over the underlying representation of a dimensional value. The caller is responsible for ensuring that the supplied function respects the dimensional abstraction. This means that the function must preserve numerical values, or linearly scale them while preserving the origin.

Instances

KnownVariant DQuantity Source # |

Associated Types

data Dimensional (DQuantity :: Variant) (a :: Dimension) b :: * Source #

Methods

extractValue :: Dimensional DQuantity d a -> (a, Maybe ExactPi)

extractName :: Dimensional DQuantity d a -> Maybe (UnitName NonMetric)

injectValue :: Maybe (UnitName NonMetric) -> (a, Maybe ExactPi) -> Dimensional DQuantity d a

dmap :: (a1 -> a2) -> Dimensional DQuantity d a1 -> Dimensional DQuantity d a2 Source #

Typeable Metricality m => KnownVariant (DUnit m) Source # |

Associated Types

data Dimensional (DUnit m :: Variant) (a :: Dimension) b :: * Source #

Methods

extractValue :: Dimensional (DUnit m) d a -> (a, Maybe ExactPi)

extractName :: Dimensional (DUnit m) d a -> Maybe (UnitName NonMetric)

injectValue :: Maybe (UnitName NonMetric) -> (a, Maybe ExactPi) -> Dimensional (DUnit m) d a

dmap :: (a1 -> a2) -> Dimensional (DUnit m) d a1 -> Dimensional (DUnit m) d a2 Source #

changeRep :: (KnownVariant v, Real a, Fractional b) => Dimensional v d a -> Dimensional v d b Source #

Convenient conversion between numerical types while retaining dimensional information.

changeRepApproximate :: (KnownVariant v, Floating b) => Dimensional v d ExactPi -> Dimensional v d b Source #

Convenient conversion from exactly represented values while retaining dimensional information.