Tengri is a panchromatic galaxy SED inference library, written in
JAX. The same forward model covers stellar populations, dust,
nebular emission, AGN, IGM, radio, and X-ray. Inference is modular
too: the Fitter interface borrows optimizers from optax, samplers
from BlackJAX, and variational inference from NIFTy.re, so new
fitting methods plug in without touching the physics. Gradients are
available everywhere, and they are exact.
Tengri is pre-1.0 and developed as a community effort. The API is
still moving in places, and the repository will move to the
tengri-project GitHub organization shortly, where collaborative
development and issue tracking will live going forward.
Documentation: suchethacooray.com/tengri · Notebooks: notebooks/
The name Tengri comes from the all-encompassing God of Heaven in traditional Turkic, Mongolic, and other Central Asian nomadic religions. A fitting name for a code that models the light of galaxies across cosmic time. This name is chosen with respect for the cultural and spiritual traditions it originates from; no religious claim or appropriation is intended.
Modern galaxy SED inference needs speed, differentiability, and modularity at once; most codes give you one or two. Tengri is an attempt at all three.
JIT compilation gets the core forward model down to tens of
microseconds per galaxy in batched (vmap) evaluation on a single
CPU core, fast enough for catalog-scale inference without putting a
neural emulator in the loop. (A full panchromatic model with dust IR
re-emission and nebular emission is heavier: of order a millisecond
per galaxy.) Exact gradients make HMC, variational inference, and Laplace
approximation work in the 100+ parameter spaces where bursty
star formation histories and hierarchical population fits live. And
the physics and the instrument models are separate, swappable pieces,
so a new SFH family, dust law, or AGN template is one new file, with
no changes to the sampling machinery.
The full philosophy and an architecture flow chart are on the Overview page.
Most of tengri was built in about six months by a human author
working closely with AI agents. That is a deliberate part of the
design philosophy, and the development trail is kept open (see
docs/dev/agents.md). Trust has to be earned the usual way:
every piece gets checked against established codes, and the status
of each one is tracked at
docs/dev/verification-protocol.md.
Modules marked PENDING there have not been cross-checked yet, so
don't use them for publication-grade science.
Tengri is not yet on PyPI. Install from source:
pip install git+https://github.com/suchethac/tengri.gitOr clone and install for development:
git clone https://github.com/suchethac/tengri.git
cd tengri
pip install -e ".[all]"The [all] extra pulls in the optimizer and sampler backends (optax, blackjax) that the quick start below uses. A bare install can build models and predict but not fit.
Requirements: Python ≥ 3.12, JAX ≥ 0.4.20, DSPS 0.4.6–0.4.7 (0.4.8 excluded: its PyPI sdist breaks at install time), NIFTy 8.5+ with the re extra.
(The planned PyPI distribution name will be astro-tengri, with import name tengri.)
JAX backends:
- CPU: default, no extra setup.
- CUDA:
pip install -e ".[gpu]", then follow JAX's CUDA notes. - Apple Silicon: Apple's own
jax-metal(0.1.1, 2024-10) is not viable against this JAX version. The supported path is the communityjax-mpsplugin (0.11.0 or later, in its own environment; MLX-backed, float32 only) -- seenotebooks/apple_mps.pyfor setup andbench/scripts/benchmark_float32_mps_parity.pyfor the float32 accuracy check. SetJAX_PLATFORMS=cpufor any fit you intend to trust without it.
Precision: float64 by default. Pure float32 (JAX_ENABLE_X64=0 before Python starts) runs the full panchromatic model and the default photometry + emission-line fit end-to-end on CPU, CUDA and Apple GPU, converging to the float64 optimum to ~1e-5 (measured; docs/dev/float32-tier-b-boundary.md).
The smoke gate uses pytest, which ships in the [dev] extra (it is not
included in [all]), so install that first:
pip install -e ".[dev]"
pytest tests/components/sps/test_alpha_fe.py tests/components/stellar/test_stellar_skeleton.py -q --no-headerThe same two-file selection runs as the smoke gate on every PR.
Tengri needs a pre-computed Simple Stellar Population grid in DSPS HDF5 format. Pre-formatted grids (BC03, BPASS, FSPS, ProGeny) live at the public mirror. Pull the default FSPS grid (MIST isochrones with the C3K library; the Padova grids are available by name):
import tengri
tengri.download_ssp() # -> data/fsps_mist_c3k_a_chabrier.h5 (or $TENGRI_DATA_DIR)
tengri.list_known_ssps() # other gridsOr via shell:
bash scripts/setup_ssp.shimport jax
import tengri
from tengri import (
SEDModel, Fitter, Fixed, ForwardModel,
Observation, Photometry, load_ssp_data, recipes,
)
# download_ssp() fetches the default bare-stellar grid on first run and
# skips on subsequent runs. See "SSP grids" above for other grids or shell setup.
ssp = load_ssp_data(tengri.download_ssp())
obs = Observation(photometry=Photometry.from_names(
["sdss_u", "sdss_g", "sdss_r", "sdss_i", "sdss_z"]
))
# The mock is at a known redshift, so fix z. The model then builds a
# single-redshift table in seconds instead of tabulating the
# full z in (0.01, 6) grid.
# Leave z free for real catalogs with unknown redshifts.
config = recipes.star_forming_photometry()
config["redshift"] = Fixed(0.05)
sed = SEDModel.build(ssp_data=ssp, observation=obs, **config)
forward = ForwardModel.build(sed=sed, observation=obs)
key = jax.random.PRNGKey(0)
mock = sed.mock(sed.spec.sample(key), key=key)
# This recipe has 8 free parameters. Past D ~ 6, NUTS spends most of its
# time in warmup, so use fixed-length HMC. See
# docs/method_selection.md for the decision table.
fitter = Fitter(forward, mock.flux_obs, mock.noise)
result = fitter.run("mcmc_hmc")
print(result.summary_table())Building the model takes a few seconds and the fit about 40 s on a laptop
CPU; the first run also pays a one-off JAX compile. Swap in "map" for a
point estimate in ~4 s, or "laplace" for credible intervals in ~5 s.
"mcmc_nuts" is the gold standard below D ≈ 6, but on this 8-parameter
model its warmup pushes the fit past 8 minutes.
For real data, pass your own (flux, noise) to Fitter. The full
walkthrough is in notebooks/00_quickstart.py.
If you want more control than a recipe gives you, build the model with
the nested-dict grammar. Import the sentinel it uses first (FREE is a
singleton, distinct from the Fixed(...) prior above):
from tengri import DEFAULT, Fixed, FREE, Uniform
sed = SEDModel.build(
ssp_data=ssp, observation=obs, redshift=Fixed(0.05),
sfh={'type': 'dpl', 'all_params': FREE, 'beta': Uniform(1, 3)},
dust_attenuation={'type': 'two_component', 'law': 'calzetti', 'all_params': Fixed(DEFAULT)},
neb={'type': 'cue', 'all_params': Fixed(DEFAULT)},
)all_params sets every parameter in the group at once (default: fixed at
the registry default); per-parameter keys (like beta above) override it.
See notebooks/04_building_models.py
for the grammar; tengri.recipes shows the curated starting points.
The notebook spine in notebooks/ is the main learning path. The .py files are Jupytext source.
| # | Notebook | Topic |
|---|---|---|
| 00 | 00_quickstart.py |
mock galaxy → posterior, end to end |
| 01 | 01_why_jax.py |
JIT, vmap, grad in the context of galaxy SED inference |
| 02 | 02_sed_anatomy.py |
the panchromatic SED, component by component |
| 03 | 03_discovering_the_menu.py |
discovery API (list_*, describe, search) |
| 04 | 04_building_models.py |
the nested-dict / recipe grammar |
| 05 | 05_fitting_photometry.py |
photometric fit, end to end |
| 05 | 05_adding_a_model.py |
registering a new physics block |
| 06 | 06_fitting_spectroscopy.py |
spectroscopy with calibration nuisance parameters |
| 07 | 07_joint_photo_spec.py |
joint photo + spec to break degeneracies |
| 08 | 08_emission_lines.py |
BPT diagnostics, line ratios, Hα-based SFR |
| 09 | 09_parameter_sweeps.py |
one knob at a time: how each parameter moves the SED |
| 10 | 10_fastspecfit_joint_fit.py |
joint DESI photometry + emission-line fluxes, timed |
| 11 | 11_catalog_fits.py |
a catalog fit in parallel: LSST+Euclid photo-z, timed |
| 12 | 12_simulation_populations.py |
simulation SFH + Z(t) → photometry and lines, ~8k galaxies/s |
| 19 | 19_joint_spec_phot.py |
joint spec-phot with a Sersic fiber aperture |
For single-figure recipes, see the examples gallery.
import tengri
tengri.summary() # live counts from every registry
tengri.help() # curated cheatsheet
tengri.list_filters() # also list_sfh_models, list_nebular_backends, ...
tengri.list_inference_methods()
tengri.describe("skirtor")
tengri.search("torus")
tengri.doctor() # install + JAX backend + SSP filesThe same commands are available from the shell:
python -m tengri summary
python -m tengri describe skirtor
python -m tengri doctorThese read the registries directly, so a model registered via @register_agn_model shows up without a documentation edit.
Parameters declares priors. SEDModel ties priors, an SSP grid, and an Observation into a differentiable SED chain. ForwardModel wraps the chain into a single .predict(params) interface that every backend consumes. Fitter drives the chosen backend and returns a Posterior. The samplers themselves are pulled in from optax, BlackJAX, and NIFTy.re, plus a population layer that runs hierarchical fits on top.
tengri.list_inference_methods() returns the live registry, including the experimental backends.
Stellar populations are integrated over SSP grids in the DSPS format
(BC03, BPASS, FSPS, ProGeny) by tengri's own differentiable CIC kernel;
DSPS's histogram kernel is selectable for cross-code parity.
The SFH layer covers parametric families (15+, registry-driven),
non-parametric reconstructions (Leja+ continuity, Dirichlet), and
stochastic fields (IFT correlated fields with PSD-governed
burstiness). Dust is swappable on both the attenuation and emission
sides. Nebular emission has four backends: ssp (emission baked into
the SSP grid), cue (emulator), cloudy, and cb19. AGN spans disc,
torus, BLR/NLR, and IR
re-emission, unified across optical, IR, and X-ray. IGM, radio, and
X-ray sit alongside as components, not afterthoughts.
Every physics component is a pure JAX function, so jit, vmap, and
grad compose through the whole forward model.
tengri.print_components_bibtex(result) prints BibTeX for every SSP,
model, and code used in a fit.
- CONTRIBUTING.md: bug reports, feature requests, pull requests
- GOVERNANCE.md: decision-making
- .github/CODE_OF_CONDUCT.md
- .github/SECURITY.md
- .github/SUPPORT.md
- docs/dev/verification-protocol.md: component verification status
- CHANGELOG.md · CONTRIBUTORS.md
Contributors at every level are welcome. If a science case you care about isn't supported yet, that's exactly the conversation we want to have.
For anything that doesn't fit in an issue (collaborations, the
tengri-project org move, joining the project), write to
astro.tengri@gmail.com or
cooraysuchetha@gmail.com.
tengri reproduces the physics in the established panchromatic SED codes: the same models, implemented in one framework, so you can check every assumption and compare models side by side. The comparisons live in docs/reproduction/. Seven are online now (CIGALE, BAGPIPES, Prospector/FSPS, AGNFITTER-RX, ProSpect, GRAHSP, BEAGLE), each putting the two codes on the same axes, component by component, ending with a full-SED head-to-head. Synthesizer is being revised, and MAGPHYS and GalaPy are next.
While Paper I is in preparation, the shortest correct in-text citation is:
Cooray et al., tengri: A Differentiable Framework for High-Dimensional Bayesian Inference from Galaxy Spectral Energy Distributions, in prep. (2026).
See CITATION.cff for the machine-readable form and the
Citing tengri page
for the BibTeX + acknowledgement block. For automatic, fit-specific
citations (every SSP grid, model, and sampler that actually ran),
pass the fit to cite, which prints the component table and BibTeX:
tengri.cite(result)BSD-3-Clause. See LICENSE and NOTICE (which lists every project whose models tengri implements or depends on).