chebax 0.1.0.dev0__tar.gz → 0.3.0__tar.gz

chebax-0.3.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: chebax
+Version: 0.3.0
+Summary: Differentiable Chebyshev approximants for special functions, aimed at JAX and GPUs
+Author-email: Andres Hernandez <andres.hernandez.deml@gmail.com>
+License-Expression: BSD-3-Clause
+Project-URL: Repository, https://github.com/andreshernandez-spec/chebax
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jax>=0.5.3
+Requires-Dist: numpy>=1.26
+Provides-Extra: gen
+Requires-Dist: mpmath<1.5,>=1.4.1; extra == "gen"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: scipy; extra == "test"
+Provides-Extra: examples
+Requires-Dist: matplotlib; extra == "examples"
+Requires-Dist: numpyro; extra == "examples"
+Provides-Extra: numpyro
+Requires-Dist: numpyro>=0.15; extra == "numpyro"
+Provides-Extra: pytensor
+Requires-Dist: pytensor>=3.2; extra == "pytensor"
+Dynamic: license-file
+
+# chebax
+
+Differentiable special functions for JAX and GPUs, built from Chebyshev
+approximants. A build-time generator (mpmath precision) produces fixed-degree
+branchless polynomial kernels with exact derivative series — including gradients
+with respect to function *parameters* (Bessel order, Beta shape, von Mises
+concentration), which mainstream ML libraries lack. No mpmath at use time; the
+runtime imports only jax and numpy.
+
+```sh
+pip install chebax
+```
+
+```python
+import jax
+jax.config.update("jax_enable_x64", True)   # before building instances: tables
+                                            # materialize in the active precision
+import jax.numpy as jnp
+import chebax
+
+jv = chebax.besselj(2.5)                    # any real order in [0, 10]; cached
+x = jnp.linspace(0.1, 30.0, 200)
+jv(x), jax.vmap(jax.grad(jv))(x)            # values and dJ/dx, jit/vmap-safe
+
+chebax.besselk_fn(1.7, x)                   # order as a traced scalar:
+jax.grad(chebax.besselk_fn)(1.7, 5.0)       #   jax.grad w.r.t. the ORDER
+chebax.betainc_fn(2.0, 3.0, 0.4)            # dI/da, dI/db via jax.grad (jax#38610)
+chebax.betaincinv(2.0, 3.0, 0.05)           # differentiable Beta quantile (jax#2399)
+```
+
+## What's in
+
+| family | factory | traced params | param derivative | notes |
+|---|---|---|---|---|
+| `besselj` | `besselj(v)`, `besselj(v, domain=(lo, hi))` | — | `besselj_dnu(v)` | x ≥ 0, validated to 1e4; `domain=` keeps only the regions covering the window and drops the rest of the evaluation, measured 2.5x f64 / 2.6x f32 (`experiments/04`), nan outside it |
+| `bessely` | `bessely(v)` | — (structural) | `bessely_dnu(v)` | x ≥ 1e-6 |
+| `besseli` | `besseli(v, scaled=)` | `besseli_fn`, `besseli_ratio` | `besseli_dnu(v, scaled=)` | `scaled` = scipy's ive; the ratio I_{v+1}/I_v is the circular-statistics workhorse |
+| `besselk` | `besselk(v)` | `besselk_fn`, `log_besselk_fn` | `besselk_dnu(v)` | x ≥ 1e-6; the log form has no underflow ceiling |
+| Matérn | — | `matern(nu, r, lengthscale)` | via `grad` | unit-variance correlation, LEARNABLE smoothness ν ∈ (0, 10] |
+| `betainc` | `betainc(a, b)` | `betainc_fn`, `log_betainc_fn` | via `grad` of `_fn` | (a, b) ∈ [0.1, 100]² (panels, split at 10); the log form resolves the lower tail with no underflow floor |
+| `gammainc` | `gammainc(a)`, `gammaincc(a)` | `gammainc_fn`, `gammaincc_fn`, `log_gammainc_fn`, `log_gammaincc_fn` | via `grad` of `_fn` | a ≥ 0.1 (above 10 via Temme-zone tables, whose v = 10/a axis reaches a = ∞), x ≥ 0; branchless (no while_loop), measured 10–27x vs jax's on GPU f64 at a ≤ 10 (`experiments/05`) |
+| `hyp1f1` | `hyp1f1(a, b)` | `hyp1f1_fn`, `log_hyp1f1_fn` | via `grad` of `_fn` | Kummer M, (a, b) ∈ [0.1, 10]², x ≥ 0; jax's is documented-unstable (jax#21503); the log form has no overflow ceiling |
+| spherical | `spherical_jn/yn(n)` | — | — | n ∈ [0, 9], via half-integer tables |
+| quantiles | — | `betaincinv`, `gammaincinv`, `gammainccinv`, `chi2inv`, `stdtr`, `stdtrit` | via `grad` (IFT) | jax#2399/#5350/#20358; chi-squared at real dof to 2000; Student-t ν ∈ [0.2, 200] via dedicated slice tables |
+| von Mises | — | `vonmises_cdf/icdf` | via `grad` | κ ∈ [0, 50] |
+| erf family | — | `dawsn`, `erfcx` | — (no params) | recent jax ships both; kept as a worked parameter-free recipe (plain functions, so not `bake` inputs: bake takes Recipe instances) |
+| Lambert W | — | `lambertw(x, k)` | — | both real branches, jax#13680 |
+
+Plus the generic core (`fit`, `ChebSeries`, `PiecewiseCheb`) and bake emitters
+(`chebax.bake.jax_module`, `chebax.bake.xsf_header`: self-contained pure-jax
+modules and C++17 headers from an instance; `dtype="float"` emits an f32
+CUDA-shaped kernel body, and `truncate_tol=1e-7` drops the converged f64
+tail — measured 1.4–2.2x faster f32 evaluation, `experiments/12`).
+
+For pymc users: `import chebax.pytensor` (installs with
+`pip install chebax[pytensor]`) registers JAX-backend lowerings for the
+pytensor ops that otherwise need tfp-nightly under
+`pm.sample(nuts_sampler="numpyro"|"blackjax")` — betaincinv, gammaincinv,
+gammainccinv, erfcx, erfcinv, ive, kve — and adds betainc gradients in its
+shape parameters, so censored or truncated StudentT/Beta likelihoods with a
+latent scalar shape sample instead of raising. Shape parameters must be
+scalar (batched ones fall back to tfp or fail loudly); out-of-domain values
+return nan, never silently wrong numbers. `gammainccinv` takes its
+upper-tail probability directly (it used to be solved at `1 - p`, which
+collapsed everything below ~1e-17 onto one point), so both tails resolve to
+the same depth.
+
+For numpyro users: `from chebax.numpyro import TruncatedGamma, TruncatedBeta,
+TruncatedStudentT` (installs with `pip install chebax[numpyro]`) gives the
+truncated distributions numpyro's location-scale machinery cannot cover
+(numpyro#969, numpyro#1365): full Distribution classes with reparameterized
+inverse-CDF sampling (`has_rsample`), truncation-normalized `log_prob`, and
+gradients through every parameter including the shapes, so NUTS and SVI work
+with a latent concentration or df. The truncation is normalized in log space,
+so an interval whose two ends land in the same tail still works: `Gamma(3)`
+truncated to [50, 51] has mass ~3e-20 and returns an ordinary density.
+Shape parameters are uniform per call; domain boxes are in the module
+docstring and checked at construction.
+
+`notebooks/` holds themed, executed walkthroughs: why Chebyshev nodes work,
+the Bessel family with a learnable Matérn kernel, differentiable quantiles,
+truncated and circular distributions in numpyro, Gaussian tails / Lambert W /
+binomial reliability, copulas, and baking. The numpyro and plotting
+dependencies install with `pip install chebax[examples]`. `examples/` holds
+plain scripts: a few of the notebook workflows in copy-paste form, plus
+integration examples with no notebook counterpart (a GIG distribution for
+efax, learned Matérn smoothness, truncated sampling, `chebax.numpyro` with
+latent shape parameters under NUTS).
+
+Parameters come first, evaluation point last (opposite of scipy). Orders/shapes
+are uniform per call; per-element parameter arrays are out of scope by design.
+The middle ground is `chebax.pergroup(fn, group_idx)`: a static integer array
+assigns each element to a group, each group gets its own (traceable) parameter
+set — one group per chain, mixture component, or plate level.
+Accuracy is validated against mpmath at 40 dps — measured worst cases and the
+per-family error metrics are in each test file's docstring; tables regenerate
+bit-for-bit from checked-in generators.
+
+## Docs
+
+`docs/adding-a-recipe.md` is the workflow for new functions;
+`docs/increments.md` the design log of every recipe (what was measured, which
+traps were found); `PROJECT.md` the plan and evidence; `CLAUDE.md` how to work
+in the repo. Grown out of a private research project on GPU Bessel functions;
+its two load-bearing measurements are reproduced here in `experiments/`.
+BSD-3-Clause.

chebax-0.3.0/README.md

@@ -0,0 +1,106 @@
+# chebax
+
+Differentiable special functions for JAX and GPUs, built from Chebyshev
+approximants. A build-time generator (mpmath precision) produces fixed-degree
+branchless polynomial kernels with exact derivative series — including gradients
+with respect to function *parameters* (Bessel order, Beta shape, von Mises
+concentration), which mainstream ML libraries lack. No mpmath at use time; the
+runtime imports only jax and numpy.
+
+```sh
+pip install chebax
+```
+
+```python
+import jax
+jax.config.update("jax_enable_x64", True)   # before building instances: tables
+                                            # materialize in the active precision
+import jax.numpy as jnp
+import chebax
+
+jv = chebax.besselj(2.5)                    # any real order in [0, 10]; cached
+x = jnp.linspace(0.1, 30.0, 200)
+jv(x), jax.vmap(jax.grad(jv))(x)            # values and dJ/dx, jit/vmap-safe
+
+chebax.besselk_fn(1.7, x)                   # order as a traced scalar:
+jax.grad(chebax.besselk_fn)(1.7, 5.0)       #   jax.grad w.r.t. the ORDER
+chebax.betainc_fn(2.0, 3.0, 0.4)            # dI/da, dI/db via jax.grad (jax#38610)
+chebax.betaincinv(2.0, 3.0, 0.05)           # differentiable Beta quantile (jax#2399)
+```
+
+## What's in
+
+| family | factory | traced params | param derivative | notes |
+|---|---|---|---|---|
+| `besselj` | `besselj(v)`, `besselj(v, domain=(lo, hi))` | — | `besselj_dnu(v)` | x ≥ 0, validated to 1e4; `domain=` keeps only the regions covering the window and drops the rest of the evaluation, measured 2.5x f64 / 2.6x f32 (`experiments/04`), nan outside it |
+| `bessely` | `bessely(v)` | — (structural) | `bessely_dnu(v)` | x ≥ 1e-6 |
+| `besseli` | `besseli(v, scaled=)` | `besseli_fn`, `besseli_ratio` | `besseli_dnu(v, scaled=)` | `scaled` = scipy's ive; the ratio I_{v+1}/I_v is the circular-statistics workhorse |
+| `besselk` | `besselk(v)` | `besselk_fn`, `log_besselk_fn` | `besselk_dnu(v)` | x ≥ 1e-6; the log form has no underflow ceiling |
+| Matérn | — | `matern(nu, r, lengthscale)` | via `grad` | unit-variance correlation, LEARNABLE smoothness ν ∈ (0, 10] |
+| `betainc` | `betainc(a, b)` | `betainc_fn`, `log_betainc_fn` | via `grad` of `_fn` | (a, b) ∈ [0.1, 100]² (panels, split at 10); the log form resolves the lower tail with no underflow floor |
+| `gammainc` | `gammainc(a)`, `gammaincc(a)` | `gammainc_fn`, `gammaincc_fn`, `log_gammainc_fn`, `log_gammaincc_fn` | via `grad` of `_fn` | a ≥ 0.1 (above 10 via Temme-zone tables, whose v = 10/a axis reaches a = ∞), x ≥ 0; branchless (no while_loop), measured 10–27x vs jax's on GPU f64 at a ≤ 10 (`experiments/05`) |
+| `hyp1f1` | `hyp1f1(a, b)` | `hyp1f1_fn`, `log_hyp1f1_fn` | via `grad` of `_fn` | Kummer M, (a, b) ∈ [0.1, 10]², x ≥ 0; jax's is documented-unstable (jax#21503); the log form has no overflow ceiling |
+| spherical | `spherical_jn/yn(n)` | — | — | n ∈ [0, 9], via half-integer tables |
+| quantiles | — | `betaincinv`, `gammaincinv`, `gammainccinv`, `chi2inv`, `stdtr`, `stdtrit` | via `grad` (IFT) | jax#2399/#5350/#20358; chi-squared at real dof to 2000; Student-t ν ∈ [0.2, 200] via dedicated slice tables |
+| von Mises | — | `vonmises_cdf/icdf` | via `grad` | κ ∈ [0, 50] |
+| erf family | — | `dawsn`, `erfcx` | — (no params) | recent jax ships both; kept as a worked parameter-free recipe (plain functions, so not `bake` inputs: bake takes Recipe instances) |
+| Lambert W | — | `lambertw(x, k)` | — | both real branches, jax#13680 |
+
+Plus the generic core (`fit`, `ChebSeries`, `PiecewiseCheb`) and bake emitters
+(`chebax.bake.jax_module`, `chebax.bake.xsf_header`: self-contained pure-jax
+modules and C++17 headers from an instance; `dtype="float"` emits an f32
+CUDA-shaped kernel body, and `truncate_tol=1e-7` drops the converged f64
+tail — measured 1.4–2.2x faster f32 evaluation, `experiments/12`).
+
+For pymc users: `import chebax.pytensor` (installs with
+`pip install chebax[pytensor]`) registers JAX-backend lowerings for the
+pytensor ops that otherwise need tfp-nightly under
+`pm.sample(nuts_sampler="numpyro"|"blackjax")` — betaincinv, gammaincinv,
+gammainccinv, erfcx, erfcinv, ive, kve — and adds betainc gradients in its
+shape parameters, so censored or truncated StudentT/Beta likelihoods with a
+latent scalar shape sample instead of raising. Shape parameters must be
+scalar (batched ones fall back to tfp or fail loudly); out-of-domain values
+return nan, never silently wrong numbers. `gammainccinv` takes its
+upper-tail probability directly (it used to be solved at `1 - p`, which
+collapsed everything below ~1e-17 onto one point), so both tails resolve to
+the same depth.
+
+For numpyro users: `from chebax.numpyro import TruncatedGamma, TruncatedBeta,
+TruncatedStudentT` (installs with `pip install chebax[numpyro]`) gives the
+truncated distributions numpyro's location-scale machinery cannot cover
+(numpyro#969, numpyro#1365): full Distribution classes with reparameterized
+inverse-CDF sampling (`has_rsample`), truncation-normalized `log_prob`, and
+gradients through every parameter including the shapes, so NUTS and SVI work
+with a latent concentration or df. The truncation is normalized in log space,
+so an interval whose two ends land in the same tail still works: `Gamma(3)`
+truncated to [50, 51] has mass ~3e-20 and returns an ordinary density.
+Shape parameters are uniform per call; domain boxes are in the module
+docstring and checked at construction.
+
+`notebooks/` holds themed, executed walkthroughs: why Chebyshev nodes work,
+the Bessel family with a learnable Matérn kernel, differentiable quantiles,
+truncated and circular distributions in numpyro, Gaussian tails / Lambert W /
+binomial reliability, copulas, and baking. The numpyro and plotting
+dependencies install with `pip install chebax[examples]`. `examples/` holds
+plain scripts: a few of the notebook workflows in copy-paste form, plus
+integration examples with no notebook counterpart (a GIG distribution for
+efax, learned Matérn smoothness, truncated sampling, `chebax.numpyro` with
+latent shape parameters under NUTS).
+
+Parameters come first, evaluation point last (opposite of scipy). Orders/shapes
+are uniform per call; per-element parameter arrays are out of scope by design.
+The middle ground is `chebax.pergroup(fn, group_idx)`: a static integer array
+assigns each element to a group, each group gets its own (traceable) parameter
+set — one group per chain, mixture component, or plate level.
+Accuracy is validated against mpmath at 40 dps — measured worst cases and the
+per-family error metrics are in each test file's docstring; tables regenerate
+bit-for-bit from checked-in generators.
+
+## Docs
+
+`docs/adding-a-recipe.md` is the workflow for new functions;
+`docs/increments.md` the design log of every recipe (what was measured, which
+traps were found); `PROJECT.md` the plan and evidence; `CLAUDE.md` how to work
+in the repo. Grown out of a private research project on GPU Bessel functions;
+its two load-bearing measurements are reproduced here in `experiments/`.
+BSD-3-Clause.

chebax-0.3.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chebax"
+version = "0.3.0"
+description = "Differentiable Chebyshev approximants for special functions, aimed at JAX and GPUs"
+readme = "README.md"
+license = "BSD-3-Clause"
+authors = [{ name = "Andres Hernandez", email = "andres.hernandez.deml@gmail.com" }]
+requires-python = ">=3.11"
+# jax floor = the oldest version the full suite passes on (CI pins a job to it)
+dependencies = ["jax>=0.5.3", "numpy>=1.26"]
+
+[project.urls]
+Repository = "https://github.com/andreshernandez-spec/chebax"
+
+[project.optional-dependencies]
+# tables record the mpmath version that built them; regeneration is verified
+# byte for byte, so the build dependency is pinned to the recorded minor
+gen = ["mpmath>=1.4.1,<1.5"]
+test = ["pytest", "scipy"]
+examples = ["matplotlib", "numpyro"]
+numpyro = ["numpyro>=0.15"]
+pytensor = ["pytensor>=3.2"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "slow: table regeneration and other multi-minute tests",
+]

chebax-0.3.0/src/chebax/__init__.py

@@ -0,0 +1,54 @@
+"""chebax: differentiable Chebyshev approximants for special functions.
+
+Full float64 accuracy needs jax's x64 mode (jax.config.update("jax_enable_x64", True)).
+"""
+
+from chebax._src.generate import fit
+from chebax._src.recipes.besseli import (besseli, besseli_dnu, besseli_fn,
+                                          besseli_ratio)
+from chebax._src.recipes.erf_family import dawsn, erfcx
+from chebax._src.recipes.lambertw import lambertw
+from chebax._src.recipes.matern import matern
+from chebax._src.recipes.spherical import spherical_jn, spherical_yn
+from chebax._src.recipes.besselj import besselj, besselj_dnu
+from chebax._src.recipes.besselk import (besselk, besselk_dnu, besselk_fn,
+                                         log_besselk_fn)
+from chebax._src.recipes.bessely import bessely, bessely_dnu
+from chebax._src.recipes.betainc import betainc, betainc_fn, log_betainc_fn
+from chebax._src.recipes.gammainc import (gammainc, gammainc_fn, gammaincc,
+                                          gammaincc_fn, log_gammainc_fn,
+                                          log_gammaincc_fn)
+from chebax._src.recipes.hyp1f1 import hyp1f1, hyp1f1_fn, log_hyp1f1_fn
+from chebax._src.recipes.quantiles import (betaincinv, chi2inv,
+                                           gammainccinv, gammaincinv,
+                                           log_stdtr, log_stdtr_sf, stdtr,
+                                           stdtrit)
+from chebax._src.recipes.vonmises import vonmises_cdf, vonmises_icdf
+from chebax._src.pergroup import pergroup
+from chebax._src.series import ChebSeries, PiecewiseCheb
+
+# single-sourced from pyproject.toml via package metadata
+try:
+    from importlib.metadata import version as _pkg_version
+    __version__ = _pkg_version("chebax")
+except Exception:  # not installed (e.g. running from a source checkout)
+    __version__ = "0+unknown"
+__all__ = ["ChebSeries", "PiecewiseCheb", "besseli", "besseli_dnu", "besseli_fn",
+           "besseli_ratio", "besselj", "besselj_dnu", "besselk", "besselk_dnu", "besselk_fn",
+           "log_besselk_fn",
+           "bessely", "bessely_dnu", "betainc", "betainc_fn", "betaincinv",
+           "chi2inv", "dawsn", "erfcx", "fit", "gammainc", "gammainc_fn", "gammaincc",
+           "gammaincc_fn", "gammainccinv", "gammaincinv", "hyp1f1", "hyp1f1_fn", "lambertw",
+           "log_betainc_fn", "log_hyp1f1_fn",
+           "matern",
+           "log_gammainc_fn", "log_gammaincc_fn", "log_stdtr", "log_stdtr_sf",
+           "pergroup",
+           "spherical_jn",
+           "spherical_yn", "stdtr", "stdtrit", "vonmises_cdf", "vonmises_icdf",
+           "__version__"]
+
+# submodule re-export so `import chebax; chebax.bake` works as documented
+# (bake reads __version__, so this import must stay below its definition)
+from chebax import bake  # noqa: E402,F401
+
+__all__.append("bake")

chebax-0.3.0/src/chebax/_src/generate.py

@@ -0,0 +1,280 @@
+"""Build-time fitting: sample at Chebyshev points, DCT to coefficients.
+
+The float64 path uses numpy. Passing dps switches sampling and the DCT to
+mpmath at that precision; mpmath is imported inside that branch only (the
+runtime-imports rule in CLAUDE.md).
+
+Adaptive fitting doubles the node count until the coefficient tail sits at
+the fit's own noise floor, then truncates there. A converged-looking tail
+on one grid is never trusted by itself: on n first-kind points T_{2n-k}
+samples exactly as -T_k, so an aliased fit can look converged (T_34 on 17
+nodes reproduces -T_0 to the last bit). Every candidate the adaptive path
+returns, the all-zero fit included, is first validated against fresh
+samples on two finer grids (see _validated). A fixed deg= is not: there an
+unresolved f is a legitimate request, so under-resolution cannot be told
+from aliasing.
+
+The noise floor is estimated from the trailing sixteenth of the fit's own
+coefficients rather than assumed: float64 sampling noise scales with
+the function's derivative (measured: ~1e-16 relative for exp, ~2.5e-15 for
+sin(50x)), so a fixed tolerance either fails to converge on oscillatory
+functions or keeps hundreds of noise coefficients.
+"""
+
+import numpy as np
+
+from chebax._src import algorithms
+from chebax._src.series import ChebSeries, PiecewiseCheb
+
+# ~2*eps: the practical floor of the float64 build path. Use dps= to go below.
+_DEFAULT_TOL = 5e-16
+
+
+def fit(f, domain=(-1.0, 1.0), *, deg=None, tol=None, breaks=None, dps=None, max_deg=256):
+    """Chebyshev interpolant of f, as a ChebSeries (or PiecewiseCheb if breaks given).
+
+    f:       callable on the domain. Vectorized over numpy arrays if possible;
+             with dps set it must accept mpmath floats instead.
+    domain:  (a, b), finite with a < b. Ignored when breaks is given.
+    deg:     fixed degree, at most max_deg; otherwise the degree adapts until
+             tol is met. A fixed degree is taken as an instruction: the
+             interpolant is returned as asked, with no convergence check and
+             no aliasing check (fit(T_29, deg=5) returns T_5, which is what
+             interpolating T_29 at 6 points gives). Leave deg unset for a
+             validated fit.
+    tol:     target for the relative coefficient tail (default 5e-16), positive
+             and finite. The effective chop level is max(tol, the fit's
+             measured noise floor); float64 sampling noise can sit above tol
+             for functions with large derivatives. Build with dps to control
+             the floor.
+    breaks:  strictly increasing finite knots, at least two, endpoints
+             included; one series per segment, each fit independently, padded
+             to a common degree.
+    dps:     mpmath working precision for sampling and the DCT. Derivatives of
+             a float64-built fit sit at a ~deg^2 * eps floor (differentiation
+             amplifies sample noise); build with dps when that matters.
+    max_deg: hard cap on the returned degree. Reaching it without a validated
+             converged fit raises: f is not smooth enough on the interval
+             (split the domain) or genuinely needs a higher degree.
+    """
+    max_deg = _check_int("max_deg", max_deg, 1)
+    if deg is not None:
+        deg = _check_int("deg", deg, 0)
+        if deg > max_deg:
+            raise ValueError(f"deg={deg} is above the max_deg={max_deg} cap")
+    if dps is not None:
+        dps = _check_int("dps", dps, 1)
+    if tol is None:
+        tol = _DEFAULT_TOL
+    else:
+        tol = float(tol)
+        if not np.isfinite(tol) or tol <= 0.0:
+            raise ValueError(f"tol must be positive and finite, got {tol}")
+    if breaks is not None:
+        br = [float(t) for t in breaks]
+        if len(br) < 2:
+            raise ValueError("breaks needs at least two knots")
+        if not all(np.isfinite(t) for t in br):
+            raise ValueError("breaks must be finite")
+        if not all(u < v for u, v in zip(br, br[1:])):
+            raise ValueError("breaks must be strictly increasing")
+        cs = [_fit_interval(f, br[i], br[i + 1], deg, tol, max_deg, dps)
+              for i in range(len(br) - 1)]
+        n = max(c.size for c in cs)
+        coef = np.zeros((len(cs), n))
+        for i, c in enumerate(cs):
+            coef[i, : c.size] = c
+        return PiecewiseCheb(coef, br)
+    try:
+        n_dom = len(domain)
+    except TypeError:
+        n_dom = -1
+    if n_dom != 2:
+        # (1,) used to reach an IndexError and a 3-tuple silently dropped
+        # its third element (review, 2026-08-02)
+        raise ValueError(f"domain must be a pair (a, b), got {domain!r}")
+    a, b = float(domain[0]), float(domain[1])
+    if not (np.isfinite(a) and np.isfinite(b) and a < b):
+        raise ValueError(f"domain must be finite with a < b, got ({a}, {b})")
+    return ChebSeries(_fit_interval(f, a, b, deg, tol, max_deg, dps), (a, b))
+
+
+def _check_int(name, v, low):
+    kind = "a nonnegative integer" if low == 0 else "a positive integer"
+    if isinstance(v, bool) or not isinstance(v, (int, np.integer)) or v < low:
+        raise ValueError(f"{name} must be {kind}, got {v!r}")
+    return int(v)
+
+
+def _fit_interval(f, a, b, deg, tol, max_deg, dps):
+    dct, sample_unit = (_dct_mp(f, a, b, dps) if dps is not None
+                        else _dct_np(f, a, b))
+    if deg is not None:
+        return dct(deg + 1)
+    return _adaptive(dct, sample_unit, tol, max_deg, (a, b))
+
+
+_NOISE_CEIL = 1e-8   # a window this close to the function scale is signal
+_PHI = 0.6180339887498949   # (sqrt(5) - 1)/2, irrational: see _offgrid
+
+
+def _chop(c, tol):
+    """Truncate at the noise level; returns (candidate, absolute level,
+    measured plateau relative to the scale, inf when there is none).
+
+    The level is max(tol, noise floor), where the noise floor is read off
+    the last sixteenth of the coefficients: for a still-decaying tail those
+    sit below tol and the requested tol governs (measured: exp's last
+    coefficients decay through 1e-16); for a converged fit they are the
+    sampling-noise plateau (sin(50x): ~5e-16 relative at n=129, edge-
+    singular sampling can push higher) and doubling the largest of them
+    clears the plateau's own scatter.
+
+    That window only holds noise if the fit has room to spare, and it does
+    not when the top mode lands inside it: fitting T20 on 21 points puts
+    c[20] = 1 in the last sixteenth, which read as a noise floor of 2 and
+    chopped the exact fit down to one coefficient (with max_deg = 20 there
+    is no doubling left, so `fit(T20, max_deg=20)` then raised). A real
+    plateau sits at the sampling floor, decades under the function scale
+    (the settled test below wants 1e-10 relative before it will believe
+    one), so a window within _NOISE_CEIL of the scale is signal and the
+    requested tol governs instead."""
+    scale = np.max(np.abs(c))
+    win = float(np.max(np.abs(c[-max(2, c.size // 16):])))
+    measured = win <= _NOISE_CEIL * scale
+    noise = 2.0 * win if measured else 0.0
+    level = max(tol * scale, noise)
+    keep = np.nonzero(np.abs(c) > level)[0]
+    return ((c[: keep[-1] + 1] if keep.size else c[:1]), level,
+            noise / scale if measured else np.inf)
+
+
+def _offgrid(m):
+    """m points cos(pi (i + PHI) / m), PHI irrational.
+
+    NOT the nodes of any Chebyshev grid, which is the whole point. On m
+    first-kind points T_K samples as +-T_j with (j, sign) fixed by
+    K mod 4m, so any set of harmonically related grids has whole families
+    of modes it cannot see: n, 2n and 4n all read T_{16n} as +1, which is
+    how `fit(T272)` used to come back as the constant 1 with sup error 2
+    (found in review, 2026-08-02). Here an alias would need
+    cos(K theta_i) = +-cos(j theta_i) at every point, i.e.
+    (K -+ j)(i + PHI)/m in 2Z for every i; differencing over i forces
+    K -+ j = 2 m q, and then 2 q PHI in Z, which for irrational PHI needs
+    q = 0. So the only mode that can hide is the one already in the
+    candidate."""
+    i = np.arange(m)
+    return np.cos(np.pi * (i + _PHI) / m)
+
+
+def _validated(cand, level, sample_unit, n):
+    """Check the candidate against fresh samples away from the fit grid.
+
+    A finite point set can never prove a fit: any f agreeing with cand at
+    the test points passes, and there are always such f. This is a
+    gross-error detector, nothing more. What it must not have is a
+    STRUCTURAL blind spot, and harmonically related Chebyshev grids have
+    one (see _offgrid), so the off-grid sets carry the argument and the 2n
+    grid is kept only because it is cheap and catches the ordinary
+    mistakes. Sizes are fixed by the fitting resolution n rather than by
+    the candidate's own size, which could otherwise land back on the
+    fitting grid.
+
+    An aliased fit is off by O(scale) here, ~1e15x the chop level, where
+    an honest one is at ~1x; the 1000x margin is the gap between those,
+    not an accuracy contract. The second term is the Clenshaw evaluation
+    floor, which grows with the degree and not just with sum|c|: a
+    degree-544 candidate lands 6e-13 off its own exact samples, over the
+    1000x chop margin, so an honest high-degree fit was being rejected
+    (measured on T544 once the off-grid sets started catching it)."""
+    allow = max(1000.0 * level,
+                100.0 * np.finfo(float).eps * cand.size
+                * float(np.sum(np.abs(cand))))
+    for t in (algorithms.chebpts(2 * n), _offgrid(2 * n + 1),
+              _offgrid(4 * n + 1)):
+        err = np.max(np.abs(algorithms.chebval(t, cand) - sample_unit(t)))
+        if err > allow:
+            return False
+    return True
+
+
+def _adaptive(dct, sample_unit, tol, max_deg, interval):
+    n = min(17, max_deg + 1)
+    prev_rel = np.inf
+    while True:
+        c = dct(n)
+        scale = float(np.max(np.abs(c)))
+        if scale == 0.0:
+            # all-zero samples prove nothing off the grid, T_n vanishes on
+            # chebpts(n), so the zero series is validated like any other
+            cand, level, settled = np.zeros(1), 0.0, True
+        else:
+            cand, level, rel = _chop(c, tol)
+            # The tail has settled if the chop level reached the requested
+            # tol, or if the MEASURED plateau stopped improving under node
+            # doubling while being far below the function scale: that is the
+            # sampling-noise plateau, and more nodes cannot beat it. A tail
+            # that is small but still shrinking (a segment one doubling short
+            # of converged) must escalate, not chop. rel is inf when the
+            # window held signal rather than noise, so a resolution with no
+            # plateau to report cannot seed the comparison either way.
+            settled = level <= 2.0 * tol * scale or (rel <= 1e-10 and rel >= prev_rel / 4.0)
+            prev_rel = rel
+        at_cap = n >= max_deg + 1
+        # A candidate holding nearly every coefficient of its grid has not
+        # shown a resolved tail, so double instead. At the cap there is no
+        # doubling left and validation is the only evidence available.
+        chopped = cand.size <= c.size - max(2, c.size // 8)
+        if settled and (chopped or at_cap) and _validated(cand, level, sample_unit, n):
+            return cand
+        if at_cap:
+            raise ValueError(
+                f"no validated convergence to tol={tol:g} by degree {max_deg} on "
+                f"{interval}; f may not be smooth there (split the domain), may "
+                "need a higher max_deg, or float64 sampling noise may sit above "
+                "tol (build with dps)")
+        n = min(2 * n - 1, max_deg + 1)
+
+
+def _dct_np(f, a, b):
+    def sample_unit(t):
+        xk = a + (b - a) * (t + 1) / 2
+        return _sample(f, xk)
+
+    def dct(n):
+        return algorithms.chebfit_dct(sample_unit(algorithms.chebpts(n)))
+    return dct, sample_unit
+
+
+def _sample(f, xk):
+    # scalar-only callables (wrapped special functions) are common; fall back.
+    try:
+        y = np.asarray(f(xk), dtype=float)
+        if y.shape == xk.shape:
+            return y
+    except (TypeError, ValueError):
+        pass
+    return np.array([float(f(x)) for x in xk])
+
+
+def _dct_mp(f, a, b, dps):
+    import mpmath as mp
+
+    def sample_unit(t):
+        with mp.workdps(dps):
+            mid = (mp.mpf(b) + mp.mpf(a)) / 2
+            half = (mp.mpf(b) - mp.mpf(a)) / 2
+            return np.array([float(f(mid + half * mp.mpf(float(tk)))) for tk in t])
+
+    def dct(n):
+        with mp.workdps(dps):
+            mid = (mp.mpf(b) + mp.mpf(a)) / 2
+            half = (mp.mpf(b) - mp.mpf(a)) / 2
+            fk = [f(mid + half * mp.cos(mp.pi * (2 * i + 1) / (2 * n))) for i in range(n)]
+            c = []
+            for j in range(n):
+                s = mp.fsum(fk[i] * mp.cos(mp.pi * j * (2 * i + 1) / (2 * n)) for i in range(n))
+                c.append(2 * s / n)
+            c[0] /= 2
+            return np.array([float(x) for x in c])
+    return dct, sample_unit