Inference¶
Fitting models to data, sampling posteriors, and running hierarchical inference across galaxy populations.
Inference always goes through a ForwardModel. The entry point
is fit():
forward = ForwardModel.build(sed=sed, observation=obs)
result = forward.fit(flux, noise, method="mcmc_nuts")
Fitter is the engine underneath. forward.fit(...) is
exactly Fitter(forward, flux, noise).run(...) and forwards every extra
keyword to run(), so the shortcut is not a reduced
surface. Reach for Fitter directly only to inspect engine state such as
compile_signature(); holding the object is not what buys you compile
reuse, because the compilation caches are keyed on that signature and shared
across instances. For many galaxies, use Catalog.
Pass a ForwardModel, not a bare SEDModel.
Fitter(sed_model, ...) still runs but is deprecated; wrap the SED chain
with ForwardModel.build(sed=..., observation=...) first.
Posterior¶
- class tengri.Posterior(samples: dict | None, params: dict, method: str, wall_time_s: float, diagnostics: dict, loss_history: Array | None = None, log_evidence: float | None = None, _model: object = None, _fitter: object = None, _runtime_values: dict | None = None, eline_fluxes: Array | None = None, eline_flux_cov: Array | None = None, eline_names: tuple | None = None, eline_wavelengths: Array | None = None, _free_names: tuple[str, ...] | None = None)[source]¶
Bases:
objectInference results with samples, diagnostics, and derived quantities.
Stores posterior samples (or point estimate for MAP), best-fit parameters, convergence diagnostics, and provides methods for summary statistics, derived physical quantities, ArviZ conversion, and refinement via resampling or additional fitting iterations.
- Parameters:
samples (dict or None) – Posterior samples in physical parameter space (optional, set by inference). Free parameters only (#2296); Fixed values are on
fixed_values.params (dict) – Best-fit or posterior mean parameters. Free parameters only (#2296); Fixed values are on
fixed_values, not merged into this dict.method (str) – Inference method name (e.g.,
"vi","mcmc_nuts","map").wall_time_s (float) – Total wall-clock runtime in seconds.
diagnostics (dict) – Method-specific convergence metrics.
loss_history (ndarray or None) – Optimization loss values (optimization methods only).
log_evidence (float or None) – Log Bayesian evidence (NSS only).
_model (SEDModel, optional) – Forward model reference.
_fitter (Fitter, optional) – Fitter reference for refinement methods.
eline_fluxes (ndarray or None) – Emission line fluxes [erg/s/cm²].
eline_flux_cov (ndarray or None) – Emission line flux covariance.
eline_names (tuple or None) – Emission line identifiers.
eline_wavelengths (ndarray or None) – Rest-frame vacuum wavelengths [Angstrom].
_free_names (tuple of str, optional) – Names of the parameters the sampler moved, for a posterior with no
_model. Restored byload()from the filesave()wrote.
- Returns:
Posterior instance with results populated.
- Return type:
- Variables:
samples (dict or None) – Posterior samples in physical parameter space. Each value has shape (n_samples, …). Keys are parameter names (e.g.,
"stellar_mass","age_gyr","psd_xi").Nonefor point estimates (MAP, Laplace, Pathfinder). Free parameters only (#2296): a key the spec declaredFixednever appears here, seefixed_values.params (dict) – Best-fit (MAP for point estimation) or posterior mean parameters in physical space. Same keys as
samples(without"psd_xi"latent field). Free parameters only (#2296): safe to feed straight back intomodel.predict(posterior.params)on the SAME model, which fills Fixed values in internally.method (str) – Inference method name (e.g.,
"vi","mcmc_nuts","map").wall_time_s (float) – Total wall-clock runtime in seconds, including compilation and sampling.
diagnostics (dict) –
Method-specific convergence and quality metrics. Contents vary by method:
VI methods:
{"kl_iter": int, "kl_final": float}, etc.NUTS:
{"n_divergent": int, "accept_rate": float}, etc.Ray Tracing:
{"accept_rate": float, "step_size": float}, etc.MAP:
{"final_loss": float, "n_steps": int}, etc.NSS:
{"n_live": int, "log_evidence_err": float, "information_nats": float, "n_live_effective": float}, etc.log_evidence_erris the standard deviation of log Z [nats], sqrt(H / n_eff);information_natsis the information H [nats] (Kullback-Leibler divergence of the posterior from the prior);n_live_effectiveis n_eff [dimensionless], the live count corrected for batch deletion (n_eff = n_live when one point is deleted per iteration).
loss_history (ndarray or None) – Optimization loss values over iterations (MAP/Laplace/Pathfinder only). Shape (n_iterations,).
Nonefor sampling methods.log_evidence (float or None) – Bayesian evidence log(Z) integral (NSS only).
Nonefor other methods. Used for model comparison via Bayes factors._model (SEDModel, optional) – Reference to the forward model. Required for computing derived quantities (stellar mass, SFR, sSFR, etc.). Set by
Fitter.run()automatically._fitter (Fitter, optional) – Reference to the Fitter instance. Enables
refine()and other refinement methods. Set byFitter.run()automatically.eline_fluxes (ndarray or None) – Emission line fluxes. Shape (n_lines,) for MAP, (n_samples, n_lines) for sampling.
Noneif no emission line fitting/marginalization was enabled. Flux units match input data [erg/s/cm²].eline_flux_cov (ndarray or None) – Posterior covariance of emission line fluxes. Shape (n_lines, n_lines) for MAP, (n_samples, n_lines, n_lines) for sampling.
Noneif unavailable.eline_names (tuple or None) – Emission line identifiers (e.g.,
("Halpha", "Hbeta", ...)) matchingeline_fluxescolumn order.eline_wavelengths (ndarray or None) – Rest-frame vacuum wavelengths [Angstrom] of emission lines, matching
eline_fluxescolumn order.
Notes
Derived quantities: The
derivedproperty computes stellar mass, SFR, sSFR, etc. by re-running the forward model on all samples. For MAP results, returns scalars; for MCMC/VI results, returns arrays (one per sample).Emission line diagnostics: Methods
line_fluxes(),bpt_nii(), andbalmer_decrement()provide astrophysical diagnostics on emission lines. Requireeline_mode != "none"in Spectroscopy config.Convergence diagnostics: Use
check_convergence(),autocorrelation(), andeffective_sample_size()to assess MCMC chain quality.Resampling and refinement: Use
resample()to draw new samples from the posterior, andrefine()to improve results by running additional inference iterations (requires_fitter).See also
Fitter.runReturns Posterior with all attributes populated.
FitterPrimary interface for inference.
Examples
Basic usage:
>>> result = fitter.run("mcmc_nuts") # Returns Posterior >>> print(result.summary_table()) >>> params_phys = result.params >>> samples = result.samples
Physical properties:
>>> stellar_masses = result.properties["stellar_mass"] # Shape (n_samples,) >>> lo, med, hi = result.properties.ci("stellar_mass") >>> stellar_masses = result.stellar_mass # attribute sugar, same array
Emission line diagnostics:
>>> fluxes = result.line_fluxes() >>> ha_med, ha_lo, ha_hi = fluxes["Halpha"] >>> x, y = result.bpt_nii() # BPT diagram coordinates >>> plt.scatter(x, y, alpha=0.3)
Convergence checks:
>>> converged = result.check_convergence() >>> ess = result.effective_sample_size() >>> print(f"Effective sample size: {ess['stellar_mass']:.0f}")
Refinement via resampling:
>>> refined_samples = result.resample(key, n=50) # Resample with replacement >>> refined = fitter.run("vi", init_from=result) # Refine posterior
- agn_fraction(wavelength=None) Array[source]¶
Wavelength-resolved AGN luminosity fraction.
Returns the median over posterior draws of
L_agn(λ) / L_total(λ)(or the MAP point estimate as a single curve).- Parameters:
wavelength (array_like, optional) – Rest-frame wavelength grid. Defaults to the model’s grid.
- Returns:
Median AGN fraction at each wavelength.
- Return type:
ndarray, shape (n_wave,)
Notes
Wraps
sed_components(). To get full credible intervals on the fraction, callsed_componentsdirectly and compute percentiles onsed_agn / sed_total.
- autocorrelation(max_lag: int | None = None) dict[source]¶
Compute autocorrelation function for each scalar parameter.
- Parameters:
max_lag (int, optional) – Maximum lag. Default: n_samples // 2.
- Returns:
Keys: parameter names. Values: ndarray of autocorrelation from lag 0 to max_lag. ACF[0] = 1.0 by definition.
- Return type:
Notes
Uses FFT for O(N log N) efficiency instead of naive O(N * max_lag). Normalized so that ACF[0] = 1 and ACF[k] ∈ [-1, 1]. Parameters with zero variance (fixed parameters) return zero ACF.
Examples
>>> acf = result.autocorrelation() >>> lag_cutoff = np.argmax(acf["stellar_mass"] < 0.05) >>> print(f"ACF drops below 0.05 at lag {lag_cutoff}")
- autocorrelation_time() dict[source]¶
Estimate integrated autocorrelation time for each parameter.
Uses Sokal’s self-consistent window method with both standard and absolute-deviation modes (Behroozi 2025).
- Returns:
Keys: parameter names. Values: dict with
'tau_standard','tau_absolute','tau_max'(integrated autocorrelation time),'ess'(effective sample size),'chain_converged'(bool, True if N > 5τ_max).- Return type:
Notes
Two autocorrelation time estimates are computed:
tau_standard: based on standard ACF
tau_absolute: based on absolute-deviation ACF (robust to mean/variance changes)
The maximum is returned (conservative). ESS = N / tau_max. Convergence flag uses the criterion N > 5τ_max from Behroozi (2025).
Examples
>>> tau_dict = result.autocorrelation_time() >>> for param, info in tau_dict.items(): ... converged = info["chain_converged"] ... print( ... f"{param}: tau_max={info['tau_max']:.1f}, " ... f"ESS={info['ess']:.0f}, converged={converged}" ... )
- balmer_av() tuple[float, float, float][source]¶
Visual extinction A(V) from the Balmer decrement (Calzetti+2000).
Converts the observed Hα/Hβ ratio to a V-band attenuation assuming Case B recombination (intrinsic ratio 2.86) and the Calzetti et al. 2000 [tengri.Posterior.balmer_av-1] starburst attenuation law (\(R_V = 4.05\), \(k(H\alpha) = 2.53\), \(k(H\beta) = 3.61\)).
- Returns:
(median, lo_68, hi_68)of A(V) in [mag]. For MAP results all three values are equal. Negative values are returned as-is (unphysical, but informative for noisy data, clip externally if desired).- Return type:
- Raises:
ValueError – If Hα or Hβ fluxes are not available.
Notes
\[\begin{split}E(B-V) &= \frac{\log_{10}\!\left(R_{\rm obs}/2.86\right)} {0.4\,\left(k(H\beta) - k(H\alpha)\right)} \\ A(V) &= R_V \cdot E(B-V)\end{split}\]For Calzetti+2000: \(0.4 \cdot (k(H\beta) - k(H\alpha)) = 0.432\), \(R_V = 4.05\), so \(A(V) \approx 9.375 \, \log_{10}(R_{\rm obs}/2.86)\).
References
[tengri.Posterior.balmer_av-1]Calzetti, D. et al., 2000, ApJ, 533, 682.
Examples
>>> av_med, av_lo, av_hi = result.balmer_av()
- balmer_decrement() tuple[float, float, float][source]¶
Observed Hα/Hβ ratio from posterior line fluxes.
Returns the posterior distribution of the Balmer decrement (Hα/Hβ), which is a direct dust attenuation diagnostic. The intrinsic Case B ratio is 2.86; higher values indicate dust.
- Returns:
(median, lo_68, hi_68)of Hα/Hβ (dimensionless ratio). For MAP results, all three values are equal.- Return type:
- Raises:
ValueError – If Hα or Hβ fluxes are not available.
Notes
The Balmer decrement (Hα/Hβ flux ratio) is insensitive to stellar population age and metallicity; deviations from the intrinsic Case B value of 2.86 (Osterbrock 1989) directly indicate dust attenuation. A Balmer decrement > 3.0 typically indicates significant dust.
Examples
med, lo, hi = result.balmer_decrement() print(f"Ha/Hb = {med:.2f} [{lo:.2f}, {hi:.2f}]") # Intrinsic Case B = 2.86; excess indicates dust attenuation
- bpt_class()[source]¶
Classify each posterior draw as SF / composite / AGN on the BPT-NII diagram.
Uses the standard demarcation lines:
Kauffmann et al. 2003 [tengri.Posterior.bpt_class-1], separates pure SF from composite (SF + AGN admixture).
Kewley et al. 2001 [tengri.Posterior.bpt_class-2], separates composite from pure AGN/Seyfert.
Below Kauffmann ⇒
"SF"; between Kauffmann and Kewley ⇒"composite"; above Kewley ⇒"AGN". Non-detections (NaN ratios) return"unknown".- Returns:
For MAP results: a single label string. For sampling results: a length-
n_samplesarray of labels.- Return type:
str or ndarray of dtype <U9
- Raises:
ValueError – If emission line fluxes are unavailable or BPT lines absent.
Notes
Kauffmann+2003 demarcation:
\[\log_{10}\!\frac{[\mathrm{O\,III}]}{H\beta} = \frac{0.61}{\log_{10}([\mathrm{N\,II}]/H\alpha) - 0.05} + 1.30 \quad (\text{for }\log [\mathrm{N\,II}]/H\alpha < 0.05)\]Kewley+2001 demarcation:
\[\log_{10}\!\frac{[\mathrm{O\,III}]}{H\beta} = \frac{0.61}{\log_{10}([\mathrm{N\,II}]/H\alpha) - 0.47} + 1.19 \quad (\text{for }\log [\mathrm{N\,II}]/H\alpha < 0.47)\]Points right of the asymptote (\(\log [\mathrm{N\,II}]/H\alpha \ge 0.47\)) are classified as AGN regardless of [O III]/Hβ.
References
[tengri.Posterior.bpt_class-1]Kauffmann, G. et al., 2003, MNRAS, 346, 1055.
[tengri.Posterior.bpt_class-2]Kewley, L. J. et al., 2001, ApJ, 556, 121.
Examples
>>> labels = result.bpt_class() >>> import numpy as np >>> agn_lum_ratio = float(np.mean(np.asarray(labels) == "AGN"))
- bpt_nii() tuple[Array, Array][source]¶
BPT-NII ([NII]/Hα vs [OIII]/Hβ) diagram coordinates.
Returns log10 line ratios for each posterior sample.
- Returns:
log_nii_ha (ndarray, shape (n_samples,) or scalar) – log10([NII]6584 / Hα). For MAP, returns scalar.
log_oiii_hb (ndarray, shape (n_samples,) or scalar) – log10([OIII]5007 / Hβ). For MAP, returns scalar.
- Raises:
ValueError – If emission line fluxes are not available or BPT lines are missing.
Notes
The BPT diagram is a standard AGN/SF diagnostic that uses the ratios [NII]/Hα (x-axis) and [OIII]/Hβ (y-axis). Non-detections (negative or zero fluxes) are returned as NaN and will not be plotted. Diagnostic lines follow Kewley et al. (2001, 2006) conventions.
Examples
x, y = result.bpt_nii() plt.scatter(x, y, alpha=0.3) # Overlay diagnostic lines from starburst/Seyfert boundaries
- check_convergence(verbose: bool = True) dict[source]¶
Check chain convergence using autocorrelation diagnostics.
Follows Behroozi (2025): chain is converged when N > 5τ for all parameters.
- Parameters:
verbose (bool) – Print diagnostics table.
- Returns:
Keys:
'all_converged'(bool),'params'(dict per-parameter convergence info),'warnings'(list of unconverged parameters).- Return type:
Notes
Convergence criterion: N > 5τ_max for all parameters. If N < 5τ for any parameter, the chain is flagged as unconverged. See Behroozi (2025) for justification of the 5τ threshold.
Examples
>>> conv = result.check_convergence() >>> if conv["all_converged"]: ... print("Chain converged!") ... else: ... print(f"Unconverged: {conv['warnings']}") ... print("Run additional samples and use refine()")
- property derived: dict¶
Derived physical quantities (stellar mass, SFR, sSFR).
Deprecated since version 2026-07: Use
propertiesinstead, it exposes every property the model provides (not a hardcoded five), under the same names as the model side, and evaluates them in memory-bounded chunks.posterior.derived["stellar_mass"]becomesposterior.properties["stellar_mass"](orposterior.stellar_mass).For MAP: computed on the single best-fit → dict of scalars. For NUTS/geoVI: computed on all samples → dict of arrays.
- Returns:
Keys: derived quantity names (
"stellar_mass","sfr_100myr", etc.). For MAP: values are scalars. For sampling: values are arrays of shape (n_samples,). Units match the forward model convention (stellar mass in [Msun], SFR in [Msun/yr]).- Return type:
Notes
This is a cached property, computed on first access and cached thereafter. Requires
_modelto be set (populated automatically byFitter.run()). For stochastic SFH, unresolved bursts are included insfr_10myrandsfr_100myroutputs.Examples
Prefer
properties, the same names, every property the model publishes rather than a hardcoded five, and credible intervals without a manual percentile call:>>> stellar_masses = result.properties["stellar_mass"] # (n_samples,) >>> lo, med, hi = result.properties.ci("stellar_mass")
- diagnostics_summary() str[source]¶
Print a diagnostics summary with ESS and credible intervals.
- Returns:
Formatted table of per-parameter ESS and 68% credible intervals.
- Return type:
Notes
For MAP results, returns a simple string indicating no samples are available. For sampling methods, tabulates ESS for each parameter alongside median and 68% credible intervals. Use
rhat()for the split-chain Gelman-Rubin diagnostic.Examples
>>> print(result.diagnostics_summary()) Method: mcmc_nuts Samples: 1000 Wall time: 5.2s
Parameter Median 68% CI ESS ──────────────────────────────────────────────────────────────── stellar_mass 10.500 [10.300, 10.700] 800 …
- effective_sample_size() dict[source]¶
Estimate effective sample size (ESS) for each parameter.
Uses Sokal’s self-consistent window method (Behroozi 2025): τ = 1 + 2 Σ ρ(k), truncated at k > 5τ. Takes the max of standard and absolute-deviation autocorrelation times for a conservative estimate.
- Returns:
Keys: parameter names. Values: ESS (float). ESS = N / τ, where N is the total number of samples and τ is the integrated autocorrelation time.
- Return type:
Notes
ESS measures the number of independent samples. Low ESS (< 100 for typical analyses) indicates poor mixing. The threshold N > 5τ (equivalently ESS > N/5) indicates adequate sampling for most purposes.
Examples
>>> ess = result.effective_sample_size() >>> print(f"Stellar mass ESS: {ess['stellar_mass']:.0f}") >>> if ess["stellar_mass"] < 100: ... print("Warning: low ESS, may need more samples")
- equivalent_widths(window_aa: float = 20.0, continuum_width_aa: float = 50.0) dict[str, tuple[float, float, float]][source]¶
Rest-frame emission line equivalent widths from posterior samples.
For each emission line, predicts the rest-frame SED for each posterior sample (or the MAP point estimate) using the attached forward model and integrates the line flux relative to the local continuum estimated from sidebands flanking the line. Sign convention follows
tengri.analysis.diagnostics.spectral.equivalent_width(): positive EW for emission, negative for absorption.- Parameters:
- Returns:
{line_name: (median_EW, lo_68, hi_68)}in [Angstrom]. For MAP results, all three values coincide.- Return type:
- Raises:
ValueError – If
eline_fluxes/eline_wavelengthsare unavailable, or if no_modelis attached to compute the continuum.
Notes
The continuum is estimated locally per line from the model-predicted rest-frame SED, not from a precomputed continuum-only grid. The sideband choice therefore must avoid contamination from neighboring emission lines; defaults are tuned for optical BPT lines.
Examples
ew = result.equivalent_widths() ha_med, ha_lo, ha_hi = ew["Halpha"]
- property fixed_values: dict¶
Fixed parameter values actually used by this fit (#2296).
Returns a dict of parameter name → pinned value for every parameter the spec declared Fixed. Use this for display/diagnostics;
paramsandsamplescarry free parameters only and are safe to feed back intomodel.predict(...).When this posterior carries a
_fitterback-reference (set bymodel.fit(...)/fitter.run(...)), the values come fromfitter._fixed_values– the spec’s declared values merged with anyFitter(params_override=...)re-pin (#1329), which is the sanctioned way to fit at a different Fixed value for one fit. Reading straight offself._model.specinstead would silently report the spec’s original value even when the fit actually ran at the override. Falls back to the spec when there is no fitter (a hand-builtPosterior).Under ``profile_mass`` (#2296):
fitter.specis the WORKING spec, which pins the mass parameter Fixed at an analytic placeholder – an internal re-pin, not something the user’s own model (self._model.spec) declared Fixed at all (the mass is free there).finalize_profile_masswrites the real, analytically profiled mass intoparams/samples, so without filtering, the same parameter would appear in BOTHparams(the real value) andfixed_values(the stale placeholder) – and worse, a caller checkingname in posterior.fixed_valuesto decide “is this Fixed on the user’s model” would get the wrong answer. Keep only the names that are actually Fixed onself._model.spec.- Returns:
Fixed parameter name → value. Empty dict if the posterior has no model and no fitter (hand-built posteriors).
- Return type:
- property free_names: tuple[str, ...] | None¶
Parameters the sampler moved, or
Nonewhen the posterior has no model.samplesholds every parameter the forward model consumes: theFixedones ride along as constant arrays (Fitter._to_physicalbroadcasts each pinned value across the draws), so a zero-variance column is evidence of a dead sampler only when it belongs to a free parameter. The model’s spec is the record of which names were free; a hand-built posterior without_modelcannot tell and getsNone(#2087).spec.free_paramsexcludes the stochastic-SFH field latent by design: it rides under the sampler’s keypsd_xi(republished assfh_field_xibyFitter._to_physical), not as a named distribution (seeParameters.n_latent). A frozen field is exactly as dead as a frozen named parameter, so when the spec is stochastic andpsd_xiis present insamples, it is appended here too.A posterior loaded from disk has no model, but
save()writes the names into the file andload()restores them into_free_names, so a reloaded real fit judges the same columns the live one did instead of re-creating the #2087 false positive. A file written before that attribute existed carries no names and still loads, with every column checked as before.
- information(params=None)[source]¶
How much of this posterior the data measured, mode by mode.
A flexible model always returns a posterior; this reports how much of it the data determined and how much is the prior reflected back.
- Parameters:
params (dict of str to float, optional) – Point to expand around, in physical units. Default
Noneuses this fit’s own point estimate.- Returns:
n_eff, per-mode shrinkage, and the per-parameter attribution.print(info.summary())is the intended first look.- Return type:
- Warns:
RuntimeWarning – If the expansion point is not a mode, in which case the curvature is not the posterior precision and
n_effmeans nothing. This fires more often than expected: on a 25-parameter field model an under-converged MAP reportedn_eff17.6 where the converged fit gives 4.9.
See also
tengri.parameter_informationthe same measurement as a free function.
Notes
Costs one dense Hessian of the log-posterior, i.e. \(O(D)\) gradient evaluations. Not JIT-compatible; call it on a finished fit.
Examples
>>> post = model.fit(data, noise, method="map") >>> print(post.information().summary())
- line_fluxes() dict[str, tuple[float, float, float]][source]¶
Emission line flux posterior summaries.
Returns median and 68% credible interval for each emission line.
- Returns:
{line_name: (median, lo_68, hi_68)}for each emission line. Flux units match the input data [erg/s/cm²]. For MAP results, all three values are the same (single-point estimate).- Return type:
- Raises:
ValueError – If no emission line fluxes are available. Set
eline_mode="marginalized"or"fitted"inSpectroscopyto enable.
Notes
Each line’s credible interval is computed as the 16th, 50th, and 84th percentiles of the posterior samples. For single samples (MAP), all three values coincide.
Examples
fluxes = result.line_fluxes() ha_median, ha_lo, ha_hi = fluxes["Halpha"]
- classmethod load(path: str, model=None) Posterior[source]¶
Load a Posterior from an HDF5 file.
- Parameters:
- Returns:
Loaded posterior with all attributes restored.
- Return type:
Notes
Reads HDF5 file saved by
save(). The_fitterback-reference is not restored (it is runtime-only). To userefine()orvalidate(), set the_fitterattribute manually or reload usingmodel.fit(...). Providemodelto enable derived quantity computation.Examples
>>> result = Posterior.load("posterior_result.h5", model=model) >>> print(result.summary_table()) >>> result.properties["stellar_mass"] # requires ``model``
- observables(filters=None, n_draws=None, approx=False, key=None, chunk_size=64, *, fast=<unset>)[source]¶
Photometry for every posterior draw, the arrays an SED plot needs.
Contract §3, exact by default. The default path integrates the model SED through the filters with no approximation, per draw.
approx=Trueopts into the lean build-time path (theapprox=LUT the model was built with, if any), much faster, and an approximation. The keyword carries the same name as the build-time one because it selects exactly that object; it was spelledfastuntil 2026-08.- Parameters:
filters (sequence of str or FilterCurve, or Photometry, optional) – Bands to integrate, filter names (
["jwst_f356w", ...]), curves, or a prebuiltPhotometry. Accepts exactly whatPrediction.photometry()accepts. Defaults to the ones the model was built with.n_draws (int, optional) – Thin to this many draws (resampled with replacement) before evaluating.
Noneuses every draw, which for a large posterior is exactly the memory problemvmap_chunked()exists to bound, so it is chunked either way.approx (bool, default False) – Route through the lean
predict_photometry(whatever build-timeapprox=the model carries) instead of the exact projector. On a model built without one this is a no-op, not an error, the lean surface is exact there.key (PRNGKey, optional) – Used only when
n_drawsis given. Defaults toPRNGKey(0).chunk_size (int, default 64) – Draws per compiled kernel.
fast (bool, optional) – Deprecated spelling of approx. Removed in v1.0.
- Returns:
Observed-frame flux density per draw per band, F_nu [erg/s/cm^2/Hz]. For a MAP fit (no samples), shape
(1, n_filters).- Return type:
ndarray, shape (n_draws, n_filters)
- Raises:
RuntimeError – If no model is attached.
Notes
JIT-compatible: no (drives compilation internally). The per-draw kernel it maps is jitted.
Examples
>>> bands = post.observables(n_draws=200) # exact >>> lo, med, hi = np.percentile(bands, [16, 50, 84], axis=0)
- plot_corner(params=None, truths=None, figsize=None, color='C0', fig=None, axes=None, label=None)[source]¶
Plot corner (triangle) plot of posterior distributions.
- Parameters:
params (list of str, optional) – Parameter names to include. Defaults to all scalar physical params. Automatically excludes
psd_xi(latent field) and constant parameters.truths (dict, optional) – True values to mark with dashed lines. Keys should match parameter names.
figsize (tuple, optional) – Figure size (width, height). Default: auto-scaled.
color (str) – Color for this posterior’s contours and histograms.
fig (matplotlib Figure, ndarray of Axes, optional) – If provided, overlay on existing corner plot (for comparing posteriors).
axes (matplotlib Figure, ndarray of Axes, optional) – If provided, overlay on existing corner plot (for comparing posteriors).
label (str, optional) – Legend label for this posterior (appears in legend on diagonal).
- Returns:
fig – The corner plot figure.
- Return type:
matplotlib Figure
Notes
Creates an N×N triangle plot (lower triangle only). Diagonal shows 1D marginal distributions with KDE overlay and quantile lines. Off-diagonal shows 2D histograms with credible region contours at 68% and 95%. Includes derived quantities (stellar_mass, sfr_100myr, sfr_10myr) if
_modelis available. Derived quantities are plotted in log10 space.Examples
>>> fig = result.plot_corner(color="C0", label="VI") >>> fig = result_mcmc.plot_corner(fig=fig, axes=fig.axes, color="C1", label="MCMC") >>> plt.show()
- plot_sed(n_draws=200, wave_range=(1000, 30000), ax=None)[source]¶
Plot posterior predictive SED with credible interval.
Draws
n_drawsparameter samples from the posterior, computes the rest-frame SED for each, and shades the 16th–84th percentile band around the median.- Parameters:
- Returns:
fig – The SED plot figure.
- Return type:
matplotlib Figure
Notes
Plots λ F_λ (rest-frame spectral energy density) normalized at 5500 Å. For MAP results, shows the single best-fit SED. For sampling methods, draws n_draws random samples and computes percentiles of the SED over those draws. Requires
_modelto be available (set bymodel.fit()). Uses log-log axes for visibility across wavelength range.Examples
>>> fig = result.plot_sed(n_draws=500, wave_range=(1000, 10000)) >>> plt.show()
- plot_sfh(n_draws=200, ax=None)[source]¶
Plot posterior SFH with credible interval.
- Parameters:
n_draws (int) – Number of posterior draws. Ignored for MAP (plots single SFH).
ax (matplotlib Axes, optional) – Axes to plot on. Creates new figure if None.
- Returns:
fig – The SFH plot figure.
- Return type:
matplotlib Figure
Notes
Plots both the stochastic SFH (burst component) and smooth component. For MAP: shows single best-fit SFH (both stochastic and smooth). For sampling: draws n_draws random samples and computes 16th–84th percentile bands. X-axis: lookback time [Gyr]. Y-axis: SFR [Msun/yr]. Requires
_modelto be available (set bymodel.fit()).Examples
>>> fig = result.plot_sfh(n_draws=500) >>> plt.show()
- pointwise_log_likelihood(n_draws: int | None = None, key=None)[source]¶
Log-likelihood of every data point under every posterior draw.
- Parameters:
n_draws (int, optional) – Number of draws to use. Default: all.
key (jax PRNG key, optional) – Selects the subset when
n_drawsis given.
- Returns:
Input of
tengri.inference.waic(),tengri.inference.loo()andtengri.inference.compare_models().- Return type:
ndarray, shape (n_draws, n_points)
- Raises:
ValueError – If the posterior has no draws or no fitter (a reloaded or hand-built posterior), or the likelihood does not factorize over data points.
Notes
See
tengri.inference.predictive.pointwise_log_likelihood().
- posterior_predictive(data: Array, noise: Array, n_samples: int | None = None, key=None) dict[str, Array][source]¶
Posterior predictive predictions, residuals, and chi^2 distribution.
Pushes posterior draws (or the MAP point estimate) through the attached forward model’s
predict_photometryand reports per-draw predictions, standardized residuals, and a chi^2 distribution against the supplied data + noise.- Parameters:
data (array_like, shape (n_obs,)) – Observed data the posterior was conditioned on. Same units as
predict_photometry’s output.noise (array_like, shape (n_obs,)) – Per-observation 1-sigma uncertainty (Gaussian).
n_samples (int, optional) – How many posterior draws to evaluate.
None(default) uses every available draw; for MAP results this is implicitly 1. For sampling results, draws are selected viaresample()(with replacement) usingkey.key (PRNGKey, optional) – JAX PRNG key for resampling. If
None, defaults tojax.random.PRNGKey(0).
- Returns:
predictions: shape(N, n_obs),residuals:(data - prediction) / noiseof shape(N, n_obs),chi2: per-draw \(\chi^2 = \sum_i r_i^2\), shape(N,),chi2_median,chi2_lo,chi2_hi: 16/50/84 percentiles of the chi^2 distribution (scalars).Nis 1 for MAP, otherwisen_samples(or the full chain length ifn_samples is None).- Return type:
- Raises:
ValueError – If no
_modelis attached.
Notes
This is a deterministic posterior predictive (no extra noise realization per draw). For replicated PPCs that draw observation noise per sample, layer
noise * jax.random.normalon top ofpredictions.
- property properties: PosteriorProperties¶
The property catalog, lifted over the sample axis.
Contract §1, same names, more axes. Every property the model provides is here under exactly the name a
Predictionuses; a scalar becomes(n_samples,). Values are computed lazily per name and evaluated in memory-bounded chunks, so a large posterior does not OOM.- Returns:
Dict-like:
[name],keys(),to_dict(names=), plus the sample-axis verbci(name, level=0.68).- Return type:
PosteriorProperties
Examples
>>> post.properties["stellar_mass"].shape (4000,) >>> post.stellar_mass.shape # attribute sugar (4000,) >>> lo, med, hi = post.properties.ci("stellar_mass")
See also
PosteriorPropertiesthe catalog object.
tengri.vmap_chunkedthe memory-bounded evaluation used underneath.
- refine(method: str, **kwargs)[source]¶
Re-run inference from this result using a different method.
Requires that this Posterior was produced by
model.fit()orfitter.run(), both set the._fitterback-reference.- Parameters:
method (str) – Any canonical method name accepted by
Fitter.run(). E.g."mcmc_raytrace","mcmc_nuts","vi".**kwargs – Passed to
Fitter.run()(e.g.n_steps,n_warmup).
- Returns:
New result warm-started from this posterior.
- Return type:
- Raises:
RuntimeError – If
._fitteris not set (Posterior created outside model.fit/fitter.run).
Notes
Warm-starts the new inference from this posterior’s parameters or samples. Common use cases: VI → MCMC refinement (exact inference on top of variational fit), MCMC → different sampler (e.g. raytrace → nuts), or quick method → expensive method for publication.
Examples
>>> result_vi = model.fit(flux, noise) >>> result_exact = result_vi.refine("mcmc_raytrace", n_steps=1000)
- resample(key, n=1) dict[source]¶
Resample from posterior with replacement.
- Parameters:
key (PRNGKey) – JAX random key.
n (int) – Number of resamples.
- Returns:
If n=1: parameter name → scalar value. If n>1: parameter name → array of shape (n, …).
- Return type:
Notes
For MAP results, returns the point estimate (repeated n times if n > 1). For sampling results, draws n indices uniformly from [0, n_samples) with replacement. Use for Monte Carlo propagation of posterior uncertainty through forward models.
Examples
>>> key = jax.random.PRNGKey(0) >>> sample = result.resample(key, n=1) # Single draw >>> samples = result.resample(key, n=100) # 100 resamples >>> sfhs = [model.predict_sfh(samples) for ...] # Propagate
- rhat(exclude_prefixes: tuple[str, ...] = ('psd_xi',)) dict[str, float][source]¶
Per-parameter split-\(\hat R\) (Gelman-Rubin).
Splits each parameter chain in half and computes the classical \(\hat R = \sqrt{\hat V / W}\) against the two halves. \(\hat R \approx 1.0\) indicates convergence; \(\hat R > 1.01\) (Vehtari+2021) suggests failure to mix.
- Parameters:
exclude_prefixes (tuple of str, optional) – Parameter name prefixes to skip. Default skips
psd_xi(GP latent vector, high-D, not informative per-component).- Returns:
Parameter name → \(\hat R\). Static (zero-variance) and excluded parameters are dropped.
- Return type:
- Raises:
ValueError – If this is a MAP result (no samples to split).
See also
tengri.analysis.diagnostics.autocorrelation.split_rhatUnderlying implementation.
Examples
>>> rh = result.rhat() >>> bad = {k: v for k, v in rh.items() if v > 1.05} >>> if bad: ... print(f"Unconverged: {bad}")
- property runtime_values: dict¶
This galaxy’s own values of the model’s runtime keys (its redshift).
A model that reads its redshift at call time evaluates every derived quantity at the redshift of the galaxy that was fit, not at the placeholder it was built at. A catalog fit records each galaxy’s value here; a single fit reads it from its fitter’s
params_override.- Returns:
Runtime key -> value [dimensionless for redshift]. Empty when the model reads nothing at call time.
- Return type:
- save(path: str) None[source]¶
Save posterior to HDF5 file.
Serializes samples, params, diagnostics, loss history, and emission line data. Model and fitter references are NOT saved (they are non-serializable runtime objects).
- Parameters:
path (str) – Output HDF5 file path.
- Return type:
None
Notes
Saves to HDF5 format with groups:
samples: posterior samples (if available)params: best-fit or MAP parametersruntime_values: this galaxy’s runtime values, e.g. its redshift (if any); restored into_runtime_valuesbyload()loss_history: optimization loss over iterations (if available)diagnostics: method-specific convergence metricseline: emission line fluxes, covariances, names, wavelengths
and root attributes
method,wall_time_s,log_evidence(when set) andfree_names(when the posterior knows which parameters were free), the last so a reload withoutmodel=still restricts the dead-fit check to them (#2087).Use
load()to restore the Posterior from disk.Examples
>>> result.save("posterior_result.h5") >>> later_result = Posterior.load("posterior_result.h5")
- sed_components(wavelength=None) dict[source]¶
Per-component SEDs across posterior draws.
Decomposes the model prediction into stellar (attenuated / intrinsic) + nebular + shock + dust IR + AGN + radio + X-ray for every posterior sample (or the MAP point estimate) by running the orchestrator pipeline per draw and reading the per-component SED arrays each adapter publishes into
state.derived.- Parameters:
wavelength (array_like, optional) – Ignored, kept for backwards compatibility. The orchestrator uses the model’s SSP wavelength grid; pass-through to a different grid is no longer supported here. Interpolate the returned arrays externally if a different grid is needed.
- Returns:
Keys:
wavelengthplus the entries ofPosterior._COMPONENT_KEYS(sed_total,sed_attenuated,sed_intrinsic,sed_nebular,sed_shock,sed_dust_ir,sed_agn,sed_agn_disc,sed_agn_torus,sed_agn_lines(nlr+blr+feii),sed_agn_lines_attenuated,sed_agn_polar,sed_radio,sed_xray). Thesed_agn_*sub-block keys are zeros for a non-composable (monolithic) AGN model or no AGN component at all. Each component array has shape(n_wave,)for MAP and(n_samples, n_wave)for sampling.- Return type:
- Raises:
ValueError – If no
_modelis attached.
Notes
Reads the orchestrator’s per-component publications:
sed_dust_attenuated(stellar post-attenuation),sed_dust_ir,sed_nebular,sed_shock,sed_agn,sed_radio,sed_xray, each adapter publishes its own contribution intostate.derived.sed_totalis the accumulatedstate.sed_intrinsicafter the chain runs;sed_intrinsic(stellar pre-attenuation) is reconstructed from the publishedlnu_agecube viasum(lnu_age, axis=0).For Posterior draws the orchestrator pass runs once per sample, compiled in chunks of
_DRAW_CHUNKdraws (bounded peak memory).Examples
>>> comp = result.sed_components() >>> agn_to_total = comp["sed_agn"] / comp["sed_total"]
- spectra(wave_obs=None, n_draws=None, approx=False, key=None, chunk_size=64, *, fast=<unset>)[source]¶
Model spectrum for every posterior draw, the other half of an SED plot.
The spectroscopic counterpart of
observables(), and the posterior lift ofPrediction.spectrum(). Contract §3, exact by default: the spectrum is LSF-convolved and calibrated exactly as the likelihood sees it, so a posterior band and a posterior spectrum answer the same question as the fit did.approx=Trueopts into the build-timeapprox=path, same word at both ends, because it is the same object.- Parameters:
wave_obs (array_like, shape (n_wave,), optional) – Observed-frame wavelength grid [Angstrom]. Defaults to the instrument grid the model was built with.
n_draws (int, optional) – Thin to this many draws (resampled with replacement).
Noneuses every draw, chunked either way.approx (bool, default False) – Route through the lean
predict_spectrum(build-timeSpectrumPrecomp) instead of the exact projector.key (PRNGKey, optional) – Used only when
n_drawsis given. Defaults toPRNGKey(0).chunk_size (int, default 64) – Draws per compiled kernel.
fast (bool, optional) – Deprecated spelling of approx. Removed in v1.0.
- Returns:
Observed-frame flux density per draw, F_nu [erg/s/cm^2/Hz]. For a MAP fit (no samples), shape
(1, n_wave).- Return type:
ndarray, shape (n_draws, n_wave)
- Raises:
RuntimeError – If no model is attached, or the model has no spectroscopy and no
wave_obswas given.TypeError – If both approx and the deprecated fast are passed with contradictory values.
Notes
JIT-compatible: no (drives compilation internally). The per-draw kernel it maps is jitted.
Examples
>>> spec = post.spectra(n_draws=200) >>> lo, med, hi = np.percentile(spec, [16, 50, 84], axis=0)
- stats() dict[source]¶
Median and 68% credible intervals for all parameters.
- Returns:
Keys: parameter names (excluding
"psd_xi"latent field). Values: dict with"median","lo_68","hi_68"for sampling methods, or"value"for MAP.- Return type:
Notes
For MCMC and VI results, credible intervals are 16th and 84th percentiles. For MAP results, returns point estimates without intervals. Does not include high-dimensional latent fields (
psd_xi).Examples
>>> stats = result.stats() >>> print(stats["stellar_mass"]) {"median": 10.5, "lo_68": 10.3, "hi_68": 10.7} # sampling # or {"value": 10.5} # MAP
- summary() None[source]¶
Print the per-parameter median ± 68% credible interval table.
Convenience wrapper around
summary_table()that prints directly, typically the first call after a fit:posterior = fitter.run("nuts") posterior.summary()
- summary_str() str[source]¶
Return the summary as a string (parity with Parameters.summary_str).
Same content as
summary_table(), alias for naming consistency across the discovery API (tengri.Parameters.summary_strreturns the same kind of string).
- summary_table() str[source]¶
Return a formatted string table of parameter summaries.
For MAP: shows parameter values. For sampling: shows median with 68% credible intervals and ESS.
- Returns:
Formatted table string with method, sample count, wall time, parameter statistics, and diagnostics.
- Return type:
Notes
The table includes:
Method name and number of samples (or
"MAP")Wall-clock time in seconds
Parameter names with median and credible intervals
Effective sample size (ESS) for sampling methods
Method-specific diagnostics (accept rate, divergences, loss, etc.)
Log evidence (if available from nested sampling)
Examples
>>> print(result.summary_table()) Posterior method: mcmc_nuts samples: 1000 wall_time: 5.2s ───────────────────────────────────────────────────────────── Parameter Median 16% 84% ESS ───────────────────────────────────────────────────────────── ...
- to_arviz()[source]¶
Convert to ArviZ InferenceData for diagnostics.
- Returns:
ArviZ InferenceData object with posterior group containing all scalar parameters.
- Return type:
az.InferenceData
Notes
Requires arviz to be installed:
pip install arviz. High-dimensional latent fields (psd_xi) are excluded. Samples are reshaped to (1, n_samples) format (1 chain). Use ArviZ tools for advanced visualization and diagnostics (forest plots, rank plots, etc.).Examples
>>> idata = result.to_arviz() >>> az.plot_forest(idata) >>> az.summary(idata)
- to_param_spec()[source]¶
Convert posterior to an empirical Parameters.
For MAP: all parameters become Fixed at their best-fit values. For sampling: fit clipped Gaussian to each marginal.
- Returns:
New Parameters object with priors fit to the posterior.
- Return type:
Notes
For MAP results, all parameters become
Fixedat the MAP value. For sampling methods, each parameter gets aGaussianprior with:mean: median of samples
sigma: standard deviation of samples
bounds: [min, max] from samples (clipping)
Inherits
stochasticandn_gridsettings from the original model.Examples
>>> posterior_params = result.to_param_spec() >>> # Use as starting point for next fit >>> refined = fitter.run("mcmc_nuts", init_from=posterior_params)
- validate(n_samples: int = 200, **kwargs)[source]¶
Run a short MCMC check and return a validation summary.
Compares this posterior’s samples against a fresh MCMC run from the posterior’s MAP estimate. Runs
n_samplesof Ray Tracing (or NUTS for D≤20), then computes the marginal overlap between this posterior and the MCMC check posterior for each parameter.- Parameters:
n_samples (int) – Number of MCMC samples. Default 200 (quick sanity check).
**kwargs – Forwarded to the MCMC run.
- Returns:
Keys:
"mcmc_result"(Posterior from MCMC check),"overlap"(dict of float per parameter, 1.0 = perfect overlap, 0.0 = no overlap),"passed"(bool, True when all overlaps > 0.5).- Return type:
- Raises:
RuntimeError – If
._fitteris not set.
Notes
Validation checks whether a quick MCMC run agrees with the current posterior (typically from VI or MAP). High overlap (> 0.5) indicates the method is reliable; low overlap suggests the posterior may be biased or misspecified. Overlap is computed as the histogram intersection at each parameter. For sampling methods (VI, geoVI), validates the approximate posterior. For MCMC methods, serves as a sanity check for chain convergence.
Examples
>>> result_vi = model.fit(flux, noise, method="vi") >>> val = result_vi.validate(n_samples=500) >>> print(f"Validation passed: {val['passed']}") >>> for param, ov in val["overlap"].items(): ... print(f"{param}: overlap={ov:.3f}")
Fitter¶
- class tengri.Fitter(model, data=None, noise=None, data_type=None, data_mask=None, presence=None, line_flux_data=None, calibration_marginalize=False, cal_n_poly=3, cal_prior_sigma=1.0, eline_marginalize=None, eline_prior_type=None, likelihood=None, auto_protocol_likelihood=True, use_components=False, compile_modes=None, cache=None, approx='auto', params_override=None, profile_mass: bool | str = 'auto', extra_log_prior: Callable | None = None, line_model_sigma: bool = True)[source]¶
Bases:
objectInference engine for differentiable SED fitting with flexible method dispatch.
Separates inference strategy from the forward model by building a loss function from the SEDModel’s predictions and the Parameters’ priors, then running the chosen optimizer/sampler. Supports point estimation (MAP, Laplace), gradient-free and gradient-based sampling (ESS, NUTS, Ray Tracing, MCMC), variational inference (geoVI, MGVI), and nested sampling (NSS) via a unified
run(method)interface.- Parameters:
model (SEDModel) – Configured forward model with
spec(Parameters),observation(Photometry/Spectroscopy/etc.), and predictor methods.data (array_like, shape (n_data,)) – Observed data (photometric fluxes or spectra). Units match the model’s
observationconfiguration. [erg/s/cm²/Hz] for photometry.noise (array_like, shape (n_data,)) – 1-sigma measurement uncertainties. Same shape and units as
data.data_type (str or None) – Data type indicator:
"photometry","spectroscopy", or"joint". IfNone(default), inferred frommodel.observation. Explicit values override inference.data_mask (array_like or None) – Optional per-datum censoring flags (CIGALE-style limits):
0= detected (Gaussian term),1= upper limit (ln Φ((limit − model)/σ)),-1= lower limit (ln Φ((model − limit)/σ)). The correspondingdataentry carries the limit value. DefaultNone(all detected). Boolean arrays are rejected:Truewould silently be read as “upper limit”, the opposite of the include/exclude semantics a boolean mask suggests. To exclude a datum, drop it fromdataandnoise(or inflate itsnoise).presence (array_like or None) – Optional exact 0/1 presence of the photometric bands:
0marks a band absent and it contributes nothing to the likelihood or its gradient. The length is the number of photometric bands:len(data)fordata_type="photometry", andmodel.observation.n_data_photfor"joint"data, where it masks the photometric block and the spectrum pixels stay present. Spectroscopy has no per-pixel presence here. Store an absent band as zero flux and zero error, or as any finite placeholder. A length that does not match raisesValueErrorstating the expected length. DefaultNone(all bands present).calibration_marginalize (bool, optional) – If
True, analytically marginalize over spectroscopic calibration polynomial coefficients (Chebyshev order 1–cal_n_poly) when computing spectroscopic log-likelihood. Only applies whendata_type∈ {"spectroscopy","joint"}. Follows Prospector (Johnson et al. 2021). DefaultFalse.cal_n_poly (int, optional) – Number of Chebyshev polynomial coefficients for calibration marginalization (order 1 through
cal_n_poly). Default3.cal_prior_sigma (float, optional) – Standard deviation of Gaussian prior on each calibration coefficient. Default
1.0.eline_marginalize (bool or None, optional) – Whether to analytically marginalize emission line amplitudes.
None(default) auto-detects from the model’sSpectroscopyconfig (checkseline_mode == "marginalized").eline_prior_type (str or None, optional) – Prior type for emission line marginalization:
"flat"(uniform) or"cloudy"(grid-interpolated from Cloudy models).Noneauto-detects fromSpectroscopy.eline_prior_type. DefaultNone.compile_modes (tuple[str, ...] or str or None, optional) –
Control background JIT compilation during
__init__. Accepted values:None(default) → no background compile; firstrun()compiles lazily."auto"→ inspectspec.stochasticanddata_typeto select sensible defaults: stochastic →("linear_resample", "nonlinear_update")(VI modes); non-stochastic photometry →("mcmc_nuts",); otherwise →("mcmc_nuts",).explicit
tuple[str, ...](e.g.,("mcmc_nuts",)) → queue exactly those modes in the background thread.explicit
str(e.g.,"mcmc_nuts") → wrap into a 1-tuple("mcmc_nuts",).
Compile modes are passed to
compile(modes=...)and determine which inference engines are pre-JIT-compiled before the firstrun()call. Seecompile()docstring for valid mode names.params_override (dict or None, optional) – The sanctioned way to pin a Fixed parameter at a different value for this one fit (e.g. a per-galaxy redshift), without rebuilding the model (#1329). Validated at construction: every key must name a parameter the spec declared
Fixed(a free parameter raisesValueError, naming the free parameters instead). This is NOT the same channel as aparamsdict handed to a predict surface – those refuse a Fixed key outright (#2296) and never accept an override;params_overrideis the one place a Fixed value can be re-pinned, and it is checked, not merged silently. DefaultNone(use the spec’s declared Fixed values unchanged).profile_mass (bool or "auto", optional) – Analytically marginalize the total-stellar-mass amplitude (the free parameter named
*_log_total_mass) instead of sampling it, so inference runs on the remainingD - 1parameters and the mass is drawn from its exact conditional posterior afterward (or set to its conditional mode formethod="map"). Supports photometry, spectroscopy, or joint photometry + spectroscopy data with a Gaussian likelihood, exactly one free*_log_total_massparameter with a bounded-support prior, and data that is numerically linear in that parameter; seetengri.inference.mass_profile.configure_profile_mass()for the full guard list and the marginalization math. Default"auto": engages only when every guard passes, otherwise falls back to ordinary sampling with onelogging.INFOline naming the reason.TrueraisesValueErrornaming the first failed guard instead of falling back;Falsedisables profiling unconditionally. The resolved choice and reason are always recorded inPosterior.diagnostics["profile_mass_resolved"]/["profile_mass_reason"].extra_log_prior (callable or None, optional) –
Opt-in extra log-prior term,
extra_log_prior(params, state) -> scalar, whereparamsis the resolved physical parameter dict (free + fixed, mirrors merged) andstateisself.model.predict_state(params)(aForwardState). Added to the physical-space log-prior built bybuild_logprior_fn()(used by nested sampling / evidence computation, and available to any caller viafitter._build_logprior_fn()). Must be JIT/grad-safe: pure, no Python-level branching on traced values. DefaultNone(no extra term; the returned log-prior is bit-identical to before this parameter existed). Example, the AGNfitter energy-balance prior:def extra(params, state): from tengri.agn.priors import prior_energy_balance return prior_energy_balance( l_gal_att=state.derived["L_absorbed"], l_sb_emit=state.derived["L_ir"], mode="restrictive", )
passed as
Fitter(model, data, noise, extra_log_prior=extra). (The derived-key names above are illustrative; verify them against the specific model’s publishedstate.derivedkeys.)line_model_sigma (bool, optional) – Score measured line fluxes with the nebular model’s own per-line error (
sigma_eff = hypot(sigma_obs, f_cal |F_model|, s_line |F_model|), theln sigma_effterm kept). Active only when the backend publishespublished_line_model_sigmaand it is nonzero for the fitted lines.Falsescores against the observation error alone, as before this option existed. Applies to line fluxes only: line ratios and spectral indices are not given a model error, because the per-line errors are correlated within a sub-network (for example [O III] 4959/5007 is fixed by atomic physics) and upstream publishes no covariance, so quadrature propagation would invent errors. DefaultTrue.
- Returns:
Fitter instance with loss function compiled and ready for inference.
- Return type:
- Variables:
model (SEDModel) – Reference to the input forward model.
data (ndarray, shape (n_data,)) – Input data as JAX array.
noise (ndarray, shape (n_data,)) – Input noise as JAX array.
data_type (str) – Resolved data type (
"photometry","spectroscopy","joint").spec (Parameters) – Reference to
model.spec.
Notes
JIT-compatibility: Methods in this class are not JIT-compatible because they perform Python-level branching on method names and manage resources (thread compilation, caching). The returned loss function and sampler engines are fully JIT-compiled and reusable across galaxies.
Background compilation: Background compilation is now opt-in via the
compile_modesparameter (defaultNone= no background thread). The firstrun()call will compile lazily. Setcompile_modes="auto"orcompile_modes=("mcmc_nuts",)to spawn a daemon thread and pre-compile specified inference modes beforerun()is called (typically <1s if warm, or the full compile time on cold XLA). SetTENGRI_NO_BACKGROUND_COMPILE=1in the environment to disable even whencompile_modesis set (test environments).Engine caching: Compiled engines are cached on the Model object so that multiple Fitters created with the same Model but different data reuse the same XLA programs. Cache key depends on data_type, dimensionality, free parameter names, and feature flags (emission lines, calibration).
References
[tengri.Fitter-1]B. D. Johnson et al., “Prospector: Stellar Population Inference from Spectra and SEDs,” ApJS, 254, 22 (2021). arXiv:2012.01426. https://doi.org/10.3847/1538-4365/abef67
Examples
Fit a single galaxy with the default method,
"mcmc_nuts_fast". The fitter takes aForwardModel, so wrap the SED chain first:>>> from tengri import Fitter, ForwardModel, SEDModel >>> sed = SEDModel.build(ssp_data=ssp, observation=obs, **config) >>> forward = ForwardModel.build(sed=sed, observation=obs) >>> data = jnp.array([1.2, 0.8, 0.5]) # photometric fluxes >>> noise = jnp.array([0.1, 0.08, 0.06]) >>> fitter = Fitter(forward, data, noise) >>> result = fitter.run("vi", n_samples=100) >>> print(result.params)
forward.fit(data, noise, method="vi", n_samples=100)is the same fit in one line. Build theFitteryourself when you want to keep it, warm starts, a reused compilation cache, or several backends over one model:>>> result_map = fitter.run("map", n_steps=1000) >>> result_mcmc = fitter.run( ... "mcmc_nuts", init_from=result_map, n_warmup=500 ... )
See the docstring of
run()for all available methods and their options.- compile(*, n_iterations=15, n_samples=3, n_posterior_samples=200, modes=('linear_resample', 'nonlinear_update'), mcmc_methods=(), n_warmup=300, n_burnin=100, n_mcmc_samples=100, nss=False, verbose=True)[source]¶
Pre-compile the JIT inference engine ahead of time.
Triggers XLA compilation for all specified modes so that subsequent
fitter.run()calls have zero compilation delay. Compiled programs are cached both in-memory (this session) and on disk (/tmp/tengri_jax_cache, survives restarts).- Parameters:
n_iterations (int) – Iteration count for the pre-compilation run. Changing
n_iterationsat run time does NOT trigger recompilation (the iteration count is a dynamic traced value).n_samples (int) – Compile for this sample count. Changing
n_samplesat run time DOES trigger recompilation (array shapes depend on it).n_posterior_samples (int) – Compile posterior draw for this many samples.
modes (tuple of str) – Which VI sample modes to pre-compile. Each mode compiles separately. Default covers MGVI + geoVI update (fastest). Add
"nonlinear_resample"for full geoVI (~56s extra).mcmc_methods (tuple of str) – MCMC methods to pre-compile. Supported values:
"nuts","hmc","dynamic_hmc","ghmc". Each call runs the full warmup + chain scan through JIT so the XLA disk cache is populated before the first user call. Afterfitter.compile(mcmc_methods=["nuts"]), a fresh kernel restart deserializes in <1s instead of ~23s.n_warmup (int) – Warmup steps used for the MCMC compilation run.
n_burnin (int) – Burn-in steps used for the MCMC compilation run.
n_mcmc_samples (int) – Sample steps used for the MCMC compilation run.
nss (bool) – Pre-compile the NSS (nested slice sampling) step and init functions. NSS has a ~10–15s cold compile on the first
fitter.run("nss")call; settingnss=Truemoves that cost to compile time.data_argsis traced so the compiled program is reused across galaxies with the same model configuration.verbose (bool) – Print compilation progress.
- Return type:
self
Notes
Compilation mechanics: Pre-compilation invokes
jax.jiton the forward model’s SED prediction and inference engines, storing compiled XLA programs to disk. Firstfitter.run()will skip XLA overhead by loading pre-compiled kernels. Typical times:"linear_resample"+"nonlinear_update"~3s; full modes ~60s; NUTS ~23s (once per unique model shape).MCMC cache key: The XLA program is keyed on
logdensity_fn_2argidentity,n_warmup,n_burnin,n_mcmc_samples, anduse_dense. Use the same values here as infitter.run()to guarantee a cache hit. Changing galaxy data does not invalidate the cache (data_argsis traced, not static).JIT-compatible: yes, internally calls JIT-compiled JAX functions.
Example
>>> fitter = Fitter(forward, data, noise) >>> fitter.compile() # ~3s for default VI modes >>> fitter.compile(mcmc_methods=["nuts"]) # ~23s, then instant restarts >>> fitter.compile(nss=True) # ~12s, then instant restarts >>> result = fitter.run("mcmc_nuts") # instant after compile >>> result = fitter.run("nss") # instant after compile
- compile_signature() tuple[source]¶
Return a hashable signature for cross-galaxy engine reuse.
Combines SEDModel’s compile_signature() with Fitter-specific parameters that affect the compiled inference engine. Two Fitters with matching signatures can share the same XLA-compiled engine, even if they reference different SEDModel instances (as long as those instances have the same compile_signature).
The signature does NOT include memory_mode, as it does not change the generated HLO graph, it only affects posterior-chunking behavior in the analysis layer (see _draw_jit_samples and _draw_nonlinear_jit_samples). Toggling memory_mode between “fast” and “low” reuses the same cached engine.
- Returns:
Hashable immutable signature suitable for keying into the module-level _SHARED_ENGINE_CACHE.
- Return type:
Notes
Used by _get_or_build_engine to enable cross-galaxy engine reuse in PopulationFitter and CatalogFitter. The signature is computed ONCE per Fitter construction and cached to avoid recomputation in tight loops.
- data_term_options() DataTermOptions[source]¶
Return the structural options the data term is built from.
- Returns:
The options read from this fitter’s resolved attributes.
- Return type:
DataTermOptions
- fit_batch(batch, *, method='mcmc_nuts_fast', key=None, verbose=True, **kwargs)[source]¶
Fit a batch of galaxies efficiently.
Creates a Fitter per galaxy, sharing the XLA compilation cache. The first galaxy pays compile cost; subsequent galaxies load from the persistent XLA cache (milliseconds each).
Works with any inference method, vi (default) gives the best speed. Also usable for hierarchical individual fits.
- Parameters:
batch (list of dict) – Each dict has “flux_obs” and “noise” arrays.
method (str) – Default
"mcmc_nuts_fast". Any method from run().key (PRNGKey, optional) – Random seed for sampling methods. Default:
jax.random.PRNGKey(42).verbose (bool) – Print progress. Default:
True.**kwargs – Passed to run() (n_iterations, n_samples, n_seeds, etc).
- Returns:
Inference results for each galaxy, in order.
- Return type:
Notes
Parallelization strategy:
For
method="map"with precomputed photometry: usesjax.vmapto fit all galaxies in a single JIT call (1-2s total).For MCMC methods with fixed SFH: uses
jax.vmap+ shared adaptation.Otherwise: sequential Fitter per galaxy (load from XLA cache).
Compilation caching: All Fitters share the same Model instance, enabling persistent XLA cache. After first galaxy, subsequent fits are 10-100× faster depending on method.
Native VI tuning: When
methodcontains"native"andn_seedsis not explicitly passed, automatically setsn_seeds=5for better convergence.Examples
Batch fit 100 galaxies:
>>> batch = [{"flux_obs": f, "noise": n} for f, n in zip(fluxes, noises)] >>> results = fitter.fit_batch(batch, method="vi") >>> # First: ~2s compile. Rest: ~2ms each. Total: ~0.2s per galaxy.
Warm-start from MAP:
>>> results_map = fitter.fit_batch(batch, method="map", n_steps=500) >>> results_vi = fitter.fit_batch(batch, method="vi", init_from=results_map)
- load_cache(path) None[source]¶
Load an adaptation cache previously written by
save_cache().Refuses to load if the spec fingerprint disagrees (different free-parameter set), to prevent silently using a stale cache.
- Parameters:
path (str or Path) – File written by
save_cache().- Return type:
None
- Raises:
ValueError – If the cache’s
spec_fingerprintdoes not match this Fitter’s model.
- prewarm(method: str = 'mcmc_nuts', *, n_chains: int | None = None, key=None, **kwargs)[source]¶
Pre-compile JIT kernels and populate the adaptation cache for
method.After this returns, a subsequent
run()call with the samemethodskips XLA compilation and sampler warmup window adaptation, only the actual sampling work remains.Concretely: runs the smallest meaningful inference (a few warmup steps + a handful of samples) to (1) compile every JIT’d kernel in the loss / sampler stack against the current data shape, and (2) write step size + mass matrix (or equivalent) into the per-model adaptation cache. The persistent XLA cache (
~/.cache/tengri_jax_cache) also captures the compile, so a fresh Python process sees a warm XLA cache too.- Parameters:
method (str, default
"mcmc_nuts") – Inference method to pre-warm. Any name accepted byrun().n_chains (int or None) – If set and greater than 1, also pre-compile the multichain
jax.vmappath forn_chainsso the second multichain call has zero compile latency. Only meaningful for backends that supportn_chains(NUTS / HMC / dHMC / GHMC / MCLMC / adjusted MCLMC / raytrace).key (jax.random.PRNGKey or None) – Optional seed. Default uses a fixed key, the pre-warm run is throwaway and its randomness does not affect the subsequent real fit.
**kwargs – Forwarded to the throwaway
run(), so the pre-warm can be matched to the fit it is warming. This matters more than it looks. A pre-warm only removes compile from a later fit if it compiles the same program, and for NUTS the program is keyed on the budget:adapt_chaintakesn_warmupas a static argument (it is thelax.scanlength) andsample_chaintraces against achain_keysarray of lengthn_burnin + n_samples. So a default pre-warm (n_samples=10,n_warmup=300) and a fit atn_warmup=600, n_samples=600compile four modules where the fit alone would compile two. Structural knobs are cheaper to match than budget ones:max_num_doublings,dense_mass_matrixandpreconditionchange the program without changing how much of it runs, whereas matchingn_warmup/n_samplesmeans the pre-warm does the fit’s own sampling work.
- Return type:
None
Examples
>>> from tengri.inference.fitter import Fitter >>> fitter = Fitter(forward, flux, noise, data_type="photometry") >>> fitter.prewarm(method="mcmc_nuts", n_chains=4) >>> posterior = fitter.run(method="mcmc_nuts", n_chains=4, n_samples=1000)
Notes
Pre-warming is soft: any exception raised during the throwaway call is swallowed so the real
run()surfaces the genuine error with a richer traceback. Callingprewarmredundantly is cheap both caches are short-circuited.
- run(method: str = 'mcmc_nuts_fast', *, init_from=None, key=None, allow_unvalidated: bool = False, **kwargs)[source]¶
Run inference using the specified method.
Dispatches to the underlying inference backend (variational, MCMC, point estimation, or nested sampling) and returns a
Posteriorobject with samples, diagnostics, and derived quantities.Hierarchical fits (
modelis a ForwardModel built withpopulation=PopulationSEDModel(...)) route throughtengri.PopulationFitterautomatically. No change in the user-facing call site.- Parameters:
method (str, optional) –
Inference method (case-sensitive). Default
"mcmc_nuts_fast".Variational Inference (VI)
"vi": geoVI via NIFTy (nonlinear, default for D>20)"vi_nonlinear": geoVI via NIFTy (alias ofvi)"vi_linear": MGVI via NIFTy (linearized Gaussian)"vi_nonlinear_fast": geoVI fast path (~35% faster, no logging)"vi_linear_fast": MGVI fast path (~35% faster, no logging)"native_vi_nonlinear": Native JAX geoVI (broken: segfaults on DPL/dense_basis photometry mocks, issue #231)"native_vi_linear": Native JAX MGVI (broken: same segfault)
MCMC Sampling
"mcmc_nuts": NUTS via BlackJAX (default for D≤20; exact posterior)"mcmc_raytrace": Ray Tracing (Behroozi 2025; O(1) gradient cost)"mcmc": Auto: NUTS (D≤20) or Ray Tracing (D>20)"mcmc_hmc": Standard HMC (fixed trajectory length)"mcmc_dynamic_hmc": Dynamic HMC (adaptive trajectory)"mcmc_chees": ChEES-HMC, one trajectory length learned from cross-chain statistics so the chains stay lock-step (experimental; measured inbench/reports/2026-08-30_chees_hmc.md)"mcmc_smc": Tempered Sequential Monte Carlo – a particle population annealed from the exact standardizedN(0, I)prior to the posterior, so it never starts at the MAP (experimental; measured inbench/reports/2026-08-31_smc_evaluation.md)"mcmc_ghmc": Generalized HMC (broken: R-hat ~ 2.5-3.1, ESS ~ 1 on D=6-8 mocks; MEADS adaptation did not fix it, seebench/reports/2026-08-30_ghmc_meads_adaptation.md)"mcmc_mclmc": MCLMC (broken: R-hat ~ 1.7, ESS ~ 1)"mcmc_adjusted_mclmc": MCLMC + Metropolis correction"mcmc_ess": Elliptical Slice Sampling (gradient-free)
Point Estimation & Approximations
"map": MAP optimization (L-BFGS by default; Adam/AdamW/SGD selectable)"laplace": Laplace approximation (Gaussian posterior at MAP)"pathfinder": L-BFGS trajectory + sequence of Gaussians (Zhang+2022)
Model Comparison (Bayesian Evidence)
"nss": Nested Slice Sampling (exact Z, D≤30)
Automatic Selection
"auto": NUTS (D≤20) or geoVI (D>20) based on dimensionality
init_from (Posterior, optional) – Previous inference result to use as warm-start initialization. The posterior mean is extracted and converted to unbounded space. Useful for refining results across different methods. Default
None.key (PRNGKey, optional) – JAX random key. Default
PRNGKey(42)for reproducibility. Ignored for deterministic methods ("map","laplace").allow_unvalidated (bool, optional) – Run a backend registered at
tier="broken", one that reports wrong answers or crashes in its own registry entry. DefaultFalse, which raisesBackendErrornaming the specific failure. Intended for benchmarking and backend development, not for science (#1287).prewarm (bool, optional) – JIT-compile the loss/gradient and the predict surface (
predict_photometry/predict_properties) before the fit loop, populating the persistent cache so the fit runs warm and post-fit posterior-predictive / derived-quantity exploration is already compiled. DefaultTrue; passFalsefor the previous lazy compile-on-first-call behavior. (The fit-time approximation policy is set withapprox=on theFitterconstructor /ForwardModel.fit(), not here.)**kwargs –
Method-specific keyword arguments passed to the underlying backend:
VI methods:
n_samples,n_kl_iter,tol_kl,sample_mode,verbose,mirror_samples.MCMC methods:
n_steps,n_warmup,thin,step_size,mass_matrix,adapt_step_size,verbose.MAP/Laplace:
n_steps,step_size,lr,verbose.Pathfinder:
n_steps,n_init,step_size,verbose.NSS:
n_live,n_batch,slice_width,verbose.
See backend docstrings for full option documentation.
- Returns:
Inference results object with attributes:
samples: dict or None, Posterior samples (None for MAP).params: dict, Best-fit or posterior mean parameters.method: str, Method used.diagnostics: dict, Convergence/quality metrics.log_evidence: float or None, ln Z [nats] of the exact data density, Gaussian normalization included (NSS and Laplace; #3427).wall_time_s: float, Total runtime.
The Posterior also has derived quantity methods:
derived,summary(),to_arviz(),refine(), etc.- Return type:
- Raises:
ParameterError – If
methodis invalid or unrecognized.RuntimeError – If background JIT compilation failed.
ValueError – If method-specific kwargs are invalid.
Notes
Method selection strategy:
Default (
"mcmc_nuts_fast"): four NUTS chains on the mass-profiled posterior; the fast photometry recipe for single galaxies.Variational (
"vi"): geoVI is recommended for high-dimensional problems (D>50) and population fitting. Captures non-Gaussian posterior geometry.Exact posterior (
"mcmc_nuts"): Use for D≤20 where exact sampling is feasible and posterior validation is critical.Fast large-D sampling (
"mcmc_raytrace"): Use for D>50 with gradient access; 250× more robust to noisy gradients than HMC.Bayesian model comparison (
"nss"): Estimates log-evidence for comparing competing physical models (e.g., different dust laws).
Important gotchas:
VI posterior equivalence:
"vi"(NIFTy geoVI) and"vi_native"(pure JAX geoVI) target the same objective but are NOT posterior-equivalent. The native version is ~19× faster but produces different posterior shapes on some problems (e.g., PSD timescale can differ by order of magnitude). Validate before swapping methods. Seebench/reports/2026-04-17_native_vs_nifty.mdin the repository (outside the docs tree, so it is not a linkable document).VIConfig.n_samples doubling: In geoVI, when
mirror_samples=True(default),n_samples=3produces 6 effective samples (3 + 3 mirrors). When tuning convergence, think in effective samples.Ray Tracing step_size scaling: Ray Tracing uses
step_size=0.05by default for D~137. There is a sharp viability cliff at ~0.06 where acceptance drops from 80% to 0%. Use smaller step sizes for safety.Method defaults from file: Default hyperparameters (
n_kl_iter,n_warmup, etc.) are loaded fromdefaults.tomlif available. Command-line kwargs override file defaults.
Warm-starting from MAP:
Fitting often proceeds in stages:
>>> result_map = fitter.run("map", n_steps=1500) >>> result_mcmc = fitter.run("mcmc_nuts", init_from=result_map, n_warmup=500) >>> result_vi = fitter.run("vi", init_from=result_map, n_samples=100)
MAP provides a quick point estimate; MCMC and VI refine from this initialization, converging faster than from random initialization.
Reproducibility:
Pass
key=jax.random.PRNGKey(seed)to control randomness across runs.key=Nonedefaults toPRNGKey(42)for reproducibility.Compile-cache behavior (smart lean, 2026-05):
runaccepts aleankwarg (default inferred fromtengri.lean()/tengri.persistent()context). Withlean=True(the default), the inference-body cache is cleared of stale entries, every entry whose(compile_signature, method)differs from the current call is dropped, but the entry that matches the current call (if it exists from a prior identical run) is kept. Forward-model, log-density, loss, and gradient compiles survive unconditionally. Implications:Multi-phase notebooks (MAP → HMC → posterior-predictive) peak at one inference scan body in RAM, not several.
Catalog loops calling
fitter.run(method)repeatedly with the same model and method pay one compile, not N, without needingtengri.persistent().
tengri.gc()drops everything including structural caches; use it between loops that build many different model configurations.References
[tengri.Fitter.run-1]M. D. Hoffman and A. Gelman, “The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo,” JMLR, 15, 1593 (2014). https://arxiv.org/abs/1111.4246
[tengri.Fitter.run-2]P. Behroozi, “The Ray Tracing Sampler,” arXiv:2504.20029 (2025). https://arxiv.org/abs/2504.20029
[tengri.Fitter.run-3]L. Zhang et al., “Pathfinder: Parallel quasi-Newton variational inference,” JMLR, 23, 306 (2022). https://arxiv.org/abs/2108.03782
[tengri.Fitter.run-4]B. D. Johnson et al., “Prospector: Stellar Population Inference from Spectra and SEDs,” ApJS, 254, 22 (2021). arXiv:2012.01426. https://doi.org/10.3847/1538-4365/abef67
Examples
Example 1: Quick exploration with MAP + geoVI
>>> fitter = Fitter(forward, data, noise) >>> result = fitter.run("vi") # geoVI with defaults >>> print(result.summary())
Example 2: Exact posterior with NUTS (small-D)
>>> result = fitter.run("mcmc_nuts", n_warmup=500, n_steps=2000) >>> samples = result.samples["stellar_mass"] >>> print(f"M_star = {jnp.median(samples):.2e} Msun")
Example 3: Warm-start MCMC from MAP
>>> result_map = fitter.run("map", n_steps=1500) >>> result_mcmc = fitter.run("mcmc_nuts", init_from=result_map, n_warmup=300, n_steps=1000)
Example 4: Nested sampling for Bayesian model comparison
>>> result_nss = fitter.run("nss", n_live=100) >>> log_z = result_nss.log_evidence >>> print(f"log(Z) = {log_z:.2f}") # Use for Bayes factors
Example 5: Using ``”auto”`` method for unknown dimensionality
>>> result = fitter.run("auto") # NUTS if D≤20, VI if D>20
- save_cache(path) None[source]¶
Persist this model’s adaptation cache (step size + mass matrix) to disk.
Reload in a fresh Python process with
load_cache()to skip sampler warmup on the nextrun()call. Useful when the same model+data is fit repeatedly across notebook restarts or batch jobs, warmup window adaptation typically dominates first-call wall time on a warm XLA cache.Stored payload:
adaptation: dict keyed by(engine_key, method_key), the contents of the model’s cache namespace under"adaptation".spec_fingerprint: a content hash of the free-parameter names and prior shape, used byload_cache()to refuse to load a cache that was written for a different model.
- Parameters:
path (str or Path) – Destination file (
.pklrecommended). Parent directory is created if missing.- Return type:
None
- summary() str[source]¶
Return a human-readable summary of the fitting problem.
- Returns:
Formatted summary showing data shape, free parameters, priors, bounds, and available inference methods.
- Return type:
Notes
The summary includes:
Data dimensionality and median signal-to-noise ratio
Free parameters and latent grid points (ξ) if stochastic SFH
Parameter names, prior distributions, and bounds
All available inference methods
Examples
>>> fitter = Fitter(forward, data, noise) >>> print(fitter.summary()) Fitter data_type: photometry ────────────────────────────────────────────────────────────── Data points: 100 Median S/N: 5.2 Parameters: 8 free + 64 latent (ξ) ...
Catalog¶
For many galaxies sharing one forward model, Catalog is the
table-in/table-out surface. It validates columns, units and the redshift
mechanism at construction — before any compile — then exposes .fit() and
.predict():
cat = Catalog(forward, table, flux_unit="cgs_fnu", redshift_col="z")
result = cat.fit(method="mcmc_hmc", key=jax.random.PRNGKey(0),
forward_chunk_size=32)
key is required, not optional — every catalog fit is explicitly seeded.
- class tengri.Catalog(fwd, table, *, flux_unit, redshift_col=None, flux_cols=None, err_cols=None, censor_cols=None, line_cols=None, line_err_cols=None, line_censor_cols=None, missing='error', default_relative_error=None, lim_flag=None, observed_relative_error=None)[source]¶
Bases:
objectAstronomer-facing catalog inference interface.
Wraps the existing per-galaxy
CatalogFitterengine with table-in/table-out access, ingestion and validation at construction time (fail fast, before any compile), and .fit() / .predict() verbs.- Parameters:
fwd (ForwardModel) – Shared forward model for all galaxies.
table (dict-like or None) – Column mapping or object supporting __getitem__[col] -> array and len(). Required for .fit(); pass None for prediction-only.
flux_unit (str) – Unit of the flux columns, required, with no default, so a table is never ingested under a guessed unit. One of:
"cgs_fnu"[erg/s/cm²/Hz],"mJy","uJy","maggies","ab_mag".redshift_col (str, optional) – Column name for per-galaxy redshifts. If given, the model must have a
Fixedredshift; the fit promotes it once to a runtime-redshift model whose table (if tabulated) spans the redshifts in the table, so the catalog is one compile. A model that declares acatalog_z_rangekeeps it, and the table must lie inside it. If not given, the model must have a free redshift parameter. Exactly one of the two conditions is required.flux_cols (list[str], optional) –
Flux column names in your table, they need not resemble the band names. If None, use
"{name}"for each band in the model’s observation.Binding is positional:
flux_cols[i]supplies the flux for bandiof the observation, so order them to match the observation rather than the table:# observation bands ("sdss_g", "sdss_r") Catalog(model, table, flux_cols=["FLUX_G", "FLUX_R"], err_cols=["ERR_G", "ERR_R"], flux_unit="cgs_fnu")
err_cols (list[str], optional) – Error column names in your table, bound positionally the same way. If None, use
"{name}_err"for each band.censor_cols (dict[str, str], optional) – Mapping from band name to censoring flag column. Flag values: 0 (detected), 1 (upper limit), -1 (lower limit).
line_cols (list[str], optional) – Emission-line flux column names in your table, bound positionally to the observation’s line order (from
observation.line_fluxes.names). If None and the model carries line fluxes, raises ValueError. If None and the model has no line fluxes, this parameter is ignored.line_err_cols (list[str], optional) – Emission-line error column names, bound positionally the same way. If None, use
"{name}_err"for each line, matching theerr_colsconvention.line_censor_cols (list[str], optional) – Emission-line censoring-flag columns, bound positionally the same way: 0 (detected), 1 (upper limit), -1 (lower limit). This is the catalog-scale form of
Data(lines={'Halpha': (f, e, 'upper')}).censor_colsis the photometric band axis and cannot express a line limit. Non-detection is a per-galaxy property, so declaring the flag on the Observation would apply it to the whole catalog.missing ({"error", "mask"}, default "error") – Policy for NaN flux values.
"error"raises with guidance onmissing="mask";"mask"sets presence to False for that cell.default_relative_error (float, optional) – Relative error [dimensionless] that fills the error of any band whose error column is absent, as CIGALE’s
defaulterror. Seeingest_catalog().lim_flag ({"none", "noscaling", "full"}, optional) – CIGALE’s
lim_flagconvention for limits and invalid bands in the error column. Seeingest_catalog().observed_relative_error (float, optional) – Relative model error [dimensionless] added in quadrature, scaled by the observed flux, to every detected band, as CIGALE’s
additionalerror.Noneadds nothing. Seeingest_catalog().
- Raises:
ValueError – If a required column is missing, flux/error counts mismatch, redshift mechanism validation fails (spec §6.2), or a NaN is present with
missing="error".TypeError – If
flux_unitis not provided.
Examples
>>> cat = Catalog(fwd, table, flux_unit="cgs_fnu", redshift_col="z") >>> post = cat.fit(key=jax.random.PRNGKey(0)) >>> post.n_galaxies 100 >>> stellar_masses = post.properties["stellar_mass"] # (100,)
- fit(method='map', *, key, forward_chunk_size='auto', n_pad=None, store=None, percentiles=None, reducers=None, properties=None, approx='auto', **kwargs) CatalogPosterior[source]¶
Fit all galaxies independently.
- Parameters:
method (str, default "map") – Inference method. Recommended:
"map"for quick point estimates,"mcmc_nuts"for posteriors. Never defaults to VI.key (jax.random.PRNGKey) – Base random key; per-galaxy keys are derived via
jax.random.split.forward_chunk_size (int or "auto", default "auto") – K galaxies evaluated in parallel per
lax.mapstep (native methods only)."auto"derives K from the memory budget; an explicit int is honored.n_pad (int, "auto", or None) – Pad the catalog up to this many galaxies before running. Allows different catalog sizes to share XLA cache entries.
None(default) pads only to the next multiple of K.approx ("auto", None or precompute config, default "auto") – Fit-time approximation policy, as for
Fitter:"auto"routes a photometry fit through the precompute LUT,Nonekeeps the model exact, a config (or tuple) overrides.store ({"full", "summary"} or None) – Storage mode for posterior samples.
None(default) auto-selects:"full"if N <= 1000, else"summary"with a warning."full"retains all samples."summary"computes percentiles and reducer statistics per name, then drops samples. A method that produces no samples ("map","laplace") has nothing to summarize: it warns and the result reportsstore="full".percentiles (tuple, optional) – Percentile levels to compute when
store="summary", in the order they should appear as columns. Default(16, 50, 84). The levels are recorded on the result aspercentile_levelsand drive bothpost[name](which reads the 50 column) andto_table()labels, include 50 if you want a median.reducers (dict, optional) – Additional reducer functions {name: callable} to apply per name (e.g., {“mean”: np.mean, “std”: np.std}). With store=”full”, these are ignored.
properties (tuple of str or None) – Derived properties to include in the summary block alongside the sampled parameters.
None(default) includes every property the model provides, sopost.percentiles["stellar_mass"]works;()includes none (parameters only, cheapest); an explicit tuple narrows it, which is the knob to reach for on a large catalog since each name costs one property evaluation per galaxy.**kwargs – Forwarded to the inference method (e.g.,
n_warmup,n_samplesfor MCMC). Also reaches_CatalogFitterOriginal.runitself, which is howfallback="mcmc_chees"– the experimental, opt-in second sampler for galaxies the first one froze on – is spelled from here. A name the chosen method does not accept raisesTypeErrorthat names the method and lists the accepted names (#1469).
- Returns:
Container for N independent per-galaxy posteriors.
- Return type:
CatalogPosterior
- Raises:
ValueError – If no table was provided at construction (use .predict() instead).
TypeError – If
**kwargscarries a name the chosen method does not accept.
- classmethod from_histories(fwd, *, t_gyr, sfr, met=None, met_gas=None, met_unit='logzsol', on_out_of_grid='raise', redshift=None, params=None, flux_unit='cgs_fnu')[source]¶
Build a mock catalog from tabulated SFH / metallicity histories (#1396).
The simulation-catalog entry point: a hydro sim, semi-analytic model or UniverseMachine-style run supplies SFH(t) and optionally Z(t) per galaxy, and the result is a
Catalogwhosepredict()returns photometry for the whole table.Histories are records, not parameters. They enter at the action, the same way fluxes do, which is why this is a classmethod rather than a model-construction argument, the
tableSFH declares zero free parameters because the table is the SFH.- Parameters:
fwd (ForwardModel) – Model built with
sfh={'type': 'table'}(andmet={'type': 'table'}ifmetis given).t_gyr (array_like, shape (n_t,) or (N, n_t)) – Cosmic time [Gyr], strictly increasing. A 1-D grid is shared by every galaxy and broadcast.
sfr (array_like, shape (N, n_t)) – Star formation rate [Msun/yr] at those times. Must be finite and non-negative.
met (array_like, shape (n_t,) or (N, n_t), optional) – Stellar metallicity history in
met_unitat the same nodes, the Z each generation of stars formed from, which selects the SSP templates. A 1-D history is shared by every galaxy and broadcast, the same wayt_gyris. Requires the model’smetallicity_model='table'; conversely a model built that way requires a history here, and says so at construction rather than inside the first forward pass.met_gas (array_like, shape (N,), (n_t,) or (N, n_t), optional) –
Gas-phase metallicity in
met_unit, the Z of the ionized gas that drives nebular emission. A separate physical quantity frommetand set independently of it: inflow of pristine gas genuinely decouples the two. Given as a track, the last node is taken as the observed epoch, because nebular emission comes from stars younger than ~10 Myr and only the present-day value is observable.Left unset, the model’s own
neb_logZ_gasapplies, and its declared default is a fixed 0.5 Zsun that does not follow the stellar history, so a tabulatedmet=alongside it emitsGasStellarMetallicityWarningrather than quietly enriching the stars but not the gas (#1677). Requires an active nebular backend; without one there is nothing to consume it and it is refused.met_unit ({"logzsol", "log_z_abs", "z_mass_fraction"}, default "logzsol") – The unit
metarrives in."logzsol"is log10(Z/Zsun), tengri’s user-facing convention;"log_z_abs"is absolute log10(Z), the SSP grid’s own;"z_mass_fraction"is the raw metal mass fraction \(Z\), which is what a simulation snapshot stores. Declaring it matters:Z = 2e-4is a perfectly legallogzsolvalue, so a mass fraction read as log10(Z/Zsun) is a silent factor of ~70 in metallicity (#1677). Leaving it at the default on a history that reads like a mass fraction emitsMetallicityUnitWarning, the SSP-grid check cannot catch that case, because those values are in-grid.on_out_of_grid ({"raise", "warn", "ignore"}, default "raise") – What to do when a metallicity node falls outside the SSP’s grid, where the lookup silently clips to the edge.
"warn"emitsOutOfSSPGridWarningcarrying the share of stellar mass affected;"ignore"restores the pre-#1677 silence. Simulations reach primordial metallicities at early times routinely, so this fires on real data, clip the history, load a wider SSP, or downgrade the policy deliberately.redshift (array_like, shape (N,), optional) – Per-galaxy redshift. The fit promotes the model once to read redshift at call time, so the catalog stays one compile (#1316).
params (dict, optional) – Per-galaxy scalars,
{name: (N,)}, every free parameter of the model that is not supplied by the histories.flux_unit (str, default "cgs_fnu") – Recorded for symmetry with the data-table constructor; predictions are returned in [erg/s/cm²/Hz] regardless.
- Returns:
Prediction-only:
.predict()and.simulate()need no argument, and.fit()raises. A catalog built from histories carries no observed fluxes to fit to, and the data-table constructor has no channel to attach histories, so “fit dust at a known simulation SFH” is not reachable through this class today. (This said.fit()was “still meaningful” until #1677 measured it raisingNo table provided at construction.)- Return type:
- Raises:
ValueError – If the model does not declare a tabulated SFH; if
metis given without a tabulated metallicity, or a tabulated metallicity is declared withoutmet; ift_gyris not strictly increasing; if any value is non-finite or any SFR negative; if the shapes disagree; or if a metallicity node is off-grid under the defaulton_out_of_grid='raise'.- Warns:
OutOfSSPGridWarning – Under
on_out_of_grid='warn', carrying the share of stellar mass formed on clamped nodes.MetallicityUnitWarning – When the history reads like a metal mass fraction taken for log10(Z/Zsun).
GasStellarMetallicityWarning – When a tabulated stellar metallicity is supplied but the gas-phase metallicity is left at its fixed declared default, so the stars enrich and the gas does not.
See also
tengri.inference.history_ingest.ingest_historiesThe validation itself, and the measured failure modes it closes.
Notes
JIT-compatible: no, eager validation at construction, by design. The forward model clips metallicity onto the SSP grid inside JIT, where no Python exception can be raised, so ingest is the only place a bad history can still be refused.
Examples
>>> cat = Catalog.from_histories( ... fwd, t_gyr=t, sfr=sfr, redshift=z, params={"dust_tau_diff": tau} ... ) >>> flux = cat.predict()
Straight from a snapshot, where metallicity is a mass fraction. The stellar history and the gas-phase value are separate knobs and do not track each other, so a snapshot that stores both passes both:
>>> cat = Catalog.from_histories( ... fwd, t_gyr=t, sfr=sfr, met=Z_star, met_gas=Z_gas, met_unit="z_mass_fraction" ... )
- predict(param_table=None, *, chunk_size=32, n_pad=None) ndarray[source]¶
Predict photometry for a catalog of parameters or histories.
Evaluates the forward model on a table of per-galaxy columns, returning observed-frame spectral flux density (or flux in the chosen units).
- Parameters:
param_table (dict-like, optional) – Mapping of name → array whose leading axis indexes galaxies; the trailing shape is free. A per-galaxy scalar is
(N,); a tabulated history (sfh_t_gyr,sfh_sfr,met_history) is(N, n_t). Every free parameter needs a column; names the model does not recognize are reported by the forward model’s own unknown-parameter check, so a typo cannot pass silently. A column named for a parameter the spec declaredFixedis refused withParameterError(#2296) rather than overriding it — rebuild the model with that parameterFREEinstead. Omitparam_tableentirely on a catalog built byfrom_histories(), which already carries its columns.chunk_size (int, default 32) – Galaxies evaluated per vmapped batch. Larger batches are faster but use more memory. Chunks are padded to a uniform width, so the whole catalog costs one compile regardless of how it divides.
n_pad (int, optional) – Pad the catalog to at least this many galaxies before chunking, so catalogs of different sizes share one XLA cache entry (the same meaning
fit()gives it). Padding rows are discarded from the result.
- Returns:
Predicted photometry [erg/s/cm²/Hz].
- Return type:
ndarray, shape (N, n_filters)
Notes
Columns are not restricted to
spec.free_params. A tabulated SFH declares zero free parameters (the table is the SFH) so extracting only free parameters dropped the history arrays entirely and the forward then refused with the #996 runtime check (#1396).Examples
>>> params = {"stellar_mass": np.linspace(9, 12, 100)} >>> flux = cat.predict(params, chunk_size=64) >>> flux.shape (100, 3)
Driving a catalog from tabulated histories:
>>> flux = cat.predict( ... { ... "dust_tau_diff": tau, # (N,) ... "sfh_t_gyr": t_gyr, # (N, n_t) ... "sfh_sfr": sfr, # (N, n_t) ... } ... )
- simulate(*, lines=None, properties=None, chunk_size=32, n_pad=None, noise=None, key=None)[source]¶
Simulate mock observables for the whole catalog (#1396 §8.1).
One verb, several channels: photometry always, plus emission lines and derived properties on request. Intended for a catalog built by
from_histories(), where the SFH/Z tables come from a simulation.- Parameters:
lines (sequence of str, optional) – Emission line names to measure, from
DESI_LINES(e.g.("Halpha", "OIII_5007")). Measured through the window-LUT fast path, which since #1396 serves tabulated histories.properties (sequence of str, optional) – Derived quantities to evaluate, e.g.
("stellar_mass",).chunk_size (int, default 32) – Galaxies per vmapped batch. Chunks are padded to a uniform width, so each channel costs one compile for the whole catalog.
n_pad (int, optional) – Pad the catalog to at least this many galaxies, so catalogs of different sizes share one XLA cache entry per channel.
noise (optional) – Not implemented, noise draws are #1312. Refused rather than ignored, so a caller asking for a noisy mock never silently receives a noiseless one.
key (optional) – Reserved for the noise draw (#1312); refused for the same reason.
- Returns:
.photometry,.lines,.properties, and.to_table().- Return type:
MockCatalog
- Raises:
NotImplementedError – If
noiseorkeyis passed.ValueError – If a line name is not recognized.
Examples
>>> mock = cat.simulate(lines=("Halpha",), properties=("stellar_mass",)) >>> mock.lines["Halpha"].shape (100,)
fit_batch is the lower-level alternative: it walks the rows one at a time
without Catalog’s column validation, which is useful when the
input is already in memory as arrays rather than a table.
- tengri.fit_batch(model: SEDModel, catalog, flux_cols: list[str], err_cols: list[str], redshift_col: str | None = None, method: str = 'mcmc_nuts_fast', n_workers: int = 1, verbose: bool = True, output_dir: str | None = None, id_col: str | None = None, approx='auto', **kwargs) list[source]¶
Fit a batch of galaxies from a catalog, one row at a time.
Deprecated since version 2026-07: Use
Catalogdirectly for new code.fit_batchwill be removed in a future release.Accepts pandas.DataFrame, astropy.table.Table, or list of dicts. Supports checkpoint resume via
output_dir.- Parameters:
model (SEDModel) – Forward model instance.
catalog (DataFrame, Table, or list of dict) – Input catalog with flux and error columns.
flux_cols (list of str) – Column names for per-band flux [erg/s/cm²/Hz].
err_cols (list of str) – Column names for per-band 1-sigma uncertainty [erg/s/cm²/Hz].
redshift_col (str, optional) – Column name for per-row redshift. If None, uses model redshift.
method (str, optional) – Inference method (e.g. “vi”, “mcmc”). Default
"mcmc_nuts_fast".n_workers (int, optional) – Reserved for future multiprocessing. Default 1.
verbose (bool, optional) – Print per-galaxy progress. Default True.
output_dir (str, optional) – Save each Posterior to
{output_dir}/{id}.h5. Supports checkpoint resume.id_col (str, optional) – Column name for galaxy IDs in output filenames. Default uses row index.
**kwargs – Forwarded to
Fitter.run()for each galaxy.
- Returns:
One inference result (Posterior) per input catalog row.
- Return type:
Notes
JIT-compatible: no, uses Python-level loop and file I/O.
Bayesian model averaging¶
Combine fits of different models to the same data, weighting each by its
marginal likelihood. Every posterior must carry Posterior.log_evidence —
fit with an evidence-returning method ("nss", "laplace", or
"hmc_is").
- tengri.bma_weights(posteriors: Sequence | Mapping) ndarray | dict[source]¶
Compute Bayesian model averaging weights from log evidences.
Under a flat prior over models, the posterior model probabilities are proportional to the marginal likelihoods (log evidences). This function computes the softmax of log evidences, which are the normalized weights for model averaging.
- Parameters:
posteriors (Sequence or Mapping) – If Sequence: iterable of posterior-like objects, each with a log_evidence attribute. If Mapping: dict-like with model names as keys and posterior-like objects as values.
- Returns:
weights – If input is a Sequence, returns a numpy array of shape (n_models,) with weights summing to 1.0. If input is a Mapping, returns a dict with the same keys as the input, with float values summing to 1.0.
- Return type:
np.ndarray or dict
- Raises:
ValueError – If any posterior’s log_evidence is None, NaN, or infinite. The error message names the offending model (by index if Sequence, by key if Mapping).
Notes
The softmax is computed using the log-sum-exp trick with max-shifting for numerical stability:
w_i = exp(log_evidence_i - max(log_evidence)) / sum_j(...)
This prevents overflow/underflow when evidence values are large or small in absolute magnitude.
Examples
>>> import jax.numpy as jnp >>> import types >>> # Create mock posteriors >>> p1 = types.SimpleNamespace(log_evidence=0.0) >>> p2 = types.SimpleNamespace(log_evidence=jnp.log(3.0)) >>> weights = bma_weights([p1, p2]) >>> weights array([0.25, 0.75])
- tengri.bma_resample(posteriors: Sequence | Mapping, n_draws: int, key: PRNGKey) dict[source]¶
Resample from multiple models weighted by Bayesian model averaging.
Performs multinomial resampling of physical-space samples from posterior chains, where each model contributes a number of draws proportional to its BMA weight. Only parameters present in all models are returned (the intersection of sample keys).
- Parameters:
posteriors (Sequence or Mapping) – Iterable of posterior-like objects, each with log_evidence and samples attributes.
n_draws (int) – Total number of draws to resample from the pooled posteriors.
key (jax.random.PRNGKey) – JAX PRNG key for deterministic randomness.
- Returns:
resampled – Dictionary mapping parameter names (the intersection of all sample keys) to numpy arrays of shape (n_draws,).
- Return type:
- Raises:
ValueError – If any posterior has
samples=None, or if the intersection of sample keys is empty (no shared parameters).
Notes
Intersection semantics: For structurally different models, only parameters present in all chains are pooled. This is the operation the CANDELS notebook requires for model comparison.
Sampling procedure:
Compute BMA weights via
bma_weights()Draw model indices via multinomial with probabilities = weights
For each model, resample (with replacement) from its chain
Concatenate samples from all models, preserving the order of models by draw count
Examples
>>> import jax >>> import numpy as np >>> import types >>> key = jax.random.PRNGKey(42) >>> p1 = types.SimpleNamespace( ... log_evidence=0.0, samples={"param_a": np.array([1.0, 2.0, 3.0])} ... ) >>> p2 = types.SimpleNamespace( ... log_evidence=0.0, samples={"param_a": np.array([10.0, 20.0, 30.0])} ... ) >>> resampled = bma_resample([p1, p2], n_draws=100, key=key) >>> resampled["param_a"].shape (100,)
Hierarchical inference¶
For a population sharing hyperparameters, build a
PopulationSEDModel and pass it to ForwardModel.build as
the population slot — the same engine drives it:
template = SEDModel.build(...)
pop = PopulationSEDModel(
sed=template,
galaxies=galaxies,
shared=("sfh_field_psd_sigma", "sfh_field_psd_tau_myr"),
)
forward = ForwardModel.build(population=pop, observation=obs)
result = forward.fit(method="vi")
Constructing PopulationFitter directly is deprecated and will
be removed in tengri v1.0; the class remains as the routed implementation
behind the pattern above.
Population SED model¶
- class tengri.PopulationSEDModel(sed: Any, galaxies: Sequence[Mapping[str, Any]], shared: Sequence[str] = ('sfh_field_psd_sigma', 'sfh_field_psd_tau_myr'), priors: Mapping[str, tuple[float, float]] | None = None, data_type: str = 'photometry')[source]¶
Bases:
objectSubModel for a hierarchical galaxy population with shared parameters.
- Parameters:
sed (SEDModel) – Template SED chain. Its physics (SFH family, dust law, nebular backend, …) is shared across the population.
galaxies (sequence of mapping) – Per-galaxy data. Each dict must contain
flux_obsandnoise; optionallyspec_obs,spec_noise,wave_spec.shared (sequence of str, optional) – Parameter names tied across the population. Default is the two canonical PSD hyperparameters.
priors (mapping of str -> (lo, hi), optional) – Uniform prior bounds for the shared parameters. Must contain an entry for every name in
shared. Defaults to PSD-typical ranges.data_type (str, default
"photometry") – Inference channel; passed to the underlyingtengri.PopulationFitter.
- Variables:
name (str) – The
tengri.protocols.SubModelidentifier,"population_sed_model". Read-only, the protocol calls it a stable identifier, and this constructor has never accepted it.
Notes
Satisfies the
tengri.protocols.SubModelProtocol. The forward-time.runpath is a stub today, the batched-vmap implementation lands whenForwardModel.predict_observableslearns the PopulationSEDModel case (issue #211). Inference is routed at thetengri.Fitterlayer.- property batched_axes: dict[str, int]¶
Named batched axes this SubModel introduces.
Returns
{"galaxy": 0}, PopulationSEDModel publishes a single named axis ("galaxy") at position 0 of every per-galaxy array. Single-galaxy SubModels (SEDModel,SpatialModel, …) return{}.Used by
ForwardModel.predict_observables()and by the inference layer to compose batching (vmap / pmap / shard_map) without hidden nested vmaps. Seepredict_one()for the un-batched primitive.
- batched_data() tuple[Array, Array][source]¶
Return
(flux_obs, noise)arrays stacked across the population.Each array has shape
(N_galaxies, n_filters), the canonical batched shape thatFitteraccepts as thedataandnoisearguments for hierarchical fits.The likelihood’s \(\chi^2\) broadcasts naturally over the leading galaxy axis against the prediction dict’s
(N_galaxies, n_filters)arrays returned byForwardModel.predict_observables().- Returns:
flux_obs (ndarray, shape
(N_galaxies, n_filters)) – Per-galaxy observed flux.noise (ndarray, shape
(N_galaxies, n_filters)) – Per-galaxy 1-sigma uncertainty.
- Raises:
KeyError – If any galaxy dict is missing
flux_obsornoise.
- declared_parameters() list[ParamDeclaration][source]¶
Free-parameter declarations seen at the population level.
Returns the shared population-level parameters. Per-galaxy free parameters are managed by the inference layer, not the population-level declared_parameters view (which is consumed by introspection helpers like
tengri.Parameters.summary).
- name: str = 'population_sed_model'¶
The
SubModelidentifier.init=Falsebecause the protocol calls it a stable identifier: this constructor never accepted it, and an ordinary field declaration advertised otherwise todataclasses.fields()and to the docstring above.
- parameter_axes(params: Mapping[str, Any]) dict[str, int | None][source]¶
Per-parameter vmap axis: 0 for per-galaxy, None for shared / scalar.
Three cases, in order:
Names in
sharedalways broadcast, axisNone.Rank-0 / scalar values (e.g. fixed values like
redshiftmerged fromspec) also broadcast, axisNone.Everything else is per-galaxy, axis
0(the value is a 1-D array of length N_galaxies).
The scalar-detection branch is what lets fixed values (
redshift, calibration coefficients, …) flow through without being treated as per-galaxy data.
- predict_one(state: ForwardState, params_one: Mapping[str, Any]) ForwardState[source]¶
Un-batched primitive: run the SED template for a single galaxy.
Corresponds to one term in the hierarchical information Hamiltonian’s data sum (paper §4):
\[\mathcal{H}_{\rm hier} = \tfrac{1}{2}\sum_{j=1}^{N_{\rm gal}} \chi^2\!\bigl(\mathbf{d}^{(j)},\, \mathbf{f}\!\bigl(\mathbf{h}(\boldsymbol{\xi}^{(j)},\, \boldsymbol{\xi}^{(\rm hyp)})\bigr)\bigr) + \tfrac{1}{2}\,\boldsymbol{\xi}^{\!\top}\boldsymbol{\xi}\]where \(\mathbf{f}\circ\mathbf{h}\) is the per-galaxy forward model from latent space to predicted observables.
predict_oneevaluates that pipeline for one galaxy;run()vmaps over the population to evaluate the full sum.Composable with outer
jax.vmap/jax.pmap/shard_map. Use this entry point when you need control over the batching strategy, e.g. multi-device sharding, catalog × hierarchical fits, or posterior-predictive sweeps that already have an outervmap. Userun()for the default batched path.- Parameters:
state (ForwardState) – Initial state. Wavelength grid + any upstream state.
params_one (Mapping) – Un-batched parameters for a single galaxy. Every value is a scalar (no leading
N_galaxiesaxis).
- Returns:
Single-galaxy state. No leading galaxy axis.
- Return type:
ForwardState
Notes
Pure JAX. JIT/grad/vmap/pmap-compatible. Forwarding to
self.sed.runis a no-op layer that exists so external callers can compose their own batching without nestingrun()’s internal vmap.
- run(state: ForwardState, params: Mapping[str, Any], *, chunk_size: int = 32) ForwardState[source]¶
Forward-time batched SED across the population, in galaxy chunks.
Each population-level parameter is either
shared(one value, broadcast to every galaxy) or per-galaxy (an array of length N, mapped over the galaxy axis). The returnedForwardStatehas a leadingN_galaxiesaxis on every array leaf (sed_intrinsic,sed_observed,sed_attenuated, …).The population is evaluated
chunk_sizegalaxies at a time: the per-galaxy axis is padded to a whole number of chunks, reshaped to(n_chunks, chunk_size)and looped withjax.lax.map(), each chunk avmapofpredict_one(). The padding is trimmed before return.See
docs/internal/plans/2026-05-22-population-sed-batched-forward.mdfor the design rationale.- Parameters:
state (ForwardState) – Initial state. The wavelength grid is shared across the population (broadcast), the SED template owns the grid.
params (Mapping) – Per-parameter values. Shared params are scalars; per-galaxy params are length-N arrays.
parameter_axes(params)returns the vmap-axis dict.chunk_size (int, default
GALAXY_CHUNK_SIZE(32)) – Galaxies per compiled chunk. Peak memory scales with this: each galaxy holds one(n_age, n_wave)per-age cube, about 8 MB on the tutorial 02 model, so a chunk of 32 holds about 256 MB of cubes where the unchunked population of N = 1000 holds about 8 GB. Must be a positive int;Noneand non-int values raiseValueError.
- Returns:
Batched state: every per-galaxy quantity has a leading
N_galaxiesaxis.- Return type:
ForwardState
- Raises:
ValueError – If
chunk_sizeis not a positive int, or no parameter is per-galaxy (there is no galaxy axis to map over).
Notes
JIT/grad/vmap-compatible: the chunk loop is one
lax.map, so the traced program holds one chunk body whatever N is, andrunmay sit inside an outerjit,gradorvmapwith no unrolling. The template’srunmust be traceable (the same requirement as the unchunkedvmap).Chunking is not bit-neutral: XLA compiles a different kernel for each chunk shape, so changing
chunk_sizecan move the last bit (about 1 ULP). Pinchunk_sizewhen bit-for-bit reproducibility matters.Notes (composability)¶
This method is the default convenience path; it maps
predict_one()over the galaxy axis in chunks. For multi-device sharding, catalog × hierarchical fits, or any case where you need to compose outer batching, callpredict_one()directly with your ownvmap/pmap/shard_map. Thebatched_axesproperty publishes the axis layout so external code can stay axis-aware.
- property spec¶
The batched-sample
Parameters-shaped view.Returns a
PopulationSpecViewwrapping the SED template’s scalar spec. Implements the same implicit ProtocolFitterconsumes (free_params,get_fixed_values,sample(key),_distributions, …), butsample()returns per-galaxy free parameters with shape(N_galaxies,), keeping shared parameters scalar.Fitter has zero special-case code for hierarchical fits: it just consumes whatever shapes the spec returns.
Notes
Construction is cheap (no JAX work). Use
self.sed.specto access the underlying scalar spec when you need it directly.
Population fitter¶
- class tengri.PopulationFitter(model_factory, galaxies, psd_sigma_prior=(0.1, 4.0), psd_tau_prior=(1.0, 300.0), data_type='photometry', *, approx='auto', _via_routing: bool = False)[source]¶
Bases:
objectHierarchical inference for shared PSD parameters.
Manages population-level inference via hierarchical VI, learning the shared PSD hyperparameters (σ_PSD, τ_PSD) across a population of galaxies while preserving per-galaxy latent fields and physical parameters.
- Parameters:
model_factory (callable) – Function(psd_sigma, psd_tau_myr) → Model. Creates a model with the given PSD params. All other params (SFH, dust, etc.) come from the model’s Parameters.
galaxies (list of dict) – Each dict has ‘flux_obs’, ‘noise’, and optionally ‘spec_obs’, ‘spec_noise’, ‘wave_spec’.
psd_sigma_prior (tuple) – (lo, hi) for uniform prior on σ_PSD.
psd_tau_prior (tuple) – (lo, hi) for uniform prior on τ_PSD (Myr).
data_type (str) – “photometry” or “spectroscopy”.
approx ("auto" or None or precompute config, optional) – Fit-time precompute policy, mirroring
Fitter."auto"(default) routes every factory-built photometry model through theWavePrecompLUT, a hierarchical sampler evaluates the forward model thousands of times, and the exact path costs a measured ~2-6x more per evaluation. A joint fit’s photometry takes the same LUT; a spectrum channel takes the spectrum LUT only where that LUT serves the pixels exactly and is exact otherwise.Noneforces the exact wave-grid path; an explicit config is used verbatim. A factory whose models already carry the LUT is respected untouched.
Notes
Wraps all hierarchical inference methods (EVI, VI, MCMC) with automatic initialization via per-galaxy MAP estimation. The class builds a single flat parameter vector [φ_shared, ξ_1, θ_1, …, ξ_N, θ_N] and optimizes it via the specified method.
- Variables:
n_galaxies (int) – Number of galaxies in the population.
Examples
>>> import jax >>> from tengri import PopulationFitter, SEDModel, Parameters, Uniform >>> # Define a factory that builds a model given shared PSD params >>> def model_factory(psd_sigma, psd_tau_myr): ... spec = Parameters( ... sfh_field_psd_sigma=Uniform(0.1, 4.0), ... sfh_field_psd_tau_myr=Uniform(1.0, 300.0), ... ) ... return SEDModel(spec, ssp_data) # ssp_data loaded separately >>> # galaxies = [{'flux_obs': ..., 'noise': ...}, ...] >>> # pop = PopulationFitter(model_factory, galaxies) >>> # result = pop.run('vi', key=jax.random.PRNGKey(0))
- run(method='vi_nonlinear_fast', *, key=None, allow_unvalidated=False, **kwargs)[source]¶
Run hierarchical inference.
- Parameters:
method (str) –
NIFTy-backed (CorrelatedFieldMaker, native PSD learning)
"vi": the canonical name, shared with every other fit surface (tengri.inference._backend_registry.DEFAULT_METHOD, #1289). Same geoVI runner as"vi_nonlinear_fast"."vi_nonlinear_fast": geoVI via NIFTyoptimize_kl(default)."vi_nonlinear": geoVI; same runner as fast, kept for API symmetry."vi_linear_fast": MGVI via NIFTyoptimize_kl."vi_linear": MGVI; same runner as fast, kept for API symmetry."evi_nifty": expansion-point VI via_run_geovi_cfm(sample_mode="evi"). Dispatched by name, with no registry entry of its own.
Pure-JAX (lax.while_loop, no NIFTy), tier=”broken”
"native_vi_linear": MGVI insidelax.while_loop. 3–4× faster than NIFTy MGVI on CPU; O(1) memory in N."native_vi_nonlinear": geoVI insidelax.while_loop. Comparable speed to NIFTy geoVI; prefers lower N (≤20).
Both native backends are registered
tier="broken", they segfault on DPL/dense_basis photometry mocks (#231). They are substantially faster when they run, so they are kept and remain reachable viaallow_unvalidated=True, but validate per-problem before relying on one. They are also not posterior-equivalent to the NIFTy path: the fitted PSD timescalesfh_field_psd_tau_myrhas been measured to differ by an order of magnitude between them (82 vs 6 Myr), which is why reaching them has to be a deliberate act rather than a default.Note
native_vi_linearwas the default fromb7c4fa1e2until 2026-07. It was chosen for speed before the segfault was validated (#231, 2026-05-22), and the tier change never propagated back to the signature, this method’s ownValueErrorfor an unknown method went on namingvi_nonlinear_fast“(default)” the whole time.MCMC and MAP (through the flat seam)
"mcmc_raytrace": Ray Tracing on the flat vector. At hierarchical D the chain is typically degenerate, and the run raisesDegenerateChainErrorrather than returning MAP-echo draws (#1530)."mcmc": pinned to NUTS, deliberately diverging from the single-galaxy auto-pick (raytrace above D~20): hierarchical D grows with the catalog, so that auto-pick would select the guaranteed-degenerate sampler."mcmc_nuts","mcmc_hmc","mcmc_dynamic_hmc", NUTS / static-leapfrog HMC / dynamic trajectory-length HMC on the flat vector."mcmc_ess": elliptical slice sampling, gradient-free. The flat parameterization’s prior is exactly the iid N(0,1) the ESS ellipse assumes, so its one structural requirement holds by construction; no step size or warmup exists to tune."mcmc_adjusted_mclmc": Metropolis-adjusted microcanonical Langevin MC, tuned by blackjax’s own (L, step size) adaptation."mcmc_mclmc": unadjusted MCLMC; tier=”broken” ([POOR MIXING] on the single-galaxy benchmarks, and biased at finite step size by construction), requiresallow_unvalidated=True."mcmc_ghmc": generalized (persistent-momentum) HMC; tier=”broken” ([POOR MIXING] on the single-galaxy benchmarks), requiresallow_unvalidated=True. Always uses a diagonal mass matrix."map": Adam MAP on the flat vector."laplace": the same MAP ascent plus a Gaussian covariance from the negative Hessian at a GRADIENT-VERIFIED mode: an unconverged ascent or non-negative-definite curvature raises rather than returning error bars measured off a mode (#1537)."pathfinder": tier=”broken” (OOM-killed the process on a measured 2-galaxy problem); requiresallow_unvalidated=True."nss": the in-tree Nested Slice Sampler (Yallup+2026) on the flat vector, with live points drawn from the exact iid N(0,1) prior; the only driver that also returnslog_evidence(hierarchical model comparison). Requiresnss_n_live > D, the HRSS direction covariance is estimated from the live set and is singular otherwise, so at stochastic-field D (hundreds of latents) prefer"mcmc_nuts", or shrinkn_gridat build time.
key (PRNGKey, optional) – Random key for reproducibility. If None, uses PRNGKey(0).
allow_unvalidated (bool, optional) – Run a
tier="broken"method anyway, for benchmarking or backend development, not for science. Default False.**kwargs – Passed to the inference method.
- Returns:
Results object with shared_params, shared_samples, individual_samples, and diagnostics.
- Return type:
Notes
Unlike
Fitter.run(),PopulationFitter.run()does not support warm-start initialization viainit_frombecause hierarchical inference methods (EVI, CFM-based geoVI, Ray Tracing) initialize per-galaxy parameters via MAP estimation automatically. Theinit_fromparameter is not meaningful in the hierarchical context.Automatic initialization: all methods initialize per-galaxy parameters via MAP estimation before starting the hierarchical inference. First call may be slow due to JIT compilation. Subsequent calls are fast. Approximate runtime: ~30 seconds for 10 galaxies on CPU (method-dependent).
Compile-cost amortization across catalog sizes¶
Unlike
CatalogFitter,PopulationFitterdoes not expose ann_padargument: the hierarchical population field couples all N galaxies, so padding with dummy galaxies would contribute spurious prior mass to the population hyperparameters (e.g.psd_sigma,psd_tau_myr) even with masked likelihoods. To amortize XLA compile cost across notebook restarts, slurm tasks, or sweeps over different catalog sizes, rely on the persistent compilation cache instead, seetengri.enable_persistent_cache()anddocs/performance/compilation.md.
Population posterior¶
- class tengri.PopulationPosterior(shared_samples: dict, shared_params: dict, individual_samples: list | None = None, method: str = '', wall_time_s: float = 0.0, diagnostics: dict = <factory>, _model: object = None)[source]¶
Bases:
objectResults from hierarchical PSD inference.
This class holds the posterior distribution over shared PSD hyperparameters (σ_PSD, τ_PSD) inferred across a population of galaxies, along with optional per-galaxy individual posteriors.
- Parameters:
shared_samples (dict) – Posterior samples for shared PSD params. Keys are param names (e.g., ‘psd_sigma’, ‘psd_tau_myr’), values are arrays of shape (n_samples,).
shared_params (dict) – Posterior mean of shared PSD params (computed from shared_samples).
individual_samples (list of dict, optional) – Per-galaxy posterior samples. Each element is a dict with per-galaxy parameter names as keys. If None, individual posteriors are not stored (for memory efficiency).
method (str) – Inference method used (e.g., “Hierarchical EVI (JIT)”).
wall_time_s (float) – Total wall-clock time for inference.
diagnostics (dict) – Method-specific diagnostics (e.g., number of iterations, convergence info).
Notes
This dataclass is the return type for PopulationFitter.run(). Access population posteriors via shared_samples and shared_params, and per-galaxy posteriors via the individual property (returns a list of lightweight objects with .samples and .params attributes).
Examples
>>> result = fitter.run("vi", n_iterations=20) >>> result.summary() # Median and 68% credible intervals >>> ax = result.plot_population(params=("sfh_field_psd_sigma", "sfh_field_psd_tau_myr"))
- property individual¶
Per-galaxy posterior marginals as a list of lightweight objects.
- Parameters:
None
- Returns:
Each element has
.samples(dict) and.params(dict). Returns empty list ifindividual_samplesis None.- Return type:
list of SimpleNamespace
Notes
Each per-galaxy posterior is marginalized over the shared PSD hyperparameters. The
.paramsfield contains the median of each per-galaxy parameter.
- plot_population(params=('sfh_field_psd_sigma', 'sfh_field_psd_tau_myr'), ax=None)[source]¶
Scatter plot of shared PSD parameter posteriors.
- Parameters:
- Returns:
The axes object with the scatter plot.
- Return type:
matplotlib Axes
Notes
Plots posterior samples as a scatter cloud. Each point is one posterior sample.
- population_diagnostics(exclude_prefixes: tuple[str, ...] = ('psd_xi',)) dict[source]¶
Convergence diagnostics for the population fit.
Computes split-Rhat and effective sample size for the shared PSD block, and (when
individual_samplesis present) aggregates per-galaxy diagnostics into population-level summaries.- Parameters:
exclude_prefixes (tuple of str, optional) – Parameter-name prefixes to skip when computing per-galaxy diagnostics. Default
("psd_xi",)skips the GP latent fields, which carry one chain entry per grid point and inflate dict size without adding interpretable information.- Returns:
Two-level structure:
{ "shared": { param_name: {"rhat": float, "ess": float}, ... }, "per_galaxy": { # only if individual_samples is set param_name: { "rhat_p50": float, # median across galaxies "rhat_p90": float, "rhat_max": float, "ess_p50": float, "ess_min": float, "n_galaxies": int, }, ... }, }
Use
"per_galaxy"to spot a single galaxy whose chain has stalled, a highrhat_maxwith lowrhat_p50is the signature.- Return type:
Notes
Reuses
tengri.analysis.diagnostics.autocorrelation.rhat()andtengri.analysis.diagnostics.effective_sample_size(). Static (zero-variance) parameters are dropped silently.Examples
>>> result = fitter.run("vi", n_iterations=20) >>> diag = result.population_diagnostics() >>> diag["shared"]["sfh_field_psd_sigma"] {'rhat': 1.012, 'ess': 318.4}
- property properties¶
The property catalog over the galaxy axis of a population fit.
Contract §1, same names, more axes. Each galaxy’s properties are evaluated on its own parameter draws merged with the shared hyperparameters: in a hierarchical fit the per-galaxy block alone is not a complete parameter set, and evaluating it without the shared PSD block would silently answer a different question.
- Returns:
[name]-> shape(n_galaxies, n_samples);ci(name)->(n_galaxies, 3).- Return type:
CatalogProperties
- Raises:
RuntimeError – If the fit carries no per-galaxy samples, or no model reference.
Examples
>>> pop = pop_fitter.run(...) >>> pop.properties["stellar_mass"].shape (12, 400)
Parameter information¶
How much of each posterior mode the data determined, as opposed to the prior — the measured-versus-prior decomposition of a fit.
- tengri.parameter_information(target, params=None, *, key=None) ParameterInformation[source]¶
Measure how much of a posterior the data determined, mode by mode.
- Parameters:
target (Posterior or InferenceContext or Fitter) – A completed fit, or a context to expand around
params.params (dict of str to float, optional) – Point to expand the posterior around, in physical units. Default
Noneuses the posterior’s own point estimate, which is where the quadratic approximation is tightest.key (jax.Array, optional) – PRNG key, used only when
targetsupplies no point estimate and an initial position must be drawn.
- Returns:
n_eff, per-mode shrinkage, and the per-parameter attribution.- Return type:
- Raises:
ValueError – If the Hessian at the expansion point is not finite.
Notes
Not JIT-compatible, and not cheap: one dense Hessian of the log-posterior, which costs \(O(D)\) gradient evaluations. Call it once on a finished fit, never inside a sampling loop.
The expansion is a Laplace approximation, so the answer describes the posterior near the given point. For a strongly multimodal posterior it characterizes the mode it was handed, which is the same caveat that applies to any curvature-based error bar.
Examples
>>> post = model.fit(data, noise, method="map") >>> info = parameter_information(post) >>> print(info.summary()) >>> info.n_eff 4.17
- class tengri.ParameterInformation(names: tuple[str, ...], eigenvalues: ndarray, shrinkage: ndarray, directions: ndarray, newton_decrement: float = nan)[source]¶
Bases:
objectThe measured-versus-prior decomposition of one posterior.
- Variables:
names (tuple of str) – Free-parameter names, in the order of the precision matrix.
eigenvalues (ndarray, shape (n_free,)) – Posterior precision per mode [dimensionless], ascending. The standardized prior contributes 1 to each.
shrinkage (ndarray, shape (n_free,)) – Fraction of each mode’s precision supplied by the data [dimensionless], in
[0, 1], aligned witheigenvalues.directions (ndarray, shape (n_free, n_free)) – Eigenvectors as columns, aligned with
eigenvalues.
- property at_a_mode: bool¶
Whether the expansion point is close enough to a mode to trust this.
- Returns:
Truewhen the Newton decrement puts the remaining log-posterior improvement belowMODE_TOLERANCE_NATS.Truealso when no gradient was supplied, since there is then nothing to contradict.- Return type:
Notes
Curvature is the posterior precision only at a stationary point. Evaluated part-way through an optimization it is just the local second derivative, and the resulting
n_effis meaningless while looking entirely reasonable, measured at 17.6 against a converged 6.3 on the same model and data.
- by_parameter() dict[str, float][source]¶
Attribute the measured directions back to named parameters.
- Returns:
Each parameter’s share of
n_eff[dimensionless].- Return type:
dict of str to float
Notes
Mode
kis spread over parameters by its squared projection \(v_{ki}^2\). Because the eigenvectors are orthonormal, each mode’s projections sum to 1, so the shares sum ton_effexactly, the attribution redistributes the total rather than inventing any of it.A mode is a combination of parameters, so a large share means the data constrained something that parameter participates in, not that the parameter is individually identified. Two perfectly degenerate parameters split one measured direction evenly.
- restrict(prefix: str) ParameterInformation[source]¶
Information content of one block of parameters, on its own.
- Parameters:
prefix (str) – Name prefix selecting the block, e.g.
"psd_xi"for the stochastic field or"dust_"for the attenuation parameters.- Returns:
Decomposition of the corresponding sub-block of the precision matrix.
- Return type:
- Raises:
ValueError – If no parameter name starts with
prefix.
Notes
This takes the sub-block of the precision matrix and re-diagonalizes it. It is not a slice of the full decomposition, and the two answer different questions:
n_effof the whole model counts every measured direction, including ones that mix the block with everything else;restrict(...).n_effcounts what the data measured about this block with the rest of the model held fixed, the conditional, not the marginal, so it is an upper bound on the block’s own information.
Comparing the two across papers without saying which was used is how “the SFH has 4 modes” and “the fit has 5 modes” turn into an argument. For the field the block is
psd_xi: components spell the same quantitysfh_field_xi, but the latent dict, which is what gets raveled, keys itpsd_xi(the #1271 two-spelling seam).Examples
>>> info = posterior.information() >>> info.n_eff, info.restrict("psd_xi").n_eff (4.91, 3.21)
Sample raytrace¶
- tengri.sample_raytrace(key, params_init, log_prob_fn, n_steps, n_leapfrog_steps, step_size, refresh_rate=0, metro_check=1, sample_hmc=False, integrator='dkd')[source]¶
Run Ray Tracing Sampler and return the full Markov chain.
- Parameters:
key (PRNGKey) – Random key.
params_init (array) – Initial parameter values (flat 1D array).
log_prob_fn (callable) – Function mapping params → scalar log probability.
n_steps (int) – Number of MCMC steps (samples to collect).
n_leapfrog_steps (int) – Leapfrog integration steps per trajectory.
step_size (float) – Leapfrog step size. Recommended: ~0.03 * sqrt(D).
refresh_rate (float) – Partial momentum refresh rate. 0 = no refresh.
metro_check (int) – 1 = apply Metropolis correction, 0 = skip.
sample_hmc (bool) – If True, use HMC instead of ray tracing.
integrator (str) – Leapfrog integrator scheme:
"dkd"(Drift-Kick-Drift, default) or"kdk"(Kick-Drift-Kick). KDK is the time-reversed partner of DKD. Both are symplectic and second-order. DKD matches Behroozi’s reference implementation.
- Returns:
chain (array, shape (n_steps, D)) – Parameter samples.
log_likelihood (array, shape (n_steps,)) – Log-likelihood at each accepted sample.
accept_prob (array, shape (n_steps,)) – Acceptance probability at each step.
n_nonfinite_proposals (int) – Count of steps where log_accept_prob was non-finite (NaN/Inf).
Notes
JIT-compatible: no, wraps blackjax sampler with Python-level loop.
Gradient-safe: no, MCMC sampler, not a differentiable operation.
Examples
>>> import jax >>> import jax.numpy as jnp >>> from tengri import sample_raytrace >>> key = jax.random.PRNGKey(0) >>> log_prob_fn = lambda x: -0.5 * jnp.sum(x**2) >>> chain, lnl, acc, n_nonfinite = sample_raytrace( ... key, jnp.zeros(5), log_prob_fn, n_steps=10, n_leapfrog_steps=5, step_size=0.1 ... ) >>> chain.shape (10, 5)