Predicting and properties¶
The core workflow after building a model is to generate predictions (forward pass results and derived physical quantities). This page covers the three prediction surfaces, the property catalog, and common workflows.
The three prediction surfaces¶
tengri provides three interfaces for computing predictions, each optimized for a different use case:
1. Lazy exploration: model.predict(params)¶
For interactive work (plotting, diagnostics, manual inspection), the recommended interface is the lazy Prediction object:
pred = model.predict(params)
# Lazy evaluation: only computed when first accessed
print(pred.sfh.stellar_mass) # shape: scalar, triggers SFH computation
print(pred.sed.l_bol) # shape: scalar, triggers SED computation
print(pred.lines.halpha) # shape: scalar, triggers nebular computation
# Repeated access reuses cached results (no recomputation)
print(pred.sfh.stellar_mass) # cached, no re-run
The Prediction object caches intermediate results, so related quantities share expensive computation. This is ideal for one-off fits or notebook exploration.
When to use: Single-galaxy analysis, model diagnostics, fitting a single spectrum.
2. Inference hot path: model.predict_photometry(), model.predict_spectrum(), etc.¶
For inference loops and likelihood evaluation, use the lean methods directly:
# These methods are called by the inference loop
photometry = model.predict_photometry(params) # the filters built into the model
spectrum = model.predict_spectrum(params, wave_obs)
lines = model.predict_emission_lines(params)
These bypass the lazy Prediction wrapper and return only what you request, with no caching overhead. They are JIT-compatible and safe to call from inside an inference loop. The lean predict_photometry uses the filters the model was built with; to evaluate a different filter set at runtime, use the rich accessor pred.photometry(filters=[...]) instead (see Exact vs fast photometry).
When to use: Likelihood evaluation, fitting, parameter sweeps.
3. Batch (posterior) computation: model.predict_properties() + jax.vmap¶
For computing derived quantities over many parameter sets (posterior chains, mock catalogs, parameter grids), use the JIT-compatible property method with jax.vmap:
import jax
import jax.numpy as jnp
# Batch of parameter sets (e.g., from posterior samples or a grid)
params_batch = spec.sample_batch(key, n=10_000)
# vmap over property computation
def predict_one_property(params):
return model.predict_properties(params, names=("stellar_mass",))["stellar_mass"]
fn = jax.vmap(predict_one_property)
stellar_mass_batch = fn(params_batch) # shape (10_000,)
This path is 100–1000× faster than calling .predict() in a loop, with no Python-level overhead.
When to use: Computing posterior summaries, generating mock catalogs, batch inference diagnostics.
The property catalog¶
A tengri model publishes derived quantities (stellar mass, SFR, emission line luminosities, colors, and diagnostics). These are called properties.
Discovering properties¶
Use list_properties() and describe_property() to explore what is available:
from tengri import list_properties, describe_property
# Print all available properties
print(list_properties())
# Filter by group
print(list_properties(group="sfh")) # star formation history
print(list_properties(group="sed")) # spectral energy distribution
print(list_properties(group="lines")) # emission lines
print(list_properties(group="radio")) # radio
print(list_properties(group="xray")) # X-ray
print(list_properties(group="ionizing")) # ionizing photon budget
# Get detailed info about one
print(describe_property("stellar_mass"))
# Output:
# name stellar_mass
# units Msun
# group sfh
# component stellar
# description Total stellar mass formed by the SFH — its time-integral,
# 1.5-1.9x above stellar_mass_surviving
Warning
stellar_mass is the mass formed — the time-integral of the SFH. Stellar
evolution returns a third to a half of it to the ISM, so it runs 1.5-1.9x above
stellar_mass_surviving on ordinary populations. Quote whichever one your
comparison sample uses; they are not interchangeable.
Accessing properties: two forms¶
Properties can be accessed in two ways: attribute sugar or dict-like access:
pred = model.predict(params)
# Form 1: Attribute sugar via lazy groups
print(pred.sfh.stellar_mass) # via the sfh group
print(pred.sed.l_bol) # via the sed group
print(pred.lines.halpha) # via the lines group
# Form 2: Direct attribute (shorthand)
print(pred.stellar_mass) # same as pred.sfh.stellar_mass
print(pred.l_bol) # same as pred.sed.l_bol
# Form 3: Dict-like access (used internally)
print(pred.properties["stellar_mass"]) # explicit dict access
Full property catalog¶
Name |
Units |
Group |
Component |
Description |
|---|---|---|---|---|
|
Lsun |
agn |
agn |
log_L_agn_adaf_accretion in solar luminosities; composable with the ‘adaf’ disc only |
|
erg/s |
agn |
agn |
AGN accretion power 10**agn_log_lbol L_sun |
|
Lsun |
agn |
agn |
10**agn_log_lbol, the accretion power in solar luminosities |
|
Lsun |
agn |
agn |
log_L_agn_direct_los in solar luminosities; composable only |
|
Lsun |
agn |
agn |
log_L_agn_disc_los in solar luminosities |
|
Lsun |
agn |
agn |
log_L_agn_disc in solar luminosities |
|
Lsun |
agn |
agn |
log_L_agn_disc_unemitted in solar luminosities |
|
Lsun |
agn |
agn |
log_L_agn_lines_los in solar luminosities |
|
Lsun |
agn |
agn |
log_L_agn_lines in solar luminosities |
|
Lsun |
agn |
agn |
log_L_agn_lines_unemitted in solar luminosities |
|
Lsun |
agn |
agn |
log_L_agn_los in solar luminosities |
|
Lsun |
agn |
agn |
log_L_agn_polar_dust_los in solar luminosities |
|
Lsun |
agn |
agn |
log_L_agn_polar_dust in solar luminosities |
|
Lsun |
agn |
agn |
log_L_agn_power in solar luminosities |
|
Lsun |
agn |
agn |
log_L_agn_torus_los in solar luminosities |
|
Lsun |
agn |
agn |
log_L_agn_torus in solar luminosities |
|
Lsun |
agn |
agn |
log_L_agn_torus_unemitted in solar luminosities |
|
— |
agn |
agn |
ADAF accretion rate in Eddington units, mdot = Mdot / Mdot_Edd (Mahadevan 1997, Eq. 4); composable with the ‘adaf’ disc only |
|
— |
agn |
agn |
AGN fraction agn_ir_frac measures, from what the model emitted: the AGN dust power over AGN dust plus the host’s absorbed power (total dust), or the AGN share of the light in ir_frac_window. Equals agn_ir_frac where agn_ir_frac_saturated is 0 and agn_ledger_closed is 1; composable AGN only |
|
— |
agn |
agn |
1.0 when agn_norm=’conserving’ cannot reach the requested agn_ir_frac: the covering factor it asks for sits at a bound of [0, 1] (or at the line bound 1 - E_lines/E_disc), so agn_ir_frac_realized differs from agn_ir_frac; else 0.0. Composable AGN only |
|
— |
agn |
agn |
1.0 when the angle-integrated pieces plus the unemitted ones add up to the accretion power agn_lum_ratio * 10**agn_log_lbol L_sun, else 0.0 (self-contained quasar templates, agn_norm=’independent’, ‘cigale_joint’ with lines or an active agn_ir_frac tie, polar dust beside a library torus with anisotropy); composable AGN only |
|
— |
agn |
agn |
torus fraction the composable AGN was evaluated at; composable only |
|
— |
sed |
stellar |
Balmer break diagnostic |
|
— |
lines |
nebular |
Balmer decrement: Hα/Hβ |
|
dex |
lines |
nebular |
BPT-NII diagnostic: log10([NII]6584 / Hα) |
|
dex |
lines |
nebular |
BPT-SII diagnostic: log10(([SII]6717+6731) / Hα) |
|
Lsun |
lines |
nebular |
CIV 1549 line luminosity, NaN with a warning on cue’s legacy 128-line subset (full_catalog=false), where no catalog line falls within tolerance of this wavelength (#2239) |
|
— |
sed |
stellar |
D n4000 break diagnostic |
|
erg/s/Hz |
sed |
stellar |
FUV flux (1000–1700 Å) |
|
erg/s/Hz |
sed |
stellar |
Intrinsic FUV flux before dust attenuation |
|
Lsun |
lines |
nebular |
Hα line luminosity |
|
Lsun |
lines |
nebular |
Hβ line luminosity |
|
dex |
sed |
stellar |
Infrared excess, log10(L_TIR / nu*L_nu at 1600 A): the Meurer+99 IRX-beta anchor |
|
dex |
sed |
stellar |
Infrared excess against the band-averaged FUV (1000-1700 A), pivoted at 1500 A |
|
erg/s/Hz |
radio |
radio |
1.4 GHz radio flux |
|
Lsun |
sed |
stellar |
Bolometric luminosity |
|
Lsun |
sed |
stellar |
Dust-absorbed luminosity |
|
erg/s/Hz |
radio |
radio |
Radio non-thermal synchrotron luminosity |
|
erg/s/Hz |
radio |
radio |
Radio thermal (free-free) luminosity |
|
Lsun |
sed |
stellar |
Infrared luminosity (8–1000 µm) |
|
Lsun |
xray |
xray |
X-ray luminosity from AGN. |
|
Lsun |
xray |
xray |
Total X-ray luminosity (XRB + AGN). |
|
Lsun |
xray |
xray |
X-ray luminosity from X-ray binaries. |
|
dex |
agn |
agn |
log10 of the ADAF accretion power eta_eff Mdot c^2 [dex re erg/s], eta_eff = 0.1; composable with the ‘adaf’ disc only |
|
dex |
agn |
agn |
log10(L_agn_bol / (erg/s)), float32-safe |
|
dex |
agn |
agn |
log10 of the line-of-sight isotropic-equivalent direct AGN luminosity [dex re erg/s]; composable only |
|
dex |
agn |
agn |
log10 power [dex re erg/s] of the disc (with its corona) as emitted, integrated over all directions (sphere mean over cos i); composable AGN only |
|
dex |
agn |
agn |
log10 power [dex re erg/s] of the disc (with its corona) as emitted along agn_cos_inc, the integral of that piece of the SED; composable AGN only |
|
dex |
agn |
agn |
log10 power [dex re erg/s] carried by the disc (with its corona) but removed before it leaves the AGN (torus screen, polar dust, attenuation block, disc reddening), integrated over all directions; composable AGN only |
|
dex |
agn |
agn |
log10 power [dex re erg/s] of the NLR + BLR + FeII emission lines as emitted, integrated over all directions (sphere mean over cos i); composable AGN only |
|
dex |
agn |
agn |
log10 power [dex re erg/s] of the NLR + BLR + FeII emission lines as emitted along agn_cos_inc, the integral of that piece of the SED; composable AGN only |
|
dex |
agn |
agn |
log10 power [dex re erg/s] carried by the NLR + BLR + FeII emission lines but removed before it leaves the AGN (torus screen, polar dust, attenuation block, disc reddening), integrated over all directions; composable AGN only |
|
dex |
agn |
agn |
log10 of the emitted AGN SED integrated over frequency along agn_cos_inc [dex re erg/s], the line-of-sight sum of the ledger pieces; composable AGN only |
|
dex |
agn |
agn |
log10 power [dex re erg/s] of the polar-dust re-emission as emitted, integrated over all directions (sphere mean over cos i); composable AGN only |
|
dex |
agn |
agn |
log10 power [dex re erg/s] of the polar-dust re-emission as emitted along agn_cos_inc, the integral of that piece of the SED; composable AGN only |
|
dex |
agn |
agn |
log10 of the AGN dust power the runner normalizes the torus and the polar dust on [dex re erg/s], the torus block’s power along agn_cos_inc (CIGALE’s agn_power, the anchor of the agn_ir_frac tie); composable AGN with a torus only |
|
dex |
agn |
agn |
log10 power [dex re erg/s] of the torus dust as emitted, integrated over all directions (sphere mean over cos i); composable AGN only |
|
dex |
agn |
agn |
log10 power [dex re erg/s] of the torus dust as emitted along agn_cos_inc, the integral of that piece of the SED; composable AGN only |
|
dex |
agn |
agn |
log10 power [dex re erg/s] carried by the torus dust but removed before it leaves the AGN (torus screen, polar dust, attenuation block, disc reddening), integrated over all directions; composable AGN only |
|
dex |
lines |
nebular |
log10 of civ 1549 line luminosity, nan with a warning on cue’s legacy 128-line subset (full_catalog=false), where no catalog line falls within tolerance of this wavelength (#2239) [dex re erg/s]; float32-safe form of |
|
dex |
lines |
nebular |
log10 of hα line luminosity [dex re erg/s]; float32-safe form of |
|
dex |
lines |
nebular |
log10 of hβ line luminosity [dex re erg/s]; float32-safe form of |
|
dex |
xray |
xray |
log10 X-ray luminosity from AGN [dex re erg/s]; float32-safe form of |
|
dex |
xray |
xray |
log10 luminosity of the unabsorbed AGN corona integrated over 0.25-1240 keV, the pcigale yang20 grid [dex re erg/s]; -inf without an AGN |
|
dex |
xray |
xray |
log10 2-10 keV luminosity of the HMXB term [dex re erg/s] |
|
dex |
xray |
xray |
log10 0.5-2 keV luminosity of the hot-gas term [dex re erg/s] |
|
dex |
xray |
xray |
log10 2-10 keV luminosity of the LMXB term [dex re erg/s] |
|
dex |
xray |
xray |
log10 total X-ray luminosity (XRB + AGN) [dex re erg/s]; float32-safe form of |
|
dex |
xray |
xray |
log10 X-ray luminosity from X-ray binaries [dex re erg/s]; float32-safe form of |
|
dex |
xray |
xray |
log10 intrinsic 2 keV monochromatic L_nu at an inclination of 30 deg (cos i = 0.866), the alpha_ox anchor [dex re erg/s/Hz]; -inf without an AGN and under lopez24 |
|
dex |
lines |
nebular |
log10 of lyman alpha line luminosity [dex re erg/s]; float32-safe form of |
|
dex |
lines |
nebular |
log10 of nii 6548 line luminosity [dex re erg/s]; float32-safe form of |
|
dex |
lines |
nebular |
log10 of nii 6584 line luminosity [dex re erg/s]; float32-safe form of |
|
dex |
lines |
nebular |
Absolute [N/O] = log10((N/O)/(N/O)_sun) the Cue backend is fed: gas_logno under nitrogen=’absolute’, else the named N/O-O/H relation at the gas metallicity plus gas_logno. NaN for other backends. |
|
dex |
lines |
nebular |
log10 of oii line luminosity [dex re erg/s]; float32-safe form of |
|
dex |
lines |
nebular |
log10 of oiii 4959 line luminosity [dex re erg/s]; float32-safe form of |
|
dex |
lines |
nebular |
log10 of oiii 5007 line luminosity [dex re erg/s]; float32-safe form of |
|
dex |
ionizing |
stellar |
log10(ionizing photon production rate / (photons/s)). |
|
dex |
lines |
nebular |
log10 of sii 6717 line luminosity [dex re erg/s]; float32-safe form of |
|
dex |
lines |
nebular |
log10 of sii 6731 line luminosity [dex re erg/s]; float32-safe form of |
|
Gyr |
sfh |
stellar |
Luminosity-weighted mean age of stellar population |
|
dex |
sfh |
stellar |
Luminosity-weighted mean metallicity (log10 Z/Zsun) |
|
Lsun |
lines |
nebular |
Lyman alpha line luminosity |
|
AB mag |
sed |
stellar |
UV absolute magnitude (1600 Å) |
|
Gyr |
sfh |
stellar |
Mass-weighted mean age of stellar population |
|
dex |
sfh |
stellar |
Mass-weighted mean metallicity (log10 Z/Zsun) |
|
Lsun |
lines |
nebular |
NII 6548 line luminosity |
|
Lsun |
lines |
nebular |
NII 6584 line luminosity |
|
erg/s/Hz |
sed |
stellar |
NUV flux (1700–3000 Å) |
|
erg/s/Hz |
sed |
stellar |
Intrinsic NUV flux before dust attenuation |
|
dex |
lines |
nebular |
O32 ionization parameter: log10([OIII]5007 / [OII]) |
|
dex |
lines |
nebular |
[OIII]5007/Hβ diagnostic: log10([OIII]5007 / Hβ) |
|
Lsun |
lines |
nebular |
OII line luminosity |
|
Lsun |
lines |
nebular |
OIII 4959 line luminosity |
|
Lsun |
lines |
nebular |
OIII 5007 line luminosity |
|
— |
radio |
radio |
Radio-infrared correlation parameter |
|
dex |
lines |
nebular |
R23 metallicity indicator: log10(([OII]+[OIII]4959+5007)/Hβ) |
|
AB mag |
sed |
stellar |
Rest-frame U-V color [AB mag]: top-hats 3200–3900 Å minus 5000–5800 Å |
|
Gyr |
sfh |
stellar |
Resolved sfh_cexp_age_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_const_start_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_declining_exp_age_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_delayed_age_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_delayed_bq_age_main_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_dexp_start_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_dpl_age_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_dpl_lookback_age_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_exp_start_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_lnorm_age_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_norm_peak_lbt_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_periodic_age_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_psb2022_tflex_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_psb2022_tlast_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_psb_age_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_psb_flex_tflex_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_psb_flex_tlast_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_sfh2exp_age_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_snorm_burst_peak_lbt_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_snorm_peak_lbt_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_trunc_exp_age_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_tsnorm_burst_peak_lbt_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Gyr |
sfh |
stellar |
Resolved sfh_tsnorm_peak_lbt_gyr of the active SFH: frac * age(z) when its fraction is sampled, the Fixed Gyr otherwise; NaN when the SFH has no such timing |
|
Msun/yr |
sfh |
stellar |
Star formation rate averaged over past 100 Myr |
|
Msun/yr |
sfh |
stellar |
Star formation rate averaged over past 10 Myr |
|
Lsun |
lines |
nebular |
SII 6717 line luminosity |
|
Lsun |
lines |
nebular |
SII 6731 line luminosity |
|
1/yr |
sfh |
stellar |
Specific star formation rate (sfr_100myr / stellar_mass_surviving; falls back to the formed mass when the SSP has no mass-remaining table) |
|
Msun |
sfh |
stellar |
Total stellar mass formed by the SFH: its time-integral, 1.5-1.9x above stellar_mass_surviving |
|
Msun |
sfh |
stellar |
Total surviving stellar mass |
|
— |
sed |
stellar |
UV slope (β in L_ν ∝ ν^β) |
|
Hz/erg |
ionizing |
stellar |
Ionizing photon efficiency |
Topology: same names, more axes¶
One principle unifies the API: the same property names work everywhere, but with different shapes depending on context.
Context |
Shape |
Example |
|---|---|---|
Prediction (single galaxy) |
scalar |
|
Posterior (samples) |
|
|
Population catalog |
|
Grid or mock catalog |
So you can write one function that works on all topologies:
def print_stellar_mass(entity):
"""Works on Prediction, Posterior, or catalog."""
mass = entity.properties["stellar_mass"]
print(f"Stellar mass: {mass}")
# All three calls work identically:
print_stellar_mass(pred) # scalar
print_stellar_mass(posterior) # (n_samples,) array
print_stellar_mass(population) # (n_galaxies,) array
Posterior-specific: credible intervals¶
For posteriors, use the .ci() method to compute credible intervals:
result = model.fit(data, noise)
posterior = result.posterior
# Credible interval on a property
lo, median, hi = posterior.properties.ci("stellar_mass")
# Default: 68% (16th/84th percentiles)
# Custom credible level
lo, median, hi = posterior.properties.ci("stellar_mass", level=0.95)
# 95% credible interval (2.5th/97.5th percentiles)
print(f"Stellar mass: {median:.2e} (−{median - lo:.2e} / +{hi - median:.2e}) Msun")
SED vs spectrum: naming and conventions¶
Two distinct concepts: understand the difference.
SED: panchromatic model grid¶
rest_sed and obs_sed are callables with a default, like photometry() and spectrum(). Call with no argument for the model’s own grid, or pass a wavelength grid to resample onto yours:
pred = model.predict(params)
# Rest-frame SED on the model's own grid
lnu = pred.rest_sed() # (n_wave,) [erg/s/Hz]
wave = pred.wave_rest # (n_wave,) [Angstrom] — the matching axis
# ...or on a grid you choose
lnu = pred.rest_sed(np.logspace(3, 5, 500)) # rest-frame Angstrom
# Observed-frame: redshift + IGM attenuation applied
lnu = pred.obs_sed() # (n_wave,) [erg/s/Hz] — STILL L_nu, not a flux
wave = pred.wave_obs # the matching observed-frame axis
lnu = pred.obs_sed(np.logspace(3, 5, 500)) # OBSERVED-frame Angstrom
The wavelength argument is in the accessor’s own frame: rest_sed(wave) takes rest-frame Å, obs_sed(wave_obs) takes observed-frame Å.
The SED array does not carry its axis. Use pred.wave_rest / pred.wave_obs. Never reconstruct the observed axis by hand as wave * (1 + params["redshift"]): a Fixed redshift is legitimately absent from params, and a 0.0 fallback silently puts the galaxy at 10 pc.
The model grid is the SSP grid, auto-extended when dust emission, radio or X-ray components are configured.
Note
pred.rest_sed without the parentheses raises TypeError. It is a method, and a bound method coerced with np.asarray would otherwise produce a dtype=object array that plots silently-wrong results. The error message tells you the fix.
Units: the distance is applied at projection, not on the SED¶
obs_sed is not a flux. “Observed” names the frame, not a flux conversion.
surface |
quantity |
units |
|---|---|---|
|
L_ν, rest-frame axis |
erg/s/Hz |
|
L_ν — observed-frame axis + IGM |
erg/s/Hz |
|
F_ν |
erg/s/cm²/Hz |
|
AB magnitude |
— |
|
F_ν |
erg/s/cm²/Hz |
obs_sed() does not apply (1+z)/(4π d_L²); that factor lives in the projection layer. The only differences from rest_sed() are the wavelength axis and IGM absorption (at z = 3 the two arrays are identical everywhere above rest-frame Lyman-α).
Integrating obs_sed() as if it were a flux is wrong by ~57 orders of magnitude. If you want a flux, use photometry() or spectrum().
Spectrum: instrument-specific, LSF-convolved, calibrated¶
The .spectrum() method returns an instrument-ready spectrum (convolved with the line-spread function, rebinned to a specific wavelength grid, and calibrated). It requires the model to have a spectroscopy channel: build with observation=Observation(spectroscopy=...), otherwise pred.spectrum(...) raises ValueError (a photometry-only model has no LSF or calibration to apply). For a bare model SED with no instrument convolution, use pred.obs_sed(wave_obs) instead.
# Spectrum at specific observer-frame wavelengths.
# Give the grid you actually observed on — do not build it from a rest-frame
# grid times (1 + z). `wave_obs` is already in the observer frame.
obs_wave = jnp.linspace(4000, 7000, 200) # Å, observer-frame
spec = pred.spectrum(wave_obs=obs_wave)
# spec.flux — F_ν at observed wavelengths [erg/s/cm²/Å]
# spec.error — noise model prediction [erg/s/cm²/Å]
Key differences from SED:
Grid: User-specified (not the model grid)
Frame: Observed-frame wavelengths
Calibration: Applied (photometry, line spread, noise)
Units: F_ν (erg/s/cm²/Å), a flux per unit wavelength
Summary table:
Aspect |
SED (rest_sed, obs_sed) |
Spectrum |
|---|---|---|
Grid |
Model internal |
Observer-specified |
Frame |
Rest (rest_sed) / Obs (obs_sed) |
Observer (wavelengths input as observed-frame) |
Calibration |
None |
Full (LSF, noise model, photometric calibration) |
Units |
erg/s/Hz (L_ν) |
erg/s/cm²/Å (F_ν) — divided by 4π d_L² |
Use case |
Model diagnostics, color/index computation |
Spectroscopic fitting, comparison with data |
Exact vs fast photometry¶
By default, photometry and spectroscopy predictions are exact (integrated over the model’s full wavelength grid):
pred = model.predict(params)
# Exact integration over the full SED grid
photometry = pred.photometry() # filters built into the model
spectrum = pred.spectrum(wave_obs=...)
If the model was built with a precomputation (approx=WavePrecomp(...)), you can opt into a fast lookup-table path:
# ONLY valid if the model was built with approx=WavePrecomp()
photometry_fast = pred.photometry(approx=True) # uses precomputed LUT
spectrum_fast = pred.spectrum(wave_obs=..., approx=True) # interpolates precomputed LUT
When to use fast¶
During inference: Fitting uses the approximation that was baked in at build time. Set it with
approx=at build (ormodel.with_approx(...), which returns a clone); read it back withmodel.approx, which reports the LUTs that actually resolved.Post-fit inspection: Use
approx=Trueto match inference exactly.Speed-critical analysis: e.g., generating a mock catalog of 1 million galaxies.
When not to use fast¶
Changing filters at runtime (
pred.photometry(filters=[...])): incompatible withapprox=True— raisesValueError.Exact science: Analysis grids where pre-computed filters would bias the results.
The principle¶
A speed knob must never silently change the physics. If you pass approx=True, you are explicitly saying “use the approximation baked into the model”. Changing filters invalidates the precomputation, so it is forbidden.
Mock catalogs: batch prediction from arbitrary parameters¶
The model is a pure function of parameters. You can generate mock catalogs from any batch of parameter sets (prior samples, a grid, hand-tuned values) without a fit or observed data:
import jax
import jax.numpy as jnp
import numpy as np
from tengri import FREE, Fixed, SEDModel, Observation, Photometry, WavePrecomp
# Build a model with only photometry. Groups are explicit: an omitted
# dust_attenuation means no dust, and parameters default to fixed, so free
# parameters must be declared. approx=WavePrecomp() routes photometry through
# the band-response table, which is what makes a batch of a thousand draws
# cheap: the exact wave-grid path would hold a (n_draw, n_age, n_wave) stack.
model = SEDModel.build(
ssp_data=ssp,
observation=Observation(
photometry=Photometry.from_names(["sdss_g", "sdss_r", "sdss_i"])
),
sfh={"type": "dpl", "all_params": FREE},
dust_attenuation={"type": "two_component", "law": "calzetti", "all_params": FREE},
redshift=Fixed(0.1),
approx=WavePrecomp(),
)
# Method 1: Sample from the prior
key = jax.random.PRNGKey(0)
params_prior = model.spec.sample_batch(key, n=1000) # shape: dict of (1000,) arrays
# Method 2: Hand-built parameter dict (all parameter names required)
params_grid = {
"sfh_dpl_alpha": jnp.linspace(0.5, 2.0, 50),
"sfh_dpl_beta": jnp.linspace(0.1, 1.5, 50),
"dust_tau_bc": jnp.linspace(0.0, 1.0, 50),
# ... all free parameters
}
# Batch prediction: vmap over the model forward
def predict_photometry_batch(params_batch):
def predict_one(p):
return model.predict_photometry(p)
return jax.vmap(predict_one)(params_batch)
mocks = predict_photometry_batch(params_prior)
# mocks.photometry shape: (1000,), each element is the photometry dict
# Extract and table: one properties pass per draw, both names at once.
# Properties need a full forward state per draw, so map them sequentially
# (lax.map); vmap would hold every draw's SED stack in memory at once.
props = jax.lax.map(
lambda p: model.predict_properties(p, names=("stellar_mass", "sfr_100myr")),
params_prior,
)
stellar_masses = props["stellar_mass"]
sfrs = props["sfr_100myr"]
# Write the table (a pandas DataFrame works the same way from these arrays)
catalog = np.column_stack([np.array(stellar_masses), np.array(sfrs)])
np.savetxt(
"mock_catalog.csv",
catalog,
delimiter=",",
header="stellar_mass_msun,sfr_100myr_msunyr",
comments="",
)
This workflow is pure JAX — no loop, fully differentiable, and trivial to parallelize.
Error handling: unknown properties raise, never return NaN¶
If you request a property the model does not provide, you get a clear error naming the available ones (never a silent NaN or None). Which exception you catch depends on how you asked:
Access style |
Raises |
|---|---|
|
|
|
|
pred = model.predict(params)
try:
print(pred.nonexistent_property) # attribute sugar
except AttributeError as e:
print(f"Error: {e}")
print("Available properties:", list(pred.properties.keys()))
try:
print(pred.properties["nonexistent"]) # catalog access
except KeyError as e:
print(f"Error: {e}")
The model always knows which properties are available. Never silently return NaN for an unknown name.
See also¶
tengri.list_properties()— discover all available propertiestengri.describe_property()— get detailed info on onePrediction— lazy exploration objectPosterior— fitting results with credible intervalsSEDModel.predict_properties()— the underlying JIT/vmap-safe methodObservation.predict()— likelihood evaluation (predict_via_precomp()on the precompute path)