-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Compensated floating-point arithmetic
--   
--   This package provides compensated floating point arithmetic.
@package compensated
@version 0.8.2


-- | This module provides a fairly extensive API for compensated floating
--   point arithmetic based on Knuth's error free transformation, various
--   algorithms by Ogita, Rump and Oishi, Hida, Li and Bailey, Kahan
--   summation, etc. with custom compensated arithmetic circuits to do
--   multiplication, division, etc. of compensated numbers.
--   
--   In general if <tt>a</tt> has x bits of significand, <tt>Compensated
--   a</tt> gives you twice that. You can iterate this construction for
--   arbitrary precision.
--   
--   References:
--   
--   <ul>
--   
--   <li><a>http://web.mit.edu/tabbott/Public/quaddouble-debian/qd-2.3.4-old/docs/qd.pdf</a></li>
--   <li><a>http://www.ti3.tuhh.de/paper/rump/OgRuOi05.pdf</a></li>
--   <li>Donald Knuth's "The Art of Computer Programming, Volume 2:
--   Seminumerical Algorithms"</li>
--   <li><a>http://en.wikipedia.org/wiki/Kahan_summation_algorithm</a></li>
--   </ul>
module Numeric.Compensated
class (RealFrac a, Floating a) => Compensable a where {
    
    -- | This provides a numeric data type with effectively doubled precision
    --   by using Knuth's error free transform and a number of custom
    --   compensated arithmetic circuits.
    --   
    --   This construction can be iterated, doubling precision each time.
    --   
    --   <pre>
    --   &gt;&gt;&gt; round (Prelude.product [2..100] :: Compensated (Compensated (Compensated Double)))
    --   93326215443944152681699238856266700490715968264381621468592963895217599993229915608941463976156518286253697920827223758251185210916864000000000000000000000000
    --   </pre>
    --   
    --   <pre>
    --   &gt;&gt;&gt; Prelude.product [2..100]
    --   93326215443944152681699238856266700490715968264381621468592963895217599993229915608941463976156518286253697920827223758251185210916864000000000000000000000000
    --   </pre>
    data family Compensated a;
}

-- | This extracts both the <a>primal</a> and <a>residual</a> components of
--   a <a>Compensated</a> number.
with :: (Compensable a, Compensable a) => Compensated a -> (a -> a -> r) -> r

-- | Used internally to construct <a>compensated</a> values that satisfy
--   our residual contract.
--   
--   When in doubt, use <tt><a>add</a> a b <a>compensated</a></tt> instead
--   of <tt><a>compensated</a> a b</tt>
compensated :: (Compensable a, Compensable a) => a -> a -> Compensated a

-- | This <a>magic</a> number is used to <a>split</a> the significand in
--   half, so we can multiply them separately without losing precision in
--   <a>times</a>.
magic :: Compensable a => a

-- | This provides the isomorphism between the compact representation we
--   store these in internally and the naive pair of the <a>primal</a> and
--   <a>residual</a> components.
_Compensated :: Compensable a => Iso' (Compensated a) (a, a)
type Overcompensated a = Compensated (Compensated a)

-- | This <a>Lens</a> lets us edit the <a>primal</a> directly, leaving the
--   <a>residual</a> untouched.
primal :: Compensable a => Lens' (Compensated a) a

-- | This <a>Lens</a> lets us edit the <a>residual</a> directly, leaving
--   the <a>primal</a> untouched.
residual :: Compensable a => Lens' (Compensated a) a

-- | Extract the <a>primal</a> component of a <a>compensated</a> value,
--   when and if compensation is no longer required.
uncompensated :: Compensable a => Compensated a -> a

-- | <tt><a>fadd</a> a b k</tt> computes <tt>k x y</tt> such that
--   
--   <pre>
--   x + y = a + b
--   x = fl(a + b)
--   </pre>
--   
--   but only under the assumption that <tt><a>abs</a> a <a>&gt;=</a>
--   <a>abs</a> b</tt>. If you aren't sure, use <a>add</a>.
--   
--   Which is to say that <tt>x</tt> is the floating point image of <tt>(a
--   + b)</tt> and <tt>y</tt> stores the residual error term.
fadd :: Num a => a -> a -> (a -> a -> r) -> r

-- | <tt><a>add</a> a b k</tt> computes <tt>k x y</tt> such that
--   
--   <pre>
--   x + y = a + b
--   x = fl(a + b)
--   </pre>
--   
--   Which is to say that <tt>x</tt> is the floating point image of <tt>(a
--   + b)</tt> and <tt>y</tt> stores the residual error term.
add :: Num a => a -> a -> (a -> a -> r) -> r

-- | <tt><a>times</a> a b k</tt> computes <tt>k x y</tt> such that
--   
--   <pre>
--   x + y = a * b
--   x = fl(a * b)
--   </pre>
--   
--   Which is to say that <tt>x</tt> is the floating point image of <tt>(a
--   * b)</tt> and <tt>y</tt> stores the residual error term.
--   
--   This could be nicer if we had access to a hardware fused multiply-add.
times :: Compensable a => a -> a -> (a -> a -> r) -> r

