Skip to content

Preserve extreme-tail precision in gamma, Rayleigh, and Cauchy distributions - #150

Merged
jmh530 merged 7 commits into
libmir:masterfrom
jmh530:codex/gamma-rayleigh-density
Oct 9, 2026
Merged

jmh530 merged 7 commits into
libmir:masterfrom
jmh530:codex/gamma-rayleigh-density

Conversation

@jmh530

@jmh530 jmh530 commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

Several distribution calculations lose representable results when an intermediate value overflows, underflows, or rounds away a small probability. This PR addresses those cases while retaining direct calculations for ordinary inputs.

Density calculations

  • Gamma PDF falls back to logarithmic evaluation when intermediate powers, exponential terms, or normalization lose the result.
  • Scaled Rayleigh PDF and log-PDF avoid squaring the scale and preserve tail densities that become representable after scaling.
  • Cauchy PDF and log-PDF retain tail values when squaring the observation overflows.

Inverse cumulative distributions

Cauchy inverse CDF evaluates extreme tails directly from the tail probability, avoiding cancellation in p - 0.5. Its scaled form also preserves results when the unscaled quantile would overflow.

Gamma inverse CDF inverts lower probabilities directly instead of first forming 1 - p. Logarithmic inversion allows a large scale to recover an otherwise underflowed quantile. This recovery also applies to tiny upper-half quantiles for small shapes, avoiding a downward jump at the median.

Validation

Regression tests cover float, double, and real, including distribution endpoints, subnormal results, extreme scales, and transitions between calculation paths. Expected values use independent high-precision calculations or analytical identities and asymptotic formulas.

Validation included Windows DMD/LDC tests and focused optimized Linux checks with LDC and older DMD versions. Paired benchmarks evaluated ordinary inputs alongside the numerical fixes. Gamma inverse improved for several smaller shapes, with roughly a 3–4% cost at shape 200; the final median-boundary fix added no meaningful ordinary-case slowdown.

Older Phobos versions

Phobos fixed the large-shape incomplete-gamma performance issue in DMD 2.112.1 (dlang/phobos#10920). Because __VERSION__ cannot distinguish 2.112.0 from 2.112.1, the largest regression cases run automatically from frontend version 2.113.

The new unittest-extreme-numerics build enables those cases explicitly on earlier versions. Routine CI does not opt into this build.

jmh530 added 7 commits October 8, 2026 23:34
Retain the direct floating-shape PDF calculation for ordinary inputs
and use a logarithmic fallback when its intermediates lose precision
or overflow. Recover the logarithm of x/scale separately when the
ratio is subnormal or rounds to zero.

Return zero for infinite standardized observations with finite shape.
Document the fallback and add regression tests for large shapes,
subnormal ratios, and tail densities restored by scaling.

AI-Assisted-By: Codex (GPT-6 Astra Medium)
Normalize the observation before squaring in the scaled PDF and LPDF,
avoiding overflow and underflow from squaring the scale.

Use a logarithmic PDF fallback when intermediate underflow could hide
a representable scaled density. Handle infinite standardized
observations and correct the LPDF scale validation message.

Document the fallback and add regression tests for extreme scales,
zero and infinite observations, and tail densities restored by scaling.

AI-Assisted-By: Codex (GPT-6 Astra Medium)
Use separate divisions for the PDF and logarithms of the absolute observation for the LPDF when x*x overflows. Preserve representable subnormal densities and finite log densities while retaining the existing formulas for ordinary inputs.

Add regression coverage for positive and negative extreme observations across float, double, and real.

AI-Assisted-By: Codex (GPT-6 Astra Medium)
Use reciprocal tangents in the tails to avoid losing small probabilities when subtracting one half. Retain a direct tangent path for central probabilities.

Apply scale within the tail calculation and handle subnormal probabilities without rounding pi*p prematurely. Preserve finite scaled quantiles when intermediate division would otherwise overflow.

Document the tail formulation and add regression tests for extreme probabilities, small scales, endpoints, and transition boundaries across float, double, and real.

AI-Assisted-By: Codex (GPT-6 Astra Medium)
Invert lower-tail probabilities directly instead of losing precision through subtraction from one. Use logarithmic iteration for small quantiles and a bracketed lower-CDF solve near the mean, retaining the existing complementary inverse for the upper half.

Apply scale in logarithmic form when the unscaled quantile underflows. Add regression coverage for tiny probabilities, scaled results, endpoints, the midpoint transition, and large shapes.

Run large-shape tests by default on frontends 2.113 and newer. Add an opt-in unittest-extreme-numerics build for older frontends and document their Phobos performance limitation.

AI-Assisted-By: Codex (GPT-6 Astra Medium)
Fall back to logarithmic inversion when the complementary inverse
produces a tiny quantile for a shape below one. Apply the scale before
underflow can discard a representable result.

Use the exponential quantile as an upper bound for the upper-half
fallback. Preserve the existing path for ordinary results and p = 1.

Add float, double, and real regressions around the median and at
p = 0.75, using independent high-precision references and checking
monotonicity across the branch boundary.

AI-Assisted-By: Codex (GPT-6 Astra Medium)
Identify DMD 2.112.1 as the release containing the fix for Phobos
issue 10920 and link to the issue.

Explain why automatic extreme-shape tests still start at 2.113:
__VERSION__ cannot distinguish 2.112.0 from 2.112.1. Document
using the opt-in build to run these tests on 2.112.1.

AI-Assisted-By: Codex (GPT-6 Astra Medium)
@jmh530
jmh530 merged commit 3a549b7 into libmir:master Oct 9, 2026
23 checks passed
@jmh530
jmh530 deleted the codex/gamma-rayleigh-density branch October 9, 2026 06:35
@codecov

codecov Bot commented Oct 9, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 96.00000% with 7 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
source/mir/stat/distribution/gamma.d 93.06% 7 Missing ⚠️

📢 Thoughts on this report? Let us know!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant