# SPDX-License-Identifier: BSD-3-Clause
"""Lazy prediction object for derived physical quantities.
The :class:`Prediction` class provides on-demand computation of derived
quantities from a tengri forward model. Properties are only computed
when first accessed, and intermediate results (SFR, SED, emission lines)
are cached so related quantities share the expensive computation.
Two usage modes
---------------
**Mode 1, Single-galaxy exploration (lazy):**
.. code-block:: python
pred = model.predict(params)
# SFH quantities, triggers only SFH computation (~100 μs)
pred.sfh.stellar_mass
pred.sfh.mass_weighted_age_gyr
# SED quantities, triggers full SED computation (~300 μs)
pred.sed.l_bol
pred.sed.uv_slope_beta
pred.sed.dn4000
# Emission lines, triggers nebular computation (~200 μs)
pred.lines.halpha
pred.lines.bpt_nii
# Radio and X-ray (empirical scaling relations)
pred.radio.l_1p4ghz
pred.xray.l_x_xrb
**Mode 2, Population / batch computation (JIT + vmap):**
For computing derived quantities over many parameter sets (posterior
chains, mock catalogs), use the JIT-compatible group methods instead:
.. code-block:: python
import jax
# Batch of 10,000 parameter sets
params_batch = spec.sample_batch(jax.random.PRNGKey(0), n=10_000)
# vmap over SFH quantities, returns SFHQuantities with shape (10000,)
sfh_fn = jax.vmap(model.predict_sfh_quantities)
sfh_batch = sfh_fn(params_batch)
sfh_batch.stellar_mass # shape (10000,)
# vmap over SED quantities, returns SEDQuantities
sed_fn = jax.vmap(model.predict_sed_quantities)
sed_batch = sed_fn(params_batch)
sed_batch.m_uv # shape (10000,)
The lazy :class:`Prediction` object is NOT JIT-compatible (it uses
Python-level caching). For inference loops and batches, always use
the JIT-compatible methods (``predict_sfh_quantities``, etc.).
Caching hierarchy
-----------------
Three computation levels, triggered on demand:
============ ============================ ==========
Level Triggered by Approx cost
============ ============================ ==========
**SFH** Any ``pred.sfh.*`` ~100 μs
**SED** Any ``pred.sed.*`` ~300 μs
**Lines** Any ``pred.lines.*`` ~200 μs
============ ============================ ==========
Each level auto-triggers its dependencies: SED triggers SFH first;
Lines triggers SFH first. Luminosity-weighted quantities in
``pred.sfh`` trigger SED (they need per-bin luminosities).
"""
from typing import NamedTuple
import jax.numpy as jnp
from tengri._deprecated import UNSET, resolve_renamed_flag
from tengri._mapping import ReadOnlyPropertyMapping
class _SEDCallable:
"""A callable SED accessor that refuses to be mistaken for an array.
``pred.rest_sed`` / ``pred.obs_sed`` are *methods*, ``pred.rest_sed()``
gives the model's own grid, ``pred.rest_sed(wave)`` resamples onto yours
(contract §4b.3: uniform callables with defaults, like ``photometry()``
and ``spectrum()``).
They were briefly plain properties. Had they simply become methods, the
forgotten-parenthesis mistake would fail *silently*: ``np.asarray`` of a
bound method yields a ``dtype=object`` array, which plots and arithmetics
happily turn into garbage rather than an exception. Every numeric dunder
below therefore raises with the fix spelled out. Failing loudly on a
misuse is the whole point, this package has shipped enough silent
NaN-and-carry-on bugs already.
"""
__slots__ = ("_fn", "_name")
def __init__(self, fn, name):
self._fn = fn
self._name = name
def __call__(self, wave=None):
return self._fn(wave)
def _not_an_array(self, *_args, **_kwargs):
raise TypeError(
f"Prediction.{self._name} is a method, not an array, you left off the "
f"parentheses. Use pred.{self._name}() for the model's own grid, or "
f"pred.{self._name}(wave) to resample onto your own grid [Angstrom]. "
f"The matching wavelength axis is pred."
f"{'wave_rest' if self._name == 'rest_sed' else 'wave_obs'}."
)
# Everything that would otherwise silently coerce to a dtype=object array.
__array__ = _not_an_array
__len__ = _not_an_array
__iter__ = _not_an_array
__getitem__ = _not_an_array
__add__ = __radd__ = _not_an_array
__sub__ = __rsub__ = _not_an_array
__mul__ = __rmul__ = _not_an_array
__truediv__ = __rtruediv__ = _not_an_array
def __repr__(self):
return f"<Prediction.{self._name}(wave=None), a method; call it to get the array>"
# ── Module-level warn-once guard ──────────────────────────────────
_WARNED_RUNTIME_PHOTOMETRY = False
def _warn_runtime_photometry_once():
"""Issue one-time warning for runtime photometry filter construction."""
global _WARNED_RUNTIME_PHOTOMETRY
if not _WARNED_RUNTIME_PHOTOMETRY:
import warnings
_WARNED_RUNTIME_PHOTOMETRY = True
warnings.warn(
"Runtime filter resolution (Photometry.from_names) uses the exact path "
"(full SED integration) and is slower than build-time filters. "
"For repeated calls with the same filters, cache the result. "
"For significantly faster photometry, rebuild the model with "
"approx=WavePrecomp() and use pred.photometry(approx=True).",
UserWarning,
stacklevel=4,
)
# ── NamedTuples for JIT-compatible batch computation ──────────────
[docs]
class SFHQuantities(NamedTuple):
"""Derived quantities from the star formation history.
All fields are JAX arrays (scalars). This is a proper JAX pytree,
so it works with ``jax.jit``, ``jax.vmap``, and ``jax.grad``.
Attributes
----------
stellar_mass : jnp.ndarray
Total formed stellar mass [Msun].
stellar_mass_surviving : jnp.ndarray
Surviving mass in living stars + remnants [Msun].
Returns NaN if the mass-remaining table was not loaded.
sfr_100myr : jnp.ndarray
Star formation rate averaged over the last 100 Myr [Msun/yr].
sfr_10myr : jnp.ndarray
Star formation rate averaged over the last 10 Myr [Msun/yr].
ssfr : jnp.ndarray
Specific star formation rate SFR/M* [1/yr].
mass_weighted_age_gyr : jnp.ndarray
Mass-weighted stellar age [Gyr].
mass_weighted_metallicity : jnp.ndarray
Mass-weighted metallicity log10(Z), evolving-Z aware.
Returns
-------
This is a NamedTuple (JAX pytree) returned by
:meth:`SEDModel.predict_sfh_quantities`.
Notes
-----
JAX-compatible array container. All fields are JAX arrays compatible with
``jax.jit`` and ``jax.vmap``. Returned by :meth:`SEDModel.predict_sfh_quantities`
and :attr:`Prediction.sfh` when accessed.
Examples
--------
>>> import jax.numpy as jnp
>>> from tengri import SFHQuantities
>>> q = SFHQuantities(
... stellar_mass=jnp.array(1e10),
... stellar_mass_surviving=jnp.array(6e9),
... sfr_100myr=jnp.array(5.0),
... sfr_10myr=jnp.array(8.0),
... ssfr=jnp.array(5e-10),
... mass_weighted_age_gyr=jnp.array(3.5),
... mass_weighted_metallicity=jnp.array(-0.5),
... )
>>> float(q.stellar_mass)
10000000000.0
>>> "stellar_mass" in q._fields and "sfr_100myr" in q._fields
True
"""
stellar_mass: jnp.ndarray
stellar_mass_surviving: jnp.ndarray
sfr_100myr: jnp.ndarray
sfr_10myr: jnp.ndarray
ssfr: jnp.ndarray
mass_weighted_age_gyr: jnp.ndarray
mass_weighted_metallicity: jnp.ndarray
[docs]
class SEDQuantities(NamedTuple):
"""Derived quantities from the spectral energy distribution.
All fields are JAX arrays. Proper JAX pytree for ``jit``/``vmap``.
Attributes
----------
l_bol : jnp.ndarray
Bolometric luminosity [Lsun].
l_tir : jnp.ndarray
Total infrared luminosity 8–1000 μm [Lsun].
l_dust_absorbed : jnp.ndarray
Dust-absorbed luminosity [Lsun]. Returns NaN if no intrinsic SED.
irx : jnp.ndarray
Infrared excess log10(L_TIR / νLν_1600) [dimensionless].
uv_slope_beta : jnp.ndarray
UV spectral slope β in range 1250–2600 Å [dimensionless].
dn4000 : jnp.ndarray
Narrow 4000 Å break, Balogh et al. 1999 [dimensionless].
balmer_break : jnp.ndarray
Modified Balmer break, Wang et al. 2024 [dimensionless].
m_uv : jnp.ndarray
Absolute UV magnitude at rest-frame 1500 Å [AB].
fuv_flux : jnp.ndarray
Mean flux density in FUV 1000–1700 Å [erg/s/Hz].
nuv_flux : jnp.ndarray
Mean flux density in NUV 1700–3200 Å [erg/s/Hz].
fuv_flux_intrinsic : jnp.ndarray
Dust-free FUV flux [erg/s/Hz]. Returns NaN if no intrinsic SED.
nuv_flux_intrinsic : jnp.ndarray
Dust-free NUV flux [erg/s/Hz]. Returns NaN if no intrinsic SED.
rest_uv_color : jnp.ndarray
U-V AB color: top-hats 3200–3900 Å minus 5000–5800 Å on rest-frame L_nu [AB magnitudes].
luminosity_weighted_age_gyr : jnp.ndarray
Luminosity-weighted age [Gyr].
luminosity_weighted_metallicity : jnp.ndarray
Luminosity-weighted metallicity log10(Z).
Returns
-------
This is a NamedTuple (JAX pytree) returned by
:meth:`SEDModel.predict_sed_quantities`.
Notes
-----
JAX-compatible array container. All fields are JAX arrays compatible with
``jax.jit`` and ``jax.vmap``. Returned by :meth:`SEDModel.predict_sed_quantities`
and :attr:`Prediction.sed` when accessed.
Examples
--------
Access via :attr:`Prediction.sed` after calling :meth:`SEDModel.predict`:
.. code-block:: python
pred = model.predict(params)
sed = pred.sed # SEDQuantities NamedTuple
print(float(sed.l_bol)) # bolometric luminosity [Lsun]
print(float(sed.dn4000)) # 4000 Å break strength
print(float(sed.uv_slope_beta)) # UV slope beta
"""
l_bol: jnp.ndarray
l_tir: jnp.ndarray
l_dust_absorbed: jnp.ndarray
irx: jnp.ndarray
uv_slope_beta: jnp.ndarray
dn4000: jnp.ndarray
balmer_break: jnp.ndarray
m_uv: jnp.ndarray
fuv_flux: jnp.ndarray
nuv_flux: jnp.ndarray
fuv_flux_intrinsic: jnp.ndarray
nuv_flux_intrinsic: jnp.ndarray
rest_uv_color: jnp.ndarray
luminosity_weighted_age_gyr: jnp.ndarray
luminosity_weighted_metallicity: jnp.ndarray
[docs]
class EmissionLines(NamedTuple):
"""Emission line luminosities, headline survey lines plus the full backend catalog.
**Units: every field is in erg/s.** This is the NamedTuple returned by
:meth:`SEDModel.predict_emission_lines` and built by
:func:`tengri.forward.state_to_emission_lines`. It is not the
:attr:`Prediction.lines` accessor, whose headline fields are in L_sun
(:class:`LineProperties`, #1206 section A).
NaN for the headline fields and empty arrays for ``all_*`` when no
nebular model is active. For doublets ([O II], C IV) the headline
fields sum both components.
The full ~138-line Cue catalog (and the generally smaller equivalent
grids for CloudyGrid, CB19 and MAPPINGS) is exposed via :attr:`all_waves`
/ :attr:`all_lums` so users can read
species the headline NamedTuple does not name explicitly (HeII 1640,
HeI 10830, NIII] 1750, [O III] 4363, etc.). See :meth:`get` for the
nearest-wavelength accessor.
Attributes
----------
lya : jnp.ndarray
Lyman-alpha at 1216 Å [erg/s].
civ_1549 : jnp.ndarray
C IV doublet 1548+1551 Å, summed [erg/s].
oii : jnp.ndarray
[OII] doublet 3726+3729 Å, summed [erg/s].
hbeta : jnp.ndarray
H-beta at 4861 Å [erg/s].
oiii_4959 : jnp.ndarray
[OIII] at 4959 Å [erg/s].
oiii_5007 : jnp.ndarray
[OIII] at 5007 Å [erg/s].
nii_6548 : jnp.ndarray
[NII] at 6548 Å [erg/s].
halpha : jnp.ndarray
H-alpha at 6563 Å [erg/s].
nii_6584 : jnp.ndarray
[NII] at 6584 Å [erg/s].
sii_6717 : jnp.ndarray
[SII] at 6717 Å [erg/s].
sii_6731 : jnp.ndarray
[SII] at 6731 Å [erg/s].
all_waves : jnp.ndarray, shape ``(n_lines,)``
Vacuum rest-frame wavelengths of every species published by the
active nebular backend [Angstrom]. Empty when the backend does
not expose a discrete catalog (BakedIn, shock).
all_lums : jnp.ndarray, shape ``(n_lines,)``
Luminosities at ``all_waves``, in the same dust regime as the
headline fields (i.e. attenuated by the active dust model when
present) [erg/s].
Returns
-------
This is a NamedTuple (JAX pytree) returned by
:meth:`SEDModel.predict_emission_lines`.
Notes
-----
JAX-compatible array container. All fields are JAX arrays compatible with
``jax.jit`` and ``jax.vmap``. All fields return NaN if no nebular model is
active in the SEDModel.
Examples
--------
.. code-block:: python
lines = model.predict_emission_lines(params) # EmissionLines, erg/s
print(float(lines.halpha)) # H-alpha luminosity [erg/s]
print(float(lines.oiii_5007)) # [OIII] 5007 Å luminosity [erg/s]
# BPT diagram
bpt_x = float(lines.nii_6584 / lines.halpha)
bpt_y = float(lines.oiii_5007 / lines.hbeta)
# Access lines outside the headline catalog via nearest-wavelength
heii_1640 = lines.get(1640.42) # closest match in ``all_waves``
``model.predict(params).lines`` is a different object (:class:`LineProperties`):
its headline fields are in L_sun, while its ``all_lums`` and ``get`` are in erg/s.
"""
lya: jnp.ndarray
civ_1549: jnp.ndarray
oii: jnp.ndarray
hbeta: jnp.ndarray
oiii_4959: jnp.ndarray
oiii_5007: jnp.ndarray
nii_6548: jnp.ndarray
halpha: jnp.ndarray
nii_6584: jnp.ndarray
sii_6717: jnp.ndarray
sii_6731: jnp.ndarray
all_waves: jnp.ndarray
all_lums: jnp.ndarray
[docs]
def get(self, wavelength: float, tol_aa: float = 2.0) -> jnp.ndarray:
"""Return the luminosity at the species nearest ``wavelength`` Å.
Parameters
----------
wavelength : float
Rest-frame vacuum wavelength to look up [Angstrom].
tol_aa : float, optional
Acceptable distance to the nearest cataloged line [Angstrom].
Returns ``nan`` if the nearest line is further than this. Default 2.0.
Returns
-------
jnp.ndarray
Luminosity at the matched line [erg/s], or ``nan`` if no line
is within ``tol_aa``. Returns ``nan`` if the active backend
did not publish a discrete catalog.
"""
if self.all_waves.size == 0:
return jnp.asarray(jnp.nan)
diff = jnp.abs(self.all_waves - jnp.asarray(wavelength))
idx = jnp.argmin(diff)
return jnp.where(diff[idx] <= tol_aa, self.all_lums[idx], jnp.asarray(jnp.nan))
[docs]
class DerivedQuantities(NamedTuple):
"""All derived physical quantities (convenience container).
Returned by ``model._predict_derived()``.
Attributes
----------
sfh : SFHQuantities
Star formation history derived quantities.
sed : SEDQuantities
Spectral energy distribution derived quantities.
Returns
-------
This is a NamedTuple (JAX pytree) returned by
:meth:`SEDModel.predict_derived`.
Notes
-----
JAX-compatible array container combining :class:`SFHQuantities` and
:class:`SEDQuantities`. Compatible with ``jax.jit`` and ``jax.vmap``.
Returned by :meth:`SEDModel.predict_derived`.
Examples
--------
.. code-block:: python
from tengri import DerivedQuantities
derived = model._predict_derived(params)
print(float(derived.sfh.stellar_mass)) # [Msun]
print(float(derived.sed.dn4000)) # 4000 Å break
print(float(derived.sed.uv_slope_beta)) # UV slope β
"""
sfh: SFHQuantities
sed: SEDQuantities
# ── Lazy property group base ──────────────────────────────────────
class _CachedBase:
"""Base class for lazy-cached prediction property groups.
Each subclass accesses the parent :class:`Prediction` object's
shared cache via ``self._pred._cache`` and triggers the appropriate
computation level via ``self._pred._ensure_*()`` methods.
"""
__slots__ = ("_pred",)
def __init__(self, prediction):
self._pred = prediction
# ── SFH properties (lazy) ─────────────────────────────────────────
class SFHProperties(_CachedBase):
"""Lazy property accessor for SFH-derived quantities.
Accessing any property triggers SFH computation (SFR, CSP weights)
if not already cached. Luminosity-weighted quantities additionally
trigger SED computation.
Attributes
----------
stellar_mass : property
Total formed stellar mass [Msun].
stellar_mass_surviving : property
Surviving stellar mass [Msun].
sfr_100myr : property
SFR averaged over 100 Myr [Msun/yr].
sfr_10myr : property
SFR averaged over 10 Myr [Msun/yr].
ssfr : property
Specific SFR [1/yr].
mass_weighted_age_gyr : property
Mass-weighted age [Gyr].
mass_weighted_metallicity : property
Mass-weighted metallicity log10(Z).
luminosity_weighted_age_gyr : property
Luminosity-weighted age [Gyr].
luminosity_weighted_metallicity : property
Luminosity-weighted metallicity log10(Z).
Notes
-----
JAX-compatible array container. Properties are lazy-cached within a
:class:`Prediction` object. Returned by :attr:`Prediction.sfh`.
Not JIT-compatible (uses Python caching). For batch computation, use
JIT-compatible methods :meth:`SEDModel.predict_sfh_quantities` instead.
Examples
--------
>>> pred = model.predict(params)
>>> pred.sfh.stellar_mass # triggers SFH computation
Array(1.23e10, dtype=float64)
>>> pred.sfh.mass_weighted_age_gyr # reuses cached weights
Array(3.45, dtype=float64)
"""
@property
def stellar_mass(self):
"""Total formed stellar mass.
Returns
-------
float
Total stellar mass ever formed [Msun].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["stellar_mass"]
@property
def stellar_mass_surviving(self):
"""Surviving stellar mass in living stars and remnants.
Returns NaN if the mass-remaining table was not loaded in the
SSP data.
Returns
-------
float
Surviving stellar mass [Msun], or NaN if mass table unavailable.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["stellar_mass_surviving"]
@property
def sfr_100myr(self):
"""Star formation rate averaged over the last 100 Myr.
Returns
-------
float
Time-averaged SFR over the last 100 Myr [Msun/yr].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["sfr_100myr"]
@property
def sfr_10myr(self):
"""Star formation rate averaged over the last 10 Myr.
Returns
-------
float
Time-averaged SFR over the last 10 Myr [Msun/yr].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["sfr_10myr"]
@property
def ssfr(self):
"""Specific star formation rate normalized by stellar mass.
Uses surviving mass if available, otherwise formed mass.
Returns
-------
float
Specific star formation rate SFR/M* [1/yr].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["ssfr"]
@property
def mass_weighted_age_gyr(self):
"""Mass-weighted stellar age.
Returns
-------
float
Age weighted by stellar mass [Gyr].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["mass_weighted_age_gyr"]
@property
def mass_weighted_metallicity(self):
"""Mass-weighted metallicity.
For single metallicity models, returns the metallicity parameter.
For evolving metallicity, computes Σ(w·Z)/Σ(w).
Returns
-------
float
Metallicity weighted by stellar mass, log10(Z).
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["mass_weighted_metallicity"]
@property
def luminosity_weighted_age_gyr(self):
"""Luminosity-weighted stellar age.
Accessing this property triggers SED computation.
Returns
-------
float
Age weighted by stellar luminosity [Gyr].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["luminosity_weighted_age_gyr"]
@property
def luminosity_weighted_metallicity(self):
"""Luminosity-weighted metallicity.
Accessing this property triggers SED computation.
Returns
-------
float
Metallicity weighted by stellar luminosity, log10(Z).
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["luminosity_weighted_metallicity"]
# ── SED properties (lazy) ─────────────────────────────────────────
class SEDProperties(_CachedBase):
"""Lazy property accessor for SED-derived quantities.
Accessing any property triggers the full SED computation (dust
attenuation, emission, AGN, etc.) if not already cached.
Attributes
----------
l_bol : property
Bolometric luminosity [Lsun].
l_tir : property
Total infrared luminosity [Lsun].
l_dust_absorbed : property
Dust-absorbed luminosity [Lsun].
irx : property
Infrared excess [dimensionless].
uv_slope_beta : property
UV spectral slope [dimensionless].
dn4000 : property
4000 Å break [dimensionless].
balmer_break : property
Balmer break [dimensionless].
m_uv : property
Absolute UV magnitude [AB].
fuv_flux : property
FUV flux density [erg/s/Hz].
nuv_flux : property
NUV flux density [erg/s/Hz].
fuv_flux_intrinsic : property
Dust-free FUV flux [erg/s/Hz].
nuv_flux_intrinsic : property
Dust-free NUV flux [erg/s/Hz].
rest_uv_color : property
U-V AB color: top-hats 3200–3900 Å minus 5000–5800 Å on rest-frame L_nu [AB magnitudes].
luminosity_weighted_age_gyr : property
Luminosity-weighted age [Gyr].
luminosity_weighted_metallicity : property
Luminosity-weighted metallicity log10(Z).
Notes
-----
JAX-compatible array container. Properties are lazy-cached within a
:class:`Prediction` object. Returned by :attr:`Prediction.sed`.
Not JIT-compatible (uses Python caching). For batch computation,
use JIT-compatible methods :meth:`SEDModel.predict_sed_quantities`.
Examples
--------
>>> pred = model.predict(params)
>>> pred.sed.l_bol # triggers SED computation
Array(2.5e43, dtype=float64)
>>> pred.sed.uv_slope_beta # reuses cached SED
Array(-1.8, dtype=float64)
"""
def _wave(self):
"""Rest-frame wavelength grid of the cached ForwardState.
The pipeline evaluates on its own grid (auto-extended for dust
emission, trimmed to the modeling range), NOT the raw
``ssp_data.ssp_wave``. Every cached SED array shares the state's
axis, so quantities integrating sed × wave must use it too.
"""
self._pred._ensure_sfh()
return self._pred._cache["_state"].wave
@property
def components(self):
r"""Per-component SED decomposition on the rest-frame grid.
The single-prediction counterpart of
:meth:`Posterior.sed_components
<tengri.inference.posterior.Posterior.sed_components>`, both
read the per-component arrays every adapter publishes into
``state.derived`` (ADR-0009) via
:func:`tengri.forward.state_to_sed_components`. Reuses the
prediction's cached forward state: no extra forward pass.
Returns
-------
dict
``wavelength`` [Angstrom] plus rest-frame :math:`L_\nu`
[erg/s/Hz] per component, each shape ``(n_wave,)``:
``sed_total``, ``sed_intrinsic`` (stellar pre-dust),
``sed_attenuated`` (stellar post-dust), ``sed_nebular``,
``sed_shock``, ``sed_dust_ir``, ``sed_agn``, ``sed_radio``,
``sed_xray``, zeros for components not in the chain.
``sed_agn_disc``, ``sed_agn_torus``, ``sed_agn_lines``
(nlr + blr + feii), ``sed_agn_polar``: the composable AGN
runner's per-sub-block rest-frame SEDs (summing exactly to
``sed_agn``); zeros for a non-composable (monolithic) AGN
model or no AGN component at all. ``sed_agn_lines_attenuated``,
the AGN line light after the AGN's own and the host screen
(instrument-kernel-only in the spectrum projection), is zeros
for an AGN without lines or no AGN component.
Examples
--------
>>> pred = model.predict(params)
>>> comp = pred.sed.components
>>> comp["sed_dust_ir"] # one component
>>> (comp["sed_agn"] / comp["sed_total"]).max() # AGN fraction
"""
from tengri.forward.component_factory import state_to_sed_components
self._pred._ensure_sfh()
return state_to_sed_components(self._pred._cache["_state"])
def _sed(self):
"""Retrieve cached total SED, computing if necessary."""
self._pred._ensure_sed()
return self._pred._cache["sed_total"]
@property
def l_bol(self):
"""Bolometric luminosity.
Returns
-------
float
Total bolometric luminosity [Lsun].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["l_bol"]
@property
def l_tir(self):
"""Total infrared luminosity.
Returns
-------
float
Integrated luminosity in the 8–1000 μm range [Lsun].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["l_tir"]
@property
def l_dust_absorbed(self):
"""Dust-absorbed luminosity.
Returns NaN if no intrinsic SED is available.
Returns
-------
float
Luminosity absorbed by dust [Lsun], or NaN if unavailable.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["l_dust_absorbed"]
@property
def irx(self):
"""Infrared excess.
Returns
-------
float
Infrared excess IRX = log10(L_TIR / νLν_1600) [dimensionless].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["irx"]
@property
def uv_slope_beta(self):
"""UV spectral slope.
Returns
-------
float
Spectral slope β in the rest-frame range 1250–2600 Å [dimensionless].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["uv_slope_beta"]
@property
def dn4000(self):
"""Narrow 4000 Å break.
Returns
-------
float
Narrow D_n(4000) break from Balogh et al. 1999 [dimensionless].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["dn4000"]
@property
def balmer_break(self):
"""Modified Balmer break.
Returns
-------
float
Modified Balmer break from Wang et al. 2024 [dimensionless].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["balmer_break"]
@property
def m_uv(self):
"""Absolute UV magnitude.
Returns
-------
float
Absolute magnitude at rest-frame 1500 Å [AB].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["m_uv"]
@property
def fuv_flux(self):
"""Mean flux density in the FUV.
Returns
-------
float
Mean flux density in the FUV 1000–1700 Å range [erg/s/Hz].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["fuv_flux"]
@property
def nuv_flux(self):
"""Mean flux density in the NUV.
Returns
-------
float
Mean flux density in the NUV 1700–3200 Å range [erg/s/Hz].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["nuv_flux"]
@property
def fuv_flux_intrinsic(self):
"""Dust-free FUV flux.
Returns NaN if no intrinsic SED is available.
Returns
-------
float
Dust-free flux density in the FUV 1000–1700 Å range [erg/s/Hz],
or NaN if unavailable.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["fuv_flux_intrinsic"]
@property
def nuv_flux_intrinsic(self):
"""Dust-free NUV flux.
Returns NaN if no intrinsic SED is available.
Returns
-------
float
Dust-free flux density in the NUV 1700–3200 Å range [erg/s/Hz],
or NaN if unavailable.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["nuv_flux_intrinsic"]
@property
def rest_uv_color(self):
"""U-V AB color: top-hats 3200–3900 Å minus 5000–5800 Å on rest-frame L_nu.
Not FUV−NUV and not f_1500 − f_2300.
Returns
-------
float
U-V color in rest frame [AB magnitudes].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["rest_uv_color"]
@property
def luminosity_weighted_age_gyr(self):
"""Luminosity-weighted stellar age.
Returns
-------
float
Age weighted by stellar luminosity [Gyr].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["luminosity_weighted_age_gyr"]
@property
def luminosity_weighted_metallicity(self):
"""Luminosity-weighted metallicity.
Returns
-------
float
Metallicity weighted by stellar luminosity, log10(Z).
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["luminosity_weighted_metallicity"]
# ── Emission line properties (lazy) ───────────────────────────────
# ``_LINE_RATIO_FLOOR = 1e-50`` stood here until #1568, described as the floor
# "used in BPT and other line-ratio diagnostics to avoid log10(0)". It had no
# readers, the BPT ratios live in ``NebularSEDComponent`` and use that module's
# own floor. Removed rather than made representable: a dead constant that is
# also 0.0 in float32 is the worst of both, since it reads as a live guard.
class LineProperties(_CachedBase):
"""Lazy property accessor for emission line luminosities and diagnostic ratios.
Accessing any line property triggers the nebular computation
if not already cached. All eleven individual line luminosities are in
Lsun (**breaking, no alias, #1206 §A**; the ``log_<line>`` companions on
:attr:`Prediction.properties` stay in dex re erg/s). Diagnostic ratios
are dimensionless log10 values.
If no nebular model is active, all line luminosities return NaN
and all ratios return NaN.
Attributes
----------
lya : property
Lyman-alpha [Lsun].
civ_1549 : property
C IV doublet [Lsun].
oii : property
[OII] doublet [Lsun].
hbeta : property
H-beta [Lsun].
oiii_4959 : property
[OIII] 4959 [Lsun].
oiii_5007 : property
[OIII] 5007 [Lsun].
nii_6548 : property
[NII] 6548 [Lsun].
halpha : property
H-alpha [Lsun].
nii_6584 : property
[NII] 6584 [Lsun].
sii_6717 : property
[SII] 6717 [Lsun].
sii_6731 : property
[SII] 6731 [Lsun].
bpt_nii : property
BPT [NII] diagnostic [dimensionless].
bpt_sii : property
BPT [SII] diagnostic [dimensionless].
o3hb : property
[OIII]/Hβ diagnostic [dimensionless].
r23 : property
R23 metallicity diagnostic [dimensionless].
o32 : property
O32 ionization parameter [dimensionless].
balmer_decrement : property
Hα/Hβ ratio [dimensionless].
Notes
-----
JAX-compatible array container. Properties are lazy-cached within a
:class:`Prediction` object. Returned by :attr:`Prediction.lines`.
Not JIT-compatible (uses Python caching). For batch computation,
use JIT-compatible methods :meth:`SEDModel.predict_emission_lines`.
Examples
--------
>>> pred = model.predict(params)
>>> pred.lines.halpha # Hα luminosity in Lsun
Array(6.3e7, dtype=float64)
>>> pred.lines.bpt_nii # log10([NII]6584 / Hα)
Array(-0.45, dtype=float64)
"""
# --- Individual lines ---
@property
def lya(self):
"""Lyman-alpha at 1216 Å.
Returns
-------
float
Line luminosity [Lsun], or NaN if no nebular model.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred.properties["lya"]
@property
def civ_1549(self):
"""C IV doublet at 1548+1551 Å.
Returns
-------
float
Summed line luminosity [Lsun], or NaN if no nebular model.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred.properties["civ_1549"]
@property
def oii(self):
"""[OII] doublet at 3726+3729 Å.
Returns
-------
float
Summed line luminosity [Lsun], or NaN if no nebular model.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred.properties["oii"]
@property
def hbeta(self):
"""H-beta at 4861 Å.
Returns
-------
float
Line luminosity [Lsun], or NaN if no nebular model.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred.properties["hbeta"]
@property
def oiii_4959(self):
"""[OIII] at 4959 Å.
Returns
-------
float
Line luminosity [Lsun], or NaN if no nebular model.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred.properties["oiii_4959"]
@property
def oiii_5007(self):
"""[OIII] at 5007 Å.
Returns
-------
float
Line luminosity [Lsun], or NaN if no nebular model.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred.properties["oiii_5007"]
@property
def nii_6548(self):
"""[NII] at 6548 Å.
Returns
-------
float
Line luminosity [Lsun], or NaN if no nebular model.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred.properties["nii_6548"]
@property
def halpha(self):
"""H-alpha at 6563 Å.
Returns
-------
float
Line luminosity [Lsun], or NaN if no nebular model.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred.properties["halpha"]
@property
def nii_6584(self):
"""[NII] at 6584 Å.
Returns
-------
float
Line luminosity [Lsun], or NaN if no nebular model.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred.properties["nii_6584"]
@property
def sii_6717(self):
"""[SII] at 6717 Å.
Returns
-------
float
Line luminosity [Lsun], or NaN if no nebular model.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred.properties["sii_6717"]
@property
def sii_6731(self):
"""[SII] at 6731 Å.
Returns
-------
float
Line luminosity [Lsun], or NaN if no nebular model.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred.properties["sii_6731"]
# --- Diagnostic ratios ---
@property
def bpt_nii(self):
"""BPT-NII diagnostic ratio.
Returns
-------
float
log10([NII]6584 / Hα) for BPT diagram [dimensionless].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred.properties["bpt_nii"]
@property
def bpt_sii(self):
"""BPT-SII diagnostic ratio.
Returns
-------
float
log10(([SII]6717+6731) / Hα) for BPT diagram [dimensionless].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred.properties["bpt_sii"]
@property
def o3hb(self):
"""[OIII]5007/Hβ diagnostic ratio.
Returns
-------
float
log10([OIII]5007 / Hβ), the BPT diagram y-axis [dimensionless].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred.properties["o3hb"]
@property
def r23(self):
"""R23 metallicity diagnostic indicator.
Returns
-------
float
log10(([OII]+[OIII]4959+5007)/Hβ), metallicity indicator [dimensionless].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred.properties["r23"]
@property
def o32(self):
"""O32 ionization parameter.
Returns
-------
float
log10([OIII]5007 / [OII]), ionization indicator [dimensionless].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred.properties["o32"]
@property
def balmer_decrement(self):
"""Balmer decrement ratio.
Returns
-------
float
Hα/Hβ intensity ratio [dimensionless]. Case B intrinsic value: 2.86.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred.properties["balmer_decrement"]
@property
def all_waves(self):
"""Rest-frame vacuum wavelengths of all cataloged lines [Angstrom].
Returns
-------
jnp.ndarray, shape (n_lines,)
Wavelengths published by the active nebular backend. Empty array
when the backend does not expose a discrete catalog (BakedIn, Shock).
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred._cache.get("line_waves", jnp.array([]))
@property
def all_lums(self):
"""Luminosities at all_waves [erg/s].
Returns
-------
jnp.ndarray, shape (n_lines,)
Line luminosities in the same dust regime as the headline fields
(attenuated by the active dust model when present). Empty array
when the backend does not expose a discrete catalog.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._pred._ensure_lines()
return self._pred._cache.get("line_lums", jnp.array([]))
def get(self, wavelength: float, tol_aa: float = 2.0) -> jnp.ndarray:
"""Return the luminosity at the species nearest *wavelength* Å.
Matches the semantics of :meth:`EmissionLines.get` for parity between
the deprecated and new prediction surfaces (#1889).
Parameters
----------
wavelength : float
Rest-frame vacuum wavelength to look up [Angstrom].
tol_aa : float, optional
Acceptable distance to the nearest cataloged line [Angstrom].
Returns ``nan`` if the nearest line is further than this. Default 2.0.
Returns
-------
jnp.ndarray
Luminosity at the matched line [erg/s], or ``nan`` if no line
is within ``tol_aa``. Returns ``nan`` if the active backend
did not publish a discrete catalog.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
Examples
--------
>>> pred = model.predict(params)
>>> halpha_lum = pred.lines.get(6564.61) # match H-alpha
>>> heii_1640 = pred.lines.get(1640.42) # match He II
"""
all_waves = self.all_waves
all_lums = self.all_lums
if all_waves.size == 0:
return jnp.asarray(jnp.nan)
diff = jnp.abs(all_waves - jnp.asarray(wavelength))
idx = jnp.argmin(diff)
return jnp.where(diff[idx] <= tol_aa, all_lums[idx], jnp.asarray(jnp.nan))
# ── Radio properties (lazy) ───────────────────────────────────────
class RadioProperties(_CachedBase):
"""Lazy property accessor for radio-derived quantities.
These use empirical scaling relations: the FIR-radio correlation
(Bell 2003; Murphy+2011) and free-free emission from the ionizing
photon budget.
Attributes
----------
l_1p4ghz : property
Radio luminosity at 1.4 GHz [erg/s/Hz].
l_thermal : property
Thermal free-free luminosity [erg/s/Hz].
l_nonthermal : property
Non-thermal synchrotron luminosity [erg/s/Hz].
q_ir : property
FIR-radio correlation parameter [dimensionless].
Notes
-----
JAX-compatible array container. Properties are lazy-cached within a
:class:`Prediction` object. Returned by :attr:`Prediction.radio`.
Not JIT-compatible (uses Python caching).
Examples
--------
>>> pred = model.predict(params)
>>> pred.radio.l_1p4ghz # 1.4 GHz luminosity
Array(5.2e28, dtype=float64)
"""
@property
def l_1p4ghz(self):
"""Radio luminosity at 1.4 GHz.
Returns
-------
float
Radio luminosity density at 1.4 GHz [erg/s/Hz], from SFR scaling.
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["l_1p4ghz"]
@property
def l_thermal(self):
"""Thermal radio luminosity at 1.4 GHz.
Returns
-------
float
Free-free radio luminosity density at 1.4 GHz [erg/s/Hz].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["l_thermal"]
@property
def l_nonthermal(self):
"""Non-thermal radio luminosity at 1.4 GHz.
Returns
-------
float
Synchrotron radio luminosity density [erg/s/Hz].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["l_nonthermal"]
@property
def q_ir(self):
"""FIR-radio correlation parameter.
Returns
-------
float
FIR-radio correlation parameter q_TIR [dimensionless].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["q_ir"]
# ── X-ray properties (lazy) ───────────────────────────────────────
class XRayProperties(_CachedBase):
"""Lazy property accessor for X-ray derived quantities.
The 2-10 keV luminosities of the X-ray terms the model emits: the HMXB +
LMXB terms (Fragos et al. 2013, SFR averaged over 100 Myr) and the AGN
corona, published by the X-ray component (``log_L_x_xrb_2_10``,
``log_L_x_agn_2_10``).
Attributes
----------
l_x_xrb : property
X-ray binary luminosity [Lsun].
l_x_agn : property
AGN X-ray luminosity [Lsun].
l_x_total : property
Total X-ray luminosity [Lsun].
Notes
-----
JAX-compatible array container. Properties are lazy-cached within a
:class:`Prediction` object. Returned by :attr:`Prediction.xray`.
Not JIT-compatible (uses Python caching).
**Breaking, no alias (#1206 §B)**: all three return Lsun, not erg/s (an
AGN X-ray luminosity is ~1e40-1e45 erg/s, past float32's 3.4e38 ceiling).
The ``log_l_x_*`` companions on :attr:`Prediction.properties` stay in dex
re erg/s.
Examples
--------
>>> pred = model.predict(params)
>>> pred.xray.l_x_xrb # XRB luminosity (2-10 keV), in Lsun
Array(8.1e6, dtype=float64)
"""
@property
def l_x_xrb(self):
"""X-ray luminosity from X-ray binaries.
Returns
-------
float
2-10 keV luminosity of the emitted HMXB + LMXB terms [Lsun].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["l_x_xrb"]
@property
def l_x_agn(self):
"""AGN X-ray luminosity.
Returns
-------
float
AGN X-ray luminosity in 2–10 keV band [Lsun].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["l_x_agn"]
@property
def l_x_total(self):
"""Total X-ray luminosity.
Returns
-------
float
Combined XRB and AGN X-ray luminosity [Lsun].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["l_x_total"]
# ── Ionizing properties (lazy) ────────────────────────────────────
class IonizingProperties(_CachedBase):
"""Lazy property accessor for ionizing photon budget quantities.
The ionizing photon rate Q_H is extracted from the nebular model
backend (Cloudy grid or Cue emulator). If no nebular model is
active, returns NaN.
Attributes
----------
log_q_h : property
log10 ionizing photon production rate [dex re photons/s].
xi_ion : property
Ionizing photon production efficiency [Hz/erg].
Notes
-----
JAX-compatible array container. Properties are lazy-cached within a
:class:`Prediction` object. Returned by :attr:`Prediction.ionizing`.
Not JIT-compatible (uses Python caching).
**``q_h`` retired, no alias (#1206 §C).** The linear ionizing photon rate
(~1e56 photons/s) overflows float32 at every physical rate, including
zero. ``pred.ionizing.q_h`` now raises ``KeyError`` naming the
replacement; use ``pred.ionizing.log_q_h`` (log10(photons/s)) and
convert with ``10**log_q_h`` where the linear value is needed.
Examples
--------
>>> pred = model.predict(params)
>>> pred.ionizing.xi_ion # ionizing efficiency
Array(25.3, dtype=float64)
"""
@property
def q_h(self):
"""Retired, no alias (#1206 §C). Raises ``KeyError`` naming ``log_q_h``.
Raises
------
KeyError
Always: the linear photons/s value overflows float32 at every
physical ionizing rate. Use :attr:`log_q_h` and ``10**log_q_h``.
"""
return self._pred.properties["q_h"]
@property
def log_q_h(self):
"""log10 total ionizing photon production rate [dex re photons/s].
The float32-safe replacement for the retired linear ``q_h`` (#1206
§C): ``q_h [photons/s] = 10**log_q_h``.
Returns
-------
float
log10(ionizing photon production rate / (photons/s)).
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["log_q_h"]
@property
def xi_ion(self):
"""Ionizing photon production efficiency.
Defined as Q_H / L_UV(1600 Å). Key parameter for cosmic
reionization studies. Typical values: 25.0–25.6.
Returns
-------
float
Ionizing photon efficiency log10(ξ_ion) [Hz/erg].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
return self._pred.properties["xi_ion"]
# ── Property catalog accessor ────────────────────────────────────
class PropertyCatalog(ReadOnlyPropertyMapping):
"""View of computed properties with dict-like and attribute access.
A PropertyCatalog is a dict-like accessor bound to a Prediction that
lazily evaluates each property from the cached ForwardState. It
implements ``__getitem__``, ``__contains__``, iteration, and
``to_dict(names=...)`` for batch export.
Parameters
----------
prediction : Prediction
Parent Prediction object (which caches the ForwardState and params).
Attributes
----------
_prediction : Prediction
Reference to parent Prediction instance.
"""
def __init__(self, prediction):
"""Initialize the catalog bound to a Prediction."""
object.__setattr__(self, "_prediction", prediction)
def __getitem__(self, name: str):
"""Access a property by name (dict-like syntax).
Parameters
----------
name : str
Property name (e.g., ``"stellar_mass"``).
Returns
-------
scalar
Computed property value.
Raises
------
KeyError
If the property is unknown or not available in this model.
"""
pred = object.__getattribute__(self, "_prediction")
catalog = pred._model._ensure_property_catalog()
if name not in catalog:
from tengri.forward.properties import missing_property_message
raise KeyError(missing_property_message(name, available=catalog))
from tengri.forward.properties import warn_if_lines_are_unavailable
warn_if_lines_are_unavailable(pred._model, (name,))
entry = catalog[name]
state = pred._ensure_state()
cache = pred._cache.setdefault("_property_bundles", {})
return entry.evaluate(state, pred._params, model=pred._model, cache=cache)
def __contains__(self, name: str) -> bool:
"""Check if a property is available."""
pred = object.__getattribute__(self, "_prediction")
return name in pred._model._ensure_property_catalog()
def __iter__(self):
"""Iterate over property names."""
pred = object.__getattribute__(self, "_prediction")
return iter(sorted(pred._model._ensure_property_catalog().keys()))
def get(self, name: str, default=None):
"""Return the property value for ``name``, or ``default`` if absent.
Mirrors :meth:`dict.get` so the catalog is safe to probe without a
``try``/``except KeyError`` when a property may not be available for
this model (e.g. asking for ``"agn_luminosity"`` on a galaxy-only fit).
Parameters
----------
name : str
Property name (e.g., ``"stellar_mass"``).
default : object, optional
Value to return when ``name`` is not available. Default ``None``.
Returns
-------
scalar or object
Computed property value, or ``default`` if ``name`` is unknown.
"""
if name in self:
return self[name]
return default
def values(self):
"""Return computed values for every available property.
Returns
-------
list
One value per name in :meth:`keys`, in the same order.
"""
return [self[name] for name in self]
def items(self):
"""Return ``(name, value)`` pairs for every available property.
Returns
-------
list of tuple
``(name, value)`` for each name in :meth:`keys`.
"""
return [(name, self[name]) for name in self]
# ``keys`` / ``to_dict`` / read-only ``__setattr__`` come from
# ReadOnlyPropertyMapping (#1431). ``get`` / ``values`` / ``items`` stay
# here: they return plain lists, which a Mapping base would turn into views.
from tengri.parameters.resolve import resolve_fixed_params
# ── Main Prediction class ─────────────────────────────────────────
[docs]
class Prediction:
"""Lazy prediction object with on-demand computation of derived quantities.
Created via ``model.predict(params)``. Properties are computed on
first access and cached. The cache is shared across all property
groups (``sfh``, ``sed``, ``lines``, ``radio``, ``xray``,
``ionizing``), so related quantities share the expensive
intermediates.
Parameters
----------
model : SEDModel
The tengri SEDModel instance.
params : dict
Parameter values (public names).
Attributes
----------
sfh : SFHProperties
Star formation history derived quantities. Lazy accessor.
sed : SEDProperties
Spectral energy distribution derived quantities. Lazy accessor.
lines : LineProperties
Emission line luminosities and diagnostic ratios. Lazy accessor.
radio : RadioProperties
Radio-derived quantities from empirical relations. Lazy accessor.
xray : XRayProperties
X-ray derived quantities from empirical relations. Lazy accessor.
ionizing : IonizingProperties
Ionizing photon budget quantities. Lazy accessor.
Returns
-------
Prediction
Lazy prediction object with cached computed quantities.
Notes
-----
This class is NOT JIT-compatible due to Python-level caching. For
batch computations over many parameter sets (MCMC chains, mock
catalogs), use :meth:`SEDModel.predict_properties`, the one
JIT/vmap-safe surface for derived quantities, or
:meth:`SEDModel.predict_photometry` on an inference hot path. Both
return plain JAX values suitable for :func:`jax.vmap`,
:func:`jax.jit`, and :func:`jax.grad`.
Examples
--------
**Two equivalent ways to access derived quantities:**
>>> pred = model.predict(params)
>>> pred.stellar_mass # flat shortcut
>>> pred.sfh.stellar_mass # grouped form (same value)
>>> pred.dn4000 # flat
>>> pred.sed.dn4000 # grouped
>>> pred.halpha # flat
>>> pred.lines.halpha # grouped
The grouped form (``pred.sfh``, ``pred.sed``, ``pred.lines``,
``pred.radio``, ``pred.xray``, ``pred.ionizing``) exposes every
derived quantity. The top-level shortcuts cover the most-used
quantities for quick access; for less-common ones use the grouped
form. Both share the same lazy cache, so accessing a quantity by
either route triggers computation only once.
**Accessing the full SED or photometry:**
>>> pred.sed_array # shape (n_wave,)
>>> pred.photometry() # shape (n_filters,) -- call it, it is a method
**For batch computation, use JIT-compatible methods instead:**
>>> batch = jax.vmap(lambda p: model.predict_properties(p, names=("stellar_mass",)))(
... params_batch
... )
"""
__slots__ = (
"_cache",
"_free_params",
"_model",
"_params",
"_photometry_cache",
"ionizing",
"lines",
"properties",
"radio",
"sed",
"sfh",
"xray",
)
def __init__(self, model, params):
self._model = model
# (#2296) Refuses any Fixed key in ``params``, then merges in every
# Fixed value the caller omitted. This is the ONE refusal check for
# this Prediction's lifetime, run once here on exactly what the
# caller supplied. ``self._params`` (fixed+free) is what the exact
# projectors below need -- ``project_photometry``/``project_spectrum``
# and ``_predict_obs_sed`` read values like ``redshift``/``igm_x_HI``
# straight out of the dict with no fallback of their own.
self._params = resolve_fixed_params(model, params)
# The free-only dict exactly as the caller supplied it (already
# refused above). Use THIS, not ``self._params``, for any call into a
# public ``predict_*`` surface: those surfaces refuse a Fixed key of
# their own (#2296), and ``self._params`` legitimately carries every
# one of them, so handing it back in would trip that refusal on
# values this constructor injected, not on anything the caller
# overrode.
self._free_params = dict(params)
self._cache = {}
self._photometry_cache = {}
self.sfh = SFHProperties(self)
self.sed = SEDProperties(self)
self.lines = LineProperties(self)
self.radio = RadioProperties(self)
self.xray = XRayProperties(self)
self.ionizing = IonizingProperties(self)
self.properties = PropertyCatalog(self)
def __getattr__(self, name: str):
"""Attribute-access sugar for derived properties.
Supports ``pred.stellar_mass`` as a shorthand for
``pred.properties["stellar_mass"]``. Falls back to AttributeError
if the name is not in the property catalog.
Parameters
----------
name : str
Property name.
Returns
-------
scalar
Computed property value from the property catalog.
Raises
------
AttributeError
If the name is not a known property, with a message listing
available properties.
Notes
-----
This method is only called when standard attribute lookup fails,
so it cannot shadow normal attributes like ``_model``, ``_params``,
or the ``sfh``/``sed``/``lines`` groups (which are set in __init__).
"""
# Avoid infinite recursion by checking if we're still initializing
if name.startswith("_"):
raise AttributeError(f"No attribute '{name}'")
try:
properties = object.__getattribute__(self, "properties")
if name in properties:
return properties[name]
except AttributeError:
pass
# Not a property, raise AttributeError
props = object.__getattribute__(self, "properties")
available = sorted(props.keys()) if props else []
raise AttributeError(
f"'{type(self).__name__}' object has no attribute '{name}'. "
f"Available properties: {available}"
)
def __dir__(self) -> list[str]:
"""Include property names in tab completion and dir().
Returns
-------
list[str]
All normal attributes plus property catalog names for autocomplete.
"""
base = [
"_cache",
"_model",
"_params",
"ionizing",
"lines",
"properties",
"radio",
"sed",
"sfh",
"xray",
]
properties = object.__getattribute__(self, "properties")
if properties:
base.extend(sorted(properties.keys()))
return base
def __jax_array__(self):
"""Guard against accidental JIT/vmap tracing of Prediction objects.
Raises
------
TypeError
Always, with a message directing users to use
``model.predict_properties(...)``, which is JIT-compatible.
"""
raise TypeError(
"Prediction objects are not JIT/vmap-compatible due to Python-level "
"caching. For batch computations use model.predict_properties("
"params, names=(...)), the one JIT/vmap-safe surface for derived "
"quantities, or model.predict_photometry(params) on an inference "
"hot path. Both return plain JAX values suitable for jax.vmap "
"and jax.jit."
)
def _ensure_sfh(self):
"""Populate SFH cache (SFR history, age weights, internal params).
Reads the orchestrator's :class:`ForwardState` to keep SFH-only
consumers (``stellar_mass``, ``sfr_*``, ``mass_weighted_age``)
and SED-consuming consumers
(``luminosity_weighted_age``, ``dn4000``) on the same numerics.
``weights`` is the orchestrator's DSPS-canonical
``age_weights`` (Msun per SSP age bin); ``sfr`` is
``sfr_history`` on the SFH lookback grid (same shape as
``model.age_yr``). The orchestrator state itself is cached on
``_state`` so :meth:`_ensure_sed` can reuse it without a
second forward-pass.
"""
if "weights" in self._cache:
return
# Free-only: both calls self-merge Fixed values from the spec (#2296).
p = self._model._get_internal_params(self._free_params)
state = self._model.predict_state(self._free_params)
derived = state.derived
# The stellar block integrates the SFH on
# ``spec.n_grid`` (default 64) regardless of whether the model
# is stochastic. Legacy ``SEDModel`` uses ``n_grid=256`` for
# non-stochastic configs, so cache consumers index ``sfr``
# against ``model.age_yr`` of length 256. Resample the
# orchestrator's SFR history to the legacy grid so masks like
# ``model.age_yr <= 1e8`` still align.
sfh_grid = jnp.asarray(derived["sfh_grid_lbt_yr"])
sfr_history = jnp.asarray(derived["sfr_history"])
sfr_on_legacy_grid = jnp.interp(self._model.age_yr, sfh_grid, sfr_history, right=0.0)
self._cache.update(
{
"p": p,
"sfr": sfr_on_legacy_grid,
"weights": jnp.asarray(derived["age_weights"]),
"_state": state,
}
)
def _ensure_state(self):
"""Ensure the ForwardState is cached and return it.
Returns
-------
ForwardState
The cached orchestrator state, computed on first call to
_ensure_sfh and reused by all downstream consumers.
"""
if "_state" not in self._cache:
self._ensure_sfh()
return self._cache["_state"]
def _ensure_sed(self):
"""Populate SED cache from the orchestrator's ForwardState.
Re-uses the state computed in :meth:`_ensure_sfh` (cached on
``self._cache["_state"]``). Reconstructs the legacy cache
contract:
- ``sed_total`` ← ``state.sed_intrinsic`` (post-dust total)
- ``sed_intrinsic`` ← ``sum(lnu_age, axis=0)`` (pre-dust stellar)
- ``sed_attenuated`` ← ``state.derived["sed_dust_attenuated"]``
- ``ssp_flux_at_z`` ← ``lnu_age / (age_weights * LSUN_ERG)``
(safe-divided where ``age_weights`` is zero)
- ``agn_bol_erg`` ← ``state.derived["L_agn_bol"]`` if present.
"""
if "sed_total" in self._cache:
return
self._ensure_sfh()
state = self._cache["_state"]
derived = state.derived
self._cache["sed_total"] = state.sed_intrinsic
from tengri.utils.physics_constants import L_SUN
lnu_age_arr = jnp.asarray(derived["lnu_age"])
self._cache["sed_intrinsic"] = jnp.sum(lnu_age_arr, axis=0)
aw = jnp.asarray(self._cache["weights"])
aw_safe = jnp.maximum(aw, 1e-30)
self._cache["ssp_flux_at_z"] = lnu_age_arr / (aw_safe[:, None] * L_SUN)
sed_attenuated = derived.get("sed_dust_attenuated")
if sed_attenuated is not None:
self._cache["sed_attenuated"] = jnp.asarray(sed_attenuated)
if "L_agn_bol" in derived:
self._cache["agn_bol_erg"] = jnp.asarray(derived["L_agn_bol"])
def _ensure_lines(self):
"""Compute and cache nebular emission line luminosities.
Reads the discrete catalog published by
:class:`~tengri.components.nebular.component.NebularSEDComponent`
(``state.derived["line_waves"]`` / ``["line_lums"]``). Matches
legacy-path luminosities within numerical tolerance for both
Cue and CloudyGrid backends.
Issues a one-time :class:`UserWarning` when the active backend
doesn't expose a per-line luminosity catalog (BakedIn / Shock).
Without the warning, ``pred.lines.halpha`` etc. silently return
NaN, see #361.
"""
if "line_waves" in self._cache:
return
self._ensure_sfh()
model = self._model
backend = model._nebular_backend
if backend is None or not hasattr(backend, "predict_nebular_line_luminosities"):
# The warning moved to `warn_if_lines_are_unavailable`, which
# `PropertyCatalog.__getitem__` calls. Every one of the 17
# `_ensure_lines()` call sites reads `properties[...]` on the next
# line, so this surface still warns, and the dict accessor and
# `predict_properties`, which used to return the same NaN in
# silence, now warn too. Warning here as well fired it twice.
self._cache["line_waves"] = jnp.array([])
self._cache["line_lums"] = jnp.array([])
self._cache["q_h_total"] = jnp.array(jnp.nan)
self._cache["log_q_h_total"] = jnp.array(jnp.nan)
return
# Pull the catalog from the orchestrator's NebularSEDComponent
# publication. BakedIn / Shock backends won't publish it; fall
# back to all-NaN for those (matches the legacy "no catalog"
# behavior without raising). Reuse the ForwardState cached by
# _ensure_sfh(), re-running predict_state here doubled the
# forward pass (and its transient memory) for pred.lines.
state = self._cache["_state"]
derived = state.derived
if "line_waves" in derived and "line_lums" in derived:
waves = jnp.asarray(derived["line_waves"])
lums = jnp.asarray(derived["line_lums"])
self._cache["line_waves"] = waves
# Backends publish INTRINSIC line_lums; the dust component publishes
# the reddened catalog alongside it (#1867), with the same screen it
# applies to the nebular continuum. Read that when present.
#
# This used to call `model._attenuate_line_catalog(...)` here. The
# result was correct and completely dead: every `.lines.*` accessor
# calls `_ensure_lines()` and then reads `properties[...]`, which
# routes to `_line_luminosity_helper` -> `state.derived[...]` and
# never consults this cache. So the reddening was recomputed on
# every access and discarded, and both public line surfaces were
# intrinsic while documented as observed.
_log_atten = derived.get("log_line_lums_attenuated")
if _log_atten is None:
self._cache["line_lums"] = lums
else:
from tengri.utils.scale import pow10
self._cache["line_lums"] = pow10(jnp.asarray(_log_atten))
else:
self._cache["line_waves"] = jnp.array([])
self._cache["line_lums"] = jnp.array([])
# Q_H: compute from backend's precomputed table if available.
# Uses the orchestrator-published ``age_weights`` (Msun/bin) +
# ``log_metallicity_history`` (present-day value) so the value
# matches the legacy path even when other consumers of the
# cache still go through the legacy ``_ensure_sed``.
weights_orch = derived.get("age_weights")
log_z_history = derived.get("log_metallicity_history")
if (
weights_orch is not None
and log_z_history is not None
and hasattr(backend, "_qh_table")
and backend._qh_table is not None
):
from tengri.components.nebular._shared import log_q_h_total
from tengri.utils.scale import pow10
log_z = jnp.asarray(log_z_history)[0]
neb_fesc = jnp.asarray(self._params.get("neb_fesc", 0.0))
# Summed in the log domain (#2853): a linear Q_H is ~1e47 photons/s per
# Msun and overflows float32 once multiplied by the mass weight.
log_total = log_q_h_total(
backend,
model.ssp_log_ages_yr,
jnp.asarray(weights_orch),
log_z,
neb_fesc,
)
self._cache["log_q_h_total"] = log_total
self._cache["q_h_total"] = pow10(log_total)
else:
self._cache["q_h_total"] = jnp.array(jnp.nan)
self._cache["log_q_h_total"] = jnp.array(jnp.nan)
@property
def sed_array(self):
"""Full rest-frame SED array.
Returns
-------
ndarray, shape (n_wave,)
Total spectral energy distribution [erg/s/Hz].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
"""
self._ensure_sed()
return self._cache["sed_total"]
[docs]
def photometry(self, filters=None, approx=False, *, fast=UNSET):
r"""Observed-frame photometric flux densities.
Integrates the model SED through each filter and applies the cosmological
dimming, returning :math:`F_\nu` in the observer frame. For the same
quantity as AB magnitudes, see :meth:`magnitudes`.
**Exact by default, approximate by choice.** The default integrates the
full SED, including on a model built with ``approx=WavePrecomp(...)``,
where the lean :meth:`~tengri.SEDModel.predict_photometry` would instead
read the lookup table. That is deliberate: ``pred.photometry()`` must mean
the same thing on every model. The LUT is an approximation carrying real
error, so you reach it only by asking for it, with ``approx=True``.
The keyword is spelled ``approx`` because it selects exactly the object
installed at build time by ``SEDModel.build(..., approx=WavePrecomp(...))``
one mechanism, one name at both ends. It was called ``fast`` until
2026-08, which named the benefit and hid the cost; that spelling still
works and emits a ``DeprecationWarning``.
Parameters
----------
filters : sequence of str or FilterCurve, optional
Filter names (e.g., ``["jwst_f356w", "jwst_f444w"]``) or
:class:`~tengri.observation.photometry.FilterCurve` objects.
If None, uses the filters configured at model build time.
approx : bool, optional
If True, use the build-time WavePrecomp LUT (20–50× faster, and an
approximation). Only valid when the model was built with
``approx=WavePrecomp(...)``. If `filters` is also provided, raises
ValueError. Default: False (exact path).
fast : bool, optional
Deprecated spelling of `approx`. Removed in v1.0.
Returns
-------
ndarray, shape (n_filters,)
Observed-frame flux densities [erg/s/cm²/Hz].
Raises
------
ValueError
If the model was not built with ``approx=WavePrecomp(...)`` but
``approx=True`` is requested, or if both `filters` and ``approx=True``.
ValueError
If no photometry is configured on the model.
TypeError
If both `approx` and the deprecated `fast` are passed with
contradictory values.
Notes
-----
**JIT-compatible**: no, Python method with caching. Use in postprocessing,
not inside :func:`jax.jit`.
**Default (exact) path**: integrates ``state.sed_intrinsic`` through each
filter via :func:`~tengri.observation.photometry.project_photometry`, the
same kernel the likelihood uses, on the ``ForwardState`` this Prediction
already cached, so it costs the filter integration and not a second
forward pass.
**Approximate path** (``approx=True``): Uses the precomputed photometric
LUT (filter effective wavelengths × SSP grid). Requires
``approx=WavePrecomp(...)`` at model build time. Runtime cost is
~150 μs per forward model (20–50× speedup for typical models).
**How wrong is it?** Measured against this exact path on a 12-band
tsnorm + two-component-dust model, worst band per redshift: 0.085 % at
z = 0.05, 1.5 % at z = 1, 10.4 % at z = 1.5, 83 % at z = 3, but the
large numbers are all GALEX FUV, which by z = 2 is below the Lyman
break and carries 1e-7 of the g-band flux. On bands carrying flux the
error is 1e-4 to 1e-2 (sdss_g is 1.38 % at z = 3). The error is set by
:class:`~tengri.WavePrecomp`'s ``band_integration``, not by ``n_z``
(measured: 250 -> 1000 nodes moves it by nothing). It is a *bias*, so
per #1671 it enters the posterior gradient multiplied by SNR.
Full numbers: ``bench/reports/2026-08-17_wave_precomp_accuracy.md``.
**Runtime filters** (``filters=...``): Constructs a runtime Photometry
object from filter names or objects. Cached on ``self._photometry_cache``
keyed by filter tuple for zero-cost repeat calls. Issues a one-time
UserWarning (exact-path cost). The exact path is always used; a LUT
built for one filter set cannot cover filters it was never built for.
Examples
--------
**Default exact path:**
>>> pred = model.predict(params)
>>> phot = pred.photometry() # shape (n_filters,)
>>> phot.shape
(8,)
**Approximate path (requires WavePrecomp):**
>>> phot_lut = pred.photometry(approx=True) # 20-50x faster, approximate
>>> bool(jnp.allclose(phot, phot_lut, rtol=1e-2))
True
**Runtime filter set:**
>>> phot_custom = pred.photometry(filters=["jwst_f356w", "jwst_f444w"])
>>> phot_custom.shape
(2,)
"""
approx = resolve_renamed_flag(
approx,
fast,
old_name="fast",
new_name="approx",
caller="Prediction.photometry",
)
# A model built without an observation is a valid rest-frame-only model
# (pred.rest_sed(), pred.stellar_mass, ... all work), but has nothing to
# project photometry onto. Name the fix instead of crashing with a bare
# ``'NoneType' object has no attribute 'photometry'``, the lean
# model.predict_photometry() already raises a helpful ValueError here.
if self._model.observation is None:
raise ValueError(
"No observation is configured on the model, so photometry cannot "
"be projected. Build the model with observation=... (or filters=...) "
"to get photometry; without one, only rest-frame quantities "
"(pred.rest_sed(), pred.stellar_mass, ...) are available."
)
# Validate arguments
if approx and filters is not None:
raise ValueError(
"approx=True and filters=[...] are mutually exclusive. "
"A LUT built for one filter set cannot cover filters it was never built for."
)
# Mode 1: Fast path (WavePrecomp LUT).
#
# Route through the lean jitted shortcut, NOT through
# ``predict_via_precomp`` on ``self._ensure_state()``. The whole saving of
# WavePrecomp is that XLA dead-code-eliminates the full-resolution SED
# einsum when only the LUT is consumed, and ``_ensure_state`` materializes
# that state eagerly, so the einsum runs and the saving is already spent.
# Going through the state made ``approx=True`` *slower* than the exact
# default (measured 0.7-0.8x) while also returning an approximation: the
# worst of both. ``predict_photometry`` is the same LUT to ~1 ULP and keeps
# the elision, so it is both faster and the number the fit itself sees.
if approx:
if not self._model._approx.get("wave_precomp"):
raise ValueError(
"approx=True requires the model to be built with approx=WavePrecomp(...). "
"Rebuild the model with approx=WavePrecomp() and try again."
)
# Free-only: predict_photometry refuses a Fixed key of its own
# (#2296) and self-merges self.spec.get_fixed_values() internally.
return self._model.predict_photometry(self._free_params)
# Mode 2: Runtime filters
if filters is not None:
# The convention (Bessell photon-counting vs energy, ADR-0017) is part
# of the filter integral, not of the filter. ``Photometry.from_names``
# defaults to Bessell, so resolving runtime filters without passing the
# model's own convention silently answers a different question than
# ``photometry()`` does, same filters, two numbers (~0.5% apart on an
# energy-convention model). It is part of the cache key for the same
# reason.
from tengri.observation.photometry_config import resolve_runtime_photometry
from tengri.utils.filter_convention import FilterConvention
build_time = self._model.observation.photometry
convention = (
build_time.convention if build_time is not None else FilterConvention.BESSELL
)
filter_names = tuple(f if isinstance(f, str) else f.name for f in filters)
cache_key = (filter_names, convention)
if cache_key in self._photometry_cache:
phot_obj = self._photometry_cache[cache_key]
else:
# The shared normalizer, so ``filters=`` resolves identically here
# and on Posterior.observables (#1129).
phot_obj = resolve_runtime_photometry(filters, build_time=build_time)
self._photometry_cache[cache_key] = phot_obj
_warn_runtime_photometry_once()
from tengri.observation.photometry import project_photometry
return project_photometry(self._ensure_state(), self._params, phot_obj)
# Mode 3: Default, the EXACT path, on the build-time filters.
#
# This deliberately does NOT call ``model.predict_photometry``: that is
# the lean inference shortcut, and on a model built with
# ``approx=WavePrecomp(...)`` it returns the LUT. Routing the default
# here through it would make ``pred.photometry()`` silently mean "exact"
# on one model and "approximate" on another, which is precisely the
# ambiguity the exact-by-default rule exists to kill. The LUT path is
# reachable, but only by asking for it, with ``approx=True``.
if self._model.observation.photometry is None:
raise ValueError(
"No photometry is configured on the model. "
"Build the model with observation=Observation(photometry=...) and try again."
)
from tengri.observation.photometry import project_photometry
return project_photometry(
self._ensure_state(), self._params, self._model.observation.photometry
)
[docs]
def magnitudes(self, filters=None, approx=False, *, fast=UNSET):
r"""AB magnitudes through filters.
Computes AB magnitudes by converting observed flux densities from
:meth:`photometry` using the AB magnitude system.
Parameters
----------
filters : sequence of str or FilterCurve, optional
Filter names or :class:`~tengri.observation.photometry.FilterCurve`
objects. If None, uses the filters configured at model build time.
approx : bool, optional
If True, use the build-time WavePrecomp LUT (20–50× faster, and an
approximation). Only valid when the model was built with
``approx=WavePrecomp(...)``. If `filters` is also provided, raises
ValueError. Default: False (exact path). See :meth:`photometry` for
the measured size of the approximation.
fast : bool, optional
Deprecated spelling of `approx`. Removed in v1.0.
Returns
-------
ndarray, shape (n_filters,)
AB magnitudes [dimensionless].
Raises
------
ValueError
If the model was not built with ``approx=WavePrecomp(...)`` but
``approx=True`` is requested, or if both `filters` and ``approx=True``.
ValueError
If no photometry is configured on the model.
TypeError
If both `approx` and the deprecated `fast` are passed with
contradictory values.
Notes
-----
**JIT-compatible**: no, Python method delegating to :meth:`photometry`.
Use in postprocessing, not inside :func:`jax.jit`.
**Semantics**: Computes :meth:`photometry` in the requested mode
(exact, approximate, or runtime filters), then converts flux densities to
AB magnitudes via:
.. math::
m_{\mathrm{AB}} = -2.5 \log_{10}(f_\nu / f_0)
where f_0 = 3.631×10⁻²⁰ erg s⁻¹ cm⁻² Hz⁻¹ is the AB zeropoint.
References
----------
Oke & Gunn 1983, ApJ, 266, 713, AB magnitude definition.
Examples
--------
>>> pred = model.predict(params)
>>> mags = pred.magnitudes() # AB mags, shape (n_filters,)
>>> mags[0] # first filter AB magnitude
20.5
"""
from tengri.utils.magnitudes import fnu_to_ab_mag
# Resolved here rather than forwarded, so the DeprecationWarning names
# ``magnitudes`` (what the user called) and not ``photometry``.
approx = resolve_renamed_flag(
approx,
fast,
old_name="fast",
new_name="approx",
caller="Prediction.magnitudes",
)
fnu = self.photometry(filters=filters, approx=approx)
return fnu_to_ab_mag(fnu)
[docs]
def spectrum(self, wave_obs=None, approx=False, *, fast=UNSET):
r"""Instrument-grid, LSF-convolved spectrum.
Computes the observed-frame spectrum at the instrument wavelength grid,
convolved with the line-spread function and calibrated.
Parameters
----------
wave_obs : ndarray, optional
Custom observed-frame wavelength grid [Angstrom]. If None, uses
the grid configured in the spectroscopy setup at model build time.
approx : bool, optional
If True, use the build-time ``SpectrumPrecomp`` LUT. Only valid when
the model was built with ``approx=SpectrumPrecomp(...)``.
Default False, the exact projector. Named for the object it
selects, which is the same word the build takes.
fast : bool, optional
Deprecated spelling of `approx`. Removed in v1.0.
Returns
-------
ndarray, shape (n_wave_obs,)
Observed-frame flux density [erg/s/cm^2/Hz].
Raises
------
ValueError
If no spectroscopy is configured on the model, or if ``approx=True``
on a model not built with ``approx=SpectrumPrecomp(...)``.
TypeError
If both `approx` and the deprecated `fast` are passed with
contradictory values.
Notes
-----
**JIT-compatible**: no, Python accessor delegating to
:meth:`SEDModel.predict_spectrum`. Use in postprocessing,
not inside :func:`jax.jit`.
**Naming contract**: SED = panchromatic model-grid array
(:meth:`rest_sed` / :meth:`obs_sed`); spectrum = instrument-grid,
LSF-convolved, calibrated observable (:meth:`spectrum`).
**Preprocessing**: The instrument LSF (Gaussian with resolution R),
velocity broadening, and calibration polynomial all apply on top
of the SED redshift.
Examples
--------
>>> pred = model.predict(params)
>>> spec = pred.spectrum() # shape (n_wave,)
>>> spec.shape
(2048,)
"""
approx = resolve_renamed_flag(
approx,
fast,
old_name="fast",
new_name="approx",
caller="Prediction.spectrum",
)
if self._model.observation is None or self._model.observation.spectroscopy is None:
raise ValueError(
"No spectroscopy is configured on the model. "
"Build the model with observation=Observation(spectroscopy=...) and try again."
)
# Same rule as :meth:`photometry`, for the same reason. ``predict_spectrum``
# honors the SpectrumPrecomp LUT, so defaulting to it would make
# ``pred.spectrum()`` mean "exact" on one model and "approximate" on another
# measured 5-7% apart on a SpectrumPrecomp model, the same order as the
# photometry LUT error, and not a rounding difference.
if approx:
if not self._model._approx.get("spectrum_precomp"):
raise ValueError(
"approx=True requires the model to be built with "
"approx=SpectrumPrecomp(...). Rebuild the model with "
"approx=SpectrumPrecomp() and try again."
)
# Free-only: predict_spectrum refuses a Fixed key of its own
# (#2296) and self-merges self.spec.get_fixed_values() internally
# on the configured-spectroscopy (predict_observables_jit) route,
# the one this approx=True branch is documented to take.
return self._model.predict_spectrum(self._free_params, wave_obs=wave_obs)
# Exact: project the cached ForwardState through the shared spectrum
# projector. ``Observation.predict`` is the canonical exact path, it
# routes through ``project_spectrum_kernel_split`` and applies the flux
# calibration (#1086), and it never falls through to the LUT. The LSF
# and kinematics kwargs come from ``_observation_predict_kwargs`` — the
# same helper :meth:`SEDModel._spectrum_via_state` uses — so this
# accessor agrees with ``model.predict_spectrum`` to numerical
# precision instead of silently falling back to
# ``Observation.predict``'s defaults (no LSF, no sigma_v_kms).
out = self._model.observation.predict(
self._ensure_state(),
self._params,
wave_obs=wave_obs,
**self._model._observation_predict_kwargs(self._free_params),
)
return out["spec_fnu"]
@property
def rest_sed(self):
r"""Rest-frame panchromatic SED, **call it**: ``pred.rest_sed()``.
A uniform callable with a default, like :meth:`photometry`,
:meth:`magnitudes` and :meth:`spectrum` (contract §4b.3).
Parameters
----------
wave : array_like, shape (n_out,), optional
Rest-frame wavelength grid to resample onto [Angstrom]. Default
``None`` returns the SED on the model's own grid
(:attr:`wave_rest`), with no interpolation.
Returns
-------
ndarray, shape (n_wave,) or (n_out,)
Rest-frame luminosity density [erg/s/Hz].
Notes
-----
**JIT-compatible**: no, a postprocessing accessor. Use the lean
``model.predict_photometry`` / ``predict_properties`` shortcuts inside
:func:`jax.jit`.
**Naming contract**: SED = panchromatic model-grid array
(:meth:`rest_sed` / :meth:`obs_sed`); spectrum = instrument-grid,
LSF-convolved, calibrated observable (:meth:`spectrum`).
**Grid**: the model's SSP grid, auto-extended when dust emission,
radio or X-ray components are configured. The axis is
:attr:`wave_rest`, the SED array does not carry it.
**Resampling** is ``jnp.interp`` onto ``wave``, bit-exact with the
wavelength argument of the deprecated ``model.predict_rest_sed``.
Examples
--------
>>> pred = model.predict(params)
>>> lnu = pred.rest_sed() # the model's own grid
>>> lnu = pred.rest_sed(np.logspace(3, 5, 500)) # your grid
>>> plt.loglog(pred.wave_rest, pred.rest_sed())
See Also
--------
obs_sed : Observed-frame SED (redshifted + IGM + DLA).
wave_rest : The wavelength axis this SED lives on.
"""
return _SEDCallable(self._rest_sed_on, "rest_sed")
def _rest_sed_on(self, wave):
"""Rest-frame L_nu, optionally resampled onto ``wave`` [Angstrom]."""
# The fast-nebular grid zeroes the Cue continuum, so ``sed_intrinsic``
# would come back without the nebular continuum or the lines (#1665).
# Same census as predict_spectrum / predict_spectral_indices.
state = self._ensure_state()
sed = state.sed_intrinsic
if wave is None:
return sed
# Same interpolation the deprecated predict_rest_sed(wave=...) used, so
# migrating a call site changes no number.
return jnp.interp(jnp.asarray(wave), state.wave, sed)
@property
def obs_sed(self):
r"""Observed-frame panchromatic SED, **call it**: ``pred.obs_sed()``.
The rest-frame SED moved onto the observed-frame wavelength axis, with
IGM (and DLA) absorption applied. "Observed" refers to the **frame**,
not to a flux conversion.
Parameters
----------
wave_obs : array_like, shape (n_out,), optional
**Observed**-frame wavelength grid to resample onto [Angstrom],
the same frame as :attr:`wave_obs`, and as :meth:`spectrum`. Default
``None`` returns the SED on the model's own grid.
Returns
-------
ndarray, shape (n_wave,)
Luminosity density L_nu [erg/s/Hz], **not** a flux.
Notes
-----
**Units, read this.** This returns **L_nu [erg/s/Hz]**, exactly like
:meth:`rest_sed`. It does **NOT** apply the cosmological dimming factor
``(1+z) / (4 pi d_L^2)``. The only differences from :meth:`rest_sed` are
the wavelength axis and IGM absorption; at z = 3 the two arrays are
identical everywhere above rest-frame Lyman-alpha.
The distance is applied at the **projection** step, not here, see
``observation/redshift_kernel.py``. The surfaces that return a genuine
flux F_nu [erg/s/cm^2/Hz] are :meth:`photometry`, :meth:`magnitudes`
and :meth:`spectrum`. Integrating ``obs_sed()`` as if it were a flux is
wrong by ~57 orders of magnitude.
(This docstring previously claimed the opposite, "Returns F_nu, not
L_nu ... accounts for the (1+z)/(4 pi d_L^2) dimming factor". It was
false, and the claim had propagated into the naming contract. Measured,
not assumed.)
**JIT-compatible**: no, a postprocessing accessor.
**Naming contract**: SED = panchromatic model-grid array
(:meth:`rest_sed` / :meth:`obs_sed`); spectrum = instrument-grid,
LSF-convolved, calibrated observable (:meth:`spectrum`).
**Wavelength frame**: observed-frame (rest x (1+z)) [Angstrom]; the
matching axis is :attr:`wave_obs`.
**Absorption**: Includes:
- IGM Lyman absorption (Inoue et al. 2014 [1]_) when ``igm=True``
- DLA (damping wing absorption) when ``dla=True``
- Reionization epoch (CGM) when configured
- Patchy reionization when configured
References
----------
.. [1] Inoue A. K., et al. 2014, MNRAS, 442, 1805, IGM absorption
tables and mean transmission.
Examples
--------
>>> pred = model.predict(params)
>>> fnu = pred.obs_sed() # the model's own grid
>>> fnu = pred.obs_sed(np.logspace(3, 5, 500)) # your grid
>>> plt.loglog(pred.wave_obs, pred.obs_sed())
See Also
--------
rest_sed : Rest-frame SED (no absorption, no redshift).
wave_obs : The observed-frame wavelength axis this SED lives on.
spectrum : Instrument-grid observable (LSF-convolved).
"""
return _SEDCallable(self._obs_sed_on, "obs_sed")
def _obs_sed_on(self, wave_obs):
"""Observed-frame F_nu, optionally resampled onto ``wave_obs`` [Angstrom].
Refuses on a fast-nebular model for the same reason as
:meth:`_rest_sed_on`; this is the same SED, on a different axis (#1665).
``wave_obs`` is OBSERVED-frame, matching this SED's own axis
(:attr:`wave_obs`) and :meth:`spectrum`. The deprecated
``model.predict_obs_sed(params, wave=...)`` took a *rest*-frame grid
and redshifted it, an observed-frame result with a rest-frame
argument. That asymmetry was a footgun; it is not reproduced here.
"""
result = self._model._predict_obs_sed(self._params)
if wave_obs is None:
return result.sed
return jnp.interp(jnp.asarray(wave_obs), result.wavelength, result.sed)
@property
def wave_rest(self):
r"""Rest-frame wavelength grid.
Returns the wavelength grid on which ``rest_sed`` and ``obs_sed`` are
evaluated. The grid is determined by the model's SSP wavelength array,
optionally extended for dust emission (IR), radio, and X-ray components.
Returns
-------
ndarray, shape (n_wave,)
Rest-frame wavelengths [Angstrom].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
Pairs exactly with ``rest_sed`` and forms the x-axis for plotting
the rest-frame SED. The same wavelength grid is shared with derived
properties (e.g., ``l_bol``, ``l_tir``, ``fuv_flux``) that integrate
over it.
Examples
--------
>>> pred = model.predict(params)
>>> wave_rest = pred.wave_rest # shape (n_wave,)
>>> sed_rest = pred.rest_sed() # the SED is a call, not an attribute
>>> wave_rest.shape == sed_rest.shape
True
See Also
--------
wave_obs : Observed-frame wavelength grid.
rest_sed : Rest-frame SED on this grid.
"""
self._ensure_sfh()
return self._cache["_state"].wave
@property
def wave_obs(self):
r"""Observed-frame wavelength grid.
Returns the observed-frame wavelength grid, computed as the rest-frame
wavelengths shifted by redshift: ``wave_obs = wave_rest * (1 + z)``.
Pairs exactly with ``obs_sed``.
Returns
-------
ndarray, shape (n_wave,)
Observed-frame wavelengths [Angstrom].
Notes
-----
**JIT-compatible**: no, Python property accessor. Use in postprocessing,
not inside :func:`jax.jit`.
The redshift value is resolved through the model's spec:
- If ``redshift`` is a free parameter, it is taken from ``params``.
- If ``redshift`` is fixed in the spec, the fixed value is used.
- If ``redshift`` is not found in either place, raises ``KeyError``.
This design avoids the silent bugs (#1097, #1124, #1127) that arose
from using ``params.get("redshift", 0.0)``, which can silently return
a default value instead of raising an error when redshift is absent.
Examples
--------
>>> pred = model.predict(params)
>>> wave_obs = pred.wave_obs # shape (n_wave,)
>>> sed_obs = pred.obs_sed() # the SED is a call, not an attribute
>>> wave_obs.shape == sed_obs.shape
True
>>> # For a model with Fixed redshift:
>>> (wave_obs / wave_rest - 1).mean() # should be z
0.1
See Also
--------
wave_rest : Rest-frame wavelength grid.
obs_sed : Observed-frame SED on this grid.
"""
z = self._model._get_redshift(self._params)
return self.wave_rest * (1.0 + z)
# ── Top-level shortcuts to grouped derived quantities ───────────────
# ``pred.stellar_mass`` and ``pred.sfh.stellar_mass`` return the same value;
# the flat form is for tab-completion convenience and aligns with how
# astronomers typically refer to derived quantities (no domain prefix).
# Where two groups expose the same name (e.g. luminosity_weighted_*),
# the flat shortcut points to the SED version, that's the canonical
# "luminosity-weighted" meaning (uses attenuated SED, not stellar-only).
# --- SFH-derived (forward to pred.sfh) ---
@property
def stellar_mass(self):
"""Total stellar mass formed [M☉]. Same as ``pred.sfh.stellar_mass``."""
return self.sfh.stellar_mass
@property
def stellar_mass_surviving(self):
"""Surviving stellar + remnant mass [M☉]. Same as ``pred.sfh.stellar_mass_surviving``."""
return self.sfh.stellar_mass_surviving
@property
def sfr_100myr(self):
"""SFR averaged over last 100 Myr [M☉/yr]. Same as ``pred.sfh.sfr_100myr``."""
return self.sfh.sfr_100myr
@property
def sfr_10myr(self):
"""SFR averaged over last 10 Myr [M☉/yr]. Same as ``pred.sfh.sfr_10myr``."""
return self.sfh.sfr_10myr
@property
def ssfr(self):
"""Specific SFR [yr⁻¹]. Same as ``pred.sfh.ssfr``."""
return self.sfh.ssfr
@property
def mass_weighted_age_gyr(self):
"""Mass-weighted stellar age [Gyr]. Same as ``pred.sfh.mass_weighted_age_gyr``."""
return self.sfh.mass_weighted_age_gyr
@property
def mass_weighted_metallicity(self):
"""Mass-weighted log₁₀(Z/Z☉). Same as ``pred.sfh.mass_weighted_metallicity``."""
return self.sfh.mass_weighted_metallicity
# --- SED-derived (forward to pred.sed) ---
@property
def l_bol(self):
"""Bolometric luminosity [L☉]. Same as ``pred.sed.l_bol``."""
return self.sed.l_bol
@property
def l_tir(self):
"""Total infrared (8–1000 μm) luminosity [L☉]. Same as ``pred.sed.l_tir``."""
return self.sed.l_tir
@property
def l_dust_absorbed(self):
"""Dust-absorbed luminosity [L☉]. Same as ``pred.sed.l_dust_absorbed``."""
return self.sed.l_dust_absorbed
@property
def irx(self):
"""Infrared excess L_TIR / L_UV(1600 Å). Same as ``pred.sed.irx``."""
return self.sed.irx
@property
def uv_slope_beta(self):
"""UV slope β in f_λ ∝ λ^β. Same as ``pred.sed.uv_slope_beta``."""
return self.sed.uv_slope_beta
@property
def dn4000(self):
"""D_n(4000) break ratio. Same as ``pred.sed.dn4000``."""
return self.sed.dn4000
@property
def balmer_break(self):
"""Balmer break flux ratio. Same as ``pred.sed.balmer_break``."""
return self.sed.balmer_break
@property
def m_uv(self):
"""Absolute magnitude at 1500 Å. Same as ``pred.sed.m_uv``."""
return self.sed.m_uv
@property
def fuv_flux(self):
"""FUV flux at 1500 Å [erg/s/cm²]. Same as ``pred.sed.fuv_flux``."""
return self.sed.fuv_flux
@property
def nuv_flux(self):
"""NUV flux at 2300 Å [erg/s/cm²]. Same as ``pred.sed.nuv_flux``."""
return self.sed.nuv_flux
@property
def fuv_flux_intrinsic(self):
"""Dust-free FUV flux. Same as ``pred.sed.fuv_flux_intrinsic``."""
return self.sed.fuv_flux_intrinsic
@property
def nuv_flux_intrinsic(self):
"""Dust-free NUV flux. Same as ``pred.sed.nuv_flux_intrinsic``."""
return self.sed.nuv_flux_intrinsic
@property
def rest_uv_color(self):
"""U-V AB color: top-hats 3200–3900 Å minus 5000–5800 Å.
Same as ``pred.sed.rest_uv_color``.
"""
return self.sed.rest_uv_color
@property
def luminosity_weighted_age_gyr(self):
"""Luminosity-weighted age [Gyr]. Same as ``pred.sed.luminosity_weighted_age_gyr``.
Both ``pred.sfh`` and ``pred.sed`` define this; the top-level shortcut
forwards to the SED version (canonical "luminosity-weighted" using the
attenuated stellar SED).
"""
return self.sed.luminosity_weighted_age_gyr
@property
def luminosity_weighted_metallicity(self):
"""Luminosity-weighted log₁₀(Z/Z☉).
Same as ``pred.sed.luminosity_weighted_metallicity``.
"""
return self.sed.luminosity_weighted_metallicity
# --- Emission lines (forward to pred.lines) ---
@property
def halpha(self):
"""Hα 6564 Å luminosity [Lsun]. Same as ``pred.lines.halpha``."""
return self.lines.halpha
@property
def hbeta(self):
"""Hβ 4862 Å luminosity [Lsun]. Same as ``pred.lines.hbeta``."""
return self.lines.hbeta
@property
def oiii_5007(self):
"""[O III] 5007 Å luminosity [Lsun]. Same as ``pred.lines.oiii_5007``."""
return self.lines.oiii_5007
@property
def balmer_decrement(self):
"""Hα/Hβ flux ratio. Same as ``pred.lines.balmer_decrement``."""
return self.lines.balmer_decrement
# --- Ionizing budget (forward to pred.ionizing) ---
@property
def q_h(self):
"""Retired, no alias (#1206 §C). Raises ``KeyError`` naming ``log_q_h``.
Same as ``pred.ionizing.q_h``.
"""
return self.ionizing.q_h
@property
def log_q_h(self):
"""log10 ionizing photon production rate [dex re s⁻¹].
Same as ``pred.ionizing.log_q_h``.
"""
return self.ionizing.log_q_h
@property
def xi_ion(self):
"""Ionizing photon production efficiency [Hz·erg⁻¹]. Same as ``pred.ionizing.xi_ion``."""
return self.ionizing.xi_ion