-- | <tt><a>squared</a> a k</tt> computes <tt>k x y</tt> such that
--   
--   <pre>
--   x + y = a * a
--   x = fl(a * a)
--   </pre>
--   
--   Which is to say that <tt>x</tt> is the floating point image of <tt>(a
--   * a)</tt> and <tt>y</tt> stores the residual error term.
squared :: Compensable a => a -> (a -> a -> r) -> r
divide :: Compensable a => a -> a -> (a -> a -> r) -> r

-- | error-free split of a floating point number into two parts.
--   
--   Note: these parts do not satisfy the <a>compensated</a> contract
split :: Compensable a => a -> (a -> a -> r) -> r

-- | Perform Kahan summation over a list.
kahan :: (Foldable f, Compensable a) => f a -> Compensated a

-- | Calculate a scalar + compensated sum with Kahan summation.
(+^) :: Compensable a => a -> Compensated a -> Compensated a

-- | Compute <tt>a * <a>Compensated</a> a</tt>
(*^) :: Compensable a => a -> Compensated a -> Compensated a

-- | Calculate a fast square of a compensated number.
square :: Compensable a => Compensated a -> Compensated a
instance Numeric.Compensated.Compensable GHC.Types.Double
instance Numeric.Compensated.Compensable GHC.Types.Float
instance Numeric.Compensated.Compensable a => Numeric.Compensated.Compensable (Numeric.Compensated.Compensated a)
instance (Numeric.Compensated.Compensable a, Data.Hashable.Class.Hashable a) => Data.Hashable.Class.Hashable (Numeric.Compensated.Compensated a)
instance (Numeric.Compensated.Compensable a, Data.Data.Data a) => Data.Data.Data (Numeric.Compensated.Compensated a)
instance (Numeric.Compensated.Compensable a, Control.DeepSeq.NFData a) => Control.DeepSeq.NFData (Numeric.Compensated.Compensated a)
instance (Numeric.Compensated.Compensable a, GHC.Show.Show a) => GHC.Show.Show (Numeric.Compensated.Compensated a)
instance (Numeric.Compensated.Compensable a, GHC.Read.Read a) => GHC.Read.Read (Numeric.Compensated.Compensated a)
instance (Numeric.Compensated.Compensable a, Numeric.Compensated.Compensable b) => Control.Lens.Each.Each (Numeric.Compensated.Compensated a) (Numeric.Compensated.Compensated b) a b
instance Numeric.Compensated.Compensable a => GHC.Classes.Eq (Numeric.Compensated.Compensated a)
instance Numeric.Compensated.Compensable a => GHC.Classes.Ord (Numeric.Compensated.Compensated a)
instance Numeric.Compensated.Compensable a => GHC.Base.Semigroup (Numeric.Compensated.Compensated a)
instance Numeric.Compensated.Compensable a => GHC.Base.Monoid (Numeric.Compensated.Compensated a)
instance Numeric.Compensated.Compensable a => GHC.Num.Num (Numeric.Compensated.Compensated a)
instance Numeric.Compensated.Compensable a => GHC.Enum.Enum (Numeric.Compensated.Compensated a)
instance Numeric.Compensated.Compensable a => GHC.Real.Fractional (Numeric.Compensated.Compensated a)
instance Numeric.Compensated.Compensable a => GHC.Real.Real (Numeric.Compensated.Compensated a)
instance Numeric.Compensated.Compensable a => GHC.Real.RealFrac (Numeric.Compensated.Compensated a)
instance (Numeric.Compensated.Compensable a, Data.Binary.Class.Binary a) => Data.Binary.Class.Binary (Numeric.Compensated.Compensated a)
instance (Numeric.Compensated.Compensable a, Data.Serialize.Serialize a) => Data.Serialize.Serialize (Numeric.Compensated.Compensated a)
instance (Numeric.Compensated.Compensable a, Data.Bytes.Serial.Serial a) => Data.Bytes.Serial.Serial (Numeric.Compensated.Compensated a)
instance (Numeric.Compensated.Compensable a, Data.Serialize.Serialize a) => Data.SafeCopy.SafeCopy.SafeCopy (Numeric.Compensated.Compensated a)
instance (Numeric.Compensated.Compensable a, Foreign.Storable.Storable a) => Foreign.Storable.Storable (Numeric.Compensated.Compensated a)
instance (Numeric.Compensated.Compensable a, Data.Vector.Unboxed.Base.Unbox a) => Data.Vector.Generic.Mutable.Base.MVector Data.Vector.Unboxed.Base.MVector (Numeric.Compensated.Compensated a)
instance (Numeric.Compensated.Compensable a, Data.Vector.Unboxed.Base.Unbox a) => Data.Vector.Generic.Base.Vector Data.Vector.Unboxed.Base.Vector (Numeric.Compensated.Compensated a)
instance Numeric.Compensated.Compensable a => GHC.Float.Floating (Numeric.Compensated.Compensated a)