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: object

Inference 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 by load() from the file save() wrote.

Returns:

Posterior instance with results populated.

Return type:

Posterior

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"). None for point estimates (MAP, Laplace, Pathfinder). Free parameters only (#2296): a key the spec declared Fixed never appears here, see fixed_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 into model.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_err is the standard deviation of log Z [nats], sqrt(H / n_eff); information_nats is the information H [nats] (Kullback-Leibler divergence of the posterior from the prior); n_live_effective is 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,). None for sampling methods.

  • log_evidence (float or None) – Bayesian evidence log(Z) integral (NSS only). None for 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 by Fitter.run() automatically.

  • eline_fluxes (ndarray or None) – Emission line fluxes. Shape (n_lines,) for MAP, (n_samples, n_lines) for sampling. None if 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. None if unavailable.

  • eline_names (tuple or None) – Emission line identifiers (e.g., ("Halpha", "Hbeta", ...)) matching eline_fluxes column order.

  • eline_wavelengths (ndarray or None) – Rest-frame vacuum wavelengths [Angstrom] of emission lines, matching eline_fluxes column order.

Notes

Derived quantities: The derived property 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(), and balmer_decrement() provide astrophysical diagnostics on emission lines. Require eline_mode != "none" in Spectroscopy config.

Convergence diagnostics: Use check_convergence(), autocorrelation(), and effective_sample_size() to assess MCMC chain quality.

Resampling and refinement: Use resample() to draw new samples from the posterior, and refine() to improve results by running additional inference iterations (requires _fitter).

See also

Fitter.run

Returns Posterior with all attributes populated.

Fitter

Primary 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, call sed_components directly and compute percentiles on sed_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:

dict

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:

dict

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:

tuple

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:

tuple

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:

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_samples array 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:

dict

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 properties instead, 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"] becomes posterior.properties["stellar_mass"] (or posterior.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:

dict

Notes

This is a cached property, computed on first access and cached thereafter. Requires _model to be set (populated automatically by Fitter.run()). For stochastic SFH, unresolved bursts are included in sfr_10myr and sfr_100myr outputs.

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: dict
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:

str

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:

dict

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")
eline_flux_cov: Array | None = None
eline_fluxes: Array | None = None
eline_names: tuple | None = None
eline_wavelengths: Array | None = None
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:
  • window_aa (float, optional) – Half-width of the line integration window [Angstrom]. Default 20.

  • continuum_width_aa (float, optional) – Width of each sideband used to estimate the continuum [Angstrom]. Sidebands sit at [lambda_0 +/- window +/- continuum_width]. Default 50.

Returns:

{line_name: (median_EW, lo_68, hi_68)} in [Angstrom]. For MAP results, all three values coincide.

Return type:

dict

Raises:

ValueError – If eline_fluxes / eline_wavelengths are unavailable, or if no _model is 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; params and samples carry free parameters only and are safe to feed back into model.predict(...).

