From ab5607392bbe03930f5d19003dee10bd5b9aae28 Mon Sep 17 00:00:00 2001 From: jmh530 Date: Mon, 12 Oct 2026 19:01:57 -0400 Subject: [PATCH 1/5] Preserve extended precision in negative-binomial probabilities Validate Fp probabilities from their represented value and form 1-p with integer significand arithmetic. Avoid rounding through double, which could turn a probability just below one into one and discard a positive mass. Build coefficients at the requested Fp width without narrowing success counts to uint or overflowing k+r-1. Use exact ulong coefficients for small counts and symmetric numerator/denominator products for larger counts. Divide their integer significands with guard bits instead of using Fp division, which currently converts through hardware real. Replace linear fp_powi multiplication with exponentiation by squaring so large exponents remain practical. Avoid an unused final square and retain the zero-exponent identity. Document rounded arithmetic and the remaining linear cost in the smaller coefficient count. Add Fp64, Fp128, and Fp256 regressions for cancellation near one, complement rounding, endpoint probabilities, full-width counts, and coefficients that require more precision than hardware floating point. Keep the existing public function names and built-in floating-point implementation unchanged. AI-Assisted-By: Codex (GPT-6 Astra Medium) --- source/mir/math/internal/fp_powi.d | 25 +-- .../mir/stat/distribution/negative_binomial.d | 153 +++++++++++++++++- 2 files changed, 163 insertions(+), 15 deletions(-) diff --git a/source/mir/math/internal/fp_powi.d b/source/mir/math/internal/fp_powi.d index a492b342..20b04d57 100644 --- a/source/mir/math/internal/fp_powi.d +++ b/source/mir/math/internal/fp_powi.d @@ -16,17 +16,18 @@ package(mir) T fp_powi(T)(const T x, size_t i) if (is(T == Fp!size, size_t size)) { - if (i == 0) { - return T(1.0); - } else if (i == 1) { - return x; - } else { - T output = x; - for (size_t j = 1; j < i; j++) { - output *= x; - } - return output; + // Exponentiation by squaring keeps full-width counts practical. Avoid an + // unused final square, which could overflow even when the result fits. + T output = T(1); + T factor = x; + while (i) { + if (i & 1) + output *= factor; + i >>= 1; + if (i) + factor *= factor; } + return output; } version(mir_stat_test) @@ -38,4 +39,8 @@ unittest assert(x.fp_powi(0).to!double == 1); assert(x.fp_powi(1).to!double == 3); assert(x.fp_powi(2).to!double == 9); + assert(x.fp_powi(5).to!double == 243); + assert(Fp!128(1).fp_powi(size_t.max).to!double == 1); + assert(Fp!128(0).fp_powi(0).to!double == 1); + assert(Fp!128(0).fp_powi(17).to!double == 0); } diff --git a/source/mir/stat/distribution/negative_binomial.d b/source/mir/stat/distribution/negative_binomial.d index 6f496c69..d1c87b9b 100644 --- a/source/mir/stat/distribution/negative_binomial.d +++ b/source/mir/stat/distribution/negative_binomial.d @@ -109,7 +109,14 @@ unittest /++ Computes the negative binomial probability mass function (PMF) directly with extended floating point types (e.g. `Fp!128`), which provides additional accuracy for -extreme values of `k`, `r`, or `p`. +extreme values of `k`, `r`, or `p`. Complements and coefficient ratios retain +the supplied `Fp` precision rather than converting through hardware floating +point. Intermediate arithmetic is rounded to that precision; it is not exact +arbitrary-precision probability arithmetic. + +The coefficient requires `O(min(k, r - 1))` iterations. Powers use logarithmic +time in their exponents, so a large count is practical when the other count is +small. Central probabilities with two enormous counts remain expensive. Params: k = number of failures before stopping @@ -123,13 +130,149 @@ See_also: T fp_negativeBinomialPMF(T)(const size_t k, const size_t r, const T p) if (is(T == Fp!size, size_t size)) in (r > 0, "number of successes must be larger than zero") - in (cast(double) p >= 0, "p must be greater than or equal to 0") - in (cast(double) p <= 1, "p must be less than or equal to 1") + in (fpProbabilityValid(p), "p must be finite and between zero and one") { import mir.math.internal.fp_powi: fp_powi; - import mir.math.numeric: binomialCoefficient; + import mir.bignum.fixed: UInt; + enum size = typeof(p.coefficient).sizeof * 8; + + if (!p.coefficient) + return T(0); + if (k == 0) + return fp_powi(p, r); + const T complement = fpProbabilityComplement(p); + if (!complement.coefficient) + return T(0); + T coefficient; + if (k <= 64 && r - 1 <= 64 - k) { + // Every coefficient through row 64 fits exactly in ulong. + import mir.combinatorics: binomial; + coefficient = T(binomial(k + r - 1, r - 1)); + } else { + // Exploit symmetry before forming a coefficient. A factor may need 65 + // bits even though each input count fits size_t; never add them in size_t. + const size_t smaller = k < r - 1 ? k : r - 1; + const size_t larger = k < r - 1 ? r - 1 : k; + T numeratorProduct = T(1); + T denominatorProduct = T(1); + foreach (i; 0 .. smaller) { + UInt!128 numerator = UInt!128(larger); + numerator += i; + numerator += 1; + numeratorProduct *= T(numerator); + denominatorProduct *= T(i + 1); + } + // Fp division currently converts through hardware real. Divide the + // significands once, with 64 guard bits beyond the requested precision. + // Accumulating the products first avoids a wide division per factor. + UInt!(2 * size + 64) quotient = numeratorProduct.coefficient.toSize!(2 * size + 64); + quotient <<= size + 64; + quotient /= denominatorProduct.coefficient; + coefficient = T(quotient); + coefficient.exponent += numeratorProduct.exponent - denominatorProduct.exponent - cast(long)size - 64; + } + return coefficient * fp_powi(complement, k) * fp_powi(p, r); +} + +// Validate the represented value, including probabilities that round to 0 or +// 1 in a hardware type. Fp's special exponent denotes infinity or NaN. +private @safe pure nothrow @nogc +bool fpProbabilityValid(uint bits)(Fp!bits p) +{ + import mir.bignum.fixed: UInt; + if (p.exponent == long.max) + return false; + if (!p.coefficient) + return true; + if (p.sign || p.exponent > 0) + return false; + if (p.exponent <= -cast(long)bits) + return true; + UInt!bits one = UInt!bits(1); + one <<= cast(size_t)-p.exponent; + return p.coefficient <= one; +} + +// Fp does not supply subtraction. Form 1-p exactly as an integer at p's +// binary exponent, then let Fp's integer constructor round to its precision. +// The temporary accommodates cancellation near one and guard bits near zero. +private @safe pure nothrow @nogc +Fp!bits fpProbabilityComplement(uint bits)(Fp!bits p) +{ + import mir.bignum.fixed: UInt; + if (!p.coefficient || p.exponent < -2 * cast(long)bits) + return Fp!bits(1); // p is less than half the spacing immediately below 1. + UInt!(2 * bits + 64) difference = UInt!(2 * bits + 64)(1); + difference <<= cast(size_t)-p.exponent; + difference -= p.coefficient; + auto result = Fp!bits(difference); + result.exponent += p.exponent; + return result; +} - return binomialCoefficient(k + r - 1, cast(const uint) (r - 1)) * fp_powi(T(1 - cast(double) p), k) * fp_powi(p, r); +// Exact dyadic probabilities exercise precision unavailable through double. +version(mir_stat_test) +@safe pure nothrow @nogc unittest +{ + import mir.bignum.fixed: UInt; + import mir.math.common: approxEqual; + static foreach (bits; [64u, 128u, 256u]) {{ + alias T = Fp!bits; + UInt!bits allOnes; + allOnes.data[] = size_t.max; + const T p = T(false, -cast(long)bits, allOnes); // 1 - 2^-bits + const T mass = fp_negativeBinomialPMF(1, 1, p); + assert(mass.coefficient == p.coefficient); + assert(mass.exponent == -2 * cast(long)bits); + assert(!mass.sign); + // C(14,10)*(1/4)^5*(3/4)^10 = 59108049/2^30 exactly. + T expected = T(59108049); + expected.exponent -= 30; + const T dyadic = fp_negativeBinomialPMF(10, 5, T(0.25)); + assert(dyadic.coefficient == expected.coefficient); + assert(dyadic.exponent == expected.exponent); + // C(200,100)/2^201 tests the large-coefficient path. Compare at the + // requested precision, so conversion through real cannot pass. + enum exactCoefficient = UInt!256("90548514656103281165404177077484163874504589675413336841320"); + T centralExpected = T(exactCoefficient); + centralExpected.exponent -= 201; + const T central = fp_negativeBinomialPMF(100, 101, T(0.5)); + assert(central.exponent == centralExpected.exponent); + const error = central.coefficient > centralExpected.coefficient + ? central.coefficient - centralExpected.coefficient + : centralExpected.coefficient - central.coefficient; + assert(error <= UInt!bits(16)); + assert(cast(double)fp_negativeBinomialPMF(1, 2, T(0.5)) == 0.25); + assert(cast(double)fp_negativeBinomialPMF(0, size_t.max, T(1)) == 1); + assert(!fp_negativeBinomialPMF(1, size_t.max, T(1)).coefficient); + assert(!fp_negativeBinomialPMF(0, 2, T(0)).coefficient); + assert(fpProbabilityValid(T(0)) && fpProbabilityValid(T(1))); + assert(!fpProbabilityValid(T(-0.5)) && !fpProbabilityValid(T(2))); + assert(!fpProbabilityValid(T(double.infinity))); + // A negative value too small to survive a double conversion is invalid. + assert(!fpProbabilityValid(T(true, -2000, p.coefficient))); + // This coefficient/exponent represents a value just above 1. + assert(!fpProbabilityValid(T(false, 1 - cast(long)bits, allOnes))); + const T tiny = T(false, -3 * cast(long)bits, p.coefficient); + assert(cast(double)fpProbabilityComplement(tiny) == 1); + T spacing = T(1); + spacing.exponent -= bits; + const T predecessor = fpProbabilityComplement(spacing); + assert(predecessor.coefficient == allOnes && predecessor.exponent == -cast(long)bits); + --spacing.exponent; // Exactly halfway between 1 and its predecessor. + const T halfway = fpProbabilityComplement(spacing); + assert(halfway.coefficient == T(1).coefficient && halfway.exponent == T(1).exponent); + static if (size_t.sizeof == 8) { + // k=1 makes the coefficient exactly r. The old uint conversion + // erased it when r-1 was 2^32. Reference uses exact binary p. + assert(approxEqual(cast(double)fp_negativeBinomialPMF(1, + 4_294_967_297UL, T(1 - 0x1p-32)), + 0.36787944112861551803393984760514035666, 1e-12, 0.0)); + // k+r-1 needs 65 bits. Underflow of this astronomically small mass + // is expected; wrapping the coefficient input or asserting is not. + assert(!fp_negativeBinomialPMF(2, size_t.max, T(0.5)).coefficient); + } + }} } /// Extended precision provides accurate values for large counts. From 32e0a94981c2affb3c5ab0405eb5a84390cb6ce2 Mon Sep 17 00:00:00 2001 From: jmh530 Date: Mon, 12 Oct 2026 19:05:28 -0400 Subject: [PATCH 2/5] Overload negativeBinomialPMF for extended-precision probabilities Expose the corrected Fp implementation through negativeBinomialPMF, using disjoint template constraints to select it from the probability type. Retain fp_negativeBinomialPMF as a forwarding compatibility wrapper so existing callers remain supported without a deprecation warning. Add a documented example that checks the Fp return type and probability, and verifies that a double argument still selects the built-in overload. Document the compatibility name and preserve safe, pure, nothrow, and nogc attributes on both entry points. AI-Assisted-By: Codex (GPT-6 Astra Medium) --- .../mir/stat/distribution/negative_binomial.d | 30 ++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/source/mir/stat/distribution/negative_binomial.d b/source/mir/stat/distribution/negative_binomial.d index d1c87b9b..a9b1caa1 100644 --- a/source/mir/stat/distribution/negative_binomial.d +++ b/source/mir/stat/distribution/negative_binomial.d @@ -127,7 +127,7 @@ See_also: $(LINK2 https://en.wikipedia.org/wiki/Negative_binomial_distribution, Negative Binomial Distribution) +/ @safe pure nothrow @nogc -T fp_negativeBinomialPMF(T)(const size_t k, const size_t r, const T p) +T negativeBinomialPMF(T)(const size_t k, const size_t r, const T p) if (is(T == Fp!size, size_t size)) in (r > 0, "number of successes must be larger than zero") in (fpProbabilityValid(p), "p must be finite and between zero and one") @@ -174,6 +174,34 @@ T fp_negativeBinomialPMF(T)(const size_t k, const size_t r, const T p) return coefficient * fp_powi(complement, k) * fp_powi(p, r); } +/// The probability type selects the extended-precision implementation. +version(mir_stat_test) +@safe pure nothrow @nogc unittest +{ + auto probability = Fp!128(0.5); + auto mass = negativeBinomialPMF(1, 2, probability); + static assert(is(typeof(mass) == Fp!128)); + assert(cast(double)mass == 0.25); + static assert(is(typeof(negativeBinomialPMF(1, 2, 0.5)) == double)); +} + +/++ +Compatibility name for the `Fp` overload of $(LREF negativeBinomialPMF). +Existing calls remain supported; new code can use `negativeBinomialPMF` with +either a built-in floating-point probability or an `Fp` probability. + +Params: + k = number of failures before stopping + r = number of successes until stopping + p = success probability as an `Fp` value ++/ +@safe pure nothrow @nogc +T fp_negativeBinomialPMF(T)(const size_t k, const size_t r, const T p) + if (is(T == Fp!size, size_t size)) +{ + return negativeBinomialPMF(k, r, p); +} + // Validate the represented value, including probabilities that round to 0 or // 1 in a hardware type. Fp's special exponent denotes infinity or NaN. private @safe pure nothrow @nogc From c3b2d689635544394b29f9c8ae277c2b9294ffa0 Mon Sep 17 00:00:00 2001 From: jmh530 Date: Mon, 12 Oct 2026 19:21:53 -0400 Subject: [PATCH 3/5] Preserve the Fp power identity at the exponent floor Return x directly when fp_powi receives exponent one. Multiplying by one can underflow in Mir's Fp implementation because it adds raw exponents before normalization, discarding a representable result. Add representation-level regressions for positive and negative values near the minimum exponent across Fp64, Fp128, and Fp256. Check signs, coefficients, and exponents without conversion to hardware floats. Cover negativeBinomialPMF(0, 1, p) at the exponent floor, where the mass must equal p. Retain exponentiation by squaring for other powers; the broader Fp multiplication limitation remains a separate issue. AI-Assisted-By: Codex (GPT-6 Astra Medium) --- source/mir/math/internal/fp_powi.d | 25 +++++++++++++++++++ .../mir/stat/distribution/negative_binomial.d | 8 ++++++ 2 files changed, 33 insertions(+) diff --git a/source/mir/math/internal/fp_powi.d b/source/mir/math/internal/fp_powi.d index 20b04d57..2b1e79c1 100644 --- a/source/mir/math/internal/fp_powi.d +++ b/source/mir/math/internal/fp_powi.d @@ -16,6 +16,11 @@ package(mir) T fp_powi(T)(const T x, size_t i) if (is(T == Fp!size, size_t size)) { + // Preserve the identity without multiplication: Fp can underflow while + // adding raw exponents in 1*x near its minimum exponent. + if (i == 1) + return x; + // Exponentiation by squaring keeps full-width counts practical. Avoid an // unused final square, which could overflow even when the result fits. T output = T(1); @@ -44,3 +49,23 @@ unittest assert(Fp!128(0).fp_powi(0).to!double == 1); assert(Fp!128(0).fp_powi(17).to!double == 0); } + +// Exponent-one identity must preserve values at the Fp exponent floor. +version(mir_stat_test) +@safe pure nothrow @nogc unittest +{ + static foreach (bits; [64u, 128u, 256u]) {{ + alias T = Fp!bits; + foreach (offset; [0L, 1L, cast(long)bits - 2]) { + auto x = T(1); + x.exponent = long.min + offset; + foreach (negative; [false, true]) { + x.sign = negative; + const result = fp_powi(x, 1); + assert(result.sign == x.sign); + assert(result.coefficient == x.coefficient); + assert(result.exponent == x.exponent); + } + } + }} +} diff --git a/source/mir/stat/distribution/negative_binomial.d b/source/mir/stat/distribution/negative_binomial.d index a9b1caa1..e8c8bf16 100644 --- a/source/mir/stat/distribution/negative_binomial.d +++ b/source/mir/stat/distribution/negative_binomial.d @@ -274,6 +274,14 @@ version(mir_stat_test) assert(cast(double)fp_negativeBinomialPMF(0, size_t.max, T(1)) == 1); assert(!fp_negativeBinomialPMF(1, size_t.max, T(1)).coefficient); assert(!fp_negativeBinomialPMF(0, 2, T(0)).coefficient); + // With no failures and one required success, the mass is p itself, + // even at the Fp exponent floor where multiplication can underflow. + auto smallestExponent = T(1); + smallestExponent.exponent = long.min; + const identityMass = negativeBinomialPMF(0, 1, smallestExponent); + assert(identityMass.coefficient == smallestExponent.coefficient); + assert(identityMass.exponent == smallestExponent.exponent); + assert(!identityMass.sign); assert(fpProbabilityValid(T(0)) && fpProbabilityValid(T(1))); assert(!fpProbabilityValid(T(-0.5)) && !fpProbabilityValid(T(2))); assert(!fpProbabilityValid(T(double.infinity))); From bd7336ccc907a58a0e07f014e1b2915883433235 Mon Sep 17 00:00:00 2001 From: jmh530 Date: Mon, 12 Oct 2026 19:52:29 -0400 Subject: [PATCH 4/5] Make the Fp negative-binomial documentation example self-contained Import Fp inside the documented unittest. CircleCI extracts documentation examples into standalone modules, where the source module's private imports are unavailable, causing the example to fail compilation. AI-Assisted-By: Codex (GPT-6 Astra Medium) --- source/mir/stat/distribution/negative_binomial.d | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/mir/stat/distribution/negative_binomial.d b/source/mir/stat/distribution/negative_binomial.d index e8c8bf16..a3c87866 100644 --- a/source/mir/stat/distribution/negative_binomial.d +++ b/source/mir/stat/distribution/negative_binomial.d @@ -178,6 +178,8 @@ T negativeBinomialPMF(T)(const size_t k, const size_t r, const T p) version(mir_stat_test) @safe pure nothrow @nogc unittest { + import mir.bignum.fp: Fp; + auto probability = Fp!128(0.5); auto mass = negativeBinomialPMF(1, 2, probability); static assert(is(typeof(mass) == Fp!128)); From 23f4c6f518566e89407ff78204f828c89e334e85 Mon Sep 17 00:00:00 2001 From: jmh530 Date: Mon, 12 Oct 2026 20:05:16 -0400 Subject: [PATCH 5/5] Express the Fp coefficient tolerance as explicit bounds Replace the precision regression's conditional absolute-error calculation with lower and upper bounds on the computed significand. Preserve the existing 16-unit tolerance and exponent check. Avoid an uncovered test branch whose execution depends on rounding direction. Production arithmetic is unchanged. AI-Assisted-By: Codex (GPT-6 Astra Medium) --- source/mir/stat/distribution/negative_binomial.d | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/source/mir/stat/distribution/negative_binomial.d b/source/mir/stat/distribution/negative_binomial.d index a3c87866..bdb307bf 100644 --- a/source/mir/stat/distribution/negative_binomial.d +++ b/source/mir/stat/distribution/negative_binomial.d @@ -268,10 +268,8 @@ version(mir_stat_test) centralExpected.exponent -= 201; const T central = fp_negativeBinomialPMF(100, 101, T(0.5)); assert(central.exponent == centralExpected.exponent); - const error = central.coefficient > centralExpected.coefficient - ? central.coefficient - centralExpected.coefficient - : centralExpected.coefficient - central.coefficient; - assert(error <= UInt!bits(16)); + assert(central.coefficient >= centralExpected.coefficient - UInt!bits(16)); + assert(central.coefficient <= centralExpected.coefficient + UInt!bits(16)); assert(cast(double)fp_negativeBinomialPMF(1, 2, T(0.5)) == 0.25); assert(cast(double)fp_negativeBinomialPMF(0, size_t.max, T(1)) == 1); assert(!fp_negativeBinomialPMF(1, size_t.max, T(1)).coefficient);