dimensional: Statically checked physical dimensions

[ bsd3, library, math, physics ] [ Propose Tags ] [ Report a vulnerability ]

Dimensional is a library providing data types for performing arithmetic with physical quantities and units. Information about the physical dimensions of the quantities and units is embedded in their types and the validity of operations is verified by the type checker at compile time. The wrapping and unwrapping of numerical values as quantities is done by multiplication and division with units. The library is designed to, as far as is practical, enforce/encourage best practices of unit usage. Version 1 of the dimensional package differs from earlier version in that the dimension tracking is implemented using Closed Type Families and Data Kinds rather than functional dependencies. This enables a number of features, including improved support for unit names and quantities with statically-unknown dimensions. Requires GHC 8.0 or later.


[Skip to Readme]

Flags

Manual Flags

NameDescriptionDefault
binary

Provide instances for use with the binary package.

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

Versions [RSS] 0.7, 0.7.1, 0.7.2, 0.7.3, 0.8, 0.8.0.1, 0.8.2.1, 0.9, 0.10, 0.10.1, 0.10.1.1, 0.10.1.2, 0.10.2, 0.12, 0.12.1, 0.12.1.1, 0.12.2, 0.12.3, 0.13, 0.13.0.1, 0.13.0.2, 1.0.0.0, 1.0.1.0, 1.0.1.1, 1.0.1.2, 1.0.1.3, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.6.1
Change log CHANGELOG.md
Dependencies base (>=4.9 && <5), deepseq (>=1.3), exact-pi (>=0.4.1 && <0.6), ieee754 (>=0.7.6), numtype-dk (>=0.5 && <1.1), vector (>=0.10) [details]
Tested with ghc ==8.10.7, ghc ==9.0.2, ghc ==9.2.8, ghc ==9.4.8, ghc ==9.6.6, ghc ==9.8.2, ghc ==9.10.1
License BSD-3-Clause
Copyright Bjorn Buckwalter 2006-2024
Author Bjorn Buckwalter
Maintainer bjorn@buckwalter.se
Category Math, Physics
Home page https://github.com/bjornbm/dimensional/
Bug tracker https://github.com/bjornbm/dimensional/issues/
Source repo head: git clone https://github.com/bjornbm/dimensional/
Uploaded by LaurentRDC at 2024-10-25T15:56:25Z
Distributions Debian:1.3, LTSHaskell:1.5, NixOS:1.5, Stackage:1.6.1
Reverse Dependencies 11 direct, 4 indirect [details]
Downloads 27072 total (171 in the last 30 days)
Rating 2.5 (votes: 6) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2024-10-25 [all 1 reports]

Readme for dimensional-1.6.1

[back to package description]

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.

Hackage Version Stackage version

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

Package Flags

To provide Binary serialization for Quantity from the binary package, the binary flag can be used like so:

cabal install dimensional -f binary

If you use a cabal.project file, you can instead add the following clause to activate this package flag:

package dimensional
    flags: +binary

Contributing

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