When this posterior carries a _fitter back-reference (set by model.fit(...) / fitter.run(...)), the values come from fitter._fixed_values – the spec’s declared values merged with any Fitter(params_override=...) re-pin (#1329), which is the sanctioned way to fit at a different Fixed value for one fit. Reading straight off self._model.spec instead 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-built Posterior).

Under ``profile_mass`` (#2296): fitter.spec is 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_mass writes the real, analytically profiled mass into params/samples, so without filtering, the same parameter would appear in BOTH params (the real value) and fixed_values (the stale placeholder) – and worse, a caller checking name in posterior.fixed_values to decide “is this Fixed on the user’s model” would get the wrong answer. Keep only the names that are actually Fixed on self._model.spec.

Returns:

Fixed parameter name → value. Empty dict if the posterior has no model and no fitter (hand-built posteriors).

Return type:

dict

property free_names: tuple[str, ...] | None

Parameters the sampler moved, or None when the posterior has no model.

samples holds every parameter the forward model consumes: the Fixed ones ride along as constant arrays (Fitter._to_physical broadcasts 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 _model cannot tell and gets None (#2087).

spec.free_params excludes the stochastic-SFH field latent by design: it rides under the sampler’s key psd_xi (republished as sfh_field_xi by Fitter._to_physical), not as a named distribution (see Parameters.n_latent). A frozen field is exactly as dead as a frozen named parameter, so when the spec is stochastic and psd_xi is present in samples, it is appended here too.

A posterior loaded from disk has no model, but save() writes the names into the file and load() 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 None uses 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:

ParameterInformation

Warns:

RuntimeWarning – If the expansion point is not a mode, in which case the curvature is not the posterior precision and n_eff means nothing. This fires more often than expected: on a 25-parameter field model an under-converged MAP reported n_eff 17.6 where the converged fit gives 4.9.

See also

tengri.parameter_information

the 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:

dict

Raises:

ValueError – If no emission line fluxes are available. Set eline_mode="marginalized" or "fitted" in Spectroscopy to 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:
  • path (str) – Path to HDF5 file saved by save().

  • model (SEDModel, optional) – Model reference for derived quantity computation. If provided, enables derived, plot_sed(), plot_sfh().

Returns:

Loaded posterior with all attributes restored.

Return type:

Posterior

Notes

Reads HDF5 file saved by save(). The _fitter back-reference is not restored (it is runtime-only). To use refine() or validate(), set the _fitter attribute manually or reload using model.fit(...). Provide model to enable derived quantity computation.

Examples

>>> result = Posterior.load("posterior_result.h5", model=model)
>>> print(result.summary_table())
>>> result.properties["stellar_mass"]  # requires ``model``
log_evidence: float | None = None
loss_history: Array | None = None
method: str
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=True opts into the lean build-time path (the approx= 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 spelled fast until 2026-08.

Parameters:
  • filters (sequence of str or FilterCurve, or Photometry, optional) – Bands to integrate, filter names (["jwst_f356w", ...]), curves, or a prebuilt Photometry. Accepts exactly what Prediction.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. None uses every draw, which for a large posterior is exactly the memory problem vmap_chunked() exists to bound, so it is chunked either way.

  • approx (bool, default False) – Route through the lean predict_photometry (whatever build-time approx= 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_draws is given. Defaults to PRNGKey(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)
params: dict
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 _model is 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_draws parameter samples from the posterior, computes the rest-frame SED for each, and shades the 16th–84th percentile band around the median.

Parameters:
  • n_draws (int) – Number of posterior draws to use for the band. Ignored for MAP results (plots single SED).

  • wave_range ((float, float)) – Wavelength range in [Angstrom] to display.

  • ax (matplotlib Axes, optional) – Axes to plot on. Creates new figure if None.

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 _model to be available (set by model.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 _model to be available (set by model.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_draws is given.

Returns:

Input of tengri.inference.waic(), tengri.inference.loo() and tengri.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_photometry and 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 via resample() (with replacement) using key.

  • key (PRNGKey, optional) – JAX PRNG key for resampling. If None, defaults to jax.random.PRNGKey(0).

Returns:

predictions: shape (N, n_obs), residuals: (data - prediction) / noise of 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). N is 1 for MAP, otherwise n_samples (or the full chain length if n_samples is None).

Return type:

dict

Raises:

ValueError – If no _model is 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.normal on top of predictions.

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 Prediction uses; 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 verb ci(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

PosteriorProperties

the catalog object.

tengri.vmap_chunked

the 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() or fitter.run(), both set the ._fitter back-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:

Posterior

Raises:

RuntimeError – If ._fitter is 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:

dict

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:

dict

Raises:

ValueError – If this is a MAP result (no samples to split).

See also

tengri.analysis.diagnostics.autocorrelation.split_rhat

Underlying 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:

dict

samples: dict | None
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 parameters

  • runtime_values: this galaxy’s runtime values, e.g. its redshift (if any); restored into _runtime_values by load()

  • loss_history: optimization loss over iterations (if available)

  • diagnostics: method-specific convergence metrics

  • eline: emission line fluxes, covariances, names, wavelengths

and root attributes method, wall_time_s, log_evidence (when set) and free_names (when the posterior knows which parameters were free), the last so a reload without model= 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: wavelength plus the entries of Posterior._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). The sed_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:

dict

Raises:

ValueError – If no _model is 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 into state.derived. sed_total is the accumulated state.sed_intrinsic after the chain runs; sed_intrinsic (stellar pre-attenuation) is reconstructed from the published lnu_age cube via sum(lnu_age, axis=0).

For Posterior draws the orchestrator pass runs once per sample, compiled in chunks of _DRAW_CHUNK draws (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 of Prediction.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=True opts into the build-time approx= 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). None uses every draw, chunked either way.

  • approx (bool, default False) – Route through the lean predict_spectrum (build-time SpectrumPrecomp) instead of the exact projector.

  • key (PRNGKey, optional) – Used only when n_draws is given. Defaults to PRNGKey(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_obs was 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:

dict

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_str returns 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:

str

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:

Parameters

Notes

For MAP results, all parameters become Fixed at the MAP value. For sampling methods, each parameter gets a Gaussian prior with:

  • mean: median of samples

  • sigma: standard deviation of samples

  • bounds: [min, max] from samples (clipping)

Inherits stochastic and n_grid settings 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_samples of 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:

dict

Raises:

RuntimeError – If ._fitter is 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}")
wall_time_s: float

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: object

Inference 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 observation configuration. [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". If None (default), inferred from model.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 corresponding data entry carries the limit value. Default None (all detected). Boolean arrays are rejected: True would silently be read as “upper limit”, the opposite of the include/exclude semantics a boolean mask suggests. To exclude a datum, drop it from data and noise (or inflate its noise).

  • presence (array_like or None) – Optional exact 0/1 presence of the photometric bands: 0 marks a band absent and it contributes nothing to the likelihood or its gradient. The length is the number of photometric bands: len(data) for data_type="photometry", and model.observation.n_data_phot for "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 raises ValueError stating the expected length. Default None (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 when data_type ∈ {"spectroscopy", "joint"}. Follows Prospector (Johnson et al. 2021). Default False.

  • cal_n_poly (int, optional) – Number of Chebyshev polynomial coefficients for calibration marginalization (order 1 through cal_n_poly). Default 3.

  • 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’s Spectroscopy config (checks eline_mode == "marginalized").

  • eline_prior_type (str or None, optional) – Prior type for emission line marginalization: "flat" (uniform) or "cloudy" (grid-interpolated from Cloudy models). None auto-detects from Spectroscopy.eline_prior_type. Default None.

  • compile_modes (tuple[str, ...] or str or None, optional) –

    Control background JIT compilation during __init__. Accepted values:

    • None (default) → no background compile; first run() compiles lazily.

    • "auto" → inspect spec.stochastic and data_type to 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 first run() call. See compile() 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 raises ValueError, naming the free parameters instead). This is NOT the same channel as a params dict handed to a predict surface – those refuse a Fixed key outright (#2296) and never accept an override; params_override is the one place a Fixed value can be re-pinned, and it is checked, not merged silently. Default None (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 remaining D - 1 parameters and the mass is drawn from its exact conditional posterior afterward (or set to its conditional mode for method="map"). Supports photometry, spectroscopy, or joint photometry + spectroscopy data with a Gaussian likelihood, exactly one free *_log_total_mass parameter with a bounded-support prior, and data that is numerically linear in that parameter; see tengri.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 one logging.INFO line naming the reason. True raises ValueError naming the first failed guard instead of falling back; False disables profiling unconditionally. The resolved choice and reason are always recorded in Posterior.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, where params is the resolved physical parameter dict (free + fixed, mirrors merged) and state is self.model.predict_state(params) (a ForwardState). Added to the physical-space log-prior built by build_logprior_fn() (used by nested sampling / evidence computation, and available to any caller via fitter._build_logprior_fn()). Must be JIT/grad-safe: pure, no Python-level branching on traced values. Default None (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 published state.derived keys.)

  • 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|), the ln sigma_eff term kept). Active only when the backend publishes published_line_model_sigma and it is nonzero for the fitted lines. False scores 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. Default True.

Returns:

Fitter instance with loss function compiled and ready for inference.

Return type:

Fitter

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_modes parameter (default None = no background thread). The first run() call will compile lazily. Set compile_modes="auto" or compile_modes=("mcmc_nuts",) to spawn a daemon thread and pre-compile specified inference modes before run() is called (typically <1s if warm, or the full compile time on cold XLA). Set TENGRI_NO_BACKGROUND_COMPILE=1 in the environment to disable even when compile_modes is 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 a ForwardModel, 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 the Fitter yourself 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_iterations at run time does NOT trigger recompilation (the iteration count is a dynamic traced value).

  • n_samples (int) – Compile for this sample count. Changing n_samples at 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. After fitter.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; setting nss=True moves that cost to compile time. data_args is 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.jit on the forward model’s SED prediction and inference engines, storing compiled XLA programs to disk. First fitter.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_2arg identity, n_warmup, n_burnin, n_mcmc_samples, and use_dense. Use the same values here as in fitter.run() to guarantee a cache hit. Changing galaxy data does not invalidate the cache (data_args is 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:

tuple

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:

list of Posterior

Notes

Parallelization strategy:

  • For method="map" with precomputed photometry: uses jax.vmap to 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 method contains "native" and n_seeds is not explicitly passed, automatically sets n_seeds=5 for 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_fingerprint does 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 same method skips 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 by run().

  • n_chains (int or None) – If set and greater than 1, also pre-compile the multichain jax.vmap path for n_chains so the second multichain call has zero compile latency. Only meaningful for backends that support n_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_chain takes n_warmup as a static argument (it is the lax.scan length) and sample_chain traces against a chain_keys array of length n_burnin + n_samples. So a default pre-warm (n_samples=10, n_warmup=300) and a fit at n_warmup=600, n_samples=600 compile four modules where the fit alone would compile two. Structural knobs are cheaper to match than budget ones: max_num_doublings, dense_mass_matrix and precondition change the program without changing how much of it runs, whereas matching n_warmup / n_samples means 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. Calling prewarm redundantly 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 Posterior object with samples, diagnostics, and derived quantities.

Hierarchical fits (model is a ForwardModel built with population=PopulationSEDModel(...)) route through tengri.PopulationFitter automatically. 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 of vi)

    • "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 in bench/reports/2026-08-30_chees_hmc.md)

    • "mcmc_smc": Tempered Sequential Monte Carlo – a particle population annealed from the exact standardized N(0, I) prior to the posterior, so it never starts at the MAP (experimental; measured in bench/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, see bench/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. Default False, which raises BackendError naming 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. Default True; pass False for the previous lazy compile-on-first-call behavior. (The fit-time approximation policy is set with approx= on the Fitter constructor / 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:

Posterior

Raises:

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. See bench/reports/2026-04-17_native_vs_nifty.md in 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=3 produces 6 effective samples (3 + 3 mirrors). When tuning convergence, think in effective samples.

  • Ray Tracing step_size scaling: Ray Tracing uses step_size=0.05 by 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 from defaults.toml if 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=None defaults to PRNGKey(42) for reproducibility.

Compile-cache behavior (smart lean, 2026-05):

run accepts a lean kwarg (default inferred from tengri.lean() / tengri.persistent() context). With lean=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 needing tengri.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 next run() 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 by load_cache() to refuse to load a cache that was written for a different model.

Parameters:

path (str or Path) – Destination file (.pkl recommended). 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:

str

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: object

Astronomer-facing catalog inference interface.

Wraps the existing per-galaxy CatalogFitter engine 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 Fixed redshift; 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 a catalog_z_range keeps 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 band i of 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 the err_cols convention.

  • 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_cols is 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 on missing="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. See ingest_catalog().

  • lim_flag ({"none", "noscaling", "full"}, optional) – CIGALE’s lim_flag convention for limits and invalid bands in the error column. See ingest_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. None adds nothing. See ingest_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_unit is 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.map step (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, None keeps 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 reports store="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 as percentile_levels and drive both post[name] (which reads the 50 column) and to_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, so post.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_samples for MCMC). Also reaches _CatalogFitterOriginal.run itself, which is how fallback="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 raises TypeError that 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 **kwargs carries 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 Catalog whose predict() 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 table SFH declares zero free parameters because the table is the SFH.

Parameters:
  • fwd (ForwardModel) – Model built with sfh={'type': 'table'} (and met={'type': 'table'} if met is 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_unit at 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 way t_gyr is. Requires the model’s metallicity_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 from met and 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_gas applies, and its declared default is a fixed 0.5 Zsun that does not follow the stellar history, so a tabulated met= alongside it emits GasStellarMetallicityWarning rather 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 met arrives 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-4 is a perfectly legal logzsol value, 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 emits MetallicityUnitWarning, 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" emits OutOfSSPGridWarning carrying 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 raising No table provided at construction.)

Return type:

Catalog

Raises:

ValueError – If the model does not declare a tabulated SFH; if met is given without a tabulated metallicity, or a tabulated metallicity is declared without met; if t_gyr is 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 default on_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_histories

The 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 declared Fixed is refused with ParameterError (#2296) rather than overriding it — rebuild the model with that parameter FREE instead. Omit param_table entirely on a catalog built by from_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:

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 Catalog directly for new code. fit_batch will 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:

list of Posterior

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:

dict

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:

  1. Compute BMA weights via bma_weights()

  2. Draw model indices via multinomial with probabilities = weights

  3. For each model, resample (with replacement) from its chain

  4. 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: object

SubModel 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_obs and noise; optionally spec_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 underlying tengri.PopulationFitter.

Variables:

name (str) – The tengri.protocols.SubModel identifier, "population_sed_model". Read-only, the protocol calls it a stable identifier, and this constructor has never accepted it.

Notes

Satisfies the tengri.protocols.SubModel Protocol. The forward-time .run path is a stub today, the batched-vmap implementation lands when ForwardModel.predict_observables learns the PopulationSEDModel case (issue #211). Inference is routed at the tengri.Fitter layer.

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. See predict_one() for the un-batched primitive.

Returns:

Map from named axis to its integer position in arrays.

Return type:

dict[str, int]

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 that Fitter accepts as the data and noise arguments 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 by ForwardModel.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_obs or noise.

data_type: str = 'photometry'
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).

galaxies: tuple[Mapping[str, Any], ...]
property n_galaxies: int
name: str = 'population_sed_model'

The SubModel identifier. init=False because the protocol calls it a stable identifier: this constructor never accepted it, and an ordinary field declaration advertised otherwise to dataclasses.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:

  1. Names in shared always broadcast, axis None.

  2. Rank-0 / scalar values (e.g. fixed values like redshift merged from spec) also broadcast, axis None.

  3. 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.

Parameters:

params (Mapping[str, Any]) – The parameters dict that run will be called with.

Returns:

One entry per key in params.

Return type:

dict[str, int | None]

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_one evaluates 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 outer vmap. Use run() 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_galaxies axis).

Returns:

Single-galaxy state. No leading galaxy axis.

Return type:

ForwardState

Notes

Pure JAX. JIT/grad/vmap/pmap-compatible. Forwarding to self.sed.run is a no-op layer that exists so external callers can compose their own batching without nesting run()’s internal vmap.

priors: Mapping[str, tuple[float, float]]
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 returned ForwardState has a leading N_galaxies axis on every array leaf (sed_intrinsic, sed_observed, sed_attenuated, …).

The population is evaluated chunk_size galaxies at a time: the per-galaxy axis is padded to a whole number of chunks, reshaped to (n_chunks, chunk_size) and looped with jax.lax.map(), each chunk a vmap of predict_one(). The padding is trimmed before return.

See docs/internal/plans/2026-05-22-population-sed-batched-forward.md for 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; None and non-int values raise ValueError.

Returns:

Batched state: every per-galaxy quantity has a leading N_galaxies axis.

Return type:

ForwardState

Raises:

ValueError – If chunk_size is 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, and run may sit inside an outer jit, grad or vmap with no unrolling. The template’s run must be traceable (the same requirement as the unchunked vmap).

Chunking is not bit-neutral: XLA compiles a different kernel for each chunk shape, so changing chunk_size can move the last bit (about 1 ULP). Pin chunk_size when 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, call predict_one() directly with your own vmap / pmap / shard_map. The batched_axes property publishes the axis layout so external code can stay axis-aware.

sed: Any
shared: tuple[str, ...]
property spec

The batched-sample Parameters-shaped view.

Returns a PopulationSpecView wrapping the SED template’s scalar spec. Implements the same implicit Protocol Fitter consumes (free_params, get_fixed_values, sample(key), _distributions, …), but sample() 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.spec to 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: object

Hierarchical 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 the WavePrecomp LUT, 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. None forces 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 NIFTy optimize_kl (default).

    • "vi_nonlinear": geoVI; same runner as fast, kept for API symmetry.

    • "vi_linear_fast": MGVI via NIFTy optimize_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 inside lax.while_loop. 3–4× faster than NIFTy MGVI on CPU; O(1) memory in N.

    • "native_vi_nonlinear": geoVI inside lax.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 via allow_unvalidated=True, but validate per-problem before relying on one. They are also not posterior-equivalent to the NIFTy path: the fitted PSD timescale sfh_field_psd_tau_myr has 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_linear was the default from b7c4fa1e2 until 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 own ValueError for an unknown method went on naming vi_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 raises DegenerateChainError rather 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), requires allow_unvalidated=True.

    • "mcmc_ghmc": generalized (persistent-momentum) HMC; tier=”broken” ([POOR MIXING] on the single-galaxy benchmarks), requires allow_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); requires allow_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 returns log_evidence (hierarchical model comparison). Requires nss_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 shrink n_grid at 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:

PopulationPosterior

Notes

Unlike Fitter.run(), PopulationFitter.run() does not support warm-start initialization via init_from because hierarchical inference methods (EVI, CFM-based geoVI, Ray Tracing) initialize per-galaxy parameters via MAP estimation automatically. The init_from parameter 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, PopulationFitter does not expose an n_pad argument: 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, see tengri.enable_persistent_cache() and docs/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: object

Results 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"))
diagnostics: dict
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 if individual_samples is None.

Return type:

list of SimpleNamespace

Notes

Each per-galaxy posterior is marginalized over the shared PSD hyperparameters. The .params field contains the median of each per-galaxy parameter.

individual_samples: list | None = None
method: str = ''
plot_population(params=('sfh_field_psd_sigma', 'sfh_field_psd_tau_myr'), ax=None)[source]

Scatter plot of shared PSD parameter posteriors.

Parameters:
  • params (tuple of str) – Two parameter names for x and y axes.

  • ax (matplotlib Axes, optional) – If None, creates a new figure.

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_samples is 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 high rhat_max with low rhat_p50 is the signature.

Return type:

dict

Notes

Reuses tengri.analysis.diagnostics.autocorrelation.rhat() and tengri.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)
shared_params: dict
shared_samples: dict
summary() → dict[source]

Median and 68% CI for shared PSD parameters.

Parameters:

None

Returns:

Dictionary mapping parameter names to summary statistics. Each parameter has keys ‘median’, ‘lo_68’ (16th percentile), and ‘hi_68’ (84th percentile).

Return type:

dict

wall_time_s: float = 0.0

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 None uses the posterior’s own point estimate, which is where the quadratic approximation is tightest.

  • key (jax.Array, optional) – PRNG key, used only when target supplies no point estimate and an initial position must be drawn.

Returns:

n_eff, per-mode shrinkage, and the per-parameter attribution.

Return type:

ParameterInformation

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: object

The 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 with eigenvalues.

  • 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:

True when the Newton decrement puts the remaining log-posterior improvement below MODE_TOLERANCE_NATS. True also when no gradient was supplied, since there is then nothing to contradict.

Return type:

bool

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_eff is 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 k is 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 to n_eff exactly, 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.

directions: ndarray
eigenvalues: ndarray
property n_eff: float

Effective number of directions the data measured [dimensionless].

property n_total: int

Number of free parameters, i.e. the ceiling on n_eff.

names: tuple[str, ...]
newton_decrement: float = nan
precision() → ndarray[source]

Rebuild the precision matrix this decomposition came from.

Returns:

\(V \Lambda V^T\) [dimensionless]. Exact to floating point, the eigendecomposition of a symmetric matrix loses nothing.

Return type:

ndarray, shape (n_free, n_free)

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:

ParameterInformation

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_eff of the whole model counts every measured direction, including ones that mix the block with everything else;

  • restrict(...).n_eff counts 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 quantity sfh_field_xi, but the latent dict, which is what gets raveled, keys it psd_xi (the #1271 two-spelling seam).

Examples

>>> info = posterior.information()
>>> info.n_eff, info.restrict("psd_xi").n_eff
(4.91, 3.21)
shrinkage: ndarray
summary() → str[source]

One-screen report: the total, then the worst-measured parameters.

Returns:

Formatted table. Printing it is the intended use.

Return type:

str

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)