Skip to content

fix(math): replace cancelling incomplete-beta prefactor with Boost power terms - #1478

Merged
benbenbang merged 5 commits into
mainfrom
fable/1468
Nov 15, 2026
Merged

benbenbang merged 5 commits into
mainfrom
fable/1468

Conversation

@benbenbang

Copy link
Copy Markdown
Member

QuantLib's incomplete-beta prefactor evaluates its gamma ratio by cancelling logarithms, which loses all precision for large parameters: the Binomial cdf at n = 1e16 returned only 0 or 1, and the Student-t cdf lost the tail for large degrees of freedom. This change ports Boost.Math's normalised power-terms formulation so the ratio is carried in Lanczos sums and near-1 powers are formed with log1p rather than subtracted logarithms.

What changed:

  • Port Boost's lanczos13m53 rational sum (lanczos_sum_exp_g_scaled) and normalised ibeta_power_terms into the incomplete beta, evaluating the rational function in z or 1/z so large z cannot overflow and letting deep tails evaluate to 0 rather than erroring.
  • Add incomplete_beta_xy(a, b, x, y), letting callers pass the exact complement y = 1 - x used in the power terms and the swapped continued fraction; incomplete_beta delegates to it, y is guarded to [0, 1], and the upper endpoint test moves to y == 0 so a rounded z = 1.0 no longer returns the wrong branch. A debug assertion verifies x + y ≈ 1 for finite callers.
  • Route the Student-t cdf and halley_step through the exact complement, and return the normal cdf beyond ν = 2^52 as Boost does.
  • Tighten the large-a Binomial tolerance to 1e-12 and add mpmath oracles (power-terms rational arms, Binomial at n up to 1e16, Student-t cdf and quantile at large ν) generated by tanh-sinh quadrature where betainc does not converge.
  • Document the prefactor swap, the normal limit, and the deferred near-saddle and forward-tail cancellations in beta.rs, studentt.rs, and the wiki, tracked in [math] incomplete_beta large-a,b asymptotic (basym / ibeta_large_ab) for 1e-10 Binomial cdf at n >= 1e14 #1475 and [math] Student-t forward tail and pdf normalization inaccurate at large nu (beta_small_b_large_a_series) #1476.
  • Extend the Boost.Math third-party notices to cover lanczos.hpp and beta.hpp.

Closes #1468.

U1 of #1468. Adds the private `lanczos_sum_exp_g_scaled` to
`src/math/beta.rs`, adapted from Boost.Math 1.92
`boost/math/special_functions/lanczos.hpp` (`lanczos13m53`, Copyright
John Maddock 2006). It evaluates the rational function as Boost's
`evaluate_rational`: in `z` for `z <= 1` and in `1/z` above, so large
`z` cannot overflow. The function is marked `expect(dead_code)` outside
tests until U2 consumes it.

A new mpmath oracle at 60 digits
(`tests/fixtures/ibeta_power_terms/generate.py` and `cases.csv`) pins
the result on both arms of the rational evaluation to a relative
tolerance of `1e-15`.

Extends the Boost.Math third-party notice in both copies
(`crates/libitofin/THIRD_PARTY_NOTICES.md` and the bundled Python copy)
to cover `lanczos.hpp`.

ref #1468
…wer terms

