Choosing an inference method¶
forward.fit(..., method="...") dispatches to one of ~19 backends. They are not interchangeable: some are exact samplers, some are fast approximations, and a few are still experimental. The authoritative, always-current list (with per-method tier, dependencies, and validation notes) is a function call:
import tengri
tengri.list_inference_methods() # table: name, tier, short_doc, requires
tengri.describe("mcmc_nuts") # full notes for one method
The table below is a decision aid. When it disagrees with list_inference_methods(), trust the function.
Decision table¶
Situation |
Method |
Why |
|---|---|---|
Quick point estimate / initialization |
|
L-BFGS by default (scipy L-BFGS-B single-start; JAX BFGS via |
Fast posterior approximation |
|
Gaussian around the MAP from the Hessian. Cold ~5–9 s, warm ~1–2 s. Good when the posterior is roughly Gaussian. |
Auto-dispatch (beginner) |
|
Selects NUTS for low-D, raytrace for high-D. Convenient when you’re unsure of the right sampler. |
Exact posterior, low-D (D ≤ 6) photometry |
|
No-U-Turn Sampler. Gold standard for small parametric models. Cold ~90 s at D=6 DPL. |
D ≈ 7–8, or NUTS warmup too slow |
|
Fixed-length HMC keeps the compile graph bounded. Cold ~21 s at D=6–7, ~40 s at D=8 photometry. Validated only with |
Nonparametric SFH ( |
|
One setting dominates, and it is not the sampler name: lengthen the trajectory, and judge the length by its worst seed rather than its average. The default bin ladder already reaches the age of the universe at a fixed fit redshift ( |
High-D (D ≳ 20), e.g. stochastic-field SFH |
|
Ray tracing is O(1)-gradient ensemble sampling; |
Model comparison / BMA (calibrated reference) |
|
Nested sampling. Calibrated, reference-grade evidence (σ_logZ ≈ √(H/n_live)). Cold ~60 s at D=6 with fast preset; use for cross-validation per model family. |
Model comparison / BMA (fast approximation) |
|
Gaussian approximation around the MAP. Cold ~5–9 s. Valid when diagnostics show |
Model comparison / BMA (recommended workhorse) |
|
HMC posterior chain + importance-sampled evidence. Cold ~30 s at D=6; delivers posterior samples + log Z in one run. Check |
Tiers¶
tengri.list_inference_methods() tags each backend:
primary — validated on the standard DPL / dense-basis mocks (
map,laplace,mcmc,mcmc_nuts,mcmc_hmc,mcmc_raytrace,vi,vi_nonlinear_fast).experimental — present but not yet recommended for science. Several carry explicit
[POOR MIXING]or[UNSTABLE]flags in theirshort_doc(e.g.mcmc_dynamic_hmc,mcmc_adjusted_mclmc,mcmc_ess,nss,vi_linear,vi_linear_fast). Calltengri.describe("<name>")to read the full validation notes before using them.
Memory and the one-fit-per-process rule¶
NUTS/VI warmup can peak well above the resident forward model (20+ GB on dense_basis D≈8 with dense_mass_matrix=True). Run one NUTS/VI fit per Python process, and drop to dense_mass_matrix=False or mcmc_hmc on D ≥ 8. The fitting tutorials (quickstart, 06, 07) follow these rules; see also Caveats.
Speed: build with a precompute table¶
For photometry-only models, build with approx=WavePrecomp(). It precomputes the SSP × filter integrals and projects each forward pass through a lookup table (roughly a 5× speedup on the warm call), which is what makes a full NUTS run finish in seconds rather than minutes. Free redshift is handled transparently via an interpolation table. Every entry in tengri.recipes uses it. For spectroscopy, the default approx="auto" takes SpectrumPrecomp() only where the table serves the pixels exactly: point-sampled pixels (or pixels no wider than the model grid), a fixed sigma_v_kms, and no banded resolution matrix. Otherwise, and for approx=None, the fit runs on the exact path. An explicit approx=SpectrumPrecomp() always engages the table. On a joint observation either opt-in builds both the photometry and spectrum tables. See Joint photometry + spectroscopy and Caveats.