HMath.Scalar¶
Module index · Numerical conventions
Description
Scalar utilities. Generic Num arithmetic follows the chosen numeric type.
Checked real operations require finite inputs and report domain failures and
finite-result overflow explicitly. Exact combinatorics use Integer.
expm1/log1p use convergent series near zero to avoid cancellation; their target
is a few ulps for ordinary IEEE binary32/64 inputs, not correct rounding.
On this page¶
| API | Purpose |
|---|---|
| add | Add two values using their Num instance. |
| subtractScalar | Subtract the second value from the first using Num arithmetic. |
| multiply | Multiply two values using Num arithmetic. |
| divide | Divide the first finite real value by the second. |
| quotientRemainder | Return integer quotient and remainder using quotRem (quotient truncates toward zero). |
| euclideanDivision | Euclidean remainder satisfies 0 <= r < abs divisor, for either divisor sign. |
| absolute | Return abs using the supplied Num instance, including that instance's overflow behavior. |
| sign | Return signum using the supplied Num instance. |
| minimumScalar | Return the smaller of two values under their Ord instance. |
| maximumScalar | Return the larger of two values under their Ord instance. |
| clampChecked | Given lower bound, upper bound, then value, clamp to the closed interval. |
| lerpChecked | Uses exact rational interpolation followed by one rounding. |
| inverseLerp | Given endpoints a,b then value x, return (x-a)/(b-a) using rational intermediates and one conversion. |
| remap | Given source endpoints a,b, destination endpoints c,d, then x, map x from the source interval to the destination interval. |
| step | Given edge then x, return 0 below the edge and 1 at/above it. |
| smoothstep | Given strictly increasing edges then x, clamp t=(x-a)/(b-a) to [0,1] and return tt(3-2*t). |
| smootherstep | Given increasing edges then x, apply the quintic 6t^5-15t^4+10t^3 to the clamped interpolation parameter. |
| power | Raise a finite real base to a finite real exponent using (**). |
| integerPower | Raise a finite real base to an Integer exponent, allowing negative powers except for a zero base. |
| modularPower | Given base, nonnegative exponent, positive modulus, compute modular exponentiation by squaring. |
| sqrtChecked | Return the nonnegative square root of a finite nonnegative input; reject negatives/non-finite values. |
| cubeRoot | Return the signed real cube root of a finite input, including negative values, through nthRoot 3. |
| nthRoot | Given positive integer degree n then finite x, return its signed real n-th root. |
| reciprocalSqrt | Return 1sqrt(x) for finite strictly positive x. |
| expChecked | Compute exp of a finite input, reporting non-finite output as Left NonFiniteResult. |
| logChecked | Compute the natural logarithm of finite positive x. |
| expm1 | Compute exp(x)-1, using a convergent series near zero to reduce cancellation. |
| log1p | Compute log(1+x), using a series near zero. |
| hypot | Return sqrt(aa+bb) with scaling to avoid avoidable intermediate overflow. |
| floorChecked | Convert a finite real to the greatest Integer no larger than it. |
| ceilChecked | Convert a finite real to the least Integer no smaller than it. |
| roundChecked | Round a finite real to Integer with ties to even, as bankersRound. |
| truncateChecked | Convert finite real to Integer toward zero. |
| bankersRound | Round a finite real to nearest Integer, resolving exact half ties to even. |
| roundDigits | Decimal-place rounding with exact rational scaling and ties to even. |
| integerFraction | Split finite x into its truncated Integer and signed fractional remainder. |
| positiveModulo | Given integral value then strictly positive modulus, return the nonnegative remainder. |
| absoluteError | Given actual then expected finite values, return abs(actual-expected); reject non-finite input/result. |
| relativeError | Given actual then expected, return absolute error divided by abs(expected). |
| factorialChecked | Return exact n! for nonnegative Integer n; negatives fail with DomainError. |
| doubleFactorial | Return n(n-2)... exactly for n >= 0; (-1)!! is also 1. |
| risingFactorial | Given integer x then nonnegative length n, return x(x+1)...*(x+n-1). |
| fallingFactorial | Given integer x then nonnegative length n, return x(x-1)...*(x-n+1). |
| fibonacciChecked | Return exact zero-based Fibonacci number using fast doubling (F0=0,F1=1). |
| lucas | Return exact zero-based Lucas number (L0=2,L1=1). |
| permutations | Given nonnegative n,k, return n!/(n-k)!; k>n gives zero. |
| combinations | Given nonnegative n,k, return the exact binomial coefficient; k>n gives zero. |
| multinomial | Given nonnegative group sizes, return factorial(sum sizes)/product(factorial sizes). |
| catalan | Return exact n-th Catalan number for nonnegative Integer n; negative input fails. |
| bernoulli | Bernoulli convention B1 = -1/2. |
| harmonic | Return exact Rational sum 1+12+...+1n; n=0 gives 0 and negatives fail. |
| cumulativeSum | Return inclusive running sums without a leading zero; output has input length. |
| cumulativeProduct | Return inclusive running products without a leading one. |
| prefixSum | Return running sums including a leading zero; output length is input length plus one. |
| fusedMultiplyAdd | Software single-rounding FMA for finite inputs using exact Rational. |
| saturatingAdd | Add bounded integers through an exact Integer intermediate and clamp to the destination minBound/maxBound. |
| saturatingSubtract | Subtract bounded integers through Integer and clamp to type bounds instead of wrapping. |
| saturatingMultiply | Multiply bounded integers through Integer and clamp to type bounds instead of wrapping. |
| checkedAdd | Add bounded integers using an exact intermediate. |
| checkedSubtract | Subtract bounded integers using an exact intermediate, returning Left DomainError on underflow/overflow. |
| checkedMultiply | Multiply bounded integers using an exact intermediate and reject out-of-range results. |
| checkedFloatMultiply | Report finite overflow and any nonzero exact product rounded to zero. |
Documentation
add
add :: Num a => a -> a -> a Source #
Add two values using their Num instance. No overflow check is added; bounded integral types retain their usual arithmetic behavior. Example: add 2 3 == 5.
subtractScalar
subtractScalar :: Num a => a -> a -> a Source #
Subtract the second value from the first using Num arithmetic. Example: subtractScalar 5 2 == 3; use checkedSubtract to reject bounded integer overflow.
multiply
multiply :: Num a => a -> a -> a Source #
Multiply two values using Num arithmetic. Example: multiply 3 4 == 12; use checkedMultiply or checkedFloatMultiply for explicit overflow checks.
divide
divide :: RealFloat a => a -> a -> Either MathError a Source #
Divide the first finite real value by the second. Return Left DomainError for non-finite input or a zero divisor, and Left NonFiniteResult for overflow. Example: divide 6 2 == Right 3.
quotientRemainder
quotientRemainder :: Integer -> Integer -> Either MathError (Integer, Integer) Source #
Return integer quotient and remainder using quotRem (quotient truncates toward zero). A zero divisor returns Left DomainError. Example: quotientRemainder (-7) 3 == Right (-2,-1).
euclideanDivision
euclideanDivision :: Integer -> Integer -> Either MathError (Integer, Integer) Source #
Euclidean remainder satisfies 0 <= r < abs divisor, for either divisor sign.
absolute
absolute :: Num a => a -> a Source #
Return abs using the supplied Num instance, including that instance's overflow behavior. Example: absolute (-3) == 3.
sign
sign :: Num a => a -> a Source #
Return signum using the supplied Num instance. Example: sign (-3) == -1; sign 0 == 0.
minimumScalar
minimumScalar :: Ord a => a -> a -> a Source #
Return the smaller of two values under their Ord instance. Example: minimumScalar 2 5 == 2.
maximumScalar
maximumScalar :: Ord a => a -> a -> a Source #
Return the larger of two values under their Ord instance. Example: maximumScalar 2 5 == 5.
clampChecked
clampChecked :: RealFloat a => a -> a -> a -> Either MathError a Source #
Given lower bound, upper bound, then value, clamp to the closed interval. Non-finite inputs or reversed bounds return Left DomainError. Example: clampChecked 0 1 2 == Right 1.
lerpChecked
lerpChecked :: RealFloat a => a -> a -> a -> Either MathError a Source #
Uses exact rational interpolation followed by one rounding. Extrapolation is allowed; finite overflow is reported instead of silently producing infinity.
inverseLerp
inverseLerp :: RealFloat a => a -> a -> a -> Either MathError a Source #
Given endpoints a,b then value x, return (x-a)/(b-a) using rational intermediates and one conversion. Equal endpoints/non-finite inputs fail; extrapolation is allowed. Example: inverseLerp 10 20 15 == Right 0.5.
remap
remap :: RealFloat a => a -> a -> a -> a -> a -> Either MathError a Source #
Given source endpoints a,b, destination endpoints c,d, then x, map x from the source interval to the destination interval. Extrapolation is allowed. Fails on equal source endpoints, non-finite input/result. Example: remap 0 10 0 100 5 == Right 50.
step
step :: RealFloat a => a -> a -> Either MathError a Source #
Given edge then x, return 0 below the edge and 1 at/above it. Non-finite inputs return Left DomainError. Example: step 2 2 == Right 1.
smoothstep
smoothstep :: RealFloat a => a -> a -> a -> Either MathError a Source #
Given strictly increasing edges then x, clamp t=(x-a)/(b-a) to [0,1] and return t*t*(3-2*t). Invalid edges/non-finite values fail. Example: smoothstep 0 1 0.5 == Right 0.5.
smootherstep
smootherstep :: RealFloat a => a -> a -> a -> Either MathError a Source #
Given increasing edges then x, apply the quintic 6t^5-15t^4+10t^3 to the clamped interpolation parameter. Invalid edges/non-finite values fail. Example: smootherstep 0 1 0.5 == Right 0.5.
power
power :: RealFloat a => a -> a -> Either MathError a Source #
Raise a finite real base to a finite real exponent using (**). Non-real/domain results and overflow return Left NonFiniteResult; non-finite input fails. Example: power 2 3 == Right 8.
integerPower
integerPower :: RealFloat a => a -> Integer -> Either MathError a Source #
Raise a finite real base to an Integer exponent, allowing negative powers except for a zero base. Invalid zero reciprocal/non-finite input fails; overflow is NonFiniteResult. Example: integerPower 2 (-2) == Right 0.25.
modularPower
modularPower :: Integer -> Integer -> Integer -> Either MathError Integer Source #
Given base, nonnegative exponent, positive modulus, compute modular exponentiation by squaring. Invalid exponent/modulus returns Left DomainError. Example: modularPower 2 10 1000 == Right 24.
sqrtChecked
sqrtChecked :: RealFloat a => a -> Either MathError a Source #
Return the nonnegative square root of a finite nonnegative input; reject negatives/non-finite values. Example: sqrtChecked 9 == Right 3.
cubeRoot
cubeRoot :: RealFloat a => a -> Either MathError a Source #
Return the signed real cube root of a finite input, including negative values, through nthRoot 3. Example: cubeRoot (-8) is approximately Right (-2).
nthRoot
nthRoot :: RealFloat a => Int -> a -> Either MathError a Source #
Given positive integer degree n then finite x, return its signed real n-th root. Even roots of negative x and nonpositive degrees fail. Example: nthRoot 3 (-8) is approximately Right (-2).
reciprocalSqrt
reciprocalSqrt :: RealFloat a => a -> Either MathError a Source #
Return 1sqrt(x) for finite strictly positive x. Zeronegative/non-finite inputs fail, as does a non-finite result. Example: reciprocalSqrt 4 == Right 0.5.
expChecked
expChecked :: RealFloat a => a -> Either MathError a Source #
Compute exp of a finite input, reporting non-finite output as Left NonFiniteResult. Finite underflow to zero is allowed. Example: expChecked 0 == Right 1.
logChecked
logChecked :: RealFloat a => a -> Either MathError a Source #
Compute the natural logarithm of finite positive x. Zeronegativenon-finite input fails. Example: logChecked 1 == Right 0.
expm1
expm1 :: RealFloat a => a -> Either MathError a Source #
Compute exp(x)-1, using a convergent series near zero to reduce cancellation. Reject non-finite input/output; preserve signed zero. Example: expm1 0 == Right 0. This is not a correct-rounding guarantee.
log1p
log1p :: RealFloat a => a -> Either MathError a Source #
Compute log(1+x), using a series near zero. Require finite x greater than -1; preserve signed zero and reject non-finite output. Example: log1p 0 == Right 0.
hypot
hypot :: RealFloat a => a -> a -> Either MathError a Source #
Return sqrt(a*a+b*b) with scaling to avoid avoidable intermediate overflow. Require finite inputs and result. Example: hypot 3 4 == Right 5.
floorChecked
floorChecked :: RealFloat a => a -> Either MathError Integer Source #
Convert a finite real to the greatest Integer no larger than it. Non-finite input fails. Example: floorChecked (-1.2) == Right (-2).
ceilChecked
ceilChecked :: RealFloat a => a -> Either MathError Integer Source #
Convert a finite real to the least Integer no smaller than it. Non-finite input fails. Example: ceilChecked 1.2 == Right 2.
roundChecked
roundChecked :: RealFloat a => a -> Either MathError Integer Source #
Round a finite real to Integer with ties to even, as bankersRound. Non-finite input fails. Example: roundChecked 2.5 == Right 2.
truncateChecked
truncateChecked :: RealFloat a => a -> Either MathError Integer Source #
Convert finite real to Integer toward zero. Non-finite input fails. Example: truncateChecked (-1.8) == Right (-1).
bankersRound
bankersRound :: RealFloat a => a -> Either MathError Integer Source #
Round a finite real to nearest Integer, resolving exact half ties to even. Non-finite input fails. Example: bankersRound 3.5 == Right 4.
roundDigits
roundDigits :: RealFloat a => Int -> a -> Either MathError a Source #
Decimal-place rounding with exact rational scaling and ties to even. Negative digits round to tens, hundreds, etc. Digits are bounded to avoid huge allocation.
integerFraction
integerFraction :: RealFloat a => a -> Either MathError (Integer, a) Source #
Split finite x into its truncated Integer and signed fractional remainder. Non-finite input fails. Example: integerFraction (-1.5) == Right (-1,-0.5).
positiveModulo
positiveModulo :: Integral a => a -> a -> Either MathError a Source #
Given integral value then strictly positive modulus, return the nonnegative remainder. Nonpositive modulus fails. Example: positiveModulo (-1) 5 == Right 4.
absoluteError
absoluteError :: RealFloat a => a -> a -> Either MathError a Source #
Given actual then expected finite values, return abs(actual-expected); reject non-finite input/result. Example: absoluteError 3 2 == Right 1.
relativeError
relativeError :: RealFloat a => a -> a -> Either MathError a Source #
Given actual then expected, return absolute error divided by abs(expected). Expected must be nonzero and inputs/results finite. Example: relativeError 3 2 == Right 0.5.
factorialChecked
factorialChecked :: Integer -> Either MathError Integer Source #
Return exact n! for nonnegative Integer n; negatives fail with DomainError. Example: factorialChecked 5 == Right 120. No fixed-size arithmetic overflow occurs.
doubleFactorial
doubleFactorial :: Integer -> Either MathError Integer Source #
Return n*(n-2)*... exactly for n >= 0; (-1)!! is also 1. Other negative n fail. Example: doubleFactorial 5 == Right 15.
risingFactorial
risingFactorial :: Integer -> Integer -> Either MathError Integer Source #
Given integer x then nonnegative length n, return x*(x+1)*...*(x+n-1). Negative length fails; length zero gives 1. Example: risingFactorial 3 2 == Right 12.
fallingFactorial
fallingFactorial :: Integer -> Integer -> Either MathError Integer Source #
Given integer x then nonnegative length n, return x*(x-1)*...*(x-n+1). Negative length fails; length zero gives 1. Example: fallingFactorial 3 2 == Right 6.
fibonacciChecked
fibonacciChecked :: Integer -> Either MathError Integer Source #
Return exact zero-based Fibonacci number using fast doubling (F0=0,F1=1). Negative index fails. Example: fibonacciChecked 10 == Right 55.
lucas
lucas :: Integer -> Either MathError Integer Source #
Return exact zero-based Lucas number (L0=2,L1=1). Negative index fails. Example: lucas 5 == Right 11.
permutations
permutations :: Integer -> Integer -> Either MathError Integer Source #
Given nonnegative n,k, return n!/(n-k)!; k>n gives zero. Negative inputs fail. Example: permutations 4 2 == Right 12.
combinations
combinations :: Integer -> Integer -> Either MathError Integer Source #
Given nonnegative n,k, return the exact binomial coefficient; k>n gives zero. Negative inputs fail. Example: combinations 4 2 == Right 6.
multinomial
multinomial :: [Integer] -> Either MathError Integer Source #
Given nonnegative group sizes, return factorial(sum sizes)/product(factorial sizes). Negative entries fail. Example: multinomial [2,1] == Right 3.
catalan
catalan :: Integer -> Either MathError Integer Source #
Return exact n-th Catalan number for nonnegative Integer n; negative input fails. Example: catalan 3 == Right 5.
bernoulli
bernoulli :: Int -> Either MathError Rational Source #
Bernoulli convention B1 = -1/2. Akiyama-Tanigawa exact rational recurrence.
harmonic
harmonic :: Integer -> Either MathError Rational Source #
Return exact Rational sum 1+12+...+1n; n=0 gives 0 and negatives fail. Example: harmonic 2 == Right (3/2).
cumulativeSum
cumulativeSum :: Num a => [a] -> [a] Source #
Return inclusive running sums without a leading zero; output has input length. Arithmetic follows Num. Example: cumulativeSum [1,2,3] == [1,3,6].
cumulativeProduct
cumulativeProduct :: Num a => [a] -> [a] Source #
Return inclusive running products without a leading one. Arithmetic follows Num. Example: cumulativeProduct [2,3,4] == [2,6,24].
prefixSum
prefixSum :: Num a => [a] -> [a] Source #
Return running sums including a leading zero; output length is input length plus one. Example: prefixSum [1,2] == [0,1,3].
fusedMultiplyAdd
fusedMultiplyAdd :: RealFloat a => a -> a -> a -> Either MathError a Source #
Software single-rounding FMA for finite inputs using exact Rational. This
avoids intermediate overflow and cancellation; it does not change CPU flags.
saturatingAdd
saturatingAdd :: (Integral a, Bounded a) => a -> a -> a Source #
Add bounded integers through an exact Integer intermediate and clamp to the destination minBound/maxBound. Example: saturatingAdd (127 :: Int8) 1 == 127.
saturatingSubtract
saturatingSubtract :: (Integral a, Bounded a) => a -> a -> a Source #
Subtract bounded integers through Integer and clamp to type bounds instead of wrapping. Example: saturatingSubtract (0 :: Word8) 1 == 0.
saturatingMultiply
saturatingMultiply :: (Integral a, Bounded a) => a -> a -> a Source #
Multiply bounded integers through Integer and clamp to type bounds instead of wrapping. Example: saturatingMultiply (100 :: Int8) 2 == 127.
checkedAdd
checkedAdd :: (Integral a, Bounded a) => a -> a -> Either MathError a Source #
Add bounded integers using an exact intermediate. Out-of-range results return Left DomainError, never wrap. Example: checkedAdd (2 :: Int8) 3 == Right 5.
checkedSubtract
checkedSubtract :: (Integral a, Bounded a) => a -> a -> Either MathError a Source #
Subtract bounded integers using an exact intermediate, returning Left DomainError on underflow/overflow. Example: checkedSubtract (0 :: Word8) 1 fails.