HMath.Numeric¶
Module index · Numerical conventions
Description
Numeric representations and deterministic IEEE utilities. Standard integer,
rational, binary32/64 and complex types are re-exported. Conversions never
silently promote precision: BigFloat operations explicitly select the larger
operand precision, decimal/fixed operations the larger scale. The host IEEE
rounding environment is not modified. Explicit rounding returns software flags.
On this page¶
| API | Purpose |
|---|---|
| Int8 | 8-bit signed integer type |
| Int16 | 16-bit signed integer type |
| Int32 | 32-bit signed integer type |
| Int64 | 64-bit signed integer type |
| Word8 | 8-bit unsigned integer type |
| Word16 | 16-bit unsigned integer type |
| Word32 | 32-bit unsigned integer type |
| Word64 | 64-bit unsigned integer type |
| Float32 | Alias for Haskell Float (IEEE binary32 on supported targets). |
| Float64 | Alias for Haskell Double (IEEE binary64 on supported targets). |
| Complex | A data type representing complex numbers. |
| :+ | forms a complex number from its real and imaginary rectangular components. |
| Rational | Arbitrary-precision rational numbers, represented as a ratio of two Integer values. |
| RoundingMode | Software rounding direction: nearest-even,toward zero,toward positive infinity,or toward negative infinity. |
| NearestEven | Declaration and type contract below. |
| TowardZero | Declaration and type contract below. |
| TowardPositive | Declaration and type contract below. |
| TowardNegative | Declaration and type contract below. |
| NumericException | Software operation flags: invalid operation,division by zero,overflow,underflow,or inexact conversion. |
| InvalidOperation | Declaration and type contract below. |
| DivisionByZero | Declaration and type contract below. |
| NumericOverflow | Declaration and type contract below. |
| NumericUnderflow | Declaration and type contract below. |
| Inexact | Declaration and type contract below. |
| Rounded | Rounded numeric result paired with software exception flags. |
| Rounded | Declaration and type contract below. |
| roundedValue | Value produced by the explicitly selected software rounding operation. |
| numericalExceptions | Software rounding flags; these do not modify the host IEEE exception environment. |
| roundRational | Given software rounding mode then exact Rational, return Integer rounded by nearest-even, toward zero, toward positive infinity, or toward negative infinity. |
| IEEEClass | IEEE classification distinguishing NaN,signed infinity,signed zero,subnormal,and normal finite values. |
| NotANumber | Declaration and type contract below. |
| PositiveInfinity | Declaration and type contract below. |
| NegativeInfinity | Declaration and type contract below. |
| PositiveZero | Declaration and type contract below. |
| NegativeZero | Declaration and type contract below. |
| Subnormal | Declaration and type contract below. |
| Normal | Declaration and type contract below. |
| classify | Classify a RealFloat value as NaN, signed infinity, signed zero, subnormal, or normal. |
| NumericLimits | Format limits and precision metadata derived from RealFloat or the explicit 16-bit format definition. |
| NumericLimits | Declaration and type contract below. |
| minimumNormal | Smallest positive normal value of the represented floating format. |
| minimumSubnormal | Smallest positive subnormal value of the represented floating format. |
| maximumFinite | Largest finite positive value of the represented floating format. |
| machineEpsilon | Gap between one and its next larger representable value. |
| significandDigits | Number of radix digits in the floating significand. |
| minimumExponent | Lower exponent bound returned by RealFloat.floatRange. |
| maximumExponent | Upper exponent bound returned by RealFloat.floatRange. |
| numericLimits | Derived from RealFloat radixdigitsrange, not hardcoded for Double. |
| integerLimits | Given a bounded integral type witness, return its exact (minimum,maximum) as Integers. |
| float16Limits | Limits returned as exact binary64 values for the two 16-bit storage formats. |
| bfloat16Limits | Limits returned as exact binary64 values for the two 16-bit storage formats. |
| nextAfter | Adjacent representable value toward target, including gradual underflow. |
| frexp | x=m*2^e, with abs m in [1/2,1) for nonzero finite binary inputs. |
| ldexp | Given real value then Int exponent, scale by the numeric radix to that power using scaleFloat (binary types use powers of two). |
| ulpDistance | IEEE binary64 distance. |
| withinULPs | Given nonnegative allowed ULP distance then two Doubles, test their binary64 representable-value distance. |
| safeIntegralCast | Convert an integral value to a bounded integral destination only if in range. |
| saturatingCast | Convert an integral value to a bounded integral destination, clamping to minBound/maxBound when out of range. |
| realToIntegral | Given software rounding mode then finite real value, round exactly through Rational then range-check the bounded integral destination. |
| narrowFloat | A narrowing conversion must be finite and exact; choose explicit quantized Float16/BigFloat rounding APIs when loss of precision is intentional. |
| Float16 | IEEE binary16 and bfloat16 storage. |
| float16 | Given rounding mode then Double, round directly to IEEE binary16 and return Rounded storage plus software flags. |
| fromFloat16 | Decode binary16 storage to Double, preserving finite values, signed zero, infinity and NaN classification. |
| float16Bits | Return raw IEEE binary16 storage bits, including sign, exponent and fraction, as Word16. |
| float16FromBits | Construct binary16 storage from raw Word16 without validation or rounding; all bit patterns, including NaNs, are representable. |
| BFloat16 | Opaque bfloat16 storage with 8 exponent and 7 explicit fraction bits. |
| bfloat16 | Given rounding mode then Double, round directly to bfloat16 without an intermediate binary32 rounding. |
| fromBFloat16 | Decode bfloat16 storage to Double, preserving finite values, signed zero and non-finite classification. |
| bfloat16Bits | Return raw bfloat16 storage bits as Word16. |
| bfloat16FromBits | Construct bfloat16 storage from raw Word16 without conversion; all bit patterns are retained. |
| BigFloat | An unbounded-exponent binary floating value backed by an exact Rational, rounded to a runtime number of significant bits (2..1,000,000). |
| bigFloat | Given precision in [2,1000000] bits, rounding mode, then Rational, construct configurable-precision BigFloat plus Inexact flag if rounded. |
| bigPrecision | Return the runtime number of significant binary bits retained by a BigFloat. |
| bigRational | Return the exact Rational value of the already-rounded BigFloat, without another conversion or rounding. |
| bigToDouble | Round BigFloat to host Double through fromRational. |
| bigAdd | Add two BigFloats exactly then round once to the larger operand precision, nearest-even. |
| bigSubtract | Subtract the second BigFloat from the first, rounding once nearest-even at the larger operand precision. |
| bigMultiply | Multiply two BigFloats exactly then round once nearest-even to the larger operand precision. |
| bigDivide | Divide two BigFloats and round once nearest-even to the larger precision. |
| bigSqrt | Compute nonnegative BigFloat square root using integer/rational guard precision then round to the input precision. |
| bigExp | Absolute tail controlled rational series; final rounding is accurate to the requested precision up to one final ulp, not a correctly-rounded promise. |
| bigLog | Compute natural logarithm at the BigFloat precision using rational series and guard bits. |
| extended | Software extended precision: 64 significant bits, unbounded exponent. |
| mixedAdd | Given BigFloat then finite Double, add via exact Rational intermediates at max(BigFloat precision,53) bits, nearest-even. |
| mixedMultiply | Given BigFloat then finite Double, multiply at max(BigFloat precision,53) bits using exact intermediates and nearest-even. |
| Fixed | Runtime-scale base-ten fixed point: coefficient * 10^(-scale). |
| fixed | Given decimal scale in [0,10000], rounding mode, then Rational, return Rounded Fixed and Inexact when required. |
| fixedScale | Return nonnegative decimal scale s of a Fixed value; its exact value is coefficient / 10^s. |
| fixedCoefficient | Return exact stored Integer coefficient of a Fixed value, before division by 10^fixedScale. |
| fixedRational | Return exact coefficient/10^scale represented by a Fixed value, without rounding. |
| fixedAdd | Add two Fixed values using the larger decimal scale, nearest-even, returning Rounded result and software flags. |
| fixedMultiply | Given rounding mode then two Fixed values, multiply and round to their larger scale, returning Rounded result and flags. |
| fixedDivide | Given rounding mode then Fixed numerator and denominator, divide and round to their larger scale. |
| Decimal | Opaque decimal fixed-point value with fractional-place scale, built through decimal with explicit rounding. |
| decimal | Given decimal fractional-place scale, rounding mode, then Rational, construct Rounded Decimal through fixed. |
| decimalRational | Return exact Rational value stored in a Decimal without further rounding. |
| decimalAdd | Add two Decimals at their larger decimal scale, nearest-even, returning Rounded result and software flags. |
| decimalMultiply | Given rounding mode then two Decimals, multiply at the larger fractional-place scale and return Rounded result with flags. |
| decimalDivide | Given rounding mode then two Decimals, divide at their larger scale and return Rounded result. |
| Interval | Finite closed binary64 intervals. |
| interval | Given finite lower and upper bounds in increasing order, construct a closed binary64 Interval. |
| intervalBounds | Return (lower,upper) binary64 endpoints of a validated closed interval. |
| intervalAdd | Add finite intervals with exact Rational endpoint arithmetic rounded outward, enclosing the exact sum. |
| intervalSubtract | Subtract intervals with endpoints [a-d,b-c], rounding outward. |
| intervalMultiply | Multiply intervals using the minimum/maximum of all four endpoint products and outward rounding. |
| intervalDivide | Divide intervals using endpoint quotients with outward rounding. |
| intervalContains | Given interval then Double, test closed-bound membership lower<=x<=upper. |
| Dual | Forward-mode automatic differentiation, f(a+b epsilon), epsilon^2=0. |
| Dual | Declaration and type contract below. |
| primal | Primal component of a forward-mode Dual number. |
| tangent | Directional derivative component of a forward-mode Dual number. |
| derivative | Given a function on Dual numbers then primal input x, seed Dual x 1 and extract the output tangent. |
| Quaternion | Hamilton quaternion (real, i, j, k); multiplication is noncommutative. |
| Quaternion | Declaration and type contract below. |
| quaternionConjugate | For Quaternion real i j k, negate the three imaginary components and preserve the real part. |
| quaternionNorm | Return scaled Euclidean norm of four quaternion components, reducing avoidable intermediate overflow. |
| quaternionInverse | Invert a finite nonzero quaternion using scaled norm arithmetic. |
| rotateVector | Given nonzero finite quaternion q then (x,y,z), return imaginary part of q(0,x,y,z)inverse(q). |
| DualQuaternion | Real and dual quaternion pair, commonly representing a rigid rotation/translation. |
| DualQuaternion | Declaration and type contract below. |
| dualQuaternionMultiply | Multiply real/dual quaternion pairs as (a,b)(c,d)=(ac,ad+bc). |
| dualQuaternionInverse | Invert the real quaternion a, returning (inverse(a), -inverse(a)binverse(a)). |
| rigidTransform | Construct a rigid transform from a nonzero rotation quaternion and translation. |
| transformPoint | Given dual-quaternion transform then point tuple, rotate by its real part and add translation from twice the dual part times the real inverse. |
| kahanSum | Sum a finite list using Kahan compensation; empty input yields zero. |
| neumaierSum | Sum a finite list with Neumaier compensation, correcting for differing term magnitudes. |
| pairwiseSum | Recursively split and sum a finite list to reduce sequential rounding accumulation. |
| logsumexp | Empty input is -infinity; +infinity dominates finite/-infinite inputs. |
| sumErrorBound | Conservative sequential sum bound gamma_(n-1) * sum abs x. |
Documentation
Int8
8-bit signed integer type
Instances
Int16
16-bit signed integer type
Instances
Int32
32-bit signed integer type
Instances
Int64
64-bit signed integer type
Instances
Word8
8-bit unsigned integer type
Instances
Word16
16-bit unsigned integer type
Instances
Word32
32-bit unsigned integer type
Instances
Word64
64-bit unsigned integer type
Instances
Complex
A data type representing complex numbers.
You can read about complex numbers on wikipedia.
In haskell, complex numbers are represented as a :+ b which can be thought of
as representing \(a + bi\). For a complex number z, is a number with the abs zmagnitude of z,
but oriented in the positive real direction, whereas
has the signum zphase of z, but unit magnitude.
Apart from the loss of precision due to IEEE754 floating point numbers,
it holds that z == .abs z * signum z
Note that Complex's instances inherit the deficiencies from the type
parameter's. For example, Complex Float's Ord instance has similar
problems to Float's.
As can be seen in the examples, the Foldable
and Traversable instances traverse the real part first.
Examples
>>>(5.0 :+ 2.5) + 6.511.5 :+ 2.5
>>>abs (1.0 :+ 1.0) - sqrt 2.00.0 :+ 0.0
>>>abs (signum (4.0 :+ 3.0))1.0 :+ 0.0
>>>foldr (:) [] (1 :+ 2)[1,2]
>>>mapM print (1 :+ 2)1 2
Constructors
| !a :+ !a infix 6 | forms a complex number from its real and imaginary rectangular components. |
Instances
| MonadZip Complex | Since: base-4.15.0.0 | ||||
| Foldable1 Complex | Since: base-4.18.0.0 | ||||
Defined in Data.Foldable1 Methods fold1 :: Semigroup m => Complex m -> m # foldMap1 :: Semigroup m => (a -> m) -> Complex a -> m # foldMap1' :: Semigroup m => (a -> m) -> Complex a -> m # toNonEmpty :: Complex a -> NonEmpty a # maximum :: Ord a => Complex a -> a # minimum :: Ord a => Complex a -> a # foldrMap1 :: (a -> b) -> (a -> b -> b) -> Complex a -> b # foldlMap1' :: (a -> b) -> (b -> a -> b) -> Complex a -> b # foldlMap1 :: (a -> b) -> (b -> a -> b) -> Complex a -> b # foldrMap1' :: (a -> b) -> (a -> b -> b) -> Complex a -> b # | |||||
| Eq1 Complex |
Since: base-4.16.0.0 | ||||
| Read1 Complex |
Since: base-4.16.0.0 | ||||
Defined in Data.Functor.Classes | |||||
| Show1 Complex |
Since: base-4.16.0.0 | ||||
| Applicative Complex | Since: base-4.9.0.0 | ||||
| Functor Complex | Since: base-4.9.0.0 | ||||
| Monad Complex | Since: base-4.9.0.0 | ||||
| MonadFix Complex | Since: base-4.15.0.0 | ||||
Defined in Data.Complex | |||||
| Foldable Complex | Since: base-4.9.0.0 | ||||
Defined in Data.Complex Methods fold :: Monoid m => Complex m -> m # foldMap :: Monoid m => (a -> m) -> Complex a -> m # foldMap' :: Monoid m => (a -> m) -> Complex a -> m # foldr :: (a -> b -> b) -> b -> Complex a -> b # foldr' :: (a -> b -> b) -> b -> Complex a -> b # foldl :: (b -> a -> b) -> b -> Complex a -> b # foldl' :: (b -> a -> b) -> b -> Complex a -> b # foldr1 :: (a -> a -> a) -> Complex a -> a # foldl1 :: (a -> a -> a) -> Complex a -> a # elem :: Eq a => a -> Complex a -> Bool # maximum :: Ord a => Complex a -> a # minimum :: Ord a => Complex a -> a # | |||||
| Traversable Complex | Since: base-4.9.0.0 | ||||
| Generic1 Complex | |||||
Defined in Data.Complex Associated Types
| |||||
| Data a => Data (Complex a) | Since: base-2.1 | ||||
Defined in Data.Complex Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Complex a -> c (Complex a) # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Complex a) # toConstr :: Complex a -> Constr # dataTypeOf :: Complex a -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (Complex a)) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Complex a)) # gmapT :: (forall b. Data b => b -> b) -> Complex a -> Complex a # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Complex a -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Complex a -> r # gmapQ :: (forall d. Data d => d -> u) -> Complex a -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Complex a -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Complex a -> m (Complex a) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Complex a -> m (Complex a) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Complex a -> m (Complex a) # | |||||
| RealFloat a => Floating (Complex a) | Since: base-2.1 | ||||
Defined in Data.Complex Methods exp :: Complex a -> Complex a # log :: Complex a -> Complex a # sqrt :: Complex a -> Complex a # (**) :: Complex a -> Complex a -> Complex a # logBase :: Complex a -> Complex a -> Complex a # sin :: Complex a -> Complex a # cos :: Complex a -> Complex a # tan :: Complex a -> Complex a # asin :: Complex a -> Complex a # acos :: Complex a -> Complex a # atan :: Complex a -> Complex a # sinh :: Complex a -> Complex a # cosh :: Complex a -> Complex a # tanh :: Complex a -> Complex a # asinh :: Complex a -> Complex a # acosh :: Complex a -> Complex a # atanh :: Complex a -> Complex a # log1p :: Complex a -> Complex a # expm1 :: Complex a -> Complex a # | |||||
| Storable a => Storable (Complex a) | Since: base-4.8.0.0 | ||||
Defined in Data.Complex | |||||
| Generic (Complex a) | |||||
Defined in Data.Complex Associated Types
| |||||
| RealFloat a => Num (Complex a) | Since: base-2.1 | ||||
| Read a => Read (Complex a) | Since: base-2.1 | ||||
| RealFloat a => Fractional (Complex a) | Since: base-2.1 | ||||
| Show a => Show (Complex a) | Since: base-2.1 | ||||
| Eq a => Eq (Complex a) | Since: base-2.1 | ||||
| Field (Complex Double) Source # | |||||
| FloatingPoint (Complex Double) Source # | |||||
Defined in HMath.API.Algebra | |||||
| Numeric (Complex Double) Source # | |||||
| Ring (Complex Double) Source # | |||||
| Scalar (Complex Double) Source # | |||||
Defined in HMath.API.Algebra | |||||
| Element (Complex Double) Source # | |||||
| Element (Complex Float) Source # | |||||
| type Rep1 Complex | Since: base-4.9.0.0 | ||||
Defined in Data.Complex type Rep1 Complex = D1 ('MetaData "Complex" "Data.Complex" "base" 'False) (C1 ('MetaCons ":+" ('InfixI 'NotAssociative 6) 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) Par1 :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) Par1)) | |||||
| type Rep (Complex a) | Since: base-4.9.0.0 | ||||
Defined in Data.Complex type Rep (Complex a) = D1 ('MetaData "Complex" "Data.Complex" "base" 'False) (C1 ('MetaCons ":+" ('InfixI 'NotAssociative 6) 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a))) | |||||
Rational
RoundingMode
data RoundingMode Source #
Software rounding direction: nearest-even,toward zero,toward positive infinity,or toward negative infinity. Host CPU rounding mode is unchanged.
Constructors
| NearestEven | |
| TowardZero | |
| TowardPositive | |
| TowardNegative |
Instances
| Show RoundingMode Source # | |
Defined in HMath.Numeric Methods showsPrec :: Int -> RoundingMode -> ShowS # show :: RoundingMode -> String # showList :: [RoundingMode] -> ShowS # | |
| Eq RoundingMode Source # | |
Defined in HMath.Numeric | |
NumericException
data NumericException Source #
Software operation flags: invalid operation,division by zero,overflow,underflow,or inexact conversion.
Instances
| Show NumericException Source # | |
Defined in HMath.Numeric Methods showsPrec :: Int -> NumericException -> ShowS # show :: NumericException -> String # showList :: [NumericException] -> ShowS # | |
| Eq NumericException Source # | |
Defined in HMath.Numeric Methods (==) :: NumericException -> NumericException -> Bool # (/=) :: NumericException -> NumericException -> Bool # | |
Rounded
Rounded numeric result paired with software exception flags. Inspect flags when intentional precision loss matters.
Constructors
| Rounded | |
Fields
| |
roundRational
roundRational :: RoundingMode -> Rational -> Integer Source #
Given software rounding mode then exact Rational, return Integer rounded by nearest-even, toward zero, toward positive infinity, or toward negative infinity. No host rounding flags are changed.
IEEEClass
IEEE classification distinguishing NaN,signed infinity,signed zero,subnormal,and normal finite values.
Instances
classify
classify :: RealFloat a => a -> IEEEClass Source #
Classify a RealFloat value as NaN, signed infinity, signed zero, subnormal, or normal. Signed zero is distinguished with isNegativeZero.
NumericLimits
data NumericLimits a Source #
Format limits and precision metadata derived from RealFloat or the explicit 16-bit format definition.
Constructors
| NumericLimits | |
Fields
| |
Instances
| Show a => Show (NumericLimits a) Source # | |
Defined in HMath.Numeric Methods showsPrec :: Int -> NumericLimits a -> ShowS # show :: NumericLimits a -> String # showList :: [NumericLimits a] -> ShowS # | |
| Eq a => Eq (NumericLimits a) Source # | |
Defined in HMath.Numeric Methods (==) :: NumericLimits a -> NumericLimits a -> Bool # (/=) :: NumericLimits a -> NumericLimits a -> Bool # | |
numericLimits
numericLimits :: RealFloat a => a -> NumericLimits a Source #
Derived from RealFloat radixdigitsrange, not hardcoded for Double.
integerLimits
integerLimits :: (Integral a, Bounded a) => a -> (Integer, Integer) Source #
Given a bounded integral type witness, return its exact (minimum,maximum) as Integers. The witness value is used only to select the type.
float16Limits
float16Limits :: NumericLimits Double Source #
Limits returned as exact binary64 values for the two 16-bit storage formats.
bfloat16Limits
bfloat16Limits :: NumericLimits Double Source #
Limits returned as exact binary64 values for the two 16-bit storage formats.
nextAfter
nextAfter :: RealFloat a => a -> a -> a Source #
Adjacent representable value toward target, including gradual underflow. Equal signed zeros return the target; NaN propagates. Supports binary formats.
frexp
frexp :: RealFloat a => a -> (a, Int) Source #
x=m*2^e, with abs m in [1/2,1) for nonzero finite binary inputs.
ldexp
ldexp :: RealFloat a => a -> Int -> a Source #
Given real value then Int exponent, scale by the numeric radix to that power using scaleFloat (binary types use powers of two). IEEE overflow/underflow follows the host type; no Either check is added.
ulpDistance
ulpDistance :: Double -> Double -> Either MathError Integer Source #
IEEE binary64 distance. Signed zeros compare equal; NaN is rejected.
withinULPs
withinULPs :: Integer -> Double -> Double -> Bool Source #
Given nonnegative allowed ULP distance then two Doubles, test their binary64 representable-value distance. Signed zeros compare equal. Negative tolerance or NaN gives False.
safeIntegralCast
safeIntegralCast :: (Integral a, Integral b, Bounded b) => a -> Either MathError b Source #
Convert an integral value to a bounded integral destination only if in range. Return Left DomainError rather than wrap or truncate out-of-range input.
saturatingCast
saturatingCast :: (Integral a, Integral b, Bounded b) => a -> b Source #
Convert an integral value to a bounded integral destination, clamping to minBound/maxBound when out of range. No error result is produced.
realToIntegral
realToIntegral :: (RealFloat a, Integral b, Bounded b) => RoundingMode -> a -> Either MathError b Source #
Given software rounding mode then finite real value, round exactly through Rational then range-check the bounded integral destination. Non-finite or out-of-range input returns Left DomainError.
narrowFloat
narrowFloat :: (RealFloat a, RealFloat b) => a -> Either MathError b Source #
A narrowing conversion must be finite and exact; choose explicit quantized Float16/BigFloat rounding APIs when loss of precision is intentional.
Float16
IEEE binary16 and bfloat16 storage. Conversion rounds directly from the exact binary64 value (no intermediate binary32 rounding), preserving signed zero and infinity. NaNs are canonical quiet NaNs. All four rounding modes report inexact, overflow and tininess-after-rounding underflow flags.
float16
float16 :: RoundingMode -> Double -> Rounded Float16 Source #
Given rounding mode then Double, round directly to IEEE binary16 and return Rounded storage plus software flags. Preserve signed zero/infinity; canonicalize NaN. Flags report inexact, overflow, and tininess-after-rounding underflow.
fromFloat16
fromFloat16 :: Float16 -> Double Source #
Decode binary16 storage to Double, preserving finite values, signed zero, infinity and NaN classification. Every finite binary16 value is exactly representable as Double.
float16Bits
float16Bits :: Float16 -> Word16 Source #
Return raw IEEE binary16 storage bits, including sign, exponent and fraction, as Word16.
float16FromBits
float16FromBits :: Word16 -> Float16 Source #
Construct binary16 storage from raw Word16 without validation or rounding; all bit patterns, including NaNs, are representable.
BFloat16
Opaque bfloat16 storage with 8 exponent and 7 explicit fraction bits. Use bfloat16 for rounded conversion or bfloat16FromBits for exact storage construction.
bfloat16
bfloat16 :: RoundingMode -> Double -> Rounded BFloat16 Source #
Given rounding mode then Double, round directly to bfloat16 without an intermediate binary32 rounding. Return Rounded storage and software flags, preserving signed zero/infinity and canonicalizing NaN.
fromBFloat16
fromBFloat16 :: BFloat16 -> Double Source #
Decode bfloat16 storage to Double, preserving finite values, signed zero and non-finite classification.
bfloat16FromBits
bfloat16FromBits :: Word16 -> BFloat16 Source #
Construct bfloat16 storage from raw Word16 without conversion; all bit patterns are retained.
BigFloat
An unbounded-exponent binary floating value backed by an exact Rational,
rounded to a runtime number of significant bits (2..1,000,000). Unlike Double,
this is genuinely configurable precision. No NaN/infinity or hidden CPU flags.
Algebraic operations round once, nearest-even; explicit construction can select
any RoundingMode. Transcendentals use guard bits and rational series.
bigFloat
bigFloat :: Int -> RoundingMode -> Rational -> Either MathError (Rounded BigFloat) Source #
Given precision in [2,1000000] bits, rounding mode, then Rational, construct configurable-precision BigFloat plus Inexact flag if rounded. Invalid precision returns Left InvalidArgument. Exponents are unbounded; no IEEE NaN/infinity is stored.
bigPrecision
bigPrecision :: BigFloat -> Int Source #
Return the runtime number of significant binary bits retained by a BigFloat.
bigRational
bigRational :: BigFloat -> Rational Source #
Return the exact Rational value of the already-rounded BigFloat, without another conversion or rounding.
bigToDouble
bigToDouble :: BigFloat -> Double Source #
Round BigFloat to host Double through fromRational. This may overflow/underflow or lose precision; it returns no software flags or Either validation.
bigAdd
bigAdd :: BigFloat -> BigFloat -> Either MathError BigFloat Source #
Add two BigFloats exactly then round once to the larger operand precision, nearest-even. Return the new BigFloat in Either.
bigSubtract
bigSubtract :: BigFloat -> BigFloat -> Either MathError BigFloat Source #
Subtract the second BigFloat from the first, rounding once nearest-even at the larger operand precision.
bigMultiply
bigMultiply :: BigFloat -> BigFloat -> Either MathError BigFloat Source #
Multiply two BigFloats exactly then round once nearest-even to the larger operand precision.
bigDivide
bigDivide :: BigFloat -> BigFloat -> Either MathError BigFloat Source #
Divide two BigFloats and round once nearest-even to the larger precision. Zero divisor returns Left DomainError.
bigSqrt
bigSqrt :: BigFloat -> Either MathError BigFloat Source #
Compute nonnegative BigFloat square root using integer/rational guard precision then round to the input precision. Negative input returns Left DomainError; zero succeeds.
bigExp
bigExp :: BigFloat -> Either MathError BigFloat Source #
Absolute tail controlled rational series; final rounding is accurate to the requested precision up to one final ulp, not a correctly-rounded promise.
bigLog
bigLog :: BigFloat -> Either MathError BigFloat Source #
Compute natural logarithm at the BigFloat precision using rational series and guard bits. Require positive input; invalid domain/resource limits return Left MathError. Final rounding has the module's documented accuracy limits.
extended
extended :: Rational -> Either MathError BigFloat Source #
Software extended precision: 64 significant bits, unbounded exponent.
mixedAdd
mixedAdd :: BigFloat -> Double -> Either MathError BigFloat Source #
Given BigFloat then finite Double, add via exact Rational intermediates at max(BigFloat precision,53) bits, nearest-even. Non-finite Double fails.
mixedMultiply
mixedMultiply :: BigFloat -> Double -> Either MathError BigFloat Source #
Given BigFloat then finite Double, multiply at max(BigFloat precision,53) bits using exact intermediates and nearest-even. Non-finite Double fails.
Fixed
Runtime-scale base-ten fixed point: coefficient * 10^(-scale). All constructors and arithmetic use explicit rounding and report inexactness.
fixed
fixed :: Int -> RoundingMode -> Rational -> Either MathError (Rounded Fixed) Source #
Given decimal scale in [0,10000], rounding mode, then Rational, return Rounded Fixed and Inexact when required. Invalid scale fails. This scale counts decimal fractional places, not significant digits.
fixedScale
fixedScale :: Fixed -> Int Source #
Return nonnegative decimal scale s of a Fixed value; its exact value is coefficient / 10^s.
fixedCoefficient
fixedCoefficient :: Fixed -> Integer Source #
Return exact stored Integer coefficient of a Fixed value, before division by 10^fixedScale.
fixedRational
fixedRational :: Fixed -> Rational Source #
Return exact coefficient/10^scale represented by a Fixed value, without rounding.
fixedAdd
fixedAdd :: Fixed -> Fixed -> Either MathError (Rounded Fixed) Source #
Add two Fixed values using the larger decimal scale, nearest-even, returning Rounded result and software flags.
fixedMultiply
fixedMultiply :: RoundingMode -> Fixed -> Fixed -> Either MathError (Rounded Fixed) Source #
Given rounding mode then two Fixed values, multiply and round to their larger scale, returning Rounded result and flags.
fixedDivide
fixedDivide :: RoundingMode -> Fixed -> Fixed -> Either MathError (Rounded Fixed) Source #
Given rounding mode then Fixed numerator and denominator, divide and round to their larger scale. Zero divisor returns Left DomainError; successful rounding flags are retained.
Decimal
Opaque decimal fixed-point value with fractional-place scale, built through decimal with explicit rounding. This is not an implicit significant-digit decimal context.
decimal
decimal :: Int -> RoundingMode -> Rational -> Either MathError (Rounded Decimal) Source #
Given decimal fractional-place scale, rounding mode, then Rational, construct Rounded Decimal through fixed. Scale must lie in [0,10000]; no significant-digit interpretation is implied.
decimalRational
decimalRational :: Decimal -> Rational Source #
Return exact Rational value stored in a Decimal without further rounding.
decimalAdd
decimalAdd :: Decimal -> Decimal -> Either MathError (Rounded Decimal) Source #
Add two Decimals at their larger decimal scale, nearest-even, returning Rounded result and software flags.
decimalMultiply
decimalMultiply :: RoundingMode -> Decimal -> Decimal -> Either MathError (Rounded Decimal) Source #
Given rounding mode then two Decimals, multiply at the larger fractional-place scale and return Rounded result with flags.
decimalDivide
decimalDivide :: RoundingMode -> Decimal -> Decimal -> Either MathError (Rounded Decimal) Source #
Given rounding mode then two Decimals, divide at their larger scale and return Rounded result. Zero divisor returns Left DomainError.
Interval
Finite closed binary64 intervals. Arithmetic endpoints are rounded outward using exact rationals, so results enclose exact real arithmetic. Unbounded output is rejected; division rejects denominators containing zero.
interval
interval :: Double -> Double -> Either MathError Interval Source #
Given finite lower and upper bounds in increasing order, construct a closed binary64 Interval. Reversed or non-finite bounds fail. Equal endpoints are valid.
intervalBounds
intervalBounds :: Interval -> (Double, Double) Source #
Return (lower,upper) binary64 endpoints of a validated closed interval.
intervalAdd
intervalAdd :: Interval -> Interval -> Either MathError Interval Source #
Add finite intervals with exact Rational endpoint arithmetic rounded outward, enclosing the exact sum. Results requiring unbounded endpoints fail.
intervalSubtract
intervalSubtract :: Interval -> Interval -> Either MathError Interval Source #
Subtract intervals with endpoints [a-d,b-c], rounding outward. Non-finite/unbounded resulting endpoints return Left MathError.
intervalMultiply
intervalMultiply :: Interval -> Interval -> Either MathError Interval Source #
Multiply intervals using the minimum/maximum of all four endpoint products and outward rounding. Reject unbounded output.
intervalDivide
intervalDivide :: Interval -> Interval -> Either MathError Interval Source #
Divide intervals using endpoint quotients with outward rounding. A divisor interval containing zero returns Left DomainError; unbounded output also fails.
intervalContains
intervalContains :: Interval -> Double -> Bool Source #
Given interval then Double, test closed-bound membership lower<=x<=upper. NaN comparisons give False.
Dual
Forward-mode automatic differentiation, f(a+b epsilon), epsilon^2=0. Elementary functions follow host IEEE domains; checked algorithms can inspect both components. abs at zero uses derivative zero (a chosen subgradient).
Constructors
| Dual | |
Instances
| Floating a => Floating (Dual a) Source # | |
| Num a => Num (Dual a) Source # | |
| Fractional a => Fractional (Dual a) Source # | |
| Show a => Show (Dual a) Source # | |
| Eq a => Eq (Dual a) Source # | |
derivative
derivative :: Num a => (Dual a -> Dual a) -> a -> a Source #
Given a function on Dual numbers then primal input x, seed Dual x 1 and extract the output tangent. Arithmeticdomains follow Dual's NumFloating instances; no Either validation is added.
Quaternion
data Quaternion a Source #
Hamilton quaternion (real, i, j, k); multiplication is noncommutative.
Constructors
| Quaternion a a a a |
Instances
| RealFloat a => Num (Quaternion a) Source # | |
Defined in HMath.Numeric Methods (+) :: Quaternion a -> Quaternion a -> Quaternion a # (-) :: Quaternion a -> Quaternion a -> Quaternion a # (*) :: Quaternion a -> Quaternion a -> Quaternion a # negate :: Quaternion a -> Quaternion a # abs :: Quaternion a -> Quaternion a # signum :: Quaternion a -> Quaternion a # fromInteger :: Integer -> Quaternion a # | |
| Show a => Show (Quaternion a) Source # | |
Defined in HMath.Numeric Methods showsPrec :: Int -> Quaternion a -> ShowS # show :: Quaternion a -> String # showList :: [Quaternion a] -> ShowS # | |
| Eq a => Eq (Quaternion a) Source # | |
Defined in HMath.Numeric | |
quaternionConjugate
quaternionConjugate :: Num a => Quaternion a -> Quaternion a Source #
For Quaternion real i j k, negate the three imaginary components and preserve the real part.
quaternionNorm
quaternionNorm :: RealFloat a => Quaternion a -> a Source #
Return scaled Euclidean norm of four quaternion components, reducing avoidable intermediate overflow. Empty/zero-component quaternion has norm zero.
quaternionInverse
quaternionInverse :: RealFloat a => Quaternion a -> Either MathError (Quaternion a) Source #
Invert a finite nonzero quaternion using scaled norm arithmetic. Zero/non-finite input returns DomainError; non-finite inverse returns NonFiniteResult.
rotateVector
rotateVector :: RealFloat a => Quaternion a -> (a, a, a) -> Either MathError (a, a, a) Source #
Given nonzero finite quaternion q then (x,y,z), return imaginary part of q*(0,x,y,z)*inverse(q). Normalization of q is implicit in the inverse; invalid input/result returns Left MathError.
DualQuaternion
data DualQuaternion a Source #
Real and dual quaternion pair, commonly representing a rigid rotation/translation. Construct normalized rigid transforms with rigidTransform.
Constructors
| DualQuaternion (Quaternion a) (Quaternion a) |
Instances
| Show a => Show (DualQuaternion a) Source # | |
Defined in HMath.Numeric Methods showsPrec :: Int -> DualQuaternion a -> ShowS # show :: DualQuaternion a -> String # showList :: [DualQuaternion a] -> ShowS # | |
| Eq a => Eq (DualQuaternion a) Source # | |
Defined in HMath.Numeric Methods (==) :: DualQuaternion a -> DualQuaternion a -> Bool # (/=) :: DualQuaternion a -> DualQuaternion a -> Bool # | |
dualQuaternionMultiply
dualQuaternionMultiply :: RealFloat a => DualQuaternion a -> DualQuaternion a -> DualQuaternion a Source #
Multiply real/dual quaternion pairs as (a,b)*(c,d)=(a*c,a*d+b*c). Return the product using host quaternion arithmetic; no validation or normalization is added.
dualQuaternionInverse
dualQuaternionInverse :: RealFloat a => DualQuaternion a -> Either MathError (DualQuaternion a) Source #
Invert the real quaternion a, returning (inverse(a), -inverse(a)*b*inverse(a)). Invalid real part propagates quaternionInverse failure.
rigidTransform
rigidTransform :: RealFloat a => Quaternion a -> (a, a, a) -> Either MathError (DualQuaternion a) Source #
Construct a rigid transform from a nonzero rotation quaternion and translation.
transformPoint
transformPoint :: RealFloat a => DualQuaternion a -> (a, a, a) -> Either MathError (a, a, a) Source #
Given dual-quaternion transform then point tuple, rotate by its real part and add translation from twice the dual part times the real inverse. Invalid inverse or non-finite result fails.
kahanSum
kahanSum :: Num a => [a] -> a Source #
Sum a finite list using Kahan compensation; empty input yields zero. Arithmetic follows Num and compensation does not promise exact rounding or reject non-finite values.
neumaierSum
neumaierSum :: (Num a, Ord a) => [a] -> a Source #
Sum a finite list with Neumaier compensation, correcting for differing term magnitudes. Empty input gives zero; arithmetic follows the chosen ordered Num type.
pairwiseSum
pairwiseSum :: Num a => [a] -> a Source #
Recursively split and sum a finite list to reduce sequential rounding accumulation. Empty input gives zero. Arithmetic remains that of the chosen Num type.
logsumexp
logsumexp :: RealFloat a => [a] -> Either MathError a Source #
Empty input is -infinity; +infinity dominates finite/-infinite inputs. NaN is rejected, and an all -infinity input is -infinity.
sumErrorBound
sumErrorBound :: RealFloat a => [a] -> Either MathError a Source #
Conservative sequential sum bound gamma_(n-1) * sum abs x. Returns infinity when n*u >= 1 or finite inputs overflow the bound. Does not claim bounds in the presence of underflow; an extra (n-1)*minimumSubnormal term covers it.