Data.Dimensions

The units package is a framework for strongly-typed dimensional analysis. This haddock documentation is generally not enough to be able to use this package effectively. Please see the readme at http://www.cis.upenn.edu/~eir/packages/units/README.html.

Some of the types below refer to declarations that are not exported and not documented here. This is because Haddock does not allow finely-tuned abstraction in documentation. (In particular, right-hand sides of type synonym declarations are always included.) If a symbol is not exported, you do not need to know anything about it to use this package.

Though it doesn't appear here, Scalar is an instance of Num, and generally has all the numeric instances that Double has.

Term-level combinators

(.+) :: (d1 @~ d2, Num n) => Dim n d1 -> Dim n d2 -> Dim n d1

Add two compatible dimensioned quantities

(.-) :: (d1 @~ d2, Num n) => Dim n d1 -> Dim n d2 -> Dim n d1

Subtract two compatible dimensioned quantities

(.*) :: Num n => Dim n a -> Dim n b -> Dim n (Normalize (a @+ b))

Multiply two dimensioned quantities

(./) :: Fractional n => Dim n a -> Dim n b -> Dim n (Normalize (a @- b))

Divide two dimensioned quantities

(.^) :: Fractional n => Dim n a -> Sing z -> Dim n (a @* z)

Raise a dimensioned quantity to a power known at compile time

(*.) :: Num n => n -> Dim n a -> Dim n a

Multiply a dimensioned quantity by a scalar

(.<) :: (d1 @~ d2, Ord n) => Dim n d1 -> Dim n d2 -> Bool

Check if one dimensioned quantity is less than a compatible one

(.>) :: (d1 @~ d2, Ord n) => Dim n d1 -> Dim n d2 -> Bool

Check if one dimensioned quantity is greater than a compatible one

(.<=) :: (d1 @~ d2, Ord n) => Dim n d1 -> Dim n d2 -> Bool

Check if one dimensioned quantity is less than or equal to a compatible one

(.>=) :: (d1 @~ d2, Ord n) => Dim n d1 -> Dim n d2 -> Bool

Check if one dimensioned quantity is greater than or equal to a compatible one

dimEq

Arguments

:: (d0 @~ d1, d0 @~ d2, Num n, Ord n)

=> Dim n d0

If the difference between the next two arguments are less than this amount, they are considered equal

-> Dim n d1

-> Dim n d2

-> Bool

Compare two compatible dimensioned quantities for equality

dimNeq

Arguments

:: (d0 @~ d1, d0 @~ d2, Num n, Ord n)

=> Dim n d0

If the difference between the next two arguments are less than this amount, they are considered equal

-> Dim n d1

-> Dim n d2

-> Bool

Compare two compatible dimensioned quantities for inequality

nthRoot :: ((Zero < z) ~ True, Floating n) => Sing z -> Dim n a -> Dim n (a @/ z)

Take the n'th root of a dimensioned quantity, where n is known at compile time

dimSqrt :: Floating n => Dim n a -> Dim n (a @/ Two)

Take the square root of a dimensioned quantity

dimCubeRoot :: Floating n => Dim n a -> Dim n (a @/ Three)

Take the cube root of a dimensioned quantity

unity :: Num n => Dim n `[]`

The number 1, expressed as a unitless dimensioned quantity.

zero :: Num n => Dim n dimspec

The number 0, polymorphic in its dimension. Use of this will often require a type annotation.

dim :: d @~ e => Dim n d -> Dim n e

Dimension-safe cast. See the README for more info.

dimIn :: Unit unit => MkDim (CanonicalUnit unit) -> unit -> Double

Extracts a Double from a dimensioned quantity, expressed in the given unit. For example:

 inMeters :: Length -> Double
 inMeters x = dimIn x Meter

