From be0a47ccbb2e579a4d8a35ffe458320b50690a4d Mon Sep 17 00:00:00 2001 From: nstarman Date: Tue, 3 Nov 2026 01:05:24 -0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=90=9B=20fix(incomplete=5Fbeta):=20contin?= =?UTF-8?q?ued=20fraction=20for=20large=20b=20and=20large=20a?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rebase onto upstream/main, which merged #63 (the `a == 1` closed form) after this branch was cut. Both PRs restructured the same region of beta.py independently -- #63 made `incomplete_beta` a plain wrapper around `_incomplete_beta_core`, this one added branch dispatch (`_branch`/`_dispatch`/`lax.switch` over `_SERIES`, `_CONTINUED_FRACTION`, `_LARGE_A`, `_NEGATIVE_B`) -- so this squashes the 17 commits that grew on the old base into one, reconciled against #63's structure: - `incomplete_beta` checks the `a == 1` closed form first (cheapest, exact for any `b`), then falls through to branch dispatch for everything else; a traced `a` cannot be inspected and falls through too, even at 1. - `_EXPRL_COEFFS`, previously defined separately by each PR for the same `expm1(x)/x` series, is now shared between `_expm1_over` and `_a_eq_1`. - `_incomplete_beta_core` and its benchmarks/registry probes take the `a == 1` closed form's structure (a 3-arg call before #63) into account for the branch-aware 4-arg signature this PR needs. - `test_nan_past_one_over_eps`'s `a = 1` case is dropped: the closed form has no switch point to round away past `b ~ 1/eps`, so it stays exact where the continued fraction degrades to `nan` by design. - `docs/reference/accuracy-and-domains.md` documents both the `a == 1` closed form and the branch dispatch regimes together. No functional change to either PR's own logic; 539 tests across test_beta.py, test_beta_regimes.py and test_registry.py pass, plus the module's doctests. Co-Authored-By: Claude Sonnet 5 --- benchmarks/test_beta.py | 21 +- docs/explanation/why-not-upstream.md | 2 +- docs/reference/accuracy-and-domains.md | 22 +- docs/reference/coverage.md | 2 +- src/spexial/_src/beta.py | 766 ++++++++++++++++++++++--- src/spexial/_src/registry.py | 5 +- tests/unit/conftest.py | 52 ++ tests/unit/test_beta.py | 25 +- tests/unit/test_beta_regimes.py | 713 +++++++++++++++++++++++ tests/unit/test_registry.py | 9 +- 10 files changed, 1499 insertions(+), 118 deletions(-) create mode 100644 tests/unit/conftest.py create mode 100644 tests/unit/test_beta_regimes.py diff --git a/benchmarks/test_beta.py b/benchmarks/test_beta.py index 7fd5f29..9e366ee 100644 --- a/benchmarks/test_beta.py +++ b/benchmarks/test_beta.py @@ -16,7 +16,7 @@ from benchmarks.utils import warm import spexial as sp -from spexial._src.beta import _incomplete_beta_core +from spexial._src.beta import _SERIES, _incomplete_beta_core Z_SCALAR = jnp.asarray(0.3) Z_VECTOR = jnp.linspace(0.001, 0.999, 1_000) @@ -55,7 +55,9 @@ def test_incomplete_beta_non_positive_b(benchmark: BenchmarkFixture, b: float) - @pytest.mark.parametrize( - "fn", [sp.incomplete_beta, _incomplete_beta_core], ids=["closed_form", "series"] + "fn", + [sp.incomplete_beta, lambda a, b, z: _incomplete_beta_core(a, b, z, _SERIES)], + ids=["closed_form", "series"], ) def test_incomplete_beta_a_eq_1(benchmark: BenchmarkFixture, fn: Callable) -> None: """A static ``a == 1`` is elementary; the pair is what skipping the series saves.""" @@ -75,7 +77,7 @@ def test_grad_incomplete_beta_autodiff(benchmark: BenchmarkFixture) -> None: this is the honest alternative rather than a proxy for it. The gap between this and the benchmark above is what the custom rule buys. """ - fn = jax.grad(lambda z: _incomplete_beta_core.fun(A, B, z).sum()) + fn = jax.grad(lambda z: _incomplete_beta_core.fun(A, B, z, _SERIES).sum()) benchmark(warm(fn, Z_VECTOR)) @@ -91,7 +93,9 @@ def test_grad_incomplete_beta_parameters(benchmark: BenchmarkFixture) -> None: @pytest.mark.parametrize( - "fn", [sp.incomplete_beta, _incomplete_beta_core], ids=["closed_form", "series"] + "fn", + [sp.incomplete_beta, lambda a, b, z: _incomplete_beta_core(a, b, z, _SERIES)], + ids=["closed_form", "series"], ) def test_grad_incomplete_beta_a_eq_1_b( benchmark: BenchmarkFixture, fn: Callable @@ -99,3 +103,12 @@ def test_grad_incomplete_beta_a_eq_1_b( """``d/db`` at a static ``a == 1``: the closed form against the series' autodiff.""" grad = jax.grad(lambda b: fn(1.0, b, Z_VECTOR).sum()) benchmark(warm(grad, B)) + + +@pytest.mark.parametrize("b", [50.0, 1e3]) +def test_incomplete_beta_large_b(benchmark: BenchmarkFixture, b: float) -> None: + """Above ``b = 10`` the continued fraction replaces the series (GH-64). + + About 6x the series' cost per point, against a series that is wrong there. + """ + benchmark(warm(lambda z: sp.incomplete_beta(A, b, z), Z_VECTOR)) diff --git a/docs/explanation/why-not-upstream.md b/docs/explanation/why-not-upstream.md index dc232b6..98f7814 100644 --- a/docs/explanation/why-not-upstream.md +++ b/docs/explanation/why-not-upstream.md @@ -43,7 +43,7 @@ Two functions here are not waiting for anything, because they do something upstr `zeta` extends JAX's Hurwitz zeta to the negative integers through the functional equation. JAX returns `nan` there. The extension is partial — the critical strip and negative non-integers are still `nan` — and the [accuracy page](../reference/accuracy-and-domains.md) says so rather than implying full coverage. -`incomplete_beta` is the clearest case of a _missing_ function rather than a weaker one. Neither SciPy nor JAX has the unregularized $B(a, b, z)$ at all — their `betainc` is the regularized $I_z(a,b)$, and the obvious reconstruction, `beta(a, b) * betainc(a, b, z)`, is `nan` for every $b \le 0$, because $B(a,b)$ has a pole there while the product does not. `jax.scipy.special.hyp2f1` can express it for any $b$ via DLMF 8.17.7, but it is a `lax.while_loop` whose trip count depends on its data: under `vmap` every lane pays the worst lane's iteration count, and its derivative runs a second such loop. Two fixed-length series with an exact O(1) derivative rule avoid both, and that rule is the strongest entry in the cost table — 143× faster on 70× less residual than differentiating the series it replaces. +`incomplete_beta` is the clearest case of a _missing_ function rather than a weaker one. Neither SciPy nor JAX has the unregularized $B(a, b, z)$ at all — their `betainc` is the regularized $I_z(a,b)$, and the obvious reconstruction, `beta(a, b) * betainc(a, b, z)`, is `nan` for every $b \le 0$, because $B(a,b)$ has a pole there while the product does not. `jax.scipy.special.hyp2f1` can express it for any $b$ via DLMF 8.17.7, but it is a `lax.while_loop` whose trip count depends on its data: under `vmap` every lane pays the worst lane's iteration count, and its derivative runs a second such loop. Fixed-length series (and, for $b > 10$, a fixed-length continued fraction) with an exact O(1) derivative rule avoid both, and that rule is the strongest entry in the cost table — 143× faster on 70× less residual than differentiating the series it replaces. `gamma` is the interesting middle case. The value is JAX's, called directly, so it cannot drift. What `spexial` adds is an analytic derivative that keeps 3× less residual memory through the backward pass at parity on time. That is a real benefit and a narrow one, and the registry records it as `DELEGATES` — a row that earns its place on the cost columns alone, and becomes redundant the moment upstream's own gradient matches on both. diff --git a/docs/reference/accuracy-and-domains.md b/docs/reference/accuracy-and-domains.md index 3434838..09721b5 100644 --- a/docs/reference/accuracy-and-domains.md +++ b/docs/reference/accuracy-and-domains.md @@ -10,7 +10,7 @@ Every function is tested against a reference implementation — `scipy.special` | --- | --- | --- | --- | | `eval_gegenbauer` | `eval_gegenbauer` | $n \le 20$ integer, $\alpha > -1/2$, $\lvert x \rvert \le 1$ | rtol $10^{-10}$, atol $10^{-13}\times$ recurrence scale; worst $1.5\times10^{-5}$ absolute at $n=20,\ \alpha=10$ scalar, $8.8\times10^{-5}$ batched; $2.1\times10^{-12}$ relative, worst at $n=18$ | | `eval_gegenbauers` | -- | as `eval_gegenbauer`; returns all orders $0 \ldots n$ | as `eval_gegenbauer` | -| `incomplete_beta` | -- (`betainc` is the _regularized_ form) | $a > 0$, **any real $b$**, $z \in [0, 1]$; $a$ and $b$ scalar, $z$ any shape | rtol $10^{-11}$ against the DLMF 8.17.7 `hyp2f1` identity over $a \in [0.25, 4.5]$, $b \in [-2.5, 4]$ | +| `incomplete_beta` | -- (`betainc` is the _regularized_ form) | $a > 0$, **any real $b$**, $z \in [0, 1]$; $a$ and $b$ scalar, $z$ any shape | rtol $10^{-11}$ against the DLMF 8.17.7 `hyp2f1` identity over $a \in [0.25, 4.5]$, $b \in [-2.5, 4]$; rtol $10^{-12}$ against mpmath for $b \in (10, 100]$, for $a \in (8, 50]$ with $b \ge 0.1$, and for $a \in (8, 100]$ with $b \in [-50, 0.1)$; $2\times10^{-12}$ for $a \le 8$ with $b \in [-1100, -5)$; $10^{-11}$ for $b$ to $10^4$ (rounding grows like $b\,\epsilon$ and $a\,\epsilon$ beyond; `nan` past $b \approx 1/\epsilon$) | | `comb` | `comb` (`exact=False`) | $0 \le k \le N$, to `DBL_MAX` | rtol $10^{-11}$; worst $3.6 \times 10^{-12}$, just below the $N = 1000$ join | | `gamma` | `gamma` | real (and complex, jax $\ge$ 0.10.2), $-170 \lesssim x \lesssim 171$ | rtol $10^{-11}$; worst $3.8\times10^{-13}$ for $x \ge 1/2$, $4.3\times10^{-13}$ on $[-170,-30]$ | | `k0` | `k0` | $0 < z \lesssim 705.3$ (float64; see below — the ceiling is the _dtype's_) | rtol $10^{-6}$; worst $2.0 \times 10^{-7}$ at $z = 8.9984$, ~$10^{-15}$ above $z = 30$ | @@ -40,13 +40,25 @@ Every function is tested against a reference implementation — `scipy.special` `incomplete_beta` : This is the **unregularized** $B(a, b, z) = \int_0^z t^{a-1}(1-t)^{b-1}\,\mathrm{d}t$ (DLMF 8.17.1), not SciPy's `betainc`, which is the regularized $I_z(a, b)$. The two differ by the complete beta function $B(a, b)$. Reconstructing this as `beta(a, b) * betainc(a, b, z)` is `nan` for every $b \le 0$ — $B(a, b)$ has a pole there while the product does not — and that domain is the reason the function exists. ([Why not `hyp2f1`](../explanation/why-not-upstream.md#where-it-earns-its-place-independently).) -`incomplete_beta` : Two fixed-length 64-term series, switched at $z = 1/2$, each converging like $2^{-k}$. They meet to about $10^{-11}$ relative rather than exactly, since they truncate differently; worst measured step across the seam is $2.9\times10^{-11}$, at $a = 4.5,\ b = -2.5$. That is inside the tolerance the reference tests assert, so the seam is not the accuracy-limiting feature. Above $a \approx 16$ the error stops improving with term count at all — it is cancellation between large alternating terms, not truncation. +`incomplete_beta` : Two fixed-length 64-term series, switched at $z = 1/2$, each converging like $2^{-k}$. They meet to about $10^{-11}$ relative rather than exactly, since they truncate differently; worst measured step across the seam is $2.9\times10^{-11}$, at $a = 4.5,\ b = -2.5$. That is inside the tolerance the reference tests assert, so the seam is not the accuracy-limiting feature. The near-pole term — the one step $m$ with $|b + m| < 1/2$, where $(w_0^s - w^s)/s$ cancels as $s = b + m \to 0$ — is evaluated apart, after the sum, as $w^s\,\Delta\,\operatorname{expm1}(s\Delta)/(s\Delta)$ with $\Delta = \ln(w_0/w)$, which cancels for no $s$ and in no dtype and whose $b$-derivatives are exact to every order at $s = 0$ (an earlier expansion inside $|s| < 10^{-3}$ left $10^{-3} \le |s| \lesssim 0.1$ to the direct form: $2.6\times10^{-12}$ in value, $1.5\times10^{-3}$ in the third $b$-derivative, $3.5\times10^{-4}$ in float32). The sum is carried divided by $w_0^b$ and scaled back at the end, through logarithms only if $w_0^b$ itself would overflow. -`incomplete_beta` : When `a` is a **concrete** real 1 — a Python or NumPy scalar or a concrete 0-d array, so decidable before tracing — the integral is elementary, $(1 - (1-z)^b)/b$, and that closed form replaces the series. Measured at $10^5$ points: about 3x faster to evaluate and 75–80x faster to differentiate in $b$, at parity in $z$ (it carries the same exact $z$-derivative rule). Against 50-digit mpmath over $b \in [-800, 10^4]$ and $z \in [0, 1]$: worst $1.3\times10^{-13}$ relative in float64, at $b = -800$ where $\lvert bL \rvert \approx 430$ (error grows like $\lvert bL \rvert$ ulp: the condition number of $B$ in $b$, $L = \ln(1-z)$); the first three $b$-derivatives to $5\times10^{-14}$, including at $b = 0$ and across the series band. $L$ is formed by `log1p` below $z = 0.3$ and `log(1 - z)` above: XLA's CPU `log1p` is off by up to $2.7\times10^{-14}$ for arguments in $(-0.42, -0.3)$, which the closed form would multiply by $\lvert bL \rvert$ (it was $7\times10^{-12}$ at $b = -500$), while $1 - z$ is exact enough there for `log` to be good to $3\times10^{-16}$. In float32 the error is likewise up to $\lvert bL \rvert$ ulp — $7.4\times10^{-6}$ at $b = -10$ near $z = 1$ — no worse than rounding $b$ itself. The removable singularity at $b = 0$ is handled by the formula, $-L\,\operatorname{expm1}(x)/x$ with $x = bL$ summed as a Taylor series for $\lvert x \rvert < 1/2$, not by a substituted value. At $z = 1$ it returns $1/b$ for $b > 0$ and $+\infty$ for $b \le 0$, including $b = -\infty$; the output dtype matches the series path, and its weak type follows JAX's promotion of `z` against `b` (the series path can drop weakness for a strong integer `b`, as a side effect of its arithmetic); values that would overflow only in an intermediate — $(1 - e^x)/b$ for $b < 0$, past $x \approx 709.8$ — are formed as $e^{x - \log|b|} - 1/|b|$ instead, so they stay finite as long as the result does; $z > 1$ is outside the domain and returns `nan`; and an array `b` raises `TypeError`, as the series path does. With a concrete `b`, the $z$-derivative is `(1 - z) ** (b - 1)`, accurate to about $\lvert b \rvert$ ulp; with a traced `b` it is $\exp((b-1)L)$, so that its own $b$-derivative stays accurate as $z \to 0$, with `pow` taking over at $z = 1$ so that the higher $z$-derivatives there match the concrete path. +`incomplete_beta` : **Regimes.** When `a` is a **concrete** real 1 the closed form below applies regardless of `b`; otherwise, the series are used for $a \le 8$ and $-5 \le b \le 10$. Outside that, their binomial coefficients cancel -- $(1-b)_k/k!$ grows like $b^k/k!$ with alternating sign for large $b$, and `_large_z`'s $(1-a)_m/m!$ likewise for large $a$ -- or grow before they decay, $(1-b)_k/k!$ like $(|b| z)^k/k!$ for very negative $b$; at $z = 1/2$ the series were $10^{-11}$ off at $b = 30$ and $10^{7}$ at $b = 100$, $4\times10^{-11}$ at $a = 16$ and nothing useful by $a = 50$, $6\times10^{-12}$ at $b = -10$ and 8% at $b = -50$. Three methods take over: the continued fraction with reflection for $b > 10$, or $a > 8$ with $b \ge 0.1$; `_large_a` for $a > 8$ with $b < 0.1$; and the continued fraction directly for $a \le 8$ with $b < -5$. -`incomplete_beta` : **A traced `a` loses the closed form's domain.** It cannot be inspected, so even `a = 1` takes the series — which agrees to $10^{-11}$ only for $\lvert b \rvert \lesssim 10$. At $a = 1$ the series is $2\times10^{-7}$ off at $b = -20$, $0.08$ at $b = -50$, and has no correct digits by $b = 100$. Keep `a` a Python or NumPy scalar to get the closed form. +`incomplete_beta` : **Closed form at `a == 1`.** When `a` is a **concrete** real 1 -- a Python or NumPy scalar or a concrete 0-d array, so decidable before tracing -- the integral is elementary, $(1 - (1-z)^b)/b$, and that closed form replaces the series or continued fraction for every `b`. Measured at $10^5$ points: about 3x faster to evaluate and 75-80x faster to differentiate in $b$, at parity in $z$ (it carries the same exact $z$-derivative rule). Against 50-digit mpmath over $b \in [-800, 10^4]$ and $z \in [0, 1]$: worst $1.3\times10^{-13}$ relative in float64, at $b = -800$ where $\lvert bL \rvert \approx 430$ (error grows like $\lvert bL \rvert$ ulp: the condition number of $B$ in $b$, $L = \ln(1-z)$); the first three $b$-derivatives to $5\times10^{-14}$, including at $b = 0$ and across the series band. $L$ is formed by `log1p` below $z = 0.3$ and `log(1 - z)` above: XLA's CPU `log1p` is off by up to $2.7\times10^{-14}$ for arguments in $(-0.42, -0.3)$, which the closed form would multiply by $\lvert bL \rvert$ (it was $7\times10^{-12}$ at $b = -500$), while $1 - z$ is exact enough there for `log` to be good to $3\times10^{-16}$. In float32 the error is likewise up to $\lvert bL \rvert$ ulp -- $7.4\times10^{-6}$ at $b = -10$ near $z = 1$ -- no worse than rounding $b$ itself. The removable singularity at $b = 0$ is handled by the formula, $-L\,\operatorname{expm1}(x)/x$ with $x = bL$ summed as a Taylor series for $\lvert x \rvert < 1/2$, not by a substituted value. At $z = 1$ it returns $1/b$ for $b > 0$ and $+\infty$ for $b \le 0$, including $b = -\infty$; the output dtype matches the branch-dispatch path, and its weak type follows JAX's promotion of `z` against `b` (the other paths can drop weakness for a strong integer `b`, as a side effect of their arithmetic); values that would overflow only in an intermediate -- $(1 - e^x)/b$ for $b < 0$, past $x \approx 709.8$ -- are formed as $e^{x - \log|b|} - 1/|b|$ instead, so they stay finite as long as the result does; $z > 1$ is outside the domain and returns `nan`; and an array `b` raises `TypeError`, as the other paths do. With a concrete `b`, the $z$-derivative is `(1 - z) ** (b - 1)`, accurate to about $\lvert b \rvert$ ulp; with a traced `b` it is $\exp((b-1)L)$, so that its own $b$-derivative stays accurate as $z \to 0$, with `pow` taking over at $z = 1$ so that the higher $z$-derivatives there match the concrete path. -`incomplete_beta` : `a` and `b` must be **scalars**; `z` may be any shape. The $z$-derivative comes from a `jax.custom_jvp` and is exact: by Leibniz it is the integrand at the endpoint, $z^{a-1}(1-z)^{b-1}$. The `a` and `b` tangents have no cheap closed form and fall back to differentiating the implementation — the series, or at a concrete `a = 1` the closed form — but only when actually requested — `symbolic_zeros` skips them in the common case of differentiating with respect to $z$ alone. It is a `custom_jvp` and not a `custom_vjp` specifically so that `jax.hessian`'s `jacfwd(jacrev(...))` still composes. +`incomplete_beta` : **A traced `a` loses the closed form's domain.** It cannot be inspected, so even `a = 1` falls through to the branch dispatch below -- which agrees with the closed form to $10^{-11}$ only for $\lvert b \rvert \lesssim 10$, the series' own range. At $a = 1$ the series is $2\times10^{-7}$ off at $b = -20$, $0.08$ at $b = -50$, and has no correct digits by $b = 100$ (the continued-fraction regimes, which a large or very negative `b` would otherwise route through, are unaffected -- they have no special case for $a = 1$ either way). Keep `a` a Python or NumPy scalar to get the closed form. + +`incomplete_beta` : **Continued fraction with reflection** ($b > 10$, or $a > 8$ with $b \ge 0.1$): DLMF 8.17.22 (modified Lentz, 64 fixed double steps), below $x_0 = (a+1)/(a+b+2)$ directly and above it by $B(a,b,z) = B(a,b) - B(b,a,1-z)$. The complete $B(a,b)$ is the sum of both fractions at $x_0$ rather than `exp(betaln)`, which is only good to $3\times10^{-7}$ at $(8, 10)$; it is carried as a logarithm and computed once per call. Each term is $\exp(\log(\text{front}) + \log(\text{fraction}))$, with the front factor $z^a(1-z)^b$ taken from $z$ itself, so nothing is lost to a rounded $1-z$ scaled by $b$, and nothing underflows early: $B(301, 1000, 1) \approx 3.9\times10^{-307}$ is returned, not 0. Measured against mpmath over $a \in [0.1, 50]$: worst $10^{-13}$ up to $b = 10^3$; beyond that the error is rounding and grows like $b\,\epsilon$ -- $4\times10^{-12}$ at $b = 10^5$, $5\times10^{-10}$ at $10^7$. Past $b \approx 1/\epsilon$ the switch point rounds to zero and the result is `nan`, deliberately, rather than a confident wrong number. + +`incomplete_beta` : **`_large_a`** ($a > 8$, $b < 0.1$, including every $b \le 0$, where there is no reflection because $B(a, b)$ diverges): the continued fraction directly up to $s = a/(a+2)$, at or below its switch point for $b \le 1 + 2/a$, and above it the series' own binomial expansion over $u \in [1-z, 2/(a+2)]$ instead of $[1-z, 1/2]$, where its terms fall like $2^m/m!$ instead of growing like $(a/2)^m/m!$. Measured against mpmath over $b \in [-1000, 0.1)$ and $z$ to $1 - 10^{-12}$: $10^{-13}$ or better to $a = 100$; beyond, the fraction's rounding grows like $a\,\epsilon$ -- $1.5\times10^{-13}$ at $a = 10^3$, $2\times10^{-12}$ at $10^4$, $9\times10^{-12}$ at $10^5$. + +`incomplete_beta` : **Continued fraction directly** ($a \le 8$, $b < -5$): no reflection is needed, since for $b$ this negative the fraction converges for every $z \in [0, 1)$ -- at 128 double steps, which small $a$ needs (64 leave $5\times10^{-9}$ at $a = 0.5, b = -1100$). Measured against mpmath over $a \in [0.01, 8]$, $b \in [-1100, -5.5]$: worst $4.4\times10^{-13}$, at $a = 0.01, b = -200$. + +`incomplete_beta` : **Edges and dtypes.** At $z = 1$ the result is the complete $B(a, b)$ for $b > 0$ and $+\infty$ for $b \le 0$; a true value beyond the float range is $+\infty$, never `nan`, and no intermediate overflows while the result is representable. `a`, `b` and `z` are brought to one floating dtype, `result_type(a, b, z)`, as any elementwise operation would (an integer `z` becomes float); Python-scalar parameters are weak and leave `z`'s dtype alone. Half precision is evaluated in float32 and rounded once. + +`incomplete_beta` : **Cost.** Concrete $a$ and $b$ pick their branch in the public wrapper, before `jax.custom_jvp` traces them, so even under `jit` only that branch is compiled and run; a traced $a$ or $b$ goes through `lax.switch`, which compiles all four and runs one. Measured at $10^5$ points against the series (indicative, on a loaded machine): the continued fraction about 6x, `_large_a` about 3x -- both where the series was wrong. The $a$/$b$ gradient with traced parameters is at parity with the series-only code; its second-derivative compile is about 1.6-2x. **Under `vmap` over $a$ or $b$ every branch runs on every lane** (`switch` becomes `select`): 64 parameter pairs, all in the series regime, take 35 ms against 2.5 ms for the series alone. Where that matters, a Python loop of static calls (here about 15 ms) is faster. + +`incomplete_beta` : `a` and `b` must be **scalars**; `z` may be any shape. The $z$-derivative comes from a `jax.custom_jvp` and is exact: by Leibniz it is the integrand at the endpoint, $z^{a-1}(1-z)^{b-1}$. When $b$ is itself differentiated, the factor $(1-z)^{b-1}$ is evaluated as $\exp((b-1)\,\mathrm{log1p}(-z))$, so the mixed derivative $\partial_b\partial_z B$ keeps full precision as $z \to 0$ (rather than $\sim 10^{-16}/z$ through `log` of a rounded $1 - z$); a concrete $b$ keeps `pow`, which XLA simplifies for constant exponents. That `pow` has its own derivative rule: JAX differentiates a float power $x^y$ as $y\,x^{y-1}$, which is $0 \cdot \infty$ at $x = 0$ once differentiation has brought $y$ to 0 (by design, jax-ml/jax#14397), so with $a - 1$ or $b - 1$ an integer $n \ge 0$ every $z$-derivative from order $n + 2$ was `nan` at that endpoint (GH-73). The rule makes the $x$-derivative of $x^0$ exactly 0 at $x = 0$, and only there, so the $a$- and $b$-derivatives of the $z$-derivatives stay exact elsewhere. The `a` and `b` tangents have no cheap closed form and fall back to differentiating the implementation -- the branch dispatch, or at a concrete `a = 1` the closed form -- but only when actually requested -- `symbolic_zeros` skips them in the common case of differentiating with respect to $z$ alone. It is a `custom_jvp` and not a `custom_vjp` specifically so that `jax.hessian`'s `jacfwd(jacrev(...))` still composes. `sph_legendre_p`, `sph_harm_y` : The degree and order are **static Python `int`s** and may not be arrays, unlike SciPy's, which broadcast them. The returned shape is therefore $\theta$'s own rather than a broadcast against $n$ and $m$. This is not only a simplification: it is what makes the values right. `jax.scipy.special.sph_harm_y` takes them as arrays and pairs `n[i]` with `theta[i]` positionally, so a length-1 degree against a batch of angles is correct at index 0 and wrong everywhere else, by up to 1.18 absolute for $n \le 3$. ([Why](../explanation/why-not-upstream.md#the-case-that-is-none-of-the-above-upstream-is-wrong).) diff --git a/docs/reference/coverage.md b/docs/reference/coverage.md index 9ebea38..8e5b864 100644 --- a/docs/reference/coverage.md +++ b/docs/reference/coverage.md @@ -123,7 +123,7 @@ It is also the roadmap. A function upstream covers everywhere `spexial` supports Derivative: `(l j_{l-1}(z) - (l+1) j_{l+1}(z)) / (2l+1)`. `incomplete_beta` -: The *unregularized* B(a, b, z) of DLMF 8.17.1. Neither JAX nor scipy has one: their `betainc` is the regularized I_z(a, b), and reconstructing this as `beta(a, b) * betainc(a, b, z)` is `nan` for every b <= 0 -- B(a, b) has a pole there while the product does not, and b <= 0 is an ordinary slope in a double power-law density profile. `jax.scipy.special.hyp2f1` can express it via DLMF 8.17.7, but it is a `while_loop` whose trip count depends on its data, so under `vmap` every lane pays the worst lane's count and its derivative runs a second such loop. Two fixed-length series instead, switched at z = 1/2. The custom JVP is the strongest case in this table: by Leibniz the z-derivative is just the integrand at the endpoint, so it is exact and O(1) against 64 terms -- 143x faster on 70x less residual. `custom_jvp` rather than `custom_vjp` so `jacfwd(jacrev(...))` still composes. Contributed from `galax`. +: The *unregularized* B(a, b, z) of DLMF 8.17.1. Neither JAX nor scipy has one: their `betainc` is the regularized I_z(a, b), and reconstructing this as `beta(a, b) * betainc(a, b, z)` is `nan` for every b <= 0 -- B(a, b) has a pole there while the product does not, and b <= 0 is an ordinary slope in a double power-law density profile. `jax.scipy.special.hyp2f1` can express it via DLMF 8.17.7, but it is a `while_loop` whose trip count depends on its data, so under `vmap` every lane pays the worst lane's count and its derivative runs a second such loop. Two fixed-length series instead, switched at z = 1/2; where their binomial coefficients cancel or grow (b > 10, a > 8, or b < -5) fixed-length continued fractions and a shortened expansion take over. The custom JVP is the strongest case in this table: by Leibniz the z-derivative is just the integrand at the endpoint, so it is exact and O(1) against 64 terms -- 143x faster on 70x less residual. `custom_jvp` rather than `custom_vjp` so `jacfwd(jacrev(...))` still composes. Contributed from `galax`. Derivative: `z^(a-1) (1-z)^(b-1)`. diff --git a/src/spexial/_src/beta.py b/src/spexial/_src/beta.py index fc98c23..ed3793f 100644 --- a/src/spexial/_src/beta.py +++ b/src/spexial/_src/beta.py @@ -42,6 +42,7 @@ import functools as ft import math +from collections.abc import Callable import jax import jax.numpy as jnp @@ -70,13 +71,41 @@ and a trace-time Python loop is no faster than this while compiling worse. """ -_POLE_BAND = 1e-3 -"""Half-width of the band around `b + m == 0` where `_large_z` expands. +_NEAR = 0.5 +"""Half-width of the band around ``b + m == 0`` handled apart in `_expand_from`. -Below this the direct form cancels; above it the expansion's O(s^4 L^5) -truncation shows, for `L = log(1-z)`. +At most one step ``m`` has ``|b + m| < 1/2``. Its term, +``(w0^s - w^s) / s``, cancels for small ``s``; it is evaluated once, after the +scan, in a form with no cancellation for any ``s`` or dtype. Every other step +has ``|s| >= 1/2``, where the direct quotient loses nothing worth counting. +An earlier band of 1e-3, with an expansion in ``s`` inside it, left +``1e-3 <= |s| < ~0.1`` to the direct form: 5.8e-12 at ``a = 50, b = -0.999``, +and 3.5e-4 in float32. """ +_EXPRL_COEFFS = tuple(1.0 / math.factorial(k + 1) for k in reversed(range(18))) +"""Taylor coefficients of ``expm1(y) / y = sum_k y^k / (k+1)!``, highest first. + +At ``|y| < 1/2`` the first omitted term is ``0.5^18 / 19! ~ 3e-23``. Python +floats, so Horner's rule keeps the argument's dtype and weak type. Shared by +`_expm1_over` and `_a_eq_1`. +""" + + +def _expm1_over(y: AnyArray, /) -> AnyArray: + """``expm1(y) / y``, 1 at ``y = 0``, with exact derivatives of every order there. + + By its Taylor series for ``|y| < 1/2`` (a polynomial, so autodiff is exact + at 0), and by the quotient outside it, where nothing cancels. + """ + small = jnp.abs(y) < 0.5 + y_small = jnp.where(small, y, 0.0) + y_large = jnp.where(small, 1.0, y) + series = _EXPRL_COEFFS[0] + for c in _EXPRL_COEFFS[1:]: + series = series * y_small + c + return jnp.where(small, series, jnp.expm1(y_large) / y_large) # type: ignore[no-any-return] + def _small_z(a: ScalarLike, b: ScalarLike, z: AnyArrayLike, /) -> AnyArray: r"""$B(a, b, z)$ for $z \leq 1/2$, by the defining Taylor series. @@ -140,52 +169,463 @@ def _large_z(a: ScalarLike, b: ScalarLike, z: AnyArrayLike, /) -> AnyArray: Summed into a `jax.lax.scan` carry, for the same reason as `_small_z`. - Each term is $(e^{sL_1} - e^{sL_2})/s$ with $s = b + m$, $L_1 = \ln(1/2)$ - and $L_2 = \ln w$, which the running powers below evaluate directly. That - cancels catastrophically as $s \to 0$, so within `_POLE_BAND` of zero it - switches to the expansion of the same expression, + The terms are summed by `_expand_from`, which also handles the one term with + $b + m$ near zero, where the direct form cancels. + """ + w = 1.0 - z + # `_small_z(a, b, 1/2)` below looks like a scalar being recomputed per + # point, but computing it as a scalar and broadcasting is *slower*: XLA + # already folds the constant-array input, and doing it by hand breaks the + # fusion (measured 0.80x). + return _small_z(a, b, jnp.full_like(w, 0.5)) + _expand_from(a, b, w, 0.5) # type: ignore[no-any-return] + + +def _expand_from( + a: ScalarLike, b: ScalarLike, w: AnyArray, w0: AnyArrayLike, / +) -> AnyArray: + r"""$\int_w^{w_0} u^{b-1}(1-u)^{a-1}\,du$, expanding $(1-u)^{a-1}$ binomially. .. math:: - \frac{e^{sL_1} - e^{sL_2}}{s} - = \sum_{k \geq 1} \frac{L_1^k - L_2^k}{k!} s^{k-1} + \sum_{m=0}^\infty \frac{(1-a)_m}{m!} \frac{w_0^{b+m} - w^{b+m}}{b+m} - whose $L$-powers are loop-invariant, so this costs a few extra FMAs rather - than transcendentals. Carrying the $O(s)$ term also makes the - $b$-derivative right *at* $s = 0$, which integer slopes do hit (e.g. - $\gamma = 2$ in Zhao's Eq. 7). - """ - w = 1.0 - z - log_half, log_w = jnp.log(0.5), jnp.log(w) - # L1^k - L2^k over k!, for the near-pole expansion. - d1 = log_half - log_w - d2 = (log_half**2 - log_w**2) / 2 - d3 = (log_half**3 - log_w**3) / 6 - d4 = (log_half**4 - log_w**4) / 24 + with the :math:`b + m \to 0` term :math:`\ln(w_0 / w)`. The terms fall off + like :math:`((a - 1) w_0)^m / m!`, so this is the piece of `_large_z` above + :math:`z = 1/2` (:math:`w_0 = 1/2`), and of `_large_a` above its split + (:math:`w_0 = 2/(a+2)`, where :math:`(a-1) w_0 < 2` however large ``a``). + + Each term is :math:`(w_0^s - w^s)/s` with :math:`s = b + m`. That cancels as + :math:`s \to 0`; at most one step has :math:`|s| <` `_NEAR`, and it is + evaluated once, after the scan, as + + .. math:: + + \frac{w_0^s - w^s}{s} = w^s\,\Delta\, + \frac{\operatorname{expm1}(s\Delta)}{s\Delta}, + \qquad \Delta = \ln(w_0 / w), + which cancels for no :math:`s` and in no dtype; `_expm1_over` is a + polynomial near 0, so every :math:`b`-derivative is exact at :math:`s = 0`, + which integer slopes do hit (e.g. :math:`\gamma = 2` in Zhao's Eq. 7). + + The sum is carried divided by :math:`w_0^b` and scaled back at the end, + through logarithms only if :math:`w_0^b` itself would overflow -- so a very + negative :math:`b` cannot overflow an intermediate while the result is + representable. + + At :math:`w = 0` (:math:`z = 1`) there is nothing to cancel -- :math:`w^s` + is 0 for :math:`s > 0` -- so the direct form is used there whatever + :math:`s`; :math:`s \le 0` at :math:`w = 0` is the pole, which the callers + handle. :math:`\ln w` is taken of a safe value there, so that no + :math:`-\infty` sits under the mask. + + Summed into a `jax.lax.scan` carry: the terms are batched over ``w``, so + materializing them all at once would make this memory- rather than + flop-bound. + """ + # An array, weakly typed for a Python scalar: Python float arithmetic on a + # concrete `b` (0.5 ** -1100) would raise `OverflowError`, not return inf. + w0 = jnp.asarray(w0) + at_0 = w == 0 + w_safe = jnp.where(at_0, w0, w) + log_w0 = jnp.log(w0) + delta = log_w0 - jnp.log(w_safe) # log(w0 / w) >= 0 + # The sum is carried divided by w0^b, which is applied at the end: each term + # w0^(b+m) - w^(b+m) is w0^b (w0^m - r^b w^m), r = w / w0 <= 1. Unscaled, a + # very negative b overflowed w0^b in an intermediate while the result -- a + # *difference* of such terms -- was representable. + r_b = jnp.where(at_0, 0.0, jnp.exp(-b * delta)) # r^b; 0^b = 0 for b > 0 + + # The one step with |s| < `_NEAR` is skipped here and added afterwards; the + # scan only records its coefficient and `s` (scalars). At w = 0 there is + # nothing to cancel -- w^s = 0 for s > 0 -- so that step is taken directly + # (s <= 0 at w = 0 is the pole, which the callers handle). def step( - carry: tuple[AnyArray, AnyArray, ScalarLike, ScalarLike], m: ScalarLike, / - ) -> tuple[tuple[AnyArray, AnyArray, ScalarLike, ScalarLike], None]: - total, w_pow, half_pow, coeff = carry # coeff = (1-a)_m / m! + carry: tuple[AnyArray, AnyArray, AnyArray, ScalarLike, ScalarLike, ScalarLike], + m: ScalarLike, + /, + ) -> tuple[ + tuple[AnyArray, AnyArray, AnyArray, ScalarLike, ScalarLike, ScalarLike], None + ]: + total, w0_m, w_m, coeff, near_coeff, near_s = carry # coeff = (1-a)_m/m! s = b + m - near_pole = jnp.abs(s) < _POLE_BAND - s_safe = jnp.where(near_pole, 1.0, s) - term = jnp.where( - near_pole, - d1 + s * (d2 + s * (d3 + s * d4)), - (half_pow - w_pow) / s_safe, + in_band = jnp.abs(s) < _NEAR + skip = in_band & ~at_0 + s_safe = jnp.where(skip | (s == 0), 1.0, s) + total = total + coeff * jnp.where(skip, 0.0, (w0_m - w_m) / s_safe) + near_coeff = jnp.where(in_band, coeff, near_coeff) + near_s = jnp.where(in_band, s, near_s) + next_coeff = coeff * (m + 1.0 - a) / (m + 1.0) + return (total, w0_m * w0, w_m * w, next_coeff, near_coeff, near_s), None + + zero = jnp.zeros_like(log_w0 * b) # floating, weakly typed if both are + init = (jnp.zeros_like(w), jnp.ones_like(w), r_b, jnp.ones_like(a), zero, zero) + (total, _, _, _, near_coeff, near_s), _ = jax.lax.scan( + step, init, jnp.arange(_NTERMS), unroll=_UNROLL + ) + # The skipped step, scaled likewise: (w0^s - w^s) / s / w0^b + # = r^b w^m* (e^(s delta) - 1) / s = r^b w^m* delta expm1(s delta) / (s delta), + # which cancels for no s; m* = s - b. At w = 0 it was taken in the scan. + w_m_near = r_b * jnp.exp((near_s - b) * jnp.log(w_safe)) + near = near_coeff * w_m_near * delta * _expm1_over(near_s * delta) + scaled = total + jnp.where(at_0, 0.0, near) + # Apply w0^b: directly while it is finite, and through logarithms only when + # it would overflow (b log w0 > ~700), so as not to spend |log| * eps of + # accuracy on a round trip the common case does not need. + log_scale = b * log_w0 + big = log_scale > 700.0 + direct = scaled * jnp.exp(jnp.where(big, 0.0, log_scale)) + via_log = jnp.exp( + jnp.where(big, log_scale, 0.0) + + jnp.log(jnp.where(big & (scaled > 0), scaled, 1.0)) + ) + return jnp.where( # type: ignore[no-any-return] + big, jnp.where(scaled > 0, via_log, 0.0), direct + ) + + +_CF_FROM = 10.0 +r"""Above this ``b``, `_large_b` replaces the two series. + +Both series expand :math:`(1-t)^{b-1}` binomially, and its coefficients +:math:`(1-b)_k / k!` alternate and grow like :math:`b^k / k!`: at +:math:`z = 1/2` the sum is a near-total cancellation, worst relative error +:math:`2\times10^{-15}` at :math:`b = 10`, :math:`10^{-11}` at 30, and +:math:`10^{7}` at 100. The continued fraction is :math:`5\times10^{-14}` from +:math:`b = 0.1` up, so the switch can sit wherever the series is still exact. +""" + +_CF_UNROLL = 1 +"""Not unrolled, unlike the series. + +A traced ``a`` or ``b`` goes through a `lax.switch`, which compiles every +branch, so this is compiled whenever either is traced, whatever the values +(a concrete pair compiles only its own branch). Unrolled 16-fold it made a +second ``b``-derivative take 200 s to compile for no runtime gain (measured +39 vs 41 ms at 1e5 points); unrolled once, 11 s. +""" + +_CF_STEPS = 64 +r"""Double steps of the continued fraction (each an even and an odd term). + +The slowest case is the reflected fraction -- large first parameter -- just +above its switch point, at small ``a``: at :math:`a = 0.1, b = 10^3` it is +:math:`10^{-11}` at 32 steps, :math:`5\times10^{-14}` at 48 and +:math:`6\times10^{-15}` at 64, past which nothing changes. What remains is +rounding, growing like :math:`b\,\epsilon`: worst over +:math:`a \in [0.1, 50]`, :math:`4\times10^{-12}` at :math:`b = 10^5`, +:math:`5\times10^{-10}` at :math:`10^7`. +""" + + +def _continued_fraction( + a: AnyArrayLike, b: AnyArrayLike, x: AnyArray, /, steps: int | None = None +) -> AnyArray: + r"""Evaluate the DLMF 8.17.22 continued fraction by the modified Lentz method. + + .. math:: + + B(a, b, x) = \frac{x^a (1-x)^b}{a} \cdot + \cfrac{1}{1 + \cfrac{d_1}{1 + \cfrac{d_2}{1 + \cdots}}} + + with :math:`d_{2m+1} = -\frac{(a+m)(a+b+m)x}{(a+2m)(a+2m+1)}` and + :math:`d_{2m} = \frac{m(b-m)x}{(a+2m-1)(a+2m)}`. Returns the fraction, + :math:`1/(1 + d_1/(1 + \cdots))`. It converges fast for + :math:`x < (a+1)/(a+b+2)`, and its terms are bounded for any :math:`b > 0`, + so -- unlike the series -- nothing cancels as :math:`b` grows. A fixed + number of steps, as for the series, so `vmap` lanes do not wait on each + other. + """ + # Lentz's guard against a zero denominator: the dtype's smallest normal, as + # a Python float so that it does not promote the carry. + tiny = float(jnp.finfo(x.dtype).tiny) + guard = lambda v: jnp.where(jnp.abs(v) < tiny, tiny, v) # noqa: E731 + + def step( + carry: tuple[AnyArray, AnyArray, AnyArray], m: ScalarLike, / + ) -> tuple[tuple[AnyArray, AnyArray, AnyArray], None]: + c, d, h = carry + even = m * (b - m) * x / ((a + 2.0 * m - 1.0) * (a + 2.0 * m)) + odd = -(a + m) * (a + b + m) * x / ((a + 2.0 * m) * (a + 2.0 * m + 1.0)) + for coeff in (even, odd): + d = 1.0 / guard(1.0 + coeff * d) + c = guard(1.0 + coeff / c) + h = h * d * c + return (c, d, h), None + + d = 1.0 / guard(1.0 - (a + b) * x / (a + 1.0)) + init = (jnp.ones_like(x), d, d) + (_, _, h), _ = jax.lax.scan( + step, + init, + jnp.arange(1, (_CF_STEPS if steps is None else steps) + 1), + unroll=_CF_UNROLL, + ) + return h # type: ignore[no-any-return] + + +def _complete_beta(a: ScalarLike, b: ScalarLike, /) -> AnyArray: + r"""$\log B(a, b)$ for $a, b > 0$, as the two fractions at the switch point. + + :math:`B(a, b) = B(a, b, x_0) + B(b, a, 1 - x_0)`, two positive terms, so no + cancellation. Not ``betaln``: `jax.scipy.special.betaln` is only good to + :math:`3\times10^{-7}` at :math:`(a, b) = (8, 10)`. Returned as a logarithm, + so that a complete beta function far below the smallest normal number -- + :math:`B(301, 1000) \approx 4\times10^{-307}` -- does not round to zero before + it is used. Computed once per call, not per point, so `vmap` over ``z`` does + not repeat it. + """ + x0 = (a + 1.0) / (a + b + 2.0) + # The front factor x^a (1-x)^b is the same for both terms, and is formed from + # x0 itself: `log1p(-x0)`, not `log` of a rounded `1 - x0` scaled by b. + log_front = a * jnp.log(x0) + b * jnp.log1p(-x0) + h = _continued_fraction( + jnp.stack([a, b]), + jnp.stack([b, a]), + jnp.stack([x0, 1.0 - x0]), + ) + return log_front + jnp.log(h[0] / a + h[1] / b) # type: ignore[no-any-return] + + +def _large_b(a: ScalarLike, b: ScalarLike, z: AnyArray, /) -> AnyArray: + r"""$B(a, b, z)$ for $b > 0$, by the continued fraction and reflection. + + Below the switch point :math:`x_0 = (a+1)/(a+b+2)` the fraction converges + as it stands; above it, by the reflection + :math:`B(a, b, z) = B(a, b) - B(b, a, 1-z)`, where it converges for the + swapped arguments. One fraction per point, with the arguments swapped where + reflected; the complete :math:`B(a, b)` comes from `_complete_beta`. + + Each term is :math:`\exp(\log(\text{front}) + \log(h / p))`, with + :math:`p` the fraction's first parameter: the front factor + :math:`z^a (1-z)^b` is the same either way round and is formed from ``z``, + never from a rounded ``1 - z`` scaled by ``b``; and the fraction is folded + into the exponent, so a front factor below the smallest normal number does + not flush to zero while the term itself is representable. + """ + if jnp.dtype(z.dtype).itemsize < 4: + # Half precision has too few bits for Lentz's recurrence to settle; work + # in float32 and round the result once. + f32 = jnp.float32 + return _large_b(jnp.asarray(a, f32), jnp.asarray(b, f32), z.astype(f32)).astype( + z.dtype ) - total = total + coeff * term - carry = (total, w_pow * w, half_pow * 0.5, coeff * (m + 1.0 - a) / (m + 1.0)) - return carry, None + x0 = (a + 1.0) / (a + b + 2.0) + swap = z >= x0 + # z = 0 and z = 1 make the term exactly zero (the direct one at 0, the + # reflected one at 1). Evaluated, `log(0)` would put `0 * -inf` into the + # a- and b-derivatives; it is a genuine zero for every a, b > 0, so its + # parameter derivatives are zero too. + endpoint = (z == 0) | (z == 1) + zs = jnp.where(endpoint, 0.5, z) + log_front = a * jnp.log(zs) + b * jnp.log1p(-zs) + first = jnp.where(swap, b, a) + h = _continued_fraction(first, jnp.where(swap, a, b), jnp.where(swap, 1.0 - zs, zs)) + term = jnp.where(endpoint, 0.0, jnp.exp(log_front + jnp.log(h / first))) + reflected = jnp.exp(_complete_beta(a, b)) - term + out = jnp.where(swap, reflected, term) + # Past b ~ 1/eps the switch point x0 is below eps, `1 - x0` rounds to 1, and + # the reflected fraction's first denominator is exactly zero. Long before + # that the b*eps rounding has taken every digit (0.1 relative by b ~ 1e15), + # so say so with `nan` rather than return a confident `inf` or `0`. + return jnp.where(1.0 - x0 == 1.0, jnp.nan, out) # type: ignore[no-any-return] + + +def _series(a: ScalarLike, b: ScalarLike, z: AnyArray, /) -> AnyArray: + """$B(a, b, z)$ by `_small_z` and `_large_z`, switched at $z = 1/2$.""" + # For b <= 0 the integral diverges at z = 1: a genuine pole, +inf (GH-67). + # `_large_z` cannot see it -- at w = 1 - z = 0 its expansion is `inf - inf` + # -- so the pole is returned directly, and the series is handed a harmless + # z there, so that its `nan` cannot reach a cotangent through the `where`. + pole = (z == 1.0) & (b <= 0) + z = jnp.where(pole, 0.5, z) + # Both branches are evaluated, so clamp each one's input to the range where + # it is well behaved; `where` then discards the unused value. Clamped by + # `where`, not `minimum`/`maximum`: those split the derivative at a tie, + # and at exactly z = 1/2 the series' z-derivative came out halved. + lower = z <= 0.5 + value = jnp.where( + lower, + _small_z(a, b, jnp.where(lower, z, 0.5)), + _large_z(a, b, jnp.where(lower, 0.5, z)), + ) + return jnp.where(pole, jnp.inf, value) # type: ignore[no-any-return] - # `_small_z(a, b, 1/2)` below looks like a scalar being recomputed per - # point, but computing it as a scalar and broadcasting is *slower*: XLA - # already folds the constant-array input, and doing it by hand breaks the - # fusion (measured 0.80x). - init = (jnp.zeros_like(w), w**b, 0.5**b, jnp.ones_like(a)) - (total, _, _, _), _ = jax.lax.scan(step, init, jnp.arange(_NTERMS), unroll=_UNROLL) - return _small_z(a, b, jnp.full_like(w, 0.5)) + total # type: ignore[no-any-return] + +_CF_A_FROM = 8.0 +r"""Above this ``a``, the series give way to `_large_b` or `_large_a`. + +`_large_z` expands :math:`(1-u)^{a-1}` over :math:`u \in [w, 1/2]`, and its +coefficients :math:`(1-a)_m/m!` cancel just as :math:`(1-b)_k/k!` do for +large :math:`b`: measured worst over :math:`b \in [-50, 10]`, +:math:`6\times10^{-14}` at :math:`a = 8`, :math:`4\times10^{-11}` at 16, +:math:`2\times10^{-8}` at 24, and wrong from about 50. +""" + +_CF_A_B_MIN = 0.1 +r"""For large ``a``: at or above this ``b``, `_large_b`; below it, `_large_a`. + +`_large_b`'s reflection subtracts from the complete :math:`B(a, b) \sim 1/b`, +so it loses about :math:`\log_{10}(1/b)` digits as :math:`b \to 0^+` +(:math:`10^{-8}` at :math:`b = 10^{-8}`), and has no meaning at +:math:`b \le 0`, where :math:`B(a, b)` diverges. From 0.1 it is +:math:`4\times10^{-13}` or better to :math:`a = 50`; below it `_large_a`, which +needs no reflection, takes over. +""" + + +def _large_a(a: ScalarLike, b: ScalarLike, z: AnyArray, /) -> AnyArray: + r"""$B(a, b, z)$ for large $a$ and $b < $ `_CF_A_B_MIN`, including $b \le 0$. + + Split at :math:`s = a/(a+2)`. Below it, the continued fraction directly: + that is at or below its switch point :math:`x_0 = (a+1)/(a+b+2)` whenever + :math:`b \le 1 + 2/a` -- so for every :math:`b < 0.1` routed here -- and + beyond :math:`x_0` it still converges in this range, only more slowly + (checked against mpmath; for :math:`-(a+2) < b \le -1`, :math:`x_0 > 1`, + and below that :math:`x_0 < 0`, where the textbook criterion says + nothing). Above it, + + .. math:: + + B(a, b, z) = B(a, b, s) + \int_{1-z}^{2/(a+2)} u^{b-1}(1-u)^{a-1}\,du, + + the second term by `_expand_from` with :math:`w_0 = 2/(a+2)`. That is the + expansion `_large_z` uses from :math:`w_0 = 1/2`, where its terms grow like + :math:`(a/2)^m/m!` and cancel; here they fall like :math:`2^m/m!` + (:math:`(a-1) w_0 < 2`), costing under a digit. Measured against mpmath over + :math:`a \in [12, 100]`, :math:`b \in [-50, 0.1)` and :math:`z` to + :math:`1 - 10^{-12}`: :math:`2\times10^{-14}`, where the series was + :math:`10^{-9}` at :math:`a = 24` and :math:`10^{22}` at 100. + + At :math:`z = 1` with :math:`b \le 0` the integral diverges: the pole is + returned as ``inf``, with the expansion handed a harmless ``w`` there. At + :math:`z = 0` the term is a genuine zero, guarded as in `_large_b`. + """ + if jnp.dtype(z.dtype).itemsize < 4: + f32 = jnp.float32 + return _large_a(jnp.asarray(a, f32), jnp.asarray(b, f32), z.astype(f32)).astype( + z.dtype + ) + # Arrays, weakly typed when ``a`` is a Python scalar, so `z` sets the dtype. + split = jnp.asarray(a / (a + 2.0)) + w0 = jnp.asarray(2.0 / (a + 2.0)) + below = z < split + pole = (z == 1.0) & (b <= 0) + at_0 = z == 0 + # Below the split: the fraction at z itself (z = 0 guarded, as in + # `_large_b`); above it: the fraction at the split, a scalar, plus the + # expansion out to z. + xs = jnp.where(below & ~at_0, z, split) + log_front = a * jnp.log(xs) + b * jnp.log1p(-xs) + direct = jnp.exp(log_front + jnp.log(_continued_fraction(a, b, xs) / a)) + direct = jnp.where(at_0, 0.0, direct) + log_front_s = a * jnp.log(split) + b * jnp.log(w0) + at_split = jnp.exp(log_front_s + jnp.log(_continued_fraction(a, b, split) / a)) + # At z = 1 (the pole when b <= 0) `_expand_from` takes w = 0 safely itself. + w = jnp.where(below, w0, 1.0 - z) + above = at_split + _expand_from(a, b, w, w0) + return jnp.where( # type: ignore[no-any-return] + pole, jnp.inf, jnp.where(below, direct, above) + ) + + +_NEG_B_FROM = -5.0 +r"""Below this ``b`` (for ``a`` up to `_CF_A_FROM`), `_negative_b` replaces the series. + +`_small_z`'s terms carry :math:`(1-b)_k / k!`, which for very negative +:math:`b` grows like :math:`(|b| z)^k / k!` before it decays: 64 terms cover +:math:`|b| z \lesssim 10`. Measured worst over :math:`a \in [0.5, 8]`: +:math:`2\times10^{-15}` at :math:`b = -5`, :math:`6\times10^{-12}` at -10, +:math:`2\times10^{-7}` at -20, 8% at -50, no correct digits by -200. +""" + +_NEG_B_STEPS = 128 +"""Double steps of the continued fraction in `_negative_b`. + +At very negative ``b`` and small ``a`` the fraction converges more slowly than +in `_large_b`: 64 steps leave 5e-9 at ``a = 0.5, b = -1100``; 128 give 7e-15, +and 256 change nothing. +""" + + +def _negative_b(a: ScalarLike, b: ScalarLike, z: AnyArray, /) -> AnyArray: + r"""$B(a, b, z)$ for very negative $b$, by the continued fraction directly. + + No reflection -- it would need :math:`B(a, b)`, which diverges for + :math:`b \le 0` -- and none needed: for :math:`b` this negative the fraction + converges at every :math:`z \in [0, 1)` (checked against mpmath for + :math:`a \in [0.01, 8]`, :math:`b \in [-1100, -5]`: worst + :math:`6\times10^{-14}`). The term is formed in log space, as in + `_large_b`, so a huge value that is still representable does not overflow + on the way. :math:`z = 0` is a genuine zero; :math:`z = 1` the pole. + """ + if jnp.dtype(z.dtype).itemsize < 4: + f32 = jnp.float32 + return _negative_b( + jnp.asarray(a, f32), jnp.asarray(b, f32), z.astype(f32) + ).astype(z.dtype) + endpoint = (z == 0) | (z == 1) + zs = jnp.where(endpoint, 0.5, z) + h = _continued_fraction(a, b, zs, steps=_NEG_B_STEPS) + term = jnp.exp(a * jnp.log(zs) + b * jnp.log1p(-zs) + jnp.log(h / a)) + return jnp.where( # type: ignore[no-any-return] + z == 1, jnp.inf, jnp.where(z == 0, 0.0, term) + ) + + +_SERIES, _CONTINUED_FRACTION, _LARGE_A, _NEGATIVE_B, _EITHER = 0, 1, 2, 3, 4 +"""Which evaluation `_incomplete_beta_core` runs; static, so it is compiled alone. + +`_EITHER` is for a traced ``a`` or ``b``, whose branch is only known at run time: +`_dispatch` then switches between the others. +""" + + +def _branch_index(a: ScalarLike, b: ScalarLike, /) -> ScalarLike: + """Return the branch index (`_SERIES`, `_LARGE_A`, ...) for ``a`` and ``b``.""" + large_a = jnp.where(b >= _CF_A_B_MIN, _CONTINUED_FRACTION, _LARGE_A) + small_a = jnp.where(b < _NEG_B_FROM, _NEGATIVE_B, _SERIES) + return jnp.where( # type: ignore[no-any-return] + b > _CF_FROM, _CONTINUED_FRACTION, jnp.where(a > _CF_A_FROM, large_a, small_a) + ) + + +def _branch(a: ScalarLike, b: ScalarLike, /) -> int: + """Pick the static branch for concrete ``a`` and ``b``, else `_EITHER`. + + Decided in the public wrapper, before `jax.custom_jvp` lifts every argument + to a tracer: inside it, even a literal ``b`` is traced under `jit`, so a + choice made there would always compile every branch. + """ + if isinstance(a, jax.core.Tracer) or isinstance(b, jax.core.Tracer): + return _EITHER + # Plain Python, mirroring `_branch_index`: `jnp` ops here would be staged + # into an enclosing `jit` trace even on concrete inputs. + if b > _CF_FROM: + return _CONTINUED_FRACTION + if a > _CF_A_FROM: + return _CONTINUED_FRACTION if b >= _CF_A_B_MIN else _LARGE_A + return _NEGATIVE_B if b < _NEG_B_FROM else _SERIES + + +def _incomplete_beta_impl( + a: ScalarLike, b: ScalarLike, z: AnyArrayLike, branch: int, / +) -> AnyArray: + r"""$B(a, b, z)$ for $a > 0$, any real $b$, and $z \in [0, 1]$.""" + z = jnp.asarray(z) + if not jnp.issubdtype(z.dtype, jnp.inexact): + # An integer `z` would otherwise carry its dtype into the continued + # fraction's switch point, (a+1)/(a+b+2), and truncate it to zero. + z = z.astype(jnp.promote_types(z.dtype, float)) + # Promote `z` to the common type of all three, as any elementwise op would + # (GH-66): a float32 `z` with a strong float64 `b` otherwise starts a `scan` + # carry in float32 that the first step promotes to float64, which `scan` + # rejects. Weak (Python) scalars do not promote, so the common case keeps + # `z`'s own dtype and weak type. + dtype = jnp.result_type(a, b, z) + if dtype != z.dtype: + z = z.astype(dtype) + return (_series, _large_b, _large_a, _negative_b)[branch](a, b, z) _EXPRL_BAND = 0.5 @@ -195,15 +635,6 @@ def step( its first three derivatives; below it, those derivatives cancel. """ -_EXPRL_COEFFS = tuple(1.0 / math.factorial(k + 1) for k in reversed(range(18))) -"""Taylor coefficients of ``expm1(x) / x = sum_k x^k / (k+1)!``, highest first. - -At ``|x| < 1/2`` the first omitted term is ``0.5^18 / 19! ~ 3e-23``, far below -float64 resolution. Python floats, not an array, so that Horner's rule in -`_a_eq_1` keeps the input's dtype and weak type rather than promoting both to -the default float. -""" - _LOG1P_UPTO = 0.3 """Below this ``z``, `_log1m` uses ``log1p(-z)``; above it, ``log(1 - z)``. @@ -345,18 +776,6 @@ def _is_static_one(a: object, /) -> bool: ) -def _incomplete_beta_impl(a: ScalarLike, b: ScalarLike, z: AnyArrayLike, /) -> AnyArray: - r"""$B(a, b, z)$ for $a > 0$, any real $b$, and $z \in [0, 1]$.""" - z = jnp.asarray(z) - # Both branches are evaluated, so clamp each one's input to the range where - # it is well behaved; `where` then discards the unused value. - return jnp.where( # type: ignore[no-any-return] - z <= 0.5, - _small_z(a, b, jnp.minimum(z, 0.5)), - _large_z(a, b, jnp.maximum(z, 0.5)), - ) - - def incomplete_beta(a: ScalarLike, b: ScalarLike, z: AnyArrayLike, /) -> AnyArray: r"""Unregularized incomplete beta function :math:`B(a, b, z)`. @@ -397,24 +816,30 @@ def incomplete_beta(a: ScalarLike, b: ScalarLike, z: AnyArrayLike, /) -> AnyArra Notes ----- Two fixed-length series, switched at :math:`z = 1/2`, each converging like - :math:`2^{-k}`; see `_small_z` and `_large_z`. The + :math:`2^{-k}`; see `_small_z` and `_large_z`. Outside :math:`a \le 8`, + :math:`-5 \le b \le 10` their binomial coefficients cancel or grow, and + three fixed-length methods take over: the continued fraction with + reflection (`_large_b`: :math:`b > 10`, or :math:`a > 8` with + :math:`b \ge 0.1`), `_large_a` (:math:`a > 8`, :math:`b < 0.1`), and the + continued fraction directly (`_negative_b`: :math:`a \le 8`, + :math:`b < -5`). The :math:`z`-derivative is supplied by a `jax.custom_jvp` and is exact and O(1) -- by Leibniz it is just the integrand at the endpoint, :math:`z^{a-1}(1-z)^{b-1}` -- rather than differentiating through 64 terms. - The derivative rules are `jax.custom_jvp`, not `jax.custom_vjp`, so that - `jax.hessian`'s ``jacfwd(jacrev(...))`` still composes. They sit on inner - cores: `incomplete_beta` itself is a plain function that dispatches between - them, so it has no ``.fun`` or ``.defjvp`` of its own. + It is a `custom_jvp` rather than a `custom_vjp` so that `jax.hessian`'s + ``jacfwd(jacrev(...))`` still composes. The rules sit on inner cores: + `incomplete_beta` itself is a plain function that dispatches between them, + so it has no ``.fun`` or ``.defjvp`` of its own. When ``a`` is a concrete 1 (a Python or NumPy scalar, or a concrete 0-d array; not a traced value) the integral is elementary, - :math:`(1 - (1-z)^b)/b`, and that closed form replaces the series; see - `_a_eq_1`. It carries the same exact + :math:`(1 - (1-z)^b)/b`, and that closed form replaces the series or + continued fraction; see `_a_eq_1`. It carries the same exact :math:`z`-derivative rule, and its ``b``-derivative is autodiff of the closed form, which is elementary. A traced ``a`` cannot be inspected and - takes the series even at 1, which holds its accuracy only for - :math:`\lvert b \rvert \lesssim 10`; keep ``a`` concrete for the closed - form's wider domain. + takes the branch dispatch below even at 1, which holds its accuracy only + for :math:`\lvert b \rvert \lesssim 10` in the series regime; keep ``a`` + concrete for the closed form's wider domain. Examples -------- @@ -443,37 +868,161 @@ def incomplete_beta(a: ScalarLike, b: ScalarLike, z: AnyArrayLike, /) -> AnyArra True With ``a`` a literal 1 the integral is elementary, and that closed form is - used instead of the series: + used instead: >>> round(float(sp.incomplete_beta(1.0, 0.0, jnp.asarray(0.5))), 8) 0.69314718 """ - # Decided at trace time, so it costs nothing when it does not apply. A traced - # `a` -- e.g. one being differentiated or `vmap`ped -- takes the series. + # Decided at trace time, so it costs nothing when it does not apply. A + # traced `a` -- e.g. one being differentiated or `vmap`ped -- falls through + # to the branch dispatch below. if _is_static_one(a): if np.ndim(b) != 0: - # The series path cannot broadcast `b` either (it raises inside its - # `scan`); say so here too, rather than answer for some `a` only. + # The branch dispatch cannot broadcast `b` either (it raises inside + # its `scan`); say so here too, rather than answer for some `a` only. msg = f"incomplete_beta: `b` must be a scalar, got shape {np.shape(b)}" raise TypeError(msg) - # An integer `z` promotes to float, as on the series path; against `b` + # An integer `z` promotes to float, as on the other paths; against `b` # the closed form's own arithmetic promotes it as any elementwise op. z = jnp.asarray(z) if not jnp.issubdtype(z.dtype, jnp.inexact): z = z.astype(jnp.promote_types(z.dtype, float)) return _a_eq_1_core(b, z) - return _incomplete_beta_core(a, b, z) + # The branch is chosen from the arguments as given -- before the promotion + # below, whose `jnp` ops would turn a literal into a staged value under an + # enclosing `jit` and so lose the static choice. + branch = _branch(a, b) + a, b, z = _promote(a, b, z) + if branch != _EITHER: + return _incomplete_beta_core(a, b, z, branch) + return _dispatch(a, b, z) + + +def _dispatch(a: ScalarLike, b: ScalarLike, z: AnyArray, /) -> AnyArray: + """Pick the branch at run time, for a traced ``a`` or ``b``. + + The `switch` sits outside the custom JVP, each branch its own static + `_incomplete_beta_core`: inside, the rule's `jvp` of a batched `switch` + leaves a `stop_gradient` in the linearized program that JAX cannot + transpose, so ``grad`` of a `vmap` over ``a`` or ``b`` raised. + """ + index = _branch_index(a, b) + # `a` and `b` are scalars, so `switch` runs one branch. Under `vmap` it + # becomes a `select` that runs every branch, on every lane. An unselected + # branch may then return `nan` or `inf` -- the series at large `b`, the + # reflection at `b <= 0` -- and autodiff multiplies its Jacobian by the + # zero cotangent `select` gives it, `0 * inf = nan`. What stops that + # reaching `a` and `b` is the `where(mine, ...)` on each branch's inputs, + # whose own transpose zeroes the unselected lane's cotangent. The + # substituted values matter only in that they keep the unselected branches + # cheap and finite; any value would do for correctness. `z` needs no mask: + # its cotangent is selected per lane after each branch's transpose, so an + # unselected branch's infinite (1-z)^(b-1) at z = 1 is discarded. + safe = ( + (1.0, 1.0), # series + (1.0, 2.0 * _CF_FROM), # continued fraction + (2.0 * _CF_A_FROM, 0.0), # large a + (1.0, 2.0 * _NEG_B_FROM), # negative b + ) + + def run(k: int, /) -> Callable[[], AnyArray]: + def go() -> AnyArray: + mine = index == k + ak = jnp.where(mine, a, safe[k][0]) + bk = jnp.where(mine, b, safe[k][1]) + return _incomplete_beta_core(ak, bk, z, k) # type: ignore[no-any-return] + + return go + + return jax.lax.switch(index, [run(k) for k in range(len(safe))]) # type: ignore[no-any-return] + + +def _promote( + a: ScalarLike, b: ScalarLike, z: AnyArrayLike, / +) -> tuple[ScalarLike, ScalarLike, AnyArray]: + """Make ``a``, ``b`` and ``z`` floating, and the strong ones of one dtype. + + Integer ``z`` becomes float (otherwise it carries its dtype into the + continued fraction's switch point and truncates it to zero), then takes + ``result_type(a, b, z)`` (GH-66). Integer ``a`` and ``b`` become float too + -- an integer seeding a `scan` carry that a float then updates is a type + error, and an integer primal has a ``float0`` tangent the custom JVP + cannot build -- and a *strong* ``a`` or ``b`` of another dtype is cast to + the common one, for the same reason (float32 ``a`` with float64 ``b``). + Weak parameters -- Python floats -- are left alone: they never change a + carry's type, and casting them down to a float32 ``z`` would compute the + parameter-only quantities (the switch point, the complete beta function) + in float32 for nothing, at ``b * eps`` cost. + """ + z = jnp.asarray(z) + if not jnp.issubdtype(z.dtype, jnp.inexact): + z = z.astype(jnp.promote_types(z.dtype, float)) + dtype = jnp.result_type(a, b, z) + if dtype != z.dtype: + z = z.astype(dtype) + + def match(p: ScalarLike, /) -> ScalarLike: + if isinstance(p, int | float) and not isinstance(p, bool): + return float(p) # a weak float + p = jnp.asarray(p) + if p.weak_type: + if jnp.issubdtype(p.dtype, jnp.inexact): + return p + return p * 1.0 # a weak integer becomes a weak float + return p.astype(dtype) + + return match(a), match(b), z @jax.custom_jvp -def _incomplete_beta_core(a: ScalarLike, b: ScalarLike, z: AnyArrayLike, /) -> AnyArray: - """`incomplete_beta` by the series, with an exact O(1) `z`-derivative rule.""" - return _incomplete_beta_impl(a, b, z) +def _pow(x: AnyArrayLike, y: ScalarLike, /) -> AnyArray: + """``x ** y`` for ``x >= 0``, with every x-derivative exact at ``x = 0``. + + JAX differentiates a float-exponent power as ``y x^(y-1)``, which at + ``x = 0`` is ``0 * inf`` once differentiation has brought ``y`` to 0 -- + upstream's deliberate reading of ``**`` on floats as the real function + ``x^y``, not differentiable at (0, 0) (jax-ml/jax#14397). For an integer + ``y = n >= 0`` that made the z-rule's derivatives from order ``n + 2`` on + ``nan`` at the endpoint (GH-73). Here the x-derivative of ``x^0`` at + ``x = 0`` is 0 exactly, and the rule recurses through `_pow`, so every order + meets that case in turn. + """ + return jnp.asarray(x) ** y + + +@_pow.defjvp +def _pow_jvp( + primals: tuple[AnyArrayLike, ScalarLike], + tangents: tuple[AnyArrayLike, ScalarLike], + /, +) -> tuple[AnyArray, AnyArray]: + x, y = primals + x_dot, y_dot = tangents + out = _pow(x, y) + # Only at x = 0: guarding y = 0 alone would also zero the y-derivative of + # this, y x^(y-1) -> x^(y-1), at every x -- the bug that removed JAX's own + # special case (jax-ml/jax#12033). Doubly, so the masked 0 * inf cannot + # reach a cotangent. + corner = (x == 0) & (y == 0) + dx = jnp.where(corner, 0.0, y * _pow(jnp.where(corner, 1.0, x), y - 1.0)) + # d/dy x^y = log(x) x^y, which is 0 at x = 0 for y > 0; `log` of a safe + # value there, as JAX does. + dy = jnp.log(jnp.where(x == 0, 1.0, x)) * out + return out, dx * x_dot + dy * y_dot + + +@ft.partial(jax.custom_jvp, nondiff_argnums=(3,)) +def _incomplete_beta_core( + a: ScalarLike, b: ScalarLike, z: AnyArrayLike, branch: int, / +) -> AnyArray: + """`incomplete_beta` for a given static branch, with its derivative rule.""" + return _incomplete_beta_impl(a, b, z, branch) @ft.partial(_incomplete_beta_core.defjvp, symbolic_zeros=True) def _incomplete_beta_jvp( + branch: int, primals: tuple[ScalarLike, ScalarLike, AnyArray], tangents: tuple[ ScalarLike | SymbolicZero, ScalarLike | SymbolicZero, AnyArray | SymbolicZero @@ -483,27 +1032,54 @@ def _incomplete_beta_jvp( a, b, z = primals a_dot, b_dot, z_dot = tangents - primal_out = _incomplete_beta_impl(a, b, z) - tangent_out = jnp.zeros_like(primal_out) - - # d/dz B(a, b, z) = z^(a-1) (1-z)^(b-1): the integrand at the endpoint. - if not isinstance(z_dot, SymbolicZero): - tangent_out = tangent_out + z ** (a - 1.0) * (1.0 - z) ** (b - 1.0) * z_dot - # The a/b tangents are only needed when the parameters are themselves # differentiated; there is no cheap closed form, so fall back to autodiff of - # the series. Skipped entirely in the common case, where the differentiation - # is with respect to position at fixed a and b. + # the implementation. Skipped entirely in the common case, where the + # differentiation is with respect to position at fixed a and b. When it does + # run, the primal comes from the same `jvp`, not a second evaluation. + # + # It is checkpointed. Reverse-mode through `_dispatch`'s `switch` makes + # every branch emit the same set of residuals, zero-filling the others', so + # the series branch would allocate the continued fraction's per-step carries + # (64 x the points) just to discard them. Checkpointed, its residuals are + # its inputs. Measured on the a/b gradient at 1e5 points, b = 1.5: 63 -> 46 + # ms (main, with no branching: 40), and the second-derivative compile 4.9 -> + # 3.4 s. Only this `jvp`: checkpointing the whole core also recomputed the + # primal in a z-gradient, 4.3 -> 5.6 ms for `value_and_grad`. a_zero, b_zero = isinstance(a_dot, SymbolicZero), isinstance(b_dot, SymbolicZero) - if not (a_zero and b_zero): - _, ab_tangent = jax.jvp( - lambda aa, bb: _incomplete_beta_impl(aa, bb, z), + if a_zero and b_zero: + primal_out = _incomplete_beta_impl(a, b, z, branch) + tangent_out = jnp.zeros_like(primal_out) + else: + primal_out, tangent_out = jax.jvp( + jax.checkpoint(lambda aa, bb: _incomplete_beta_impl(aa, bb, z, branch)), (a, b), ( jnp.zeros_like(a) if a_zero else a_dot, jnp.zeros_like(b) if b_zero else b_dot, ), ) - tangent_out = tangent_out + ab_tangent + + # d/dz B(a, b, z) = z^(a-1) (1-z)^(b-1): the integrand at the endpoint. + if not isinstance(z_dot, SymbolicZero): + if isinstance(b, jax.core.Tracer): + # `b` may itself be differentiated, so write (1-z)^(b-1) so that its + # `b`-derivative carries `log1p(-z)`, not `log(1 - z)` of a rounded + # `1 - z`, which keeps only ~1e-16 / z relative precision (GH-68). + # At z = 1 itself `pow` takes over, by a double `where`: `log1p(-z)` is + # `-inf` there, and any clamp of it differentiates as `0 * -inf`, + # making the second and third z-derivatives `nan`. `pow` has exact + # derivatives at a zero base, as on the concrete path. + z_arr = jnp.asarray(z) + inside = z_arr < 1.0 + z_in = jnp.where(inside, z_arr, 0.0) + via_log1p = jnp.exp((b - 1.0) * jnp.log1p(-z_in)) + one_minus_z_pow = jnp.where(inside, via_log1p, _pow(1.0 - z_arr, b - 1.0)) + else: + # A concrete `b` has no derivative to get wrong, and as a constant + # exponent XLA can simplify `pow` (to a reciprocal at b = 0, a square + # root at b = 3/2), which `exp(... log1p)` would hide from it. + one_minus_z_pow = _pow(1.0 - z, b - 1.0) + tangent_out = tangent_out + _pow(z, a - 1.0) * one_minus_z_pow * z_dot return primal_out, tangent_out diff --git a/src/spexial/_src/registry.py b/src/spexial/_src/registry.py index adb0ee9..56f95a5 100644 --- a/src/spexial/_src/registry.py +++ b/src/spexial/_src/registry.py @@ -493,7 +493,10 @@ class Coverage: "DLMF 8.17.7, but it is a `while_loop` whose trip count depends on " "its data, so under `vmap` every lane pays the worst lane's count " "and its derivative runs a second such loop. Two fixed-length " - "series instead, switched at z = 1/2. The custom JVP is the " + "series instead, switched at z = 1/2; where their binomial " + "coefficients cancel or grow (b > 10, a > 8, or b < -5) " + "fixed-length continued fractions and a shortened expansion take " + "over. The custom JVP is the " "strongest case in this table: by Leibniz the z-derivative is just " "the integrand at the endpoint, so it is exact and O(1) against 64 " "terms -- 143x faster on 70x less residual. `custom_jvp` rather " diff --git a/tests/unit/conftest.py b/tests/unit/conftest.py new file mode 100644 index 0000000..a8a6385 --- /dev/null +++ b/tests/unit/conftest.py @@ -0,0 +1,52 @@ +"""Shared fixtures for the unit tests.""" + +import os +import sys +from pathlib import Path + +import jax +import pytest + +_RSS_LIMIT = 2 * 1024**3 +"""Resident memory above which `_release_compiled_programs` drops JAX's caches.""" + + +def _resident_bytes() -> int: + """Return resident memory: current where the platform says, else the peak.""" + try: + pages = Path("/proc/self/statm").read_text().split()[1] # Linux, as on CI + return int(pages) * os.sysconf("SC_PAGE_SIZE") + except OSError: + pass + try: + import psutil # noqa: PLC0415 + + return int(psutil.Process().memory_info().rss) + except ImportError: + pass + try: + # Unix only, so imported here: on Windows it does not exist. + import resource # noqa: PLC0415 + except ImportError: + return 0 # nothing to measure with: never clear, as before this fixture + # Peak, not current: past the limit this clears after every test, which + # costs only time. + peak = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss + return peak if sys.platform == "darwin" else peak * 1024 + + +@pytest.fixture(autouse=True) +def _release_compiled_programs(): + """Drop JAX's compilation caches when this process grows past `_RSS_LIMIT`. + + Many unit tests compile large programs of their own -- every branch of a + four-way `switch`, often with derivatives -- and JAX keeps them all for the + session: one process peaked at 5.9 GB, and four ``--dist=loadfile`` + workers on a 16 GB CI runner were enough for it to be killed mid-run. + Clearing after every test held the peak to 1.9 GB but nearly doubled the + file's runtime, by recompiling programs that later tests reuse; clearing + only past the limit keeps that reuse until memory is the problem. + """ + yield + if _resident_bytes() > _RSS_LIMIT: + jax.clear_caches() diff --git a/tests/unit/test_beta.py b/tests/unit/test_beta.py index 7be9c96..5a6d095 100644 --- a/tests/unit/test_beta.py +++ b/tests/unit/test_beta.py @@ -18,7 +18,12 @@ from scipy.special import beta as scipy_beta, betainc as scipy_betainc, hyp2f1 import spexial as sp -from spexial._src.beta import _EXPRL_BAND, _incomplete_beta_core, _is_static_one +from spexial._src.beta import ( + _EXPRL_BAND, + _SERIES, + _incomplete_beta_core, + _is_static_one, +) # `a > 0` always. `b` is any real: the negative and zero values are the reason # this exists, and come up as ordinary slopes in double power-law profiles. @@ -223,11 +228,16 @@ def test_jit_and_vmap_compose(): np.testing.assert_allclose(np.asarray(mapped), np.asarray(direct), rtol=1e-14) -def test_integer_arguments_are_promoted(): - """Integer ``a``/``b``/``z`` promote to float, as everywhere else here.""" - got = sp.incomplete_beta(2, 1, jnp.asarray(1)) +@pytest.mark.parametrize("b", [1, 20]) +def test_integer_arguments_are_promoted(b): + """Integer ``a``/``b``/``z`` promote to float, as everywhere else here. + + ``b = 20`` takes the continued fraction, where an integer ``z`` once carried + its dtype into the switch point and truncated it to zero: the answer was 0. + """ + got = sp.incomplete_beta(2, b, jnp.asarray(1)) assert jnp.issubdtype(got.dtype, jnp.floating) - np.testing.assert_allclose(float(got), scipy_beta(2.0, 1.0), rtol=1e-12) + np.testing.assert_allclose(float(got), scipy_beta(2.0, b), rtol=1e-12) # ============================================================================ @@ -240,7 +250,7 @@ def test_a_eq_1_closed_form_matches_the_series(b): z = jnp.asarray(ZS) np.testing.assert_allclose( np.asarray(sp.incomplete_beta(1.0, b, z)), - np.asarray(_incomplete_beta_core(1.0, b, z)), + np.asarray(_incomplete_beta_core(1.0, b, z, _SERIES)), rtol=1e-11, ) @@ -350,7 +360,8 @@ def test_a_eq_1_keeps_the_input_dtype(z): Otherwise the output dtype would depend on whether ``a`` happens to be 1. """ - got, series = sp.incomplete_beta(1.0, 0.5, z), _incomplete_beta_core(1.0, 0.5, z) + got = sp.incomplete_beta(1.0, 0.5, z) + series = _incomplete_beta_core(1.0, 0.5, z, _SERIES) assert (got.dtype, got.weak_type) == (series.dtype, series.weak_type) diff --git a/tests/unit/test_beta_regimes.py b/tests/unit/test_beta_regimes.py new file mode 100644 index 0000000..88491af --- /dev/null +++ b/tests/unit/test_beta_regimes.py @@ -0,0 +1,713 @@ +"""Unit tests for `spexial.incomplete_beta` outside the binomial series' range. + +Large ``b`` and large ``a`` take a continued fraction (GH-64) or `_large_a`; +these tests cover those regimes, the switches between them, and the +regressions fixed alongside (GH-66, GH-67, GH-68). Split from `test_beta.py` +so the two files run on separate workers under ``--dist=loadfile``: together +they were one serialized ~20-minute file. +""" + +import jax +import jax.numpy as jnp +import mpmath as mp +import numpy as np +import pytest + +import spexial as sp +from spexial._src.beta import _CF_FROM, _branch, _branch_index + +# `a > 0` always. `b` is any real: the negative and zero values are the reason +# this exists, and come up as ordinary slopes in double power-law profiles. +AS = [0.25, 0.5, 1.0, 1.31, 2.0, 4.5] +BS = [-2.5, -1.0, -0.1, 0.0, 0.3, 1.31, 4.0] +# Straddles the z = 1/2 branch switch deliberately, and both endpoints. +ZS = [1e-6, 1e-3, 0.1, 0.3, 0.5, 0.5 + 1e-7, 0.7, 0.9, 0.99, 1 - 1e-6] + + +def _mp_incomplete_beta(a, b, z): + """Unregularized ``B(a, b, z)`` by mpmath, robust for large ``b > 0``. + + ``mp.betainc`` sums a hypergeometric series that converges too slowly for + large ``b`` above the switch point -- mpmath 1.3.0, the supported floor, + raises `NoConvergence` at ``a = 0.1, b = 1e5``. There the complement + ``B(a, b) - B(b, a, 1 - z)`` converges fast, as it does for the code under + test. + """ + a, b, z = mp.mpf(a), mp.mpf(b), mp.mpf(z) + if b > 0 and z >= (a + 1) / (a + b + 2): + return mp.beta(a, b) - mp.betainc(b, a, 0, 1 - z) + return mp.betainc(a, b, 0, z) + + +# ============================================================================ +# Large b: the continued fraction (GH-64) + +LARGE_BS = [np.nextafter(10.0, 99), 20.0, 50.0, 100.0, 300.0, 1e3, 1e4] + + +@pytest.mark.parametrize("a", [*AS, 8.0, 50.0]) +@pytest.mark.parametrize("b", LARGE_BS) +def test_large_b_matches_mpmath(a, b): + """REGRESSION: the series lost every digit above ``b ~ 50`` (GH-64). + + Its coefficients ``(1-b)_k / k!`` alternate and grow like ``b^k / k!``: at + ``b = 300, z = 1/2`` it returned ``-1.1e44`` for ``1.1e-5``. Above + `_CF_FROM` the continued fraction takes over. + + The reference is mpmath, not ``beta * betainc``: SciPy's regularized form + is itself only good to ~1e-11 at ``b = 1e4``. + + ``a`` reaches 50, the top of the documented range for the continued + fraction and a regime where the series fails even at small ``b``. + + Tolerances are the measured worst with headroom: 2e-13 up to ``b = 100``, + then rounding growing like ``b * eps`` out to ``b = 1e4``; the fraction + itself has converged by then (`_CF_STEPS`). + """ + z = np.array([1e-8, *ZS[1:], 1.0]) + got = np.asarray(sp.incomplete_beta(a, b, jnp.asarray(z))) + with mp.workdps(40): + expect = np.array([float(_mp_incomplete_beta(a, b, zi)) for zi in z]) + np.testing.assert_allclose(got, expect, rtol=1e-12 if b <= 100 else 1e-11) + + +@pytest.mark.parametrize("a", [0.5, 2.0, 8.0]) +def test_continuous_across_the_large_b_switch(a): + """Series below `_CF_FROM`, continued fraction above: they must meet.""" + z = jnp.asarray([0.05, 0.5, 0.95]) + below = sp.incomplete_beta(a, np.nextafter(_CF_FROM, 0), z) + above = sp.incomplete_beta(a, np.nextafter(_CF_FROM, 99), z) + np.testing.assert_allclose(np.asarray(below), np.asarray(above), rtol=1e-13) + + +@pytest.mark.parametrize(("a", "b", "z"), [(2.0, 50.0, 0.01), (0.5, 300.0, 0.5)]) +def test_large_b_parameter_derivatives(a, b, z): + """``a``/``b`` tangents through the continued fraction, in both modes. + + Against mpmath's derivative, not a finite difference: the ``b``-derivative + here is ~1e-4 of the value, so a difference quotient's own rounding is + already a 1e-6 relative error, where autodiff is good to 1e-15. + """ + zz = jnp.asarray(z) + refs = ( + lambda t: _mp_incomplete_beta(t, b, z), + lambda t: _mp_incomplete_beta(a, t, z), + ) + for argnum, ref in enumerate(refs): + with mp.workdps(40): + expect = float(mp.diff(ref, (a, b)[argnum])) + for mode in (jax.jacfwd, jax.jacrev): + got = mode(sp.incomplete_beta, argnum)(a, b, zz) + np.testing.assert_allclose(float(got), expect, rtol=1e-12) + + +def test_vmap_over_b_across_the_switch_has_finite_gradients(): + """Under `vmap` the `switch` becomes a `select` and every branch runs. + + Each is handed a ``b`` it is safe for, so the unselected one -- the series + at ``b = 1e4``, or the reflection at ``b <= 0`` -- cannot put a non-finite + value where autodiff multiplies it by a zero cotangent. + """ + bs = jnp.asarray([-2.0, 0.0, 5.0, 10.0, 10.5, 300.0, 1e4]) + f = lambda b: sp.incomplete_beta(2.0, b, jnp.asarray(0.3)) + batched = jax.vmap(f)(bs) + # Against mpmath, not against `f` one `b` at a time: that takes its branch + # statically, a different compilation of the same arithmetic, and the two + # differ by more than either errs -- at b = 1e4, 2.1e-14 under jax 0.10 and + # 8.2e-14 under 0.12, with each within 1e-13 of the truth. Here the + # masking must leave the selected branch's value exact. + with mp.workdps(30): + expect = [float(_mp_incomplete_beta(2.0, float(b), 0.3)) for b in bs] + np.testing.assert_allclose(np.asarray(batched), expect, rtol=1e-12) + assert bool(jnp.all(jnp.isfinite(jax.vmap(jax.grad(f))(bs)))) + + +@pytest.mark.parametrize( + ("wrt", "bs", "z"), + [ + # One lane per branch: series, continued fraction, large a, negative b. + (0, [1.5, 20.0, 0.05, -6.0], 0.3), + (1, [1.5, 20.0, 0.05, -6.0], 0.3), + # At z = 1 the unselected large-a and negative-b branches, run on their + # substitute b <= 0, have an infinite z-derivative (1-z)^(b-1), which + # must not reach the selected lanes. + (2, [1.5, 20.0, 1.0, 2.0], 1.0), + ], +) +def test_reverse_mode_through_vmap_across_the_switch(wrt, bs, z): + """REGRESSION: ``grad(sum(vmap(f)))`` equals ``vmap(grad(f))``. + + With the `switch` inside the custom JVP, the rule's `jvp` of it, once + batched, left a `stop_gradient` in the linearized program that JAX cannot + transpose, so reverse mode through `vmap` raised. + """ + args = [jnp.asarray([0.5, 2.0, 9.0, 2.0]), jnp.asarray(bs), jnp.full(4, z)] + + def total(x): + return jax.vmap(sp.incomplete_beta)(*args[:wrt], x, *args[wrt + 1 :]).sum() + + batched = jax.grad(total)(args[wrt]) + single = jax.vmap(jax.grad(sp.incomplete_beta, argnums=wrt))(*args) + assert bool(jnp.all(jnp.isfinite(batched))) + np.testing.assert_allclose(np.asarray(batched), np.asarray(single), rtol=1e-14) + + +@pytest.mark.parametrize("z", [1e-8, 1e-12]) +@pytest.mark.parametrize("b", [1.5, 20.0]) +def test_mixed_partial_at_small_z(z, b): + """REGRESSION (GH-68): ``d/db d/dz B`` to full precision as ``z -> 0``. + + ``d/dz B = z^(a-1) (1-z)^(b-1)``, so ``d/db`` of it is that times + ``log(1-z)``. The z-rule's power must carry ``log1p(-z)`` when ``b`` is + traced; ``log`` of a rounded ``1 - z`` kept only ~1e-16 / z of it: 5e-9 + relative at ``z = 1e-8`` and 2e-5 at ``1e-12``. Both the series and the + continued-fraction regimes share the rule, hence both ``b``. + """ + a = 2.0 + got = jax.grad(jax.grad(lambda bb, zz: sp.incomplete_beta(a, bb, zz), 1), 0) + expect = z ** (a - 1) * np.log1p(-z) * np.exp((b - 1) * np.log1p(-z)) + np.testing.assert_allclose(float(got(b, jnp.asarray(z))), expect, rtol=1e-14) + + +def test_z_derivative_with_traced_b_at_z_eq_1(): + """With ``b`` traced, the z-rule's clamp keeps ``(1-z)^(b-1)`` exact at z = 1.""" + one = jnp.asarray(1.0) + dz = jax.jit(jax.grad(lambda zz, bb: sp.incomplete_beta(2.0, bb, zz))) + assert float(dz(one, 1.0)) == 1.0 + assert float(dz(one, 2.0)) == 0.0 + assert float(dz(one, 0.5)) == np.inf + + +# ============================================================================ +# Large a + + +@pytest.mark.parametrize("a", [12.0, 16.0, 24.0, 50.0]) +@pytest.mark.parametrize("b", [0.1, 0.5, 4.0, 10.0]) +def test_large_a_matches_mpmath(a, b): + """Above ``a = 8`` with ``b >= 0.1`` the continued fraction takes over. + + `_large_z` expands ``(1-u)^(a-1)``, whose coefficients cancel just as + ``(1-b)_k`` does for large ``b``: the series was 4e-11 at ``a = 16``, + 2e-8 at ``24``, and wrong from about 50. Measured worst here 5e-13. + """ + z = np.array([1e-6, 0.01, 0.3, 0.7, 0.9, 0.99, 1 - 1e-6]) + got = np.asarray(sp.incomplete_beta(a, b, jnp.asarray(z))) + with mp.workdps(40): + expect = np.array([float(_mp_incomplete_beta(a, b, zi)) for zi in z]) + np.testing.assert_allclose(got, expect, rtol=1e-12) + + +@pytest.mark.parametrize("b", [0.1, 1.0, 5.0]) +def test_continuous_across_the_large_a_switch(b): + """Series at or below ``a = 8``, continued fraction above: they must meet.""" + z = jnp.asarray([0.05, 0.5, 0.95]) + below = sp.incomplete_beta(8.0, b, z) + above = sp.incomplete_beta(np.nextafter(8.0, 99), b, z) + np.testing.assert_allclose(np.asarray(below), np.asarray(above), rtol=1e-13) + + +def _mp_hyp2f1_beta(a, b, z): + """``B(a, b, z)`` by DLMF 8.17.7 at 40 digits: valid for any real ``b``.""" + with mp.workdps(40): + return float(mp.mpf(z) ** a / a * mp.hyp2f1(a, 1 - b, a + 1, z)) + + +@pytest.mark.parametrize("a", [12.0, 24.0, 50.0, 100.0]) +@pytest.mark.parametrize("b", [-50.0, -2.5, -1.0, -0.3, -1e-4, 0.0, 0.05, 0.099]) +def test_large_a_small_b(a, b): + """Large ``a`` with ``b < 0.1``, including ``b <= 0``: `_large_a`. + + The series was 1e-9 off at ``a = 24`` and had no correct digits by 50; the + continued fraction's reflection needs ``B(a, b)``, which diverges at + ``b <= 0``. Measured worst here 8e-14. + """ + z = np.array([0.01, 0.3, 0.5, 0.7, 0.9, 0.95, 0.99, 1 - 1e-6, 1 - 1e-12]) + got = np.asarray(sp.incomplete_beta(a, b, jnp.asarray(z))) + expect = np.array([_mp_hyp2f1_beta(a, b, zi) for zi in z]) + ok = np.isfinite(expect) & (expect != 0) + np.testing.assert_allclose(got[ok], expect[ok], rtol=5e-13) + + +@pytest.mark.parametrize("b", [-2.5, -0.3, 0.0, 0.05]) +def test_continuous_across_the_large_a_switch_small_b(b): + """Series at or below ``a = 8``, `_large_a` above: they must meet.""" + z = jnp.asarray([0.05, 0.5, 0.95, 0.999]) + below = sp.incomplete_beta(8.0, b, z) + above = sp.incomplete_beta(np.nextafter(8.0, 99), b, z) + np.testing.assert_allclose(np.asarray(below), np.asarray(above), rtol=1e-13) + + +@pytest.mark.parametrize("a", [2.0, 24.0]) +def test_pole_at_z_eq_1_large_and_small_a(a): + """``+inf`` at ``z = 1`` for ``b <= 0`` on the series and on `_large_a`.""" + for b in (-2.5, -0.5, 0.0): + assert float(sp.incomplete_beta(a, b, jnp.asarray(1.0))) == np.inf + + +@pytest.mark.parametrize("a", [2.0, 24.0]) +@pytest.mark.parametrize("b", [1e-6, 1e-4, 5e-4]) +def test_z_eq_1_with_tiny_positive_b(a, b): + """REGRESSION: ``B(a, b, 1)`` for ``0 < b < 1e-3`` was ``nan``. + + ``b`` sits in the near-pole band, whose expansion carries ``log(1 - z)``; + at ``z = 1`` that is ``-inf``, though there is nothing to cancel there -- + ``(1 - z)^b`` is 0 -- so the direct form is used. + """ + with mp.workdps(40): + expect = float(mp.beta(a, b)) + got = float(sp.incomplete_beta(a, b, jnp.asarray(1.0))) + np.testing.assert_allclose(got, expect, rtol=1e-12) + + +@pytest.mark.parametrize("b", [-1e-4, -1 + 5e-4, 2e-4]) +def test_near_pole_expansion_close_to_z_eq_1(b): + """REGRESSION: the near-pole expansion truncates like ``s^K L^(K+1)``. + + With 4 terms, ``b = -1e-4`` at ``z = 1 - 1e-15`` (``L ~ -35``) was 1.2e-12 + off; that step is now evaluated in a form with no truncation at all. + """ + z = np.array([0.9, 1 - 1e-8, 1 - 1e-15]) + got = np.asarray(sp.incomplete_beta(2.0, b, jnp.asarray(z))) + expect = np.array([_mp_hyp2f1_beta(2.0, b, zi) for zi in z]) + np.testing.assert_allclose(got, expect, rtol=5e-14) + + +def test_vmap_over_a_through_large_a_has_finite_gradients(): + """Under `vmap` over ``a`` the `switch` runs every branch, on safe values.""" + a_s = jnp.asarray([0.5, 4.0, 8.0, 8.5, 16.0, 50.0]) + f = lambda a: sp.incomplete_beta(a, -0.5, jnp.asarray(0.97)) + batched = jax.vmap(f)(a_s) + single = jnp.stack([f(a) for a in a_s]) + np.testing.assert_allclose(np.asarray(batched), np.asarray(single), rtol=5e-14) + assert bool(jnp.all(jnp.isfinite(jax.vmap(jax.grad(f))(a_s)))) + + +def test_vmap_over_a_across_the_switch_has_finite_gradients(): + """As for ``b``: under `vmap` over ``a`` every branch runs, on safe values.""" + a_s = jnp.asarray([0.5, 4.0, 8.0, 8.5, 16.0, 50.0]) + f = lambda a: sp.incomplete_beta(a, 0.5, jnp.asarray(0.3)) + batched = jax.vmap(f)(a_s) + single = jnp.stack([f(a) for a in a_s]) + np.testing.assert_allclose(np.asarray(batched), np.asarray(single), rtol=1e-14) + assert bool(jnp.all(jnp.isfinite(jax.vmap(jax.grad(f))(a_s)))) + + +@pytest.mark.parametrize("b", [2.5, 3.0, 4.0]) +def test_higher_z_derivatives_at_z_eq_1_with_traced_b(b): + """Traced and concrete ``b`` agree at ``z = 1`` to the third z-derivative. + + The traced path writes ``(1-z)^(b-1)`` through ``log1p(-z)`` (GH-68), which + is ``-inf`` at ``z = 1``. A clamp there differentiates as ``0 * -inf`` and + made the second and third derivatives ``nan``; `pow` takes the endpoint. + """ + one = jnp.asarray(1.0) + f = lambda bb, zz: sp.incomplete_beta(2.0, bb, zz) + d1 = jax.grad(f, 1) + d2 = jax.grad(d1, 1) + d3 = jax.grad(d2, 1) + for d in (d1, d2, d3): + traced, concrete = float(jax.jit(d)(b, one)), float(d(b, one)) + assert traced == concrete, (b, traced, concrete) + assert not np.isnan(traced) + + +def _mp_integrand_derivative(a, b, z, order): + """``d^order/dz^order`` of ``z^(a-1) (1-z)^(b-1)``, by mpmath.""" + with mp.workdps(30): + return float(mp.diff(lambda t: t ** (a - 1) * (1 - t) ** (b - 1), z, order)) + + +@pytest.mark.parametrize("traced", [False, True]) +@pytest.mark.parametrize( + ("a", "b", "z"), + [ + (9.0, 1.0, 1.0), + (2.0, 2.0, 1.0), + (2.0, 3.0, 1.0), + (1.0, 3.0, 0.0), + (2.0, 3.0, 0.0), + (2.0, 1.5, 0.0), + ], +) +def test_z_derivatives_at_an_integer_exponent_endpoint(a, b, z, traced): + """REGRESSION (GH-73): z-derivatives at an integer-exponent endpoint. + + Every z-derivative at ``z = 0`` or ``1`` is finite where the integrand's + exponent there, ``a - 1`` or ``b - 1``, is an integer ``n >= 0``. JAX + differentiates a float-exponent ``x ** y`` as ``y x^(y-1)``, which is + ``0 * inf`` at ``x = 0`` once differentiation has brought ``y`` to 0, so + the derivatives from order ``n + 2`` on were ``nan`` (jax-ml/jax#14397). + """ + d = lambda bb, zz: sp.incomplete_beta(a, bb, zz) + for order in range(1, 6): + d = jax.grad(d, 1) + got = float(jax.jit(d)(b, z) if traced else d(b, z)) # jit traces b + want = _mp_integrand_derivative(a, b, z, order - 1) + np.testing.assert_allclose( + got, want, rtol=1e-12, atol=1e-12, err_msg=f"{order=}" + ) + + +def test_a_derivative_of_z_derivatives_at_a_eq_1(): + """``d/da d^2/dz^2 B`` at ``a = 1``, ``z > 0``. + + The GH-73 guard is only at ``z = 0``. Guarding ``a = 1`` everywhere would + zero this, as the ``y == 0`` special case once did in JAX's own rule + (jax-ml/jax#12033). ``z^(a-1)`` is the factor to test: it is `_pow` at every + ``z``, while a traced ``b`` goes through ``log1p`` inside the interval. + """ + b, z = 2.0, 0.3 + d2z = lambda aa: jax.grad(jax.grad(lambda zz: sp.incomplete_beta(aa, b, zz)))(z) + got = float(jax.grad(d2z)(jnp.asarray(1.0))) + with mp.workdps(30): + want = float( + mp.diff( + lambda aa: mp.diff(lambda t: t ** (aa - 1) * (1 - t) ** (b - 1), z), + 1.0, + ) + ) + np.testing.assert_allclose(got, want, rtol=1e-12) + + +@pytest.mark.parametrize("b", [1e3, 1e4, 1e5]) +def test_large_b_small_a(b): + """``a = 0.1``: the complete beta's second fraction converges slowest here. + + At 32 steps it was 1e-11 off; `_CF_STEPS` is now 64. + """ + a = 0.1 + z = np.array( + [1e-6, 0.5 * (a + 1) / (a + b + 2), 2 * (a + 1) / (a + b + 2), 0.5, 1.0] + ) + got = np.asarray(sp.incomplete_beta(a, b, jnp.asarray(z))) + with mp.workdps(40): + expect = np.array([float(_mp_incomplete_beta(a, b, zi)) for zi in z]) + np.testing.assert_allclose(got, expect, rtol=1e-12) + + +@pytest.mark.parametrize(("a", "b"), [(301.0, 1000.0), (300.0, 1000.0), (50.0, 2000.0)]) +def test_large_b_no_premature_underflow(a, b): + """A tiny front factor must not flush to zero while the value is normal. + + ``B(301, 1000) ~ 3.9e-307``: the front factor alone underflows, and was + multiplied by the fraction after the fact, so this returned 0. + """ + with mp.workdps(40): + expect = float(mp.beta(a, b)) + got = float(sp.incomplete_beta(a, b, jnp.asarray(1.0))) + np.testing.assert_allclose(got, expect, rtol=1e-12) + + +@pytest.mark.parametrize("z", [0.0, 1.0]) +def test_large_b_parameter_gradients_at_the_endpoints(z): + """``a``/``b`` gradients at ``z = 0`` and ``z = 1``, with ``b > 10``. + + The endpoint term is a genuine zero; evaluated, ``log(0)`` puts + ``0 * -inf = nan`` into its parameter derivatives. + """ + a, b = 2.0, 50.0 + zz = jnp.asarray(z) + refs = (lambda t: mp.beta(t, b), lambda t: mp.beta(a, t)) + for argnum, ref in enumerate(refs): + got = float(jax.grad(sp.incomplete_beta, argnum)(a, b, zz)) + if z == 0.0: + expect = 0.0 + else: + with mp.workdps(40): + expect = float(mp.diff(ref, (a, b)[argnum])) + np.testing.assert_allclose(got, expect, rtol=1e-11, atol=1e-300) + + +def test_large_b_float32(): + """The continued fraction in float32: about float32 precision, still float32.""" + z = jnp.asarray([1e-3, 0.01, 0.3, 0.9], jnp.float32) + for b in (50.0, 1e4): + got = sp.incomplete_beta(2.0, b, z) + assert got.dtype == jnp.float32 + with mp.workdps(40): + expect = np.array([float(_mp_incomplete_beta(2, b, float(zi))) for zi in z]) + np.testing.assert_allclose(np.asarray(got, np.float64), expect, rtol=5e-6) + + +@pytest.mark.parametrize("b", [1.5, 50.0]) +@pytest.mark.parametrize("wrap", [np.float64, jnp.float64], ids=["numpy", "jax"]) +def test_float32_z_with_strong_float64_b(b, wrap): + """REGRESSION (GH-66): float32 ``z`` with a strong float64 ``b``. + + The `scan` carry started in float32 and the first step promoted it to + float64, which `scan` rejects with a `TypeError`. ``z`` now promotes to the + common type, as in any elementwise op -- on both the series (b = 1.5) and + the continued fraction (b = 50). + """ + z = jnp.asarray([0.3, 0.9], jnp.float32) + eager = sp.incomplete_beta(2.0, wrap(b), z) + jitted = jax.jit(lambda bb: sp.incomplete_beta(2.0, bb, z))(wrap(b)) + expect = sp.incomplete_beta(2.0, b, jnp.asarray(z, jnp.float64)) + for got in (eager, jitted): + assert got.dtype == jnp.float64 + np.testing.assert_allclose(np.asarray(got), np.asarray(expect), rtol=1e-14) + # A weak (Python) b does not promote. + assert sp.incomplete_beta(2.0, b, z).dtype == jnp.float32 + + +# Two values -- one negative, and zero -- because each compiles the a- and +# b-Jacobians afresh (~35 s apiece); `test_pole_at_z_eq_1_large_and_small_a` +# covers more `b` for the value alone. +@pytest.mark.parametrize("b", [-1.0, 0.0]) +def test_pole_at_z_eq_1_for_non_positive_b(b): + """REGRESSION (GH-67): ``B(a, b, 1) = +inf`` for ``b <= 0``, not ``nan``. + + And the series must not leak its ``nan`` there into the gradients of the + other points through the `where` that picks the pole. + """ + z = jnp.asarray([0.3, 0.9, 1.0]) + got = np.asarray(sp.incomplete_beta(2.0, b, z)) + assert got[-1] == np.inf + assert np.all(np.isfinite(got[:-1])) + for argnum in (0, 1): + jac = np.asarray( + jax.jacrev(lambda *ab: sp.incomplete_beta(*ab, z), argnum)(2.0, b) + ) + assert np.all(np.isfinite(jac[:-1])), jac + + +@pytest.mark.parametrize("a", [0.5, 8.0, np.nextafter(8.0, 99), 50.0]) +@pytest.mark.parametrize( + "b", + [ + -6.0, + -5.0, + -1.0, + 0.0, + np.nextafter(0.1, 0), + 0.1, + 5.0, + 10.0, + np.nextafter(10.0, 99), + ], +) +def test_static_and_traced_branch_choice_agree(a, b): + """`_branch` (concrete, plain Python) mirrors `_branch_index` (traced).""" + assert _branch(a, b) == int(_branch_index(a, b)) + + +# ============================================================================ +# Second audit + + +@pytest.mark.parametrize( + ("a", "b", "z", "dtype"), + [ + (np.float64(2), jnp.float32(1.5), [0.3, 0.9], jnp.float64), + (2, 1.5, np.float32([0.3, 0.9]), jnp.float32), + (jnp.float32(2), np.float64(-1), [0.3, 0.9], jnp.float64), + (jnp.float32(12), np.float64(-1), [0.3, 0.9], jnp.float64), + (12, -1.0, np.float32([0.3, 0.9]), jnp.float32), + (2, 50, np.float32([0.01, 0.3]), jnp.float32), + ], +) +def test_mixed_precision_parameters(a, b, z, dtype): + """``a``, ``b`` and ``z`` share one dtype, on every path (GH-66, completed). + + A `scan` carry seeded from one and updated with another changed type: an + integer ``a`` with float32 ``z``, float32 ``a`` with float64 ``b`` -- and, + new in this PR, the near-pole carry seeded from ``b`` but updated from + ``a``. Values are checked against the all-float64 call. + """ + got = sp.incomplete_beta(a, b, jnp.asarray(z)) + assert got.dtype == dtype + expect = sp.incomplete_beta(float(a), float(b), jnp.asarray(z, jnp.float64)) + rtol = 1e-13 if dtype == jnp.float64 else 1e-5 + np.testing.assert_allclose( + np.asarray(got, np.float64), np.asarray(expect), rtol=rtol + ) + + +def test_gradient_with_an_integer_parameter(): + """An integer ``a`` (or ``b``) no longer breaks the gradient in the other. + + Its tangent in the custom JVP was a zero of its own integer dtype, which + `jax.jvp` rejects; parameters are now promoted to floating first. + """ + z = jnp.asarray(0.3) + np.testing.assert_allclose( + float(jax.grad(lambda b: sp.incomplete_beta(2, b, z))(1.5)), + float(jax.grad(lambda b: sp.incomplete_beta(2.0, b, z))(1.5)), + rtol=1e-14, + ) + np.testing.assert_allclose( + float(jax.grad(lambda a: sp.incomplete_beta(a, 2, z))(1.5)), + float(jax.grad(lambda a: sp.incomplete_beta(a, 2.0, z))(1.5)), + rtol=1e-14, + ) + + +@pytest.mark.parametrize( + ("a", "b", "z"), + [ + (50.0, -0.999, 0.9635), + (8.5, -0.999, 0.8097), + (4.5, -1e-3, 0.6), + (4.5, -0.03, 0.75), + ], +) +def test_just_outside_the_old_pole_band(a, b, z): + """``b + m`` a little way from zero: the direct quotient cancelled there. + + With a 1e-3 band, ``1e-3 <= |s| < ~0.1`` was left to ``(w0^s - w^s) / s``: + 5.8e-12 at ``a = 50, b = -0.999``. The one step with ``|s| < 1/2`` is now + evaluated as ``w^s delta expm1(s delta) / (s delta)``. + """ + got = float(sp.incomplete_beta(a, b, jnp.asarray(z))) + np.testing.assert_allclose(got, _mp_hyp2f1_beta(a, b, z), rtol=5e-14) + + +@pytest.mark.parametrize("n", [1, 2, 3]) +def test_b_derivatives_just_outside_the_old_pole_band(n): + """1st-3rd ``b``-derivatives there: they were 3e-10, 5e-7, 1.5e-3 off.""" + a, b, z = 4.5, -1 + 1.001e-3, 0.7 + d = lambda bb: sp.incomplete_beta(a, bb, jnp.asarray(z)) + for _ in range(n): + d = jax.grad(d) + with mp.workdps(40): + expect = float( + mp.diff(lambda t: mp.mpf(z) ** a / a * mp.hyp2f1(a, 1 - t, a + 1, z), b, n) + ) + np.testing.assert_allclose(float(d(b)), expect, rtol=1e-13) + + +def test_near_pole_float32(): + """The near-pole step in float32: about float32 precision (it was 3.5e-4).""" + z = jnp.asarray([0.6, 0.9], jnp.float32) + for b in (-1e-3, -0.999): + got = np.asarray(sp.incomplete_beta(4.5, b, z), np.float64) + expect = np.array([_mp_hyp2f1_beta(4.5, b, float(zi)) for zi in z]) + np.testing.assert_allclose(got, expect, rtol=1e-5) + + +def test_no_intermediate_overflow_for_very_negative_b(): + """A representable result must not come back ``nan`` or raise. + + ``w0^b`` overflowed inside the expansion at ``a = 1e4, b = -84`` (true value + 8.3e307); a concrete ``b = -1100`` made Python float arithmetic raise + `OverflowError` even at ``z = 0.3``, below the branch that needed it. + """ + a = 1e4 + split = a / (a + 2) + with mp.workdps(40): + expect = float(mp.betainc(a, -84, 0, split)) + np.testing.assert_allclose( + float(sp.incomplete_beta(a, -84.0, jnp.asarray(split))), expect, rtol=1e-11 + ) + np.testing.assert_allclose( + float(sp.incomplete_beta(2.0, -1100.0, jnp.asarray(0.3))), + _mp_hyp2f1_beta(2.0, -1100.0, 0.3), + rtol=1e-12, + ) + + +def test_overflow_past_the_float_range_is_inf(): + """A true value beyond the float range is ``+inf``, not ``nan``.""" + assert float(sp.incomplete_beta(12.0, -400.0, jnp.asarray(0.86))) == np.inf + assert float(sp.incomplete_beta(2.0, -400.0, jnp.asarray(0.9))) == np.inf + + +def test_mixed_partial_at_z_one_half_is_symmetric(): + """``d/dz d/db`` at exactly ``z = 1/2`` was halved: `minimum` split the tie.""" + half = jnp.asarray(0.5) + bz = float(jax.grad(jax.grad(sp.incomplete_beta, 1), 2)(2.0, 1.5, half)) + zb = float(jax.grad(jax.grad(sp.incomplete_beta, 2), 1)(2.0, 1.5, half)) + np.testing.assert_allclose(bz, zb, rtol=1e-14) + + +@pytest.mark.parametrize(("dtype", "rtol"), [(jnp.bfloat16, 2e-2), (jnp.float16, 2e-3)]) +@pytest.mark.parametrize(("a", "b"), [(2.0, 50.0), (24.0, -0.5)]) +def test_half_precision(dtype, rtol, a, b): + """bfloat16/float16 on the continued fraction and on `_large_a`. + + Both evaluate in float32 and round once; Lentz's recurrence in bfloat16 + was 6% off at ``b = 20``. + """ + # Points whose values are representable in both dtypes; the reference is + # the float64 value rounded to `dtype` (below its range that is 0). + z = jnp.asarray([0.3, 0.9] if b > 0 else [0.9, 0.97], dtype) + got = sp.incomplete_beta(a, b, z) + assert got.dtype == dtype + full = sp.incomplete_beta(a, b, jnp.asarray(z, jnp.float64)) + expect = np.asarray(full.astype(dtype), np.float64) + np.testing.assert_allclose(np.asarray(got, np.float64), expect, rtol=rtol) + + +@pytest.mark.parametrize(("a", "b"), [(2.0, 1e17), (0.5, 1e20)]) +def test_nan_past_one_over_eps(a, b): + """Past ``b ~ 1/eps`` the switch point rounds to 0: ``nan``, by design. + + Without the explicit ``nan`` the arithmetic does not reliably say so: at + ``a = 2, b = 1e17`` it returned a finite 8.0e-35 (truth ~1e-34), at + ``a = 0.5, b = 1e20`` ``inf`` (truth ~1.8e-10). ``a = 1`` is exempt: its + closed form has no switch point to round away, and stays exact. + """ + assert np.isnan(float(sp.incomplete_beta(a, b, jnp.asarray(0.5)))) + + +def test_large_a_endpoint_gradients(): + """`_large_a`'s z = 0 guard and its z = 1 pole guard keep gradients finite.""" + for k in (0, 1): + assert ( + float(jax.grad(sp.incomplete_beta, k)(24.0, -0.5, jnp.asarray(0.0))) == 0.0 + ) + jac = jax.jacrev( + lambda b: sp.incomplete_beta(24.0, b, jnp.asarray([0.3, 0.9, 1.0])) + ) + assert bool(jnp.all(jnp.isfinite(jac(-0.5)[:2]))) + + +def test_continued_fraction_converged_near_x0(): + """64 steps: the slowest fraction, just above ``x0`` at small ``a``. + + 6e-15 at 64 steps; 48 left 5e-14. + """ + a, b = 0.1, 1e3 + x0 = (a + 1) / (a + b + 2) + z = np.array([x0 * (1 + 1e-9), x0 * 1.05]) + got = np.asarray(sp.incomplete_beta(a, b, jnp.asarray(z))) + expect = np.array([float(_mp_incomplete_beta(a, b, zi)) for zi in z]) + np.testing.assert_allclose(got, expect, rtol=2e-14) + + +def test_large_a_takes_large_a_below_b_one_tenth(): + """Just below ``b = 0.1``, large ``a`` goes to `_large_a`, not the reflection. + + At ``a = 50, b = 0.07`` the reflection is 6.4e-14 off (it loses digits as + ``b -> 0``); `_large_a` is 4e-15. + """ + z = np.array([0.5, 0.9, 50 / 52 * 0.999, 0.99]) + got = np.asarray(sp.incomplete_beta(50.0, 0.07, jnp.asarray(z))) + expect = np.array([_mp_hyp2f1_beta(50.0, 0.07, zi) for zi in z]) + np.testing.assert_allclose(got, expect, rtol=2e-14) + + +@pytest.mark.parametrize("a", [0.01, 0.5, 2.0, 8.0]) +@pytest.mark.parametrize("b", [-5.5, -10.0, -50.0, -200.0, -1100.0]) +def test_very_negative_b(a, b): + """``b < -5`` (``a <= 8``): the continued fraction directly, no reflection. + + The series' ``(1-b)_k / k!`` grows like ``(|b| z)^k / k!`` before it + decays, so 64 terms were 6e-12 off at ``b = -10``, 8% at -50, and had no + correct digits by -200. Measured worst here 4.4e-13 (a = 0.01, b = -200). + """ + z = np.array([1e-6, 0.01, 0.1, 0.3, 0.5, 0.7, 0.9, 0.999]) + got = np.asarray(sp.incomplete_beta(a, b, jnp.asarray(z))) + expect = np.array([_mp_hyp2f1_beta(a, b, zi) for zi in z]) + ok = np.isfinite(expect) & (np.abs(expect) < 1e300) & (expect != 0) + np.testing.assert_allclose(got[ok], expect[ok], rtol=2e-12) + + +@pytest.mark.parametrize("a", [0.5, 2.0, 8.0]) +def test_continuous_across_the_negative_b_switch(a): + """Series at ``b = -5``, continued fraction just below: they must meet.""" + z = jnp.asarray([0.05, 0.5, 0.95]) + at = sp.incomplete_beta(a, -5.0, z) + below = sp.incomplete_beta(a, np.nextafter(-5.0, -99), z) + np.testing.assert_allclose(np.asarray(at), np.asarray(below), rtol=1e-13) diff --git a/tests/unit/test_registry.py b/tests/unit/test_registry.py index ff25020..e0fa556 100644 --- a/tests/unit/test_registry.py +++ b/tests/unit/test_registry.py @@ -17,7 +17,7 @@ import pytest import spexial as sp -from spexial._src.beta import _incomplete_beta_core +from spexial._src.beta import _SERIES, _incomplete_beta_core from spexial._src.polylog import _li_core from spexial._src.spherical_bessel import _band from spexial.registry import JAX_FLOOR, REGISTRY, Status, Support @@ -25,8 +25,9 @@ ROOT = Path(__file__).resolve().parents[2] # `polylog` validates `n`, and `incomplete_beta` dispatches a static ``a == 1`` to -# a closed form, in a plain wrapper that delegates to an inner core, so the -# `jax.custom_jvp` object is not the exported name. Everything else decorates +# a closed form, or otherwise picks a static branch, in a plain wrapper that +# delegates to an inner core, so the `jax.custom_jvp` object is not the exported +# name. Everything else decorates # the export directly. These probes let the checks below stay strict rather than # being relaxed to accommodate the difference. _JVP_OBJECT = { @@ -62,7 +63,7 @@ # `b` are bound so the shared probe below can call it with one array. "incomplete_beta": ( lambda z: sp.incomplete_beta(2.0, 1.5, z), - lambda z: _incomplete_beta_core.fun(2.0, 1.5, z), + lambda z: _incomplete_beta_core.fun(2.0, 1.5, z, _SERIES), ), "polylog": ( jax.vmap(lambda t: _li_core(3, t)),