{- Data/Metrology/Poly.hs

   The units Package
   Copyright (c) 2013 Richard Eisenberg
   rae@cs.brynmawr.edu

   This file gathers and exports all user-visible pieces of the units package.
   It also defines the main creators and consumers of dimensioned objects.
-}

{-# LANGUAGE ExplicitNamespaces, DataKinds, FlexibleInstances, TypeFamilies,
             TypeOperators, ConstraintKinds, ScopedTypeVariables,
             FlexibleContexts, UndecidableInstances, CPP #-}

#if __GLASGOW_HASKELL__ >= 711
{-# OPTIONS_GHC -Wno-redundant-constraints #-}
#endif

-----------------------------------------------------------------------------
-- |
-- Module      :  Data.Metrology.Poly
-- Copyright   :  (C) 2013 Richard Eisenberg
-- License     :  BSD-style (see LICENSE)
-- Maintainer  :  Richard Eisenberg (rae@cs.brynmawr.edu)
-- Stability   :  experimental
-- Portability :  non-portable
--
-- This module exports all the gubbins needed for type-checking your
-- dimensioned quantities. See 'Data.Metrology' for some functions
-- restricted to using a default LCSU, which is suitable for many
-- applications. See also 'Data.Metrology.Vector' for polymorphic
-- functions suitable for use with the numerical classes from the
-- @vector-space@ package.
-----------------------------------------------------------------------------

module Data.Metrology.Poly (
  -- * Term-level combinators

  -- | The term-level arithmetic operators are defined by
  -- applying vertical bar(s) to the sides the dimensioned
  -- quantities acts on.

  -- ** Additive operations
  zero, (|+|), (|-|), qSum, qNegate,

  -- ** Multiplicative operations between quantities
  (|*|), (|/|),

  -- ** Multiplicative operations between a quantity and a non-quantity
  (*|), (|*), (/|), (|/),

  -- ** Exponentiation
  (|^), (|^^), qNthRoot,
  qSq, qCube, qSqrt, qCubeRoot,

  -- ** Comparison
  qCompare, (|<|), (|>|), (|<=|), (|>=|), (|==|), (|/=|),
  qApprox, qNapprox,

  -- * Nondimensional units, conversion between quantities and numeric values
  numIn, (#), quOf, (%), showIn,
  unity, redim, convert,
  defaultLCSU, constant,

  -- * Type-level unit combinators
  (:*)(..), (:/)(..), (:^)(..), (:@)(..),
  UnitPrefix(..),

  -- * Type-level quantity combinators
  type (%*), type (%/), type (%^),

  -- * Creating quantity types
  Qu, MkQu_D, MkQu_DLN, MkQu_U, MkQu_ULN,

  -- * Creating new dimensions
  Dimension,

  -- * Creating new units
  Unit(type BaseUnit, type DimOfUnit, conversionRatio),
  Canonical,

  -- * Numbers, the only built-in unit
  Dimensionless(..), Number(..), Count, quantity,

  -- * LCSUs (locally coherent system of units)
  MkLCSU, LCSU(DefaultLCSU), DefaultUnitOfDim,

  -- * Validity checks and assertions
  CompatibleUnit, CompatibleDim, ConvertibleLCSUs_D,
  DefaultConvertibleLCSU_D, DefaultConvertibleLCSU_U,
  MultDimFactors, MultUnitFactors, UnitOfDimFactors,

  -- * Type-level integers
  Z(..), Succ, Pred, type (#+), type (#-), type (#*), type (#/), Negate,

  -- ** Synonyms for small numbers
  One, Two, Three, Four, Five, MOne, MTwo, MThree, MFour, MFive,

  -- ** Term-level singletons
  sZero, sOne, sTwo, sThree, sFour, sFive,
  sMOne, sMTwo, sMThree, sMFour, sMFive,
  sSucc, sPred, sNegate,

  -- ** Deprecated synonyms for the ones above
  pZero, pOne, pTwo, pThree, pFour, pFive,
  pMOne, pMTwo, pMThree, pMFour, pMFive,
  pSucc, pPred,

  -- * Internal definitions
  -- | The following module is re-exported solely to prevent noise in error messages;
  -- we do not recommend trying to use these definitions in user code.
  module Data.Metrology.Internal

  ) where

import Data.Metrology.Z
import Data.Metrology.Qu
import Data.Metrology.Dimensions
import Data.Metrology.Factor
import Data.Metrology.Units
import Data.Metrology.Combinators
import Data.Metrology.LCSU
import Data.Metrology.Validity
import Data.Metrology.Internal

import Data.Foldable as F
import Data.Proxy

-- | Extracts a numerical value from a dimensioned quantity, expressed in
--   the given unit. For example:
--
--   > inMeters :: Length -> Double
--   > inMeters x = numIn x Meter
--
--   or
--
--   > inMeters x = x # Meter
numIn :: forall unit dim lcsu n.
         ( ValidDLU dim lcsu unit
         , Fractional n )
      => Qu dim lcsu n -> unit -> n
numIn :: Qu dim lcsu n -> unit -> n
numIn (Qu n
val) unit
u
  = n
val n -> n -> n
forall a. Num a => a -> a -> a
* Rational -> n
forall a. Fractional a => Rational -> a
fromRational
             (Proxy (LookupList dim lcsu) -> Rational
forall (units :: [Factor *]).
UnitFactor units =>
Proxy units -> Rational
canonicalConvRatioSpec (Proxy (LookupList dim lcsu)
forall k (t :: k). Proxy t
Proxy :: Proxy (LookupList dim lcsu))
              Rational -> Rational -> Rational
forall a. Fractional a => a -> a -> a
/ unit -> Rational
forall unit. Unit unit => unit -> Rational
canonicalConvRatio unit
u)

infix 5 #
-- | Infix synonym for 'numIn'
(#) :: ( ValidDLU dim lcsu unit
       , Fractional n )
    => Qu dim lcsu n -> unit -> n
# :: Qu dim lcsu n -> unit -> n
(#) = Qu dim lcsu n -> unit -> n
forall unit (dim :: [Factor *]) (lcsu :: LCSU *) n.
(ValidDLU dim lcsu unit, Fractional n) =>
Qu dim lcsu n -> unit -> n
numIn

-- | Creates a dimensioned quantity in the given unit. For example:
--
--   > height :: Length
--   > height = quOf 2.0 Meter
--
--   or
--
--   > height = 2.0 % Meter
quOf :: forall unit dim lcsu n.
         ( ValidDLU dim lcsu unit
         , Fractional n )
      => n -> unit -> Qu dim lcsu n
quOf :: n -> unit -> Qu dim lcsu n
quOf n
d unit
u
  = n -> Qu dim lcsu n
forall (a :: [Factor *]) (lcsu :: LCSU *) n. n -> Qu a lcsu n
Qu (n
d n -> n -> n
forall a. Num a => a -> a -> a
* Rational -> n
forall a. Fractional a => Rational -> a
fromRational
               (unit -> Rational
forall unit. Unit unit => unit -> Rational
canonicalConvRatio unit
u
                Rational -> Rational -> Rational
forall a. Fractional a => a -> a -> a
/ Proxy (LookupList dim lcsu) -> Rational
forall (units :: [Factor *]).
UnitFactor units =>
Proxy units -> Rational
canonicalConvRatioSpec (Proxy (LookupList dim lcsu)
forall k (t :: k). Proxy t
Proxy :: Proxy (LookupList dim lcsu))))

infix 5 %
-- | Infix synonym for 'quOf'
(%) :: ( ValidDLU dim lcsu unit
       , Fractional n )
    => n -> unit -> Qu dim lcsu n
% :: n -> unit -> Qu dim lcsu n
(%) = n -> unit -> Qu dim lcsu n
forall unit (dim :: [Factor *]) (lcsu :: LCSU *) n.
(ValidDLU dim lcsu unit, Fractional n) =>
n -> unit -> Qu dim lcsu n
quOf

infix 1 `showIn`
-- | Show a dimensioned quantity in a given unit. (The default @Show@
-- instance always uses units as specified in the LCSU.)
showIn :: ( ValidDLU dim lcsu unit
          , Fractional n
          , Show unit
          , Show n )
       => Qu dim lcsu n -> unit -> String
showIn :: Qu dim lcsu n -> unit -> String
showIn Qu dim lcsu n
x unit
u = n -> String
forall a. Show a => a -> String
show (Qu dim lcsu n
x Qu dim lcsu n -> unit -> n
forall (dim :: [Factor *]) (lcsu :: LCSU *) unit n.
(ValidDLU dim lcsu unit, Fractional n) =>
Qu dim lcsu n -> unit -> n
# unit
u) String -> String -> String
forall a. [a] -> [a] -> [a]
++ String
" " String -> String -> String
forall a. [a] -> [a] -> [a]
++ unit -> String
forall a. Show a => a -> String
show unit
u

-- | Dimension-keeping cast between different CSUs.
convert :: forall d l1 l2 n.
  ( ConvertibleLCSUs d l1 l2
  , Fractional n )
  => Qu d l1 n -> Qu d l2 n
convert :: Qu d l1 n -> Qu d l2 n
convert (Qu n
x) = n -> Qu d l2 n
forall (a :: [Factor *]) (lcsu :: LCSU *) n. n -> Qu a lcsu n
Qu (n -> Qu d l2 n) -> n -> Qu d l2 n
forall a b. (a -> b) -> a -> b
$ n
x n -> n -> n
forall a. Num a => a -> a -> a
* Rational -> n
forall a. Fractional a => Rational -> a
fromRational (
  Proxy (LookupList d l1) -> Rational
forall (units :: [Factor *]).
UnitFactor units =>
Proxy units -> Rational
canonicalConvRatioSpec (Proxy (LookupList d l1)
forall k (t :: k). Proxy t
Proxy :: Proxy (LookupList d l1))
  Rational -> Rational -> Rational
forall a. Fractional a => a -> a -> a
/ Proxy (LookupList d l2) -> Rational
forall (units :: [Factor *]).
UnitFactor units =>
Proxy units -> Rational
canonicalConvRatioSpec (Proxy (LookupList d l2)
forall k (t :: k). Proxy t
Proxy :: Proxy (LookupList d l2)))

-- | Compute the argument in the @DefaultLCSU@, and present the result as
-- lcsu-polymorphic dimension-polymorphic value. Named 'constant' because one
-- of its dominant usecase is to inject constant quantities into
-- dimension-polymorphic expressions.
constant :: ( d @~ e
            , ConvertibleLCSUs e DefaultLCSU l
            , Fractional n )
         => Qu d DefaultLCSU n -> Qu e l n
constant :: Qu d 'DefaultLCSU n -> Qu e l n
constant = Qu e 'DefaultLCSU n -> Qu e l n
forall (d :: [Factor *]) (l1 :: LCSU *) (l2 :: LCSU *) n.
(ConvertibleLCSUs d l1 l2, Fractional n) =>
Qu d l1 n -> Qu d l2 n
convert (Qu e 'DefaultLCSU n -> Qu e l n)
-> (Qu d 'DefaultLCSU n -> Qu e 'DefaultLCSU n)
-> Qu d 'DefaultLCSU n
-> Qu e l n
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Qu d 'DefaultLCSU n -> Qu e 'DefaultLCSU n
forall (d :: [Factor *]) (e :: [Factor *]) (l :: LCSU *) n.
(d @~ e) =>
Qu d l n -> Qu e l n
redim

----------------------------------------------------
-- Qu operations
----------------------------------------------------

-- | The number 0, polymorphic in its dimension. Use of this will
-- often require a type annotation.
zero :: Num n => Qu dimspec l n
zero :: Qu dimspec l n
zero = n -> Qu dimspec l n
forall (a :: [Factor *]) (lcsu :: LCSU *) n. n -> Qu a lcsu n
Qu n
0

infixl 6 |+|
-- | Add two compatible quantities
(|+|) :: (d1 @~ d2, Num n) => Qu d1 l n -> Qu d2 l n -> Qu d1 l n
(Qu n
a) |+| :: Qu d1 l n -> Qu d2 l n -> Qu d1 l n
|+| (Qu n
b) = n -> Qu d1 l n
forall (a :: [Factor *]) (lcsu :: LCSU *) n. n -> Qu a lcsu n
Qu (n
a n -> n -> n
forall a. Num a => a -> a -> a
+ n
b)

infixl 6 |-|
-- | Subtract two compatible quantities
(|-|) :: (d1 @~ d2, Num n) => Qu d1 l n -> Qu d2 l n -> Qu d1 l n
(Qu n
a) |-| :: Qu d1 l n -> Qu d2 l n -> Qu d1 l n
|-| (Qu n
b) = n -> Qu d1 l n
forall (a :: [Factor *]) (lcsu :: LCSU *) n. n -> Qu a lcsu n
Qu (n
a n -> n -> n
forall a. Num a => a -> a -> a
- n
b)

-- | Take the sum of a list of quantities
qSum :: (Foldable f, Num n) => f (Qu d l n) -> Qu d l n
qSum :: f (Qu d l n) -> Qu d l n
qSum = (Qu d l n -> Qu d l n -> Qu d l n)
-> Qu d l n -> f (Qu d l n) -> Qu d l n
forall (t :: * -> *) a b.
Foldable t =>
(a -> b -> b) -> b -> t a -> b
F.foldr Qu d l n -> Qu d l n -> Qu d l n
forall (d1 :: [Factor *]) (d2 :: [Factor *]) n (l :: LCSU *).
(d1 @~ d2, Num n) =>
Qu d1 l n -> Qu d2 l n -> Qu d1 l n
(|+|) Qu d l n
forall n (dimspec :: [Factor *]) (l :: LCSU *).
Num n =>
Qu dimspec l n
zero

-- | Negate a quantity
qNegate :: Num n => Qu d l n -> Qu d l n
qNegate :: Qu d l n -> Qu d l n
qNegate (Qu n
x) = n -> Qu d l n
forall (a :: [Factor *]) (lcsu :: LCSU *) n. n -> Qu a lcsu n
Qu (n -> n
forall a. Num a => a -> a
negate n
x)

infixl 7 *| , |* , |/
-- | Multiply a quantity by a scalar from the left
(*|) :: Num n => n -> Qu b l n -> Qu b l n
n
a *| :: n -> Qu b l n -> Qu b l n
*| (Qu n
b) = n -> Qu b l n
forall (a :: [Factor *]) (lcsu :: LCSU *) n. n -> Qu a lcsu n
Qu (n
a n -> n -> n
forall a. Num a => a -> a -> a
* n
b)

-- | Multiply a quantity by a scalar from the right
(|*) :: Num n => Qu a l n -> n -> Qu a l n
(Qu n
a) |* :: Qu a l n -> n -> Qu a l n
|* n
b = n -> Qu a l n
forall (a :: [Factor *]) (lcsu :: LCSU *) n. n -> Qu a lcsu n
Qu (n
a n -> n -> n
forall a. Num a => a -> a -> a
* n
b)

-- | Divide a quantity by a scalar
(|/) :: Fractional n => Qu a l n -> n -> Qu a l n
(Qu n
a) |/ :: Qu a l n -> n -> Qu a l n
|/ n
b = n -> Qu a l n
forall (a :: [Factor *]) (lcsu :: LCSU *) n. n -> Qu a lcsu n
Qu (n
a n -> n -> n
forall a. Fractional a => a -> a -> a
/ n
b)