# dimensional

Statically checked physical dimensions, using Type Families and Data Kinds.

https://github.com/bjornbm/dimensional/

 Version on this page: 1.0.1.3 LTS Haskell 20.23: 1.5 Stackage Nightly 2023-06-04: 1.5 Latest on Hackage: 1.5

See all snapshots `dimensional` appears in

Maintained by
This version can be pinned in stack with:`dimensional-1.0.1.3@sha256:f847a62cf258f28f78bd92be4afe1527a196e789fe46ff9a4913228e2d7b85fd,3878`
Depends on 5 packages(full list with versions):

# dimensional

This library provides statically-checked dimensional arithmetic for physical quantities, using the 7 SI base dimensions.

Data kinds and closed type families provide a flexible, safe, and discoverable implementation that leads to largely self-documenting client code.

## Usage

Simply importing `Numeric.Units.Dimensional.Prelude` provides access to dimensional arithmetic opertors, SI units and other common units accepted for use with the SI, and convenient aliases for quantities with commonly used dimensions.

The `Unit d a` type represents a unit with dimension `d`, whose conversion factor to the coherent SI base unit of the corresponding dimension is represented by a value of type `a`. `a` is commonly chosen to be `Double`, but can be any `Floating` type. Where possible, support is also provided for `Fractional` or `Num` values.

Similarly, the `Quantity d a` type represents a quantity with dimension `d`, whose numeric value is of type `a`. Aliases allow the use of, e.g., `Length Double` to mean `Quantity DLength Double`. A complete list of available aliases is given in the haddock documentation for the `Numeric.Units.Dimensional.Quantities`.

In the example below, we will solve a simple word problem.

A car travels at 60 kilometers per hour for one mile, at 50 kph for one mile, at 40 kph for one mile, and at 30 kph for one mile. How many minutes does the journey take? What is the average speed of the car? How many seconds does the journey take, rounded up to the next whole second?

``````{-# LANGUAGE NoImplicitPrelude #-}

import Numeric.Units.Dimensional.Prelude
import Numeric.Units.Dimensional.NonSI (mile)

leg :: Length Double
leg = 1 *~ mile -- *~ combines a raw number and a unit to form a quantity

speeds :: [Velocity Double]
speeds = [60, 50, 40, 30] *~~ (kilo meter / hour)
-- *~~ does the same thing for a whole Functor at once
-- Parentheses are required around unit expressions that are comingled with *~, /~, *~~, or /~~ operations

timeOfJourney :: Time Double
timeOfJourney = sum \$ fmap (leg /) speeds
-- We can use dimensional versions of ordinary functions like / and sum to combine quantities

averageSpeed :: Velocity Double
averageSpeed = _4 * leg / timeOfJourney
-- _4 is an alias for the dimensionless number 4

wholeSeconds :: Integer
wholeSeconds = ceiling \$ timeOfJourney /~ second
-- /~ lets us recover a raw number from a quantity and a unit in which it should be expressed

main :: IO ()
main = do
putStrLn \$ "Length of journey is: " ++ showIn minute timeOfJourney
putStrLn \$ "Average speed is: " ++ showIn (mile / hour) averageSpeed
putStrLn \$ "If we don't want to be explicit about units, the show instance uses the SI basis: " ++ show averageSpeed
putStrLn \$ "The journey requires " ++ show wholeSeconds ++ " seconds, rounded up to the nearest second."
``````

## Contributing

For project information (issues, updates, wiki, examples) see: https://github.com/bjornbm/dimensional

## 1.0.1.3 (2016-09)

• Fixed an issue with applying metric prefixes to units with non-rational conversion factors.

## 1.0.1.2 (2016-05)

• Support for GHC 8.0.1-rc4, avoiding GHC Trac issue 12026.
• Added support for stack.

## 1.0.1.1 (2015-11)

• Improved example in readme.

## 1.0.1.0 (2015-11)

• Added Numeric.Units.Dimensional.Coercion module.
• Bumped exact-pi dependency to < 0.5.
• Restored changelog.
• Addressed issues with documentation.

## 1.0.0.0 (2015-11)

• Changed to DataKinds and ClosedTypeFamilies encoding of dimensions.
• Added names and exact values to `Unit`s.
• Added `AnyUnit` and `AnyQuantity` for quantities whose dimension is statically unknown.
• Added Storable and Unbox instances for `Quantity`.
• Added dimensionally-polymorphic `siUnit` for the coherent SI base unit of any dimension.

## 0.13.0.2 (2015-04)

• Corrected definition of lumen.

## 0.13.0.1 (2014-09)

• Bumped time dependency to < 1.6.

## 0.13 (2014-02)

• Bump major version (should have been done in previous version).

## 0.12.3 (2014-02)

• Bump numtype dependency to 1.1 (GHC 7.8.1 compatibility fix).
• Added `Torque`.
• Added D.. for the type synonym quantities (e.g., `Angle`).

## 0.12.2 (2013-11)

• Added `FirstMassMoment`, `MomentOfInertia`, `AngularMomentum`.
• Improved unit numerics.

## 0.12.1 (2013-07)

• Typeable Dimensionals.

## 0.12 (2013-06)

• Polymorphic `_0` (closes issue 39).
• Added `astronomicalUnit`.
• Added imperial volume units.
• Added ‘mil’ (=inch/1000).
• Added `tau`.
• Added `KinematicViscosity`.

## 0.10.1.2 (2011-09)

• Bumped time dependency to < 1.5.

## 0.10.1.2 (2011-08)

• Bumped time dependency to < 1.4.

## 0.10.1 (2011-08)

GHC 7.2.1 compatibility fix:

• Increased CGS context-stack to 30.

## 0.10 (2011-05)

See the announcement.

## 0.9 (2011-04)

See the announcement.