(#) :: Unit unit => MkDim (CanonicalUnit unit) -> unit -> Double

Infix synonym for dimIn

dimOf :: Unit unit => Double -> unit -> MkDim (CanonicalUnit unit)

Creates a dimensioned quantity in the given unit. For example:

 height :: Length
 height = dimOf 2.0 Meter

(%) :: Unit unit => Double -> unit -> MkDim (CanonicalUnit unit)

Infix synonym for dimOf

Type-level unit combinators

data u1 :* u2

Multiply two units to get another unit. For example: type MetersSquared = Meter :* Meter

Constructors

u1 :* u2

Instances

(Unit u1, Unit u2) => Unit (:* u1 u2)

data u1 :/ u2

Divide two units to get another unit

Constructors

u1 :/ u2

Instances

(Unit u1, Unit u2) => Unit (:/ u1 u2)

data unit :^ power

Raise a unit to a power, known at compile time

Constructors

unit :^ (Sing power)

Instances

(Unit unit, SingI Z power) => Unit (:^ unit power)

data prefix :@ unit

Multiply a conversion ratio by some constant. Used for defining prefixes.

Constructors

prefix :@ unit

Instances

(~ Bool (CheckCanonical unit) False, Unit unit, UnitPrefix prefix) => Unit (:@ prefix unit)

class UnitPrefix prefix where

A class for user-defined prefixes

Methods

multiplier :: prefix -> Double

This should return the desired multiplier for the prefix being defined. This function must not inspect its argument.

Instances

UnitPrefix Yocto

UnitPrefix Zepto

UnitPrefix Atto

UnitPrefix Femto

UnitPrefix Pico

UnitPrefix Nano

UnitPrefix Micro

UnitPrefix Milli

UnitPrefix Centi

UnitPrefix Deci

UnitPrefix Yotta

UnitPrefix Zetta

UnitPrefix Exa

UnitPrefix Peta

UnitPrefix Tera

UnitPrefix Giga

UnitPrefix Mega

UnitPrefix Kilo

UnitPrefix Hecto

UnitPrefix Deca

Type-level dimensioned-quantity combinators

type family d1 (%*) d2 :: *

Multiply two dimension types to produce a new one. For example:

 type Velocity = Length %/ Time

type family d1 (%/) d2 :: *

Divide two dimension types to produce a new one

type family d (%^) z :: *

Exponentiate a dimension type to an integer

Creating new units

class Unit unit where

Class of units. Make an instance of this class to define a new unit.

Associated Types

type BaseUnit unit :: *

The base unit of this unit: what this unit is defined in terms of. For units that are not defined in terms of anything else, the base unit should be Canonical.

Methods

conversionRatio :: unit -> Double

The conversion ratio from the base unit to this unit. If left out, a conversion ratio of 1 is assumed.

For example:

 instance Unit Foot where
   type BaseUnit Foot = Meter
   conversionRatio _ = 0.3048

Implementations should never examine their argument!

Instances

Unit Number

Unit Katal

Unit Sievert

Unit Gray

Unit Becquerel

Unit Lux

Unit Lumen

Unit Henry

Unit Tesla

Unit Weber

Unit Siemens

Unit Ohm

Unit Farad

Unit Volt

Unit Coulomb

Unit Watt

Unit Joule

Unit Pascal

Unit Newton

Unit Hertz

Unit Candela

Unit Mole

Unit Kelvin

Unit Ampere

Unit Second

Unit Gram

Unit Meter

(~ Bool (CheckCanonical unit) False, Unit unit, UnitPrefix prefix) => Unit (:@ prefix unit)

(Unit unit, SingI Z power) => Unit (:^ unit power)

(Unit u1, Unit u2) => Unit (:/ u1 u2)

(Unit u1, Unit u2) => Unit (:* u1 u2)

type MkDim unit = Dim Double (DimSpecsOf unit)

Make a dimensioned quantity type capable of storing a value of a given unit. This uses a Double for storage of the value. For example:

 type Length = MkDim Meter

type MkGenDim n unit = Dim n (DimSpecsOf unit)

Make a dimensioned quantity with a custom numerical type.

data Canonical

Dummy type use just to label canonical units. It does not have a Unit instance.

Scalars, the only built-in unit

data Number

The unit for unitless dimensioned quantities

Constructors

Number

Instances

Unit Number

type Scalar = MkDim Number

The type of unitless dimensioned quantities This is an instance of Num, though Haddock doesn't show it.

scalar :: n -> Dim n `[]`

Convert a raw number into a unitless dimensioned quantity

Type-level integers

data Z

The datatype for type-level integers.

Constructors

Zero

S Z

P Z

Instances

Eq Z

SingI Z Zero

SEq Z (KProxy Z)

SDecide Z (KProxy Z)

SingI Z n0 => SingI Z (P n)

SingI Z n0 => SingI Z (S n)

SingKind Z (KProxy Z)

type family Succ z :: Z

Add one to an integer

type family Pred z :: Z

Subtract one from an integer

type family a (#+) b :: Z

Add two integers

type family a (#-) b :: Z

Subtract two integers

type family a (#*) b :: Z

Multiply two integers

type family a (#/) b :: Z

Divide two integers

type family NegZ z :: Z

Negate an integer

Synonyms for small numbers

type One = S Zero

type Two = S One

type Three = S Two

type Four = S Three

type Five = S Four

type MOne = P Zero

type MTwo = P MOne

type MThree = P MTwo

type MFour = P MThree

type MFive = P MFour

Term-level singletons

pZero :: Sing Z Zero

This is the singleton value representing Zero at the term level and at the type level, simultaneously. Used for raising units to powers.

pOne :: Sing Z (S Zero)

pTwo :: Sing Z (S (S Zero))

pThree :: Sing Z (S (S (S Zero)))

pFour :: Sing Z (S (S (S (S Zero))))

pFive :: Sing Z (S (S (S (S (S Zero)))))

pMOne :: Sing Z (P Zero)

pMTwo :: Sing Z (P (P Zero))

pMThree :: Sing Z (P (P (P Zero)))

pMFour :: Sing Z (P (P (P (P Zero))))

pMFive :: Sing Z (P (P (P (P (P Zero)))))

pSucc :: Sing z -> Sing (Succ z)

Add one to a singleton Z.

pPred :: Sing z -> Sing (Pred z)

Subtract one from a singleton Z.