dimensional
Statically checked physical dimensions, using Type Families and Data Kinds.
https://github.com/bjornbm/dimensional/
Version on this page: | 1.1 |
LTS Haskell 22.39: | 1.5 |
Stackage Nightly 2024-10-29: | 1.6.1 |
Latest on Hackage: | 1.6.1 |
dimensional-1.1@sha256:64d1ee8976dc87dee8ddc4584f45acd6fb96c514d750d70c5227793501cab753,4682
Module documentation for 1.1
- Numeric
- Numeric.Units
- Numeric.Units.Dimensional
- Numeric.Units.Dimensional.Coercion
- Numeric.Units.Dimensional.Dimensions
- Numeric.Units.Dimensional.Dynamic
- Numeric.Units.Dimensional.FixedPoint
- Numeric.Units.Dimensional.Float
- Numeric.Units.Dimensional.Functor
- Numeric.Units.Dimensional.NonSI
- Numeric.Units.Dimensional.Prelude
- Numeric.Units.Dimensional.Quantities
- Numeric.Units.Dimensional.SIUnits
- Numeric.Units.Dimensional.UnitNames
- Numeric.Units.Dimensional.Variants
- Numeric.Units.Dimensional
- Numeric.Units
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 #-}
module ReadmeExample where
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
Changes
1.1 (2018-03)
- Added
Semigroup
instances for GHC 8.4 compatibility. - Breaking: Renamed
Root
type family toNRoot
. AddedSqrt
andCbrt
type synonyms. Addedsqrt
andcbrt
for term level dimensions. - Breaking: Changed
Numeric.Units.Dimensional.Prelude
to export dimensionally typedsignum
,recip
, andlogBase
instead of the ones fromPrelude
. - Breaking: Changed
Numeric.Units.Dimensional.Prelude
to export(.)
andid
fromControl.Category
instead of fromPrelude
. - Breaking: Created a
product
function which take the product of a foldable structure ofDimensionless
values. Exported thisproduct
function from Numeric.Units.Dimensional.Prelude instead of the one fromPrelude
. - Breaking: Changed the
HasDimension
typeclass to require an instance of the newHasDynamicDimension
typeclass. - Breaking: Added operators for
AnyUnit
to the Numeric.Units.Dimensional.Dynamic module which may cause name collisions. - Breaking: Added dynamic versions of
(*~)
,(/~)
, andsiUnit
to the Numeric.Units.Dimensional.Dynamic module which may cause name collisions. - Breaking: Removed exports of
nMeter
,nSecond
,kilo
, etc from Numeric.Units.Dimensional.UnitNames. Access these instead by inspecting the relevant units or prefixes. - Breaking: Generalized the type of
dimensionlessLength
from(Num a, Foldable f) => f (Dimensional v d a) -> Dimensionless a)
to(Num a, Foldable f) => f b -> Dimensionless a
. This provides a weaker constraint on the typea
and may result in ambiguous types in code that depends on the former less general type. - Fixed a bug in the definition of the
inHg_NIST
. - Fixed a bug in the interchange name of the Dalton.
- Added units for the US survey foot, yard, inch, mil, and mile.
- Added the short ton as a unit of mass.
- Clarified that the UCUM acre is based on the US survey foot.
- Added a version of the acre based on the international foot.
- Added
Data
,Generic
,Typeable
andNFData
instances for many ancillary types. - Added
unQuantity
to the Coercion module to ease unwrapping without introducing ambiguous type variables. - Created explicit representation of metric
Prefix
es. - Added a multiplicative
Monoid
instance forAnyQuantity
and forAnyUnit
. - Added the
DynQuantity
type to represent possibly valid quantities of statically unknown dimension, suitable for performing arithmetic with such quantities. - Added
nroot
function for term-level dimensions. - Added the Numeric.Units.Dimensional.Float module with convenient wrappers around functions from RealFloat and IEEE for inspecting floating point quantities.
- Added an
AEq
instance forQuantity
. - Added
Eq1
andOrd1
instances forQuantity
. - Exposed the name of an ‘AnyUnit’ without promoting it to a ‘Unit’ first.
- Exposed a way to convert atomic ‘UnitName’s back into ‘NameAtom’s.
- Added the
btu
, a unit of energy. - Added the
gauss
, a unit of magnetic flux density. - Added the
angstrom
, a unit of length. - Relocated git repository to 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
andAnyQuantity
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. - Added some additional units.
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.