U2 of #1468. QuantLib's `exp(lgamma(a+b) - lgamma(a) - lgamma(b) +
a ln x + b ln(1-x))` prefactor cancels for large `a`, `b` (the Binomial
cdf at `n = 1e16` returned only 0 or 1). Port Boost 1.92's normalised
`ibeta_power_terms(a, b, x, y)` as the prefactor instead, carrying
`Γ(a+b)/(Γ(a)Γ(b))` in `lanczos13m53` sums and forming near-1 powers via
`log1p` rather than cancelling logarithms. All branches of the normalised
arm are ported; where Boost raises an underflow or overflow it returns
the product here, so a deep tail evaluates to `0` rather than `Err`.

**Incomplete beta changes:**
* Add `pub(crate) incomplete_beta_xy(a, b, x, y)`: the caller supplies the
  complement `y = 1 - x` (often exact where `1 - x` would round), used in
  the power terms and the swapped continued fraction; the branch test
  stays on `x`. `incomplete_beta` keeps its signature and delegates.
* Guard `y` to `[0, 1]`; return 1 when `x == 1.0 || y == 0.0`.
* Promote `lanczos_sum_exp_g_scaled` out of test-only `dead_code`.

**Tests and oracle:**
* Add `incomplete_beta_power_terms.rs` and `binomial` fixture rows for
  `n = 1e12, 1e14, 1e16` at `p = 1/2` and `n = 1e12` at `p = 3/4`,
  generated by mpmath log-space tanh-sinh quadrature (betainc does not
  return at these sizes), pinned at `5e-10`, `1e-8`, `5e-7`: the continued
  fraction still cancels near the saddle beyond about `1e11` (Boost 1.92
  itself misses `1e-10`), deferred to a large-parameter asymptotic.
* Tighten `incomplete_beta_large_a` binomial tolerance `1e-9` -> `1e-12`;
  the power terms bring those rows within `7e-14`.

**Docs and notices:**
* Document the prefactor swap and the saddle deferral in `beta.rs` and
  `wiki/compatibility.md`.
* Extend the Boost notices to `beta.hpp` (Copyright Matt Borland 2024).

ref #1468
The Student-t cdf and `halley_step` now hand each incomplete-beta form its
exact complement (`z` for `y`, `y` for `z`) through `incomplete_beta_xy`
instead of `1 - z`, which rounds away the tail for large `ν`; `y` is `1`
when `ν + t²` overflows. Beyond `ν = 1/eps` (`2^52`) the cdf returns the
normal cdf, as Boost's `students_t` cdf does and unlike QuantLib's always
taking the incomplete beta; the ticket's `1e20` limit lives only in the
quantile.

`incomplete_beta_xy`'s upper endpoint is `y == 0`, not `x == 1`: a rounded
`z = 1.0` at `ν = 2^52`, `t = -0.5` reached the `x == 1` branch and
returned `0.5`. The branch test stays on `x`.

New oracle rows (mpmath tanh-sinh quadrature of the density) cover the
cdf at `ν = 1e6, 1e12, 2^52, 2^52 + 2, 1e16` for centre `t` and the
forward `t` where it is accurate (to `1e-10`), and the quantile at
`ν = 1e9, 1e12` (to `1e-12`), with endpoint checks on the normal limit.

Deferred and documented in `studentt.rs` and the wiki: for `|t| > √3` the
forward continued fraction cancels for `ν ≥ 1e7` (about `1e-10` relative
at `1e7`, `0.1` at `2^52`), where Boost uses `beta_small_b_large_a_series`.

close #1468
The CDF comment now records that incomplete_beta's Boost power-terms
prefactor holds at large n, while its continued fraction cancels near
the mean for n beyond about 1e11 (5e-10 relative at n = 1e12, 5e-7 at
1e16), a deferred limitation tracked in math/beta.rs.

The cdf/pmf test comment no longer attributes the accuracy to Lanczos
log_gamma; it now refers to the Boost Lanczos power terms, matching the
current implementation. Comments only, no behaviour change.

ref #1468
`incomplete_beta_xy` documents that its caller must pass `y = 1 - x` but
never verified it, so a caller that drifted would compute a wrong result
silently. Add a `debug_assert` that `x + y` is within `8 eps` of `1`,
skipped when `x` or `y` is non-finite so the Student-t endpoints still
pass through. Every caller derives `x` and `y` from the same `t` and
`nu`, so `8 eps` covers their rounding; all beta, Student-t and Binomial
tests pass with it on in the debug build.

Also cite the follow-up issues in the deferral notes: #1475 for the
large-`a`,`b` asymptotic for the Binomial near the saddle (beta.rs and
the wiki), and #1476 for `beta_small_b_large_a_series` on the Student-t
forward tail plus the pdf normalization at huge `nu` (studentt.rs and
the wiki).

Refs: #1468, #1475, #1476

ref #1468
@benbenbang
benbenbang enabled auto-merge (rebase) November 15, 2026 18:31
@github-actions github-actions Bot added documentation Improvements or additions to documentation enhancement New feature or request labels Nov 15, 2026
@benbenbang
benbenbang merged commit 90438f4 into main Nov 15, 2026
15 checks passed
@benbenbang
benbenbang deleted the fable/1468 branch November 15, 2026 18:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[bug][math] incomplete_beta prefactor loses all precision for very large a, b (lgamma cancellation)

1 participant