Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 17 additions & 4 deletions benchmarks/test_beta.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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."""
Expand All @@ -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))


Expand All @@ -91,11 +93,22 @@ 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
) -> None:
"""``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))
2 changes: 1 addition & 1 deletion docs/explanation/why-not-upstream.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
22 changes: 17 additions & 5 deletions docs/reference/accuracy-and-domains.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/reference/coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)`.

Expand Down
Loading
Loading