The forward model¶
Tengri’s forward model is split into two clearly separated layers.
┌─────────────────────────────────────────────────────────┐
│ Inference (MAP / NUTS / VI / nested sampling / …) │
│ Entry point: ForwardModel.fit(data, noise, method). │
│ Hot path is .predict_photometry(params); .predict() │
│ is the rich, exploratory surface (bypasses the LUT). │
└────────────────────────┬────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ ForwardModel — the thin outer shell │
│ • owns one SubModel and one observation │
│ • .predict(params) → dict {phot_fnu, spec_fnu, ...} │
│ • inference never has to choose between predict_* │
│ methods; the dict tells it which channels exist │
└────────────────────────┬────────────────────────────────┘
▼
┌────────────┴────────────┐
│ SubModels │
├─────────────────────────┤
│ SEDModel │ single galaxy SED chain
│ PopulationSEDModel │ N galaxies, shared params (hierarchical)
│ SpatialModel │ single galaxy spatial profile
│ SpatialSEDModel │ SED + Spatial (joint)
│ PopulationSpatialSED │ far-future composition of all of the above
└─────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ SEDModel — the SED physics chain (used inside every │
│ SubModel variant) │
│ star formation history → simple stellar populations │
│ → nebular and AGN emission → dust attenuation and │
│ re-emission → IGM absorption → photometry/spectroscopy│
│ Pure JAX. JIT-compilable, gradient-traceable, │
│ batchable through vmap. │
└─────────────────────────────────────────────────────────┘
The outer-shell signature stays uniform across all SubModel variants.
Construction is always ForwardModel.build(<slot>=..., observation=obs)
and inference is always through forward.fit(...), whatever the
SubModel underneath happens to be.
The minimum usable fit¶
import tengri
from tengri import Fixed, DEFAULT, ForwardModel, SEDModel
ssp = tengri.load_ssp_data(tengri.download_ssp())
obs = tengri.Observation(photometry=tengri.Photometry.from_names(["sdss_u", "sdss_g", "sdss_r"]))
# 1. Build the SED chain.
sed = SEDModel.build(
ssp_data=ssp,
observation=obs,
sfh={"type": "dpl", "log_total_mass": 10.0, "other_params": Fixed(DEFAULT)},
dust_attenuation={"type": "two_component", "law": "calzetti", "all_params": Fixed(DEFAULT)},
neb={"type": "none"},
redshift=tengri.Fixed(0.05),
)
# 2. Wrap it in the outer shell.
forward = ForwardModel.build(sed=sed, observation=obs)
# 3. Hand to inference. `forward.fit` is the canonical entry point.
posterior = forward.fit(photometry_array, noise_array, method="map")
posterior.summary()
Why the split?¶
The SED chain (“the physics”) and the surface that inference consumes
(“the prediction dict”) have always been two different responsibilities.
Before the split, SEDModel carried one method per channel combination:
predict_photometry, predict_spectrum, predict_joint and others. Each
encoded “which channels exist” in the method name. Inference backends
therefore had to know whether they were fitting photometry, spectroscopy, or
both, and pick the right method. (predict_joint is gone; the others remain.)
After the split:
Adding a new observation channel is one new key in the prediction dict, with no inference-side branching.
Existing user code that calls
sed.predict_photometry(params)directly still works; nothing aboutSEDModelchanged.The dev-side surface area is smaller (a Protocol with two methods:
declared_parametersandrun, instead of a handful of channel-specific predict methods).
ForwardModel.build(...) reference¶
ForwardModel.build(
*,
sed: SEDModel | None = None, # single-galaxy SED
spatial: SpatialModel | None = None, # add a spatial profile
population: PopulationSEDModel | None = None, # hierarchical multi-galaxy
populations: Iterable[Population] | None = None, # explicit decomposition
observation: Observation,
) -> ForwardModel
Pick exactly one of sed=, population=, or populations=. Returns
a frozen dataclass. What you call afterwards is
forward.fit(data, noise, method=...); everything else is posterior
helpers. To inspect a prediction rather than fit one, use
forward.predict(params). On a fitting hot path prefer forward.predict_photometry(params). The
predict_observables method returns the full channel dict and bypasses the
photometry lookup table.
Hierarchical population fits¶
When you have many galaxies that share an underlying parameter (the
canonical case: PSD hyperparameters σ_PSD, τ_PSD of the
stochastic-SFH prior), wrap them in a PopulationSEDModel and pass it
to ForwardModel.build(population=...):
import numpy as np
from tengri import ForwardModel, PopulationSEDModel, SEDModel, recipes
# The template needs a stochastic (field) SFH — that is where the shared
# PSD hyperparameters live. A DPL-only template has none to share.
template = SEDModel.build(ssp_data=ssp, observation=obs,
**recipes.stochastic_sfh_jwst())
pop = PopulationSEDModel(
sed=template,
galaxies=[{'flux_obs': np.ones(5), 'noise': np.ones(5)} for _ in range(3)], # three galaxies
# shared= and priors= default to PSD; override for other hierarchies
)
forward = ForwardModel.build(population=pop, observation=obs)
# Inference is the same as for a single galaxy: one Hamiltonian path over
# a (N_gal, n_filters)-shaped batched prediction, minimizing
# chi^2 + xi^T xi over the joint latent space. Passing no data is what
# selects the hierarchical path — the per-galaxy arrays already live on
# the PopulationSEDModel.
posterior = forward.fit(method='vi')
The PSD priors live on the PopulationSEDModel construction, not on a
separate hierarchical fitter class. Thus there is one place that
parameterizes the hierarchy.
Inference routes through the same machinery natively. There is one
information-Hamiltonian path (forward.fit(method='vi')) whether
forward holds an :class:SEDModel (single galaxy), a
- class:
PopulationSEDModel(hierarchical), or- class:
SpatialSEDModel. The- class:
PopulationSEDModelpublishes its batched axes ({'galaxy': 0}) and the spec view publishes per-param shapes ((N_gal,)for per-galaxy,()for shared). The existing inference backends consume the batched output without any type-specific code.
The legacy :class:tengri.PopulationFitter direct API remains
importable but emits a one-shot DeprecationWarning pointing at
this canonical path; the legacy class will be removed in v1.0.
Composing SubModels¶
The SubModel lattice composes. Every variant either contains the
others or runs alongside them, but each is a strict SubModel from
ForwardModel’s perspective:
SubModel |
Used when |
|---|---|
|
one galaxy, SED only |
|
one galaxy, morphology-only fit (e.g. resolved imaging) |
|
one galaxy, joint spatial + SED (e.g. SDSS-fiber spec + photometry) |
|
many galaxies, hierarchical shared parameters (PSD) |
|
many galaxies with shared parameters and morphology |
Adding a new SubModel requires one Python file plus one entry in the ForwardModel-build kwargs table. The inference layer remains unchanged.
Forward chain — the SED physics¶
The differentiable forward chain inside SEDModel follows the standard
SED-fitting cascade:
star formation history (SFH)
↓
simple stellar populations (SSP) — DSPS interpolation
↓
nebular and AGN emission (added)
↓
dust attenuation and re-emission (transforms + adds)
↓
IGM absorption (transforms)
↓
observed-frame photometry / spectroscopy via filter / LSF convolution
Each step is a pure JAX function, so the whole chain is JIT-compiled,
gradient-traceable, and batchable through vmap.
Spine notebooks¶
Notebook |
Focus |
|---|---|
One-screen end-to-end fit, including a photometry MAP/NUTS fit and its posterior |
|
The panchromatic SED, component by component |
|
Building models with the nested-dict grammar; swapping SFH families, dust laws, IR templates |
|
Spectroscopy-only fits with calibration |
|
Combining photometry and spectroscopy in one likelihood |
|
Fitting a catalog of galaxies |
|
Forward-modeling tabulated SFH and Z(t) histories from a simulation to photometry and emission lines, and how to make it fast ( |
The pedagogical order in the spine is SFH → dust → nebular → AGN → multi-wavelength, which mirrors the order of decisions a user typically makes rather than the strict internal call order.