Physics models

The building blocks of tengri’s forward model: star formation history parameterizations, power spectral density functions, dust attenuation, stellar population synthesis, and filter handling.

Star formation history

Analytic mean-SFH functional forms. Each takes a log-age grid and shape parameters, returning SFR in solar masses per year.

tengri.tsnorm(t_lookback: Array, log_total_mass: float, peak_lbt: float, width: float, skew: float, trunc: float) → Array

Truncated skew-normal star formation history (Bellstedt+2020).

The most flexible smooth SFH model: a skewed Gaussian kernel multiplied by a normal CDF truncation factor that smoothly suppresses star formation at recent times (young lookback times).

Parameters:
  • t_lookback (array_like, shape (n_age,)) – Lookback time [yr].

  • log_total_mass (float) – log10 of total stellar mass formed [Msun]. The shape is rescaled so that trapezoid(sfr, t_lookback) = 10**log_total_mass exactly.

  • peak_lbt (float) – Peak lookback time [yr].

  • width (float) – Gaussian width parameter [yr]. SSP grid aliasing: the forward model interpolates SFR(t) at SSP grid points (a point-sample, not a bin-integral), so a width narrower than the local SSP grid spacing at the burst peak produces a non-physical staircase as the peak crosses adjacent grid boundaries. Rough minimum: width ≳ 0.3 Gyr at peaks < 2 Gyr, ≳ 0.6 Gyr past 5 Gyr. See issue #299. SEDModel.build emits a SFHBurstAliasingWarning when the chosen width is too narrow for the SSP grid.

  • skew (float) – Skewness parameter [dimensionless]. 0 = symmetric, >0 skews toward older ages.

  • trunc (float) – Truncation sharpness [dimensionless]. Larger values produce sharper truncation. Typical range: 1-10.

Returns:

SFR at each lookback time [Msun/yr], non-negative, integrating to 10**log_total_mass over the input grid.

Return type:

ndarray, shape (n_age,)

Notes

JIT-compatible: yes, uses jnp primitives and jax.lax.erfc.

Gradient-safe: yes, differentiable everywhere except at SFR=0 (where gradient is ill-defined but finite).

The SFH shape is:

\[S(t) = K(t) \, T(t)\]

rescaled by \(10^{\log M_{\rm tot}} / \int S(t)\,dt\) so the total stellar mass formed equals \(10^{\log M_{\rm tot}}\). \(K(t)\) is the skewed Gaussian kernel and \(T(t)\) is the truncation factor:

\[K(t) = \exp\left( -\frac{Y(t)^2}{2} \right), \quad Y(t) = \frac{t - t_{\rm peak}}{w} \exp(\gamma \, \mathrm{arcsinh}(Y))\]
\[T(t) = \frac{1}{2} \mathrm{erfc}\left( \frac{t - t_{\rm peak}}{w \cdot f_{\rm trunc} \sqrt{2}} \right) # noqa: E501\]

where \(w\) is width [yr], \(\gamma\) is skewness [dimensionless], and \(f_{\rm trunc}\) is the truncation sharpness [dimensionless].

Approximation: The skewness is implemented via the Robotham+2020 formulation (arcsinh-based) rather than the classical Owen’s lambda transformation. This provides better numerical stability and JAX compatibility.

References

[tengri.tsnorm-1]

S. Bellstedt et al., “Galaxy And Mass Assembly (GAMA): a forensic SED reconstruction of the cosmic star formation history and metallicity evolution by galaxy type,” MNRAS, 498, 5581 (2020). arXiv:2005.11917. https://doi.org/10.1093/mnras/staa2620

[tengri.tsnorm-2]

A. S. G. Robotham et al., “ProSpect: generating spectral energy distributions with complex star formation and metallicity histories,” MNRAS, 495, 905 (2020). arXiv:2002.06980. https://doi.org/10.1093/mnras/staa1116

Examples

>>> import jax.numpy as jnp
>>> from tengri.components.stellar.sfh import truncated_skewnormal
>>> t = jnp.linspace(0.0, 13.7e9, 100)
>>> sfr = truncated_skewnormal(
...     t, log_total_mass=10.0, peak_lbt=5e9, width=2e9, skew=0.0, trunc=5.0
... )
>>> sfr.shape
(100,)
tengri.dpl(t_lookback: Array, alpha: float, beta: float, tau: float, age: float, log_total_mass: float) → Array[source]

Double power-law SFH (Carnall+2018 / BAGPIPES dblplaw).

\[\mathrm{SFR}(T) \propto \bigl[(T/\tau)^{\alpha} + (T/\tau)^{-\beta}\bigr]^{-1}, \quad T = \mathrm{age} - t_{\mathrm{lb}} \ge 0\]

where \(T\) is cosmic time since galaxy formation and \(t_{\mathrm{lb}}\) is lookback time. The SFR turns over at \(T = \tau\,(\beta/\alpha)^{1/(\alpha+\beta)}\). The shape is rescaled so the integrated mass equals 10**log_total_mass.

Convention. Matches Carnall et al. (2018) and BAGPIPES dblplaw exactly when age is the age of the universe at the source redshift (BAGPIPES measures the double power-law forward from the Big Bang, i.e. formation at T = 0). The time variable handed in is always lookback time; the cosmic-time conversion T = age - t_lookback happens here, the same way sfhdelayed() does it. Resolves the time-reversal of #514.

Parameters:
  • t_lookback (array_like, shape (n_age,)) – Lookback time [yr].

  • alpha (float) – Falling (late-time) slope exponent [dimensionless]. Typical 0.5-4.

  • beta (float) – Rising (early-time) slope exponent [dimensionless]. Typical 0.3-3.

  • tau (float) – Turnover timescale [yr], in cosmic time since formation.

  • age (float) – Cosmic time available for star formation [yr] = lookback time of formation. Set to age_of_universe(z) for BAGPIPES parity. SFR is zero before formation (t_lookback > age).

  • log_total_mass (float) – log10 of total stellar mass formed [Msun]. The shape is rescaled so that trapezoid(sfr, t_lookback) = 10**log_total_mass.

Returns:

SFR at each lookback time [Msun/yr].

Return type:

ndarray, shape (n_age,)

Notes

JIT-compatible: yes, all operations use jnp primitives.

See double_powerlaw() for the bare shape (no formation anchor).

Examples

>>> import jax.numpy as jnp
>>> from tengri import dpl
>>> t = jnp.logspace(7, 10.14, 64)
>>> sfr = dpl(t, alpha=1.5, beta=0.5, tau=3e9, age=13.6e9, log_total_mass=10.0)
>>> sfr.shape
(64,)
tengri.double_powerlaw(t_lookback: Array, alpha: float, beta: float, tau: float, norm: float, *, age: float) → Array[source]

Double power law star formation history (Carnall+2018, BAGPIPES).

A flexible two-parameter SFH model that peaks near a characteristic timescale and can smoothly transition between rising and declining phases.

Parameters:
  • t_lookback (array_like, shape (n_age,)) – Lookback time [yr].

  • alpha (float) – Falling (late-time) slope exponent [dimensionless]. Controls the decline from peak to present. Larger alpha = steeper decline. Typical range: 0.5-4.

  • beta (float) – Rising (early-time) slope exponent [dimensionless]. Controls the rise from formation to peak. Larger beta = steeper rise. Typical range: 0.3-3.

  • tau (float) – Turnover timescale [yr]. Approximately when SFR peaks in cosmic time since formation.

  • norm (float) – Normalization factor [Msun/yr]. Note: this controls overall amplitude, not stellar mass. \(M_\star = \int \mathrm{SFR}(t) \, dt\) is derived.

  • age (float) – Cosmic time available for star formation [yr]. Set to the age of the universe at the source redshift. SFR is zero for t_lookback > age (before formation).

Returns:

SFR at each lookback time [Msun/yr].

Return type:

ndarray, shape (n_age,)

Notes

JIT-compatible: yes, all operations use jnp primitives.

Gradient-safe: yes, differentiable everywhere for positive tau and age.

The double power law SFH is evaluated in cosmic time since formation:

\[\mathrm{SFR}(T) = \frac{n}{(T/\tau)^\alpha + (T/\tau)^{-\beta}}\]

where \(T = \mathrm{age} - t_{\rm lookback}\) is cosmic time since formation, \(\tau\) is the turnover timescale, and \(\alpha\), \(\beta\) are the falling and rising slopes [dimensionless]. The SFR is exactly zero for \(T \le 0\) (before formation, i.e. \(t_{\rm lookback} \ge \mathrm{age}\)).

In cosmic time T (age since formation): \(\alpha\) controls the declining phase (after peak at \(T = \tau\)), \(\beta\) controls the rising phase (before peak).

In lookback time (as plotted, left-to-right with increasing age): The peak is at lookback \(t_{\rm lb} = \mathrm{age} - \tau\). Left side (small lookback, recent): declining phase (controlled by alpha). Right side (large lookback, ancient): rising phase (controlled by beta).

References

[tengri.double_powerlaw-1]

A. C. Carnall et al., “Inferring the star formation histories of massive quiescent galaxies with BAGPIPES: evidence for multiple quenching mechanisms,” MNRAS, 480, 4379 (2018). arXiv:1712.04452. https://doi.org/10.1093/mnras/sty2169

[tengri.double_powerlaw-2]

P. S. Behroozi, R. H. Wechsler, C. Conroy, “The Average Star Formation Histories of Galaxies in Dark Matter Halos from z=0-8,” ApJ, 770, 57 (2013). arXiv:1207.6105. https://doi.org/10.1088/0004-637X/770/1/57

Examples

>>> import jax.numpy as jnp
>>> from tengri import double_powerlaw
>>> t = jnp.linspace(1e6, 13.7e9, 100)
>>> age = 13.7e9
>>> sfr = double_powerlaw(t, alpha=1.5, beta=2.0, tau=3e9, norm=10.0, age=age)
>>> sfr.shape
(100,)
tengri.snorm(t_lookback: Array, log_total_mass: float, peak_lbt: float, width: float, skew: float) → Array

Skew-normal SFH (Robotham+2020).

Like truncated_skewnormal but without truncation.

Parameters:
  • t_lookback (array_like, shape (n_age,)) – Lookback time [yr].

  • log_total_mass (float) – log10 of total stellar mass formed [Msun]. The shape is rescaled so that trapezoid(sfr, t_lookback) = 10**log_total_mass exactly.

  • peak_lbt (float) – Peak lookback time [yr].

  • width (float) – Gaussian width [yr].

  • skew (float) – Skewness parameter [dimensionless]. 0 = symmetric, >0 skews toward older ages.

Returns:

SFR at each lookback time [Msun/yr], non-negative.

Return type:

ndarray, shape (n_age,)

Notes

JIT-compatible: yes, all operations use jnp primitives.

Examples

>>> import jax.numpy as jnp
>>> from tengri.components.stellar.sfh import skewnormal
>>> t = jnp.logspace(7, 10.14, 64)
>>> sfr = skewnormal(t, log_total_mass=10.0, peak_lbt=3e9, width=1e9, skew=1.0)
>>> sfr.shape
(64,)
tengri.norm(t_lookback: Array, log_total_mass: float, peak_lbt: float, width: float) → Array

Gaussian (normal) SFH: skewnormal with skew=0.

Parameters:
  • t_lookback (array_like, shape (n_age,)) – Lookback time [yr].

  • log_total_mass (float) – log10 of total stellar mass formed [Msun]. The shape is rescaled so that trapezoid(sfr, t_lookback) = 10**log_total_mass exactly.

  • peak_lbt (float) – Peak lookback time [yr].

  • width (float) – Gaussian width [yr].

Returns:

SFR at each lookback time [Msun/yr], non-negative.

Return type:

ndarray, shape (n_age,)

Notes

JIT-compatible: yes, all operations use jnp primitives.

Examples

>>> import jax.numpy as jnp
>>> from tengri.components.stellar.sfh import gaussian
>>> t = jnp.logspace(7, 10.14, 64)
>>> sfr = gaussian(t, log_total_mass=10.0, peak_lbt=3e9, width=1e9)
>>> sfr.shape
(64,)
tengri.lnorm(t_lookback: Array, log_total_mass: float, peak: float, width: float, age: float) → Array

Log-normal SFH peaked in cosmic time since formation.

\[\mathrm{SFR}(T) \propto \frac{1}{T} \exp\!\Bigl[-\tfrac{1}{2}\bigl(\ln T - \mu\bigr)^2 / \sigma^2\Bigr], \quad T = \mathrm{age} - t_{\mathrm{lb}} \ge 0\]

where \(T\) is cosmic time since galaxy formation, \(t_{\mathrm{lb}}\) is lookback time. The mode (peak) is located at \(T_{\mathrm{mode}} = \exp(\mu - \sigma^2) = \text{peak}\), and \(\sigma = \text{width} \times \ln(10)\) (converting from log10-space width in dex). Rescaled so the integrated mass equals 10**log_total_mass.

Convention. With age set to the age of the universe at the source redshift, the peak sits at cosmic time peak after the Big Bang: the same direction as Carnall+2018 / BAGPIPES lognormal. The time variable handed in is always lookback time; the cosmic-time conversion T = age - t_lookback happens here. Resolves the time-reversal of #514.

The 1/T Jacobian factor arises from the change of variables in the lognormal probability distribution and is essential for matching the Carnall et al. (2018) formulation exactly.

Parameters:
  • t_lookback (array_like, shape (n_age,)) – Lookback time [yr].

  • log_total_mass (float) – log10 of total stellar mass formed [Msun]. The shape is rescaled so that trapezoid(sfr, t_lookback) = 10**log_total_mass exactly.

  • peak (float) – Peak location (mode) in cosmic time since formation [yr].

  • width (float) – Width in log10(T) space [dex]. Converted internally to natural-log standard deviation σ = width × ln(10).

  • age (float) – Cosmic time available for star formation [yr] = lookback time of formation. Set to age_of_universe(z) for BAGPIPES direction. SFR is zero before formation (t_lookback > age).

Returns:

SFR at each lookback time [Msun/yr], non-negative.

Return type:

ndarray, shape (n_age,)

Notes

JIT-compatible: yes, all operations use jnp primitives.

Gradient-safe: yes, the 1/T factor is computed using safe division to avoid NaN leakage in gradients when T ≤ 0.

References

[tengri.lnorm-1]

A. C. Carnall et al., “Inferring the star formation histories of massive quiescent galaxies with BAGPIPES: evidence for multiple quenching mechanisms,” MNRAS, 480, 4379 (2018). arXiv:1712.04452. https://doi.org/10.1093/mnras/sty2169

Examples

>>> import jax.numpy as jnp
>>> from tengri.components.stellar.sfh import lognormal
>>> t = jnp.logspace(7, 10.14, 64)
>>> sfr = lognormal(t, log_total_mass=10.0, peak=3e9, width=0.3, age=13.6e9)
>>> sfr.shape
(64,)
tengri.delayed_tau(t_lookback: Array, tau: float, norm: float, *, age: float) → Array[source]

Delayed-tau SFH: SFR(T) = norm * T * exp(-T/tau). Peaks at T=tau.

A rising-exponential SFH that reaches maximum SFR at cosmic time T = tau since galaxy formation, then declines. Used as the bare shape in sfhdelayed() for the CIGALE/Bagpipes delayed model (#406).

Parameters:
  • t_lookback (array_like, shape (n_age,)) – Lookback time [yr].

  • tau (float) – Timescale [yr]. Cosmic-time location of the SFR peak relative to galaxy formation.

  • norm (float) – Normalization factor [Msun/yr]. Controls overall amplitude, not integrated mass. Use sfhdelayed() for mass-conserving version.

  • age (float) – Cosmic time available for star formation [yr]. Set to the age of the universe at the source redshift. SFR is zero for t_lookback > age (before formation).

Returns:

SFR at each lookback time [Msun/yr].

Return type:

ndarray, shape (n_age,)

Notes

JIT-compatible: yes, uses jnp primitives.

Gradient-safe: yes, differentiable everywhere for positive tau and age.

The delayed-tau SFH is evaluated in cosmic time since formation:

\[\mathrm{SFR}(T) = n \cdot T \cdot \exp(-T / \tau)\]

where \(T = \mathrm{age} - t_{\rm lookback}\) is cosmic time since galaxy formation, \(\tau\) is the timescale, and the SFR is exactly zero for \(T \le 0\) (before formation, i.e. \(t_{\rm lookback} \ge \mathrm{age}\)).

See sfhdelayed() for the mass-conserving registry-wired version (Resolves the time-reversal of #2524).

Examples

>>> import jax.numpy as jnp
>>> from tengri import delayed_tau
>>> t = jnp.logspace(7, 10.14, 64)
>>> age = 13.7e9
>>> sfr = delayed_tau(t, tau=2e9, norm=10.0, age=age)
>>> sfr.shape
(64,)
tengri.constant(t_lookback: Array, log_total_mass: float, start: float = 0.0, end: float = 14000000000.0) → Array[source]

Constant SFR between start and end lookback times.

Shape is a top-hat (1 inside [start, end], 0 outside); rescaled so the integrated mass equals 10**log_total_mass.

Parameters:
  • t_lookback (array_like, shape (n_age,)) – Lookback time [yr].

  • log_total_mass (float) – log10 of total stellar mass formed [Msun].

  • start (float) – Younger lookback boundary [yr]. Default 0 (present). Maps from user-facing sfh_const_end_gyr.

  • end (float) – Older lookback boundary [yr]. Default AGEMAX_YR. Maps from user-facing sfh_const_start_gyr.

Returns:

SFR at each lookback time [Msun/yr], flat between start and end, zero outside.

Return type:

ndarray, shape (n_age,)

Notes

JIT-compatible: yes, uses jnp.where and element-wise operations.

Internal convention: start <= t_lookback <= end (both in lookback time). The user-facing API names are reversed for chronological intuition.

Examples

>>> import jax.numpy as jnp
>>> from tengri.components.stellar.sfh import constant
>>> t = jnp.logspace(7, 10.14, 64)
>>> sfr = constant(t, log_total_mass=10.0, start=5e8, end=5e9)
>>> sfr.shape
(64,)
tengri.exponential(t_lookback: Array, log_total_mass: float, tau: float, start: float = 0.0) → Array[source]

Declining exponential SFH: forms stars in [0, start], from start outward.

start is the lookback time of SF onset (galaxy formation): shape is exp(-(start - t) / tau) for 0 <= t <= start, zero outside – maximal at formation (t = start), declining toward the present, the same T = age - t_lookback convention as declining_exponential() with start playing the role age does there. Rescaled so the integrated mass equals 10**log_total_mass.

Parameters:
  • t_lookback (array_like, shape (n_age,)) – Lookback time [yr].

  • log_total_mass (float) – log10 of total stellar mass formed [Msun].

  • tau (float) – e-folding timescale [yr].

  • start (float) – Lookback time of SF onset (galaxy formation) [yr]. Default 0 (formed at the present, degenerate).

Returns:

SFR at each lookback time [Msun/yr].

Return type:

ndarray, shape (n_age,)

Notes

JIT-compatible: yes, uses jnp primitives for exponential and masking.

Before this, the window was [start, inf) – mass sat at lookback >= start, unbounded toward the oldest SSP template age, with zero SFR between start and the present: the mirror image of this docstring’s own “declining exponential from start” and of the verified-correct declining_exponential() (#2521).

Examples

>>> import jax.numpy as jnp
>>> from tengri.components.stellar.sfh import exponential
>>> t = jnp.logspace(7, 10.14, 64)
>>> sfr = exponential(t, log_total_mass=10.0, tau=2e9, start=5e9)
>>> sfr.shape
(64,)
tengri.delayed_exponential(t_lookback: Array, log_total_mass: float, tau: float, start: float = 0.0) → Array[source]

Delayed exponential SFH: forms stars in [0, start], peaking cosmic-time tau after formation.

start is the lookback time of SF onset (galaxy formation). In cosmic time since formation T = start - t_lookback (0 <= T <= start, the same convention sfhdelayed() uses with start playing the role age does there), shape is (T/tau) * exp(-T/tau + 1): rises from 0 at formation, peaks at cosmic time T = tau (lookback start - tau), declines toward the present. Zero outside [0, start]. Rescaled so the integrated mass equals 10**log_total_mass.

Parameters:
  • t_lookback (array_like, shape (n_age,)) – Lookback time [yr].

  • log_total_mass (float) – log10 of total stellar mass formed [Msun].

  • tau (float) – Timescale [yr]. Peak shape value occurs at cosmic time tau after formation (lookback start - tau).

  • start (float) – Lookback time of SF onset (galaxy formation) [yr]. Default 0 (formed at the present, degenerate).

Returns:

SFR at each lookback time [Msun/yr].

Return type:

ndarray, shape (n_age,)

Notes

JIT-compatible: yes, all operations use jnp primitives.

Before this, the window was [start, inf) – mass sat at lookback >= start, unbounded toward the oldest SSP template age, with zero SFR between start and the present (#2521; shares the mechanism exponential() had).

Examples

>>> import jax.numpy as jnp
>>> from tengri.components.stellar.sfh import delayed_exponential
>>> t = jnp.logspace(7, 10.14, 64)
>>> sfr = delayed_exponential(t, log_total_mass=10.0, tau=2e9, start=5e9)
>>> sfr.shape
(64,)
tengri.declining_exponential(t_lookback: Array, log_total_mass: float, tau: float, age: float) → Array[source]

Declining tau SFH in lookback time: matches FSPS sfh=1 / bagpipes ‘exponential’.

In cosmic time T, the standard tau model is SFR(T) ∝ exp(-T/tau) for 0 <= T <= age. Converting T = age - t_lb gives a shape that increases going back in lookback time (galaxy formed with highest SFR, declining to the present). This is opposite to exponential.

NOT the same as CIGALE ``sfh_delayed`` / Bagpipes ``delayed``: those peak at cosmic time T = τ, not T = 0. For that shape use sfhdelayed() (registered as "delayed"). Confusing the two silently produced a wavelength-dependent residual in the CIGALE reproduction audit (#385, #406).

Rescaled so the integrated mass equals 10**log_total_mass.

Parameters:
  • t_lookback (array_like, shape (n_age,)) – Lookback time [yr].

  • log_total_mass (float) – log10 of total stellar mass formed [Msun].

  • tau (float) – e-folding timescale [yr]. Larger tau = slower decline.

  • age (float) – Galaxy age [yr] = lookback time of galaxy formation.

Returns:

SFR at each lookback time [Msun/yr].

Return type:

ndarray, shape (n_age,)

Notes

JIT-compatible: yes, uses jnp primitives for exponential and masking.

tengri.triweight_burst(t_lookback: Array, log_tpeak_myr: float, log_tmax_myr: float) → Array[source]

Triweight burst kernel in log-age space (Zacharegkas+2025).

A compact-support kernel for modeling starburst episodes. The kernel is smooth, has finite support in log-age space, and is designed for composition with smooth SFH models via mass-fraction mixing.

Parameters:
  • t_lookback (array_like, shape (n_age,)) – Lookback time [yr].

  • log_tpeak_myr (float) – log10 of burst peak time [Myr]. Center of the kernel in log-age space.

  • log_tmax_myr (float) – log10 of burst duration [Myr]. Controls the kernel half-width. The kernel has support roughly ±:math:3 times 10^{log_{mathrm{tmax}}} Myr.

Returns:

Unnormalized burst shape [dimensionless], non-negative. It integrates to 1 in the normalized offset \(x\) defined below, not in lookback time, so a caller that needs a mass must divide by \(\int B\,\mathrm{d}t\) on its own grid.

Return type:

ndarray, shape (n_age,)

Notes

JIT-compatible: yes, all operations use jnp primitives.

This is a shape-only function (unitless, not in Msun/yr). The burst amplitude is set in the composition step (_mix_burst_mass_fraction in tengri.components.stellar.sfh.registry), which normalizes this kernel by its own time integral and gives it a fraction \(f = 10^{\log f_{\rm burst}}\) of the mass the smooth members form:

\[\mathrm{SFR}(t) = (1 - f)\,\mathrm{SFR}_{\rm smooth}(t) + f\,M\,\frac{B(t)}{\int B\,\mathrm{d}t}, \qquad M = \int \mathrm{SFR}_{\rm smooth}\,\mathrm{d}t\]

with \(t\) lookback time [yr], \(\mathrm{SFR}\) [Msun/yr], \(M\) [Msun] and \(B\) this dimensionless kernel. The amplitude is therefore set by an integral of the kernel, never by its peak.

The triweight kernel in normalized variable \(u = x/3\) is:

\[K(u) = \frac{35}{96} (1 - u^2)^3, \quad |u| < 1\]

where \(x\) is the normalized time offset from peak, defined as # noqa: E501 \((\log_{10}(t/\mathrm{Myr}) - \log_{10}(t_{\rm peak}/\mathrm{Myr})) / \log_{10}(t_{\rm max}/\mathrm{Myr})\).

The kernel has compact support (finite extent) and is \(C^{\infty}\) smooth. It is superior to Gaussian kernels for burst modeling because it avoids the extended low-level wings that affect neighboring age bins.

References

[tengri.triweight_burst-1]

G. Zacharegkas, A. Hearin, and A. Benson, “Bayesian Posteriors with Stellar Population Synthesis on GPUs,” The Open Journal of Astrophysics, 8 (2025). arXiv:2506.19919. https://doi.org/10.33232/001c.151255

Examples

>>> import jax.numpy as jnp
>>> from tengri import triweight_burst
>>> t = jnp.linspace(1e6, 13.7e9, 100)
>>> kernel = triweight_burst(t, log_tpeak_myr=2.0, log_tmax_myr=1.0)
>>> kernel.shape
(100,)

SFH registry

tengri.resolve_sfh(mean_sfh_type: str | list[str], bin_edges_gyr: object = None) → tuple[object, dict[str, ParamDef], dict[str, tuple[str, float, float]], dict[str, Any]][source]

Resolve SFH specification to a composed function + params.

Parameters:
  • mean_sfh_type (str or list[str]) – Model name(s). E.g., "tsnorm" or ["tsnorm", "burst", "field"].

  • bin_edges_gyr (array-like, shape (n_bins+1,), optional) – Custom age bin edges [Gyr] for continuity and dirichlet models. When provided, overrides the default DEFAULT_BIN_EDGES_GYR. Use make_agebins_from_zred to generate redshift-appropriate edges. Ignored for non-nonparametric models. Default None (use model default).

Returns:

  • composed_fn (callable) – Pure JAX function fn(t_lookback, **all_internal_kwargs) -> SFR [Msun/yr].

  • merged_params (dict[str, ParamDef]) – All fittable parameters across selected models.

  • merged_param_map (dict[str, tuple[str, float, float]]) – Public name -> (internal, scale, offset) for all params.

  • merged_settings (dict[str, Any]) – Non-fittable settings (e.g., sfh_field_ngrid).

Raises:
  • KeyError – If a model name is not in the registry.

  • ValueError – If composition constraints are violated (e.g., >1 burst, no smooth component), or if bin_edges_gyr is provided for a nonparametric SFH and its bin count does not match the declared parameter count (see validate_bin_edges_gyr).

Notes

JIT-compatible: yes, returns a JIT-compatible closure (composed_fn).

Composition rules:

  • Additive: smooth models summed. E.g., ["tsnorm", "dpl"] yields SFR_total = SFR_tsnorm + SFR_dpl.

  • Mixture (burst): the burst takes a fraction \(f = 10^{\log f_{\rm burst}}\) of the mass the smooth members form, and the smooth history is scaled by \(1 - f\) to make room for it. With \(M = \int \mathrm{SFR}_{\rm smooth}\,\mathrm{d}t\) [Msun] over the evaluation grid and \(B(t)\) the burst kernel,

    \[\mathrm{SFR}(t) = (1 - f)\,\mathrm{SFR}_{\rm smooth}(t) + f\,M\,\frac{B(t)}{\int B\,\mathrm{d}t}\]

    where \(t\) is lookback time [yr] and \(\mathrm{SFR}\) is [Msun/yr]. The formed mass is \(M\) whether or not a burst is present, and wherever \(B\) vanishes the history is exactly \(1 - f\) times the smooth one. See _mix_burst_mass_fraction.

  • Modulator (field): multiplicative GP modulation. E.g., ["tsnorm", "field"] yields SFR = SFR_tsnorm * exp(gp_x - K_0/2).

  • Current episode (recent, recent_ssfr): a constant SFR \(\psi\) over the last \(\Delta t\), spliced over the smooth history after the field step. The smooth members keep their declared formed mass \(M_S\) (the sum of their 10**log_total_mass), so the total is \(M_S + \psi\,\Delta t\). recent_ssfr takes the specific SFR and inverts it with \(\psi = \psi_S M_S / (1 - \psi_S \Delta t)\). At most one episode is allowed, and it needs a smooth member. The GP field does not multiply the episode. See the registry block for the BEAGLE reference (Chevallard & Charlot 2016).

Repeated members. A type may appear more than once: ["norm", "norm"] is two Gaussian bursts, ["const", "norm", "norm"] a plateau under two of them. The k-th occurrence (k >= 2) takes the type’s public prefix with the ordinal appended – sfh_norm_log_total_mass for the first, sfh_norm_2_log_total_mass for the second, sfh_norm_3_... for the third – with the same priors, defaults and internal kwargs as the base entry, and dispatches to its own callable. The grammar’s short key for a repeat keeps the ordinal (norm_2_log_total_mass). Only additive members can usefully repeat: a second burst or field is still refused by the one-mixture and one-modulator rules below.

Auto-swap: dense_basis → dense_basis_pure if burst or field is present (to avoid SFR constraint interference with composition).

Examples

>>> from tengri import resolve_sfh
>>> fn, params, param_map, settings = resolve_sfh("dpl")
>>> "sfh_dpl_alpha" in params
True
>>> fn
<function ...>
tengri.components.stellar.sfh.registry.SFH_REGISTRY: dict[str, Any] = {'buat08': SFHRegistryEntry(callable=SFHModelSpec(name='buat08', fn=<function buat08>, params={'sfh_buat08_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_buat08_velocity_km_s': ParamDef(description='Rotational velocity (km/s), range [40, 360]', bound_check=<function <lambda>>, bound_error='must have 40 <= lo and hi <= 360', default=Uniform(80.0, 360.0), free_prior=None, gyr_twin=None), 'sfh_buat08_age_gyr': ParamDef(description='Galaxy age / lookback to formation (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.5, 13.787), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_buat08_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_buat08_velocity_km_s': ('velocity_km_s', 1.0, 0.0), 'sfh_buat08_age_gyr': ('age_yr', 1000000000.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Buat et al. 2008', status='production', short_doc='Velocity-parameterized SFH (Buat et al.)', doc=''), 'burst': SFHRegistryEntry(callable=SFHModelSpec(name='burst', fn=<function triweight_burst>, params={'sfh_burst_log_fburst': ParamDef(description='log10 burst mass fraction', bound_check=<function <lambda>>, bound_error='must have hi < 0 (fraction < 1)', default=Uniform(-3.0, -0.1), free_prior=None, gyr_twin=None), 'sfh_burst_log_tpeak_myr': ParamDef(description='log10 burst peak time (Myr)', bound_check=<function <lambda>>, bound_error='', default=Uniform(0.0, 3.0), free_prior=None, gyr_twin=None), 'sfh_burst_log_tmax_myr': ParamDef(description='log10 burst duration (Myr)', bound_check=<function <lambda>>, bound_error='', default=Uniform(1.0, 4.0), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_burst_log_fburst': ('log_fburst', 1.0, 0.0), 'sfh_burst_log_tpeak_myr': ('log_tpeak_myr', 1.0, 0.0), 'sfh_burst_log_tmax_myr': ('log_tmax_myr', 1.0, 0.0)}, composition_type='mixture', smooth_base=None), citation='', status='production', short_doc='Triweight burst kernel (Zacharegkas+2025)', doc=''), 'bursty_continuity': SFHRegistryEntry(callable=SFHModelSpec(name='bursty_continuity', fn=<function continuity>, params={'sfh_burstcont_log_total_mass': ParamDef(description='log10 total stellar mass formed (Msun)', bound_check=<function <lambda>>, bound_error='', default=Uniform(8.0, 12.0), free_prior=None, gyr_twin=None), 'sfh_burstcont_ratio_0': ParamDef(description='log10 SFR ratio bin 0/1 (Tacchella+22 piecewise scale)', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=1.0, df=2.0), free_prior=None, gyr_twin=None), 'sfh_burstcont_ratio_1': ParamDef(description='log10 SFR ratio bin 1/2 (Tacchella+22 piecewise scale)', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=1.0, df=2.0), free_prior=None, gyr_twin=None), 'sfh_burstcont_ratio_2': ParamDef(description='log10 SFR ratio bin 2/3 (Tacchella+22 piecewise scale)', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=1.0, df=2.0), free_prior=None, gyr_twin=None), 'sfh_burstcont_ratio_3': ParamDef(description='log10 SFR ratio bin 3/4 (Tacchella+22 piecewise scale)', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_burstcont_ratio_4': ParamDef(description='log10 SFR ratio bin 4/5 (Tacchella+22 piecewise scale)', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_burstcont_ratio_5': ParamDef(description='log10 SFR ratio bin 5/6 (Tacchella+22 piecewise scale)', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None)}, settings={'sfh_burstcont_t_split_gyr': 1.0, 'sfh_burstcont_scale_young': 1.0, 'sfh_burstcont_scale_old': 0.3}, internal_param_map={'sfh_burstcont_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_burstcont_ratio_0': ('ratio_0', 1.0, 0.0), 'sfh_burstcont_ratio_1': ('ratio_1', 1.0, 0.0), 'sfh_burstcont_ratio_2': ('ratio_2', 1.0, 0.0), 'sfh_burstcont_ratio_3': ('ratio_3', 1.0, 0.0), 'sfh_burstcont_ratio_4': ('ratio_4', 1.0, 0.0), 'sfh_burstcont_ratio_5': ('ratio_5', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Tacchella et al. 2022 (ApJ 926, 134); arXiv:2102.11954', status='production', short_doc='Bursty continuity SFH (Tacchella+22); StudentT df=2 with sigma=1.0 dex on ratios whose younger edge < 1 Gyr and sigma=0.3 dex otherwise', doc=''), 'const': SFHRegistryEntry(callable=SFHModelSpec(name='const', fn=<function constant>, params={'sfh_const_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_const_start_gyr': ParamDef(description='Lookback to SF onset (Gyr): when did SF start?', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(14.0), free_prior=Uniform(0.01, 13.787), gyr_twin=None), 'sfh_const_start_frac': ParamDef(description='Onset as a fraction of age(z) (formation time)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.0007253269356107764, 1.0), free_prior=None, gyr_twin='sfh_const_start_gyr'), 'sfh_const_end_gyr': ParamDef(description='Lookback to SF cessation (Gyr): when did SF stop? (0 = ongoing)', bound_check=<function <lambda>>, bound_error='must have lo >= 0', default=Fixed(0.0), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_const_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_const_start_gyr': ('end', 1000000000.0, 0.0), 'sfh_const_start_frac': ('sfh_const_start_frac', 1.0, 0.0), 'sfh_const_end_gyr': ('start', 1000000000.0, 0.0)}, composition_type='additive', smooth_base=None), citation='', status='production', short_doc='Constant SFR', doc=''), 'const_exp': SFHRegistryEntry(callable=SFHModelSpec(name='const_exp', fn=<function constant_then_exponential>, params={'sfh_cexp_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun] (constant + decline phases)', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_cexp_tau_gyr': ParamDef(description='Post-quench e-folding timescale (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 10.0), free_prior=None, gyr_twin=None), 'sfh_cexp_quench_gyr': ParamDef(description='Lookback time when quenching began (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.01, 10.0), free_prior=None, gyr_twin=None), 'sfh_cexp_age_gyr': ParamDef(description='Galaxy age / lookback to formation (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(5.0), free_prior=None, gyr_twin=None), 'sfh_cexp_age_frac': ParamDef(description='Onset as a fraction of age(z) (formation time)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 0.9429250162940094), free_prior=None, gyr_twin='sfh_cexp_age_gyr')}, settings={}, internal_param_map={'sfh_cexp_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_cexp_tau_gyr': ('tau', 1000000000.0, 0.0), 'sfh_cexp_quench_gyr': ('quench_age', 1000000000.0, 0.0), 'sfh_cexp_age_gyr': ('age', 1000000000.0, 0.0), 'sfh_cexp_age_frac': ('sfh_cexp_age_frac', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='', status='production', short_doc='Constant SFR then exponential quenching', doc=''), 'constant_then_exponential': SFHRegistryEntry(callable=SFHModelSpec(name='const_exp', fn=<function constant_then_exponential>, params={'sfh_cexp_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun] (constant + decline phases)', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_cexp_tau_gyr': ParamDef(description='Post-quench e-folding timescale (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 10.0), free_prior=None, gyr_twin=None), 'sfh_cexp_quench_gyr': ParamDef(description='Lookback time when quenching began (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.01, 10.0), free_prior=None, gyr_twin=None), 'sfh_cexp_age_gyr': ParamDef(description='Galaxy age / lookback to formation (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(5.0), free_prior=None, gyr_twin=None), 'sfh_cexp_age_frac': ParamDef(description='Onset as a fraction of age(z) (formation time)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 0.9429250162940094), free_prior=None, gyr_twin='sfh_cexp_age_gyr')}, settings={}, internal_param_map={'sfh_cexp_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_cexp_tau_gyr': ('tau', 1000000000.0, 0.0), 'sfh_cexp_quench_gyr': ('quench_age', 1000000000.0, 0.0), 'sfh_cexp_age_gyr': ('age', 1000000000.0, 0.0), 'sfh_cexp_age_frac': ('sfh_cexp_age_frac', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='', status='production', short_doc='Constant SFR then exponential quenching', doc=''), 'continuity': SFHRegistryEntry(callable=SFHModelSpec(name='continuity', fn=<function continuity>, params={'sfh_cont_log_total_mass': ParamDef(description='log10 total stellar mass formed (Msun)', bound_check=<function <lambda>>, bound_error='', default=Uniform(8.0, 12.0), free_prior=None, gyr_twin=None), 'sfh_cont_ratio_0': ParamDef(description='log10 SFR ratio bin 0/1', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_cont_ratio_1': ParamDef(description='log10 SFR ratio bin 1/2', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_cont_ratio_2': ParamDef(description='log10 SFR ratio bin 2/3', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_cont_ratio_3': ParamDef(description='log10 SFR ratio bin 3/4', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_cont_ratio_4': ParamDef(description='log10 SFR ratio bin 4/5', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_cont_ratio_5': ParamDef(description='log10 SFR ratio bin 5/6', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_cont_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_cont_ratio_0': ('ratio_0', 1.0, 0.0), 'sfh_cont_ratio_1': ('ratio_1', 1.0, 0.0), 'sfh_cont_ratio_2': ('ratio_2', 1.0, 0.0), 'sfh_cont_ratio_3': ('ratio_3', 1.0, 0.0), 'sfh_cont_ratio_4': ('ratio_4', 1.0, 0.0), 'sfh_cont_ratio_5': ('ratio_5', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Leja et al. 2019 (ApJ 876, 39)', status='production', short_doc='Non-parametric piecewise continuity SFH (Leja+19); StudentT(0, 0.3, df=2) on log-SFR ratios', doc=''), 'continuity_flex': SFHRegistryEntry(callable=SFHModelSpec(name='continuity_flex', fn=<function continuity_flex>, params={'sfh_cflex_log_total_mass': ParamDef(description='log10 total stellar mass formed (Msun)', bound_check=<function <lambda>>, bound_error='', default=Uniform(8.0, 12.0), free_prior=None, gyr_twin=None), 'sfh_cflex_ratio_young': ParamDef(description='log10(SFR_young / SFR_flex[0])', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_cflex_flex_0': ParamDef(description='log10 flex bin SFR ratio 0 (controls bin width)', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_cflex_flex_1': ParamDef(description='log10 flex bin SFR ratio 1 (controls bin width)', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_cflex_flex_2': ParamDef(description='log10 flex bin SFR ratio 2 (controls bin width)', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_cflex_ratio_old': ParamDef(description='log10(SFR_old / SFR_flex[N])', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None)}, settings={'sfh_cflex_n_flex': 3, 'sfh_cflex_anchor_gyr': [0.0316, 5.012, 13.7]}, internal_param_map={'sfh_cflex_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_cflex_ratio_young': ('ratio_young', 1.0, 0.0), 'sfh_cflex_flex_0': ('flex_0', 1.0, 0.0), 'sfh_cflex_flex_1': ('flex_1', 1.0, 0.0), 'sfh_cflex_flex_2': ('flex_2', 1.0, 0.0), 'sfh_cflex_ratio_old': ('ratio_old', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Leja et al. 2019 (ApJ 876, 39)', status='production', short_doc='Non-parametric continuity + flexible bin edges (Leja+19); StudentT(0, 0.3, df=2) on log-SFR ratios', doc=''), 'continuity_young_fraction': SFHRegistryEntry(callable=SFHModelSpec(name='continuity_young_fraction', fn=<function continuity_young_fraction>, params={'sfh_cont_log_total_mass': ParamDef(description='log10 total stellar mass formed (Msun)', bound_check=<function <lambda>>, bound_error='', default=Uniform(8.0, 12.0), free_prior=None, gyr_twin=None), 'sfh_cont_young_frac_0': ParamDef(description='youngest-first stick-breaking fraction of bin 0 (M_0/R_0)', bound_check=<function <lambda>>, bound_error='', default=Uniform(0.0, 1.0), free_prior=None, gyr_twin=None), 'sfh_cont_young_frac_1': ParamDef(description='youngest-first stick-breaking fraction of bin 1 (M_1/R_1)', bound_check=<function <lambda>>, bound_error='', default=Uniform(0.0, 1.0), free_prior=None, gyr_twin=None), 'sfh_cont_young_frac_2': ParamDef(description='youngest-first stick-breaking fraction of bin 2 (M_2/R_2)', bound_check=<function <lambda>>, bound_error='', default=Uniform(0.0, 1.0), free_prior=None, gyr_twin=None), 'sfh_cont_young_frac_3': ParamDef(description='youngest-first stick-breaking fraction of bin 3 (M_3/R_3)', bound_check=<function <lambda>>, bound_error='', default=Uniform(0.0, 1.0), free_prior=None, gyr_twin=None), 'sfh_cont_young_frac_4': ParamDef(description='youngest-first stick-breaking fraction of bin 4 (M_4/R_4)', bound_check=<function <lambda>>, bound_error='', default=Uniform(0.0, 1.0), free_prior=None, gyr_twin=None), 'sfh_cont_young_frac_5': ParamDef(description='youngest-first stick-breaking fraction of bin 5 (M_5/R_5)', bound_check=<function <lambda>>, bound_error='', default=Uniform(0.0, 1.0), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_cont_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_cont_young_frac_0': ('young_frac_0', 1.0, 0.0), 'sfh_cont_young_frac_1': ('young_frac_1', 1.0, 0.0), 'sfh_cont_young_frac_2': ('young_frac_2', 1.0, 0.0), 'sfh_cont_young_frac_3': ('young_frac_3', 1.0, 0.0), 'sfh_cont_young_frac_4': ('young_frac_4', 1.0, 0.0), 'sfh_cont_young_frac_5': ('young_frac_5', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Leja et al. 2019 (ApJ 876, 3)', status='production', short_doc='Continuity SFH (Leja+19) in youngest-first stick-breaking fractions; exact pullback of the StudentT(0, 0.3, df=2) ratio prior', doc=''), 'db': SFHRegistryEntry(callable=SFHModelSpec(name='dense_basis', fn=<function dense_basis>, params={'sfh_db_log_total_mass': ParamDef(description='log10 total stellar mass formed (Msun)', bound_check=<function <lambda>>, bound_error='', default=Uniform(8.0, 12.0), free_prior=None, gyr_twin=None), 'sfh_db_log_sfr_inst': ParamDef(description='log10 instantaneous SFR at observation (Msun/yr)', bound_check=<function <lambda>>, bound_error='', default=Uniform(-2.0, 3.0), free_prior=None, gyr_twin=None), 'sfh_db_tx_frac_0': ParamDef(description='Cosmic time fraction at 25% mass', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.05, 0.95), free_prior=None, gyr_twin=None), 'sfh_db_tx_frac_1': ParamDef(description='Cosmic time fraction at 50% mass', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.05, 0.95), free_prior=None, gyr_twin=None), 'sfh_db_tx_frac_2': ParamDef(description='Cosmic time fraction at 75% mass', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.05, 0.95), free_prior=None, gyr_twin=None)}, settings={'sfh_db_nparam': 3}, internal_param_map={'sfh_db_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_db_log_sfr_inst': ('log_sfr_inst', 1.0, 0.0), 'sfh_db_tx_frac_0': ('tx_frac_0', 1.0, 0.0), 'sfh_db_tx_frac_1': ('tx_frac_1', 1.0, 0.0), 'sfh_db_tx_frac_2': ('tx_frac_2', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='', status='production', short_doc='Dense-basis non-parametric SFH (Iyer+19)', doc=''), 'dbp': SFHRegistryEntry(callable=SFHModelSpec(name='dense_basis_pure', fn=<function dense_basis_pure>, params={'sfh_dbp_log_total_mass': ParamDef(description='log10 total stellar mass formed (Msun)', bound_check=<function <lambda>>, bound_error='', default=Uniform(8.0, 12.0), free_prior=None, gyr_twin=None), 'sfh_dbp_tx_frac_0': ParamDef(description='Cosmic time fraction at 25% mass', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.05, 0.95), free_prior=None, gyr_twin=None), 'sfh_dbp_tx_frac_1': ParamDef(description='Cosmic time fraction at 50% mass', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.05, 0.95), free_prior=None, gyr_twin=None), 'sfh_dbp_tx_frac_2': ParamDef(description='Cosmic time fraction at 75% mass', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.05, 0.95), free_prior=None, gyr_twin=None)}, settings={'sfh_dbp_nparam': 3}, internal_param_map={'sfh_dbp_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_dbp_tx_frac_0': ('tx_frac_0', 1.0, 0.0), 'sfh_dbp_tx_frac_1': ('tx_frac_1', 1.0, 0.0), 'sfh_dbp_tx_frac_2': ('tx_frac_2', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='', status='production', short_doc='Dense-basis SFH without GP constraints', doc=''), 'declining_exp': SFHRegistryEntry(callable=SFHModelSpec(name='declining_exp', fn=<function declining_exponential>, params={'sfh_declining_exp_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_declining_exp_tau_gyr': ParamDef(description='e-folding decline timescale (Gyr): larger τ declines slower', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 10.0), free_prior=None, gyr_twin=None), 'sfh_declining_exp_age_gyr': ParamDef(description='Galaxy age / lookback time of formation (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(5.0), free_prior=None, gyr_twin=None), 'sfh_declining_exp_age_frac': ParamDef(description='Onset as a fraction of age(z) (formation time)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 0.9429250162940094), free_prior=None, gyr_twin='sfh_declining_exp_age_gyr')}, settings={}, internal_param_map={'sfh_declining_exp_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_declining_exp_tau_gyr': ('tau', 1000000000.0, 0.0), 'sfh_declining_exp_age_gyr': ('age', 1000000000.0, 0.0), 'sfh_declining_exp_age_frac': ('sfh_declining_exp_age_frac', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Conroy et al. 2009 (FSPS); Carnall et al. 2018 (Bagpipes)', status='production', short_doc="Declining-τ SFH (FSPS sfh=1 / Bagpipes 'exponential')", doc=''), 'delayed': SFHRegistryEntry(callable=SFHModelSpec(name='delayed', fn=<function sfhdelayed>, params={'sfh_delayed_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_delayed_tau_gyr': ParamDef(description='Timescale (Gyr): cosmic-time location of SFR peak', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 10.0), free_prior=None, gyr_twin=None), 'sfh_delayed_age_gyr': ParamDef(description='Galaxy age / lookback time of formation (Gyr); must be > τ', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(5.0), free_prior=None, gyr_twin=None), 'sfh_delayed_age_frac': ParamDef(description='Onset as a fraction of age(z) (formation time)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 0.9429250162940094), free_prior=None, gyr_twin='sfh_delayed_age_gyr')}, settings={}, internal_param_map={'sfh_delayed_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_delayed_tau_gyr': ('tau', 1000000000.0, 0.0), 'sfh_delayed_age_gyr': ('age', 1000000000.0, 0.0), 'sfh_delayed_age_frac': ('sfh_delayed_age_frac', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Boquien et al. 2019 (CIGALE); Carnall et al. 2018 (Bagpipes)', status='production', short_doc="τ-delayed SFH (CIGALE sfh_delayed / Bagpipes 'delayed')", doc=''), 'delayed_bq': SFHRegistryEntry(callable=SFHModelSpec(name='delayed_bq', fn=<function delayed_bq>, params={'sfh_delayed_bq_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_delayed_bq_tau_main_gyr': ParamDef(description='e-folding timescale of main component (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 10.0), free_prior=None, gyr_twin=None), 'sfh_delayed_bq_age_main_gyr': ParamDef(description='Galaxy age / lookback to formation (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(5.0), free_prior=None, gyr_twin=None), 'sfh_delayed_bq_age_main_frac': ParamDef(description='Onset as a fraction of age(z) (formation time)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 0.9429250162940094), free_prior=None, gyr_twin='sfh_delayed_bq_age_main_gyr'), 'sfh_delayed_bq_age_bq_gyr': ParamDef(description='Lookback time of burst/quench onset (Gyr); prior ceiling equals the age_main_gyr floor so quench-before-formation (#2644) is unreachable by default', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.01, 0.5), free_prior=None, gyr_twin=None), 'sfh_delayed_bq_r_sfr': ParamDef(description='SFR ratio after/before burst/quench (0 = full quench, #2623)', bound_check=<function <lambda>>, bound_error='must have lo >= 0', default=Uniform(0.0, 10.0), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_delayed_bq_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_delayed_bq_tau_main_gyr': ('tau_main_yr', 1000000000.0, 0.0), 'sfh_delayed_bq_age_main_gyr': ('age_main_yr', 1000000000.0, 0.0), 'sfh_delayed_bq_age_main_frac': ('sfh_delayed_bq_age_main_frac', 1.0, 0.0), 'sfh_delayed_bq_age_bq_gyr': ('age_bq_yr', 1000000000.0, 0.0), 'sfh_delayed_bq_r_sfr': ('r_sfr', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='', status='production', short_doc='Delayed tau with burst/quench (Ciesla et al.)', doc=''), 'dense_basis': SFHRegistryEntry(callable=SFHModelSpec(name='dense_basis', fn=<function dense_basis>, params={'sfh_db_log_total_mass': ParamDef(description='log10 total stellar mass formed (Msun)', bound_check=<function <lambda>>, bound_error='', default=Uniform(8.0, 12.0), free_prior=None, gyr_twin=None), 'sfh_db_log_sfr_inst': ParamDef(description='log10 instantaneous SFR at observation (Msun/yr)', bound_check=<function <lambda>>, bound_error='', default=Uniform(-2.0, 3.0), free_prior=None, gyr_twin=None), 'sfh_db_tx_frac_0': ParamDef(description='Cosmic time fraction at 25% mass', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.05, 0.95), free_prior=None, gyr_twin=None), 'sfh_db_tx_frac_1': ParamDef(description='Cosmic time fraction at 50% mass', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.05, 0.95), free_prior=None, gyr_twin=None), 'sfh_db_tx_frac_2': ParamDef(description='Cosmic time fraction at 75% mass', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.05, 0.95), free_prior=None, gyr_twin=None)}, settings={'sfh_db_nparam': 3}, internal_param_map={'sfh_db_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_db_log_sfr_inst': ('log_sfr_inst', 1.0, 0.0), 'sfh_db_tx_frac_0': ('tx_frac_0', 1.0, 0.0), 'sfh_db_tx_frac_1': ('tx_frac_1', 1.0, 0.0), 'sfh_db_tx_frac_2': ('tx_frac_2', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='', status='production', short_doc='Dense-basis non-parametric SFH (Iyer+19)', doc=''), 'dense_basis_pure': SFHRegistryEntry(callable=SFHModelSpec(name='dense_basis_pure', fn=<function dense_basis_pure>, params={'sfh_dbp_log_total_mass': ParamDef(description='log10 total stellar mass formed (Msun)', bound_check=<function <lambda>>, bound_error='', default=Uniform(8.0, 12.0), free_prior=None, gyr_twin=None), 'sfh_dbp_tx_frac_0': ParamDef(description='Cosmic time fraction at 25% mass', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.05, 0.95), free_prior=None, gyr_twin=None), 'sfh_dbp_tx_frac_1': ParamDef(description='Cosmic time fraction at 50% mass', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.05, 0.95), free_prior=None, gyr_twin=None), 'sfh_dbp_tx_frac_2': ParamDef(description='Cosmic time fraction at 75% mass', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.05, 0.95), free_prior=None, gyr_twin=None)}, settings={'sfh_dbp_nparam': 3}, internal_param_map={'sfh_dbp_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_dbp_tx_frac_0': ('tx_frac_0', 1.0, 0.0), 'sfh_dbp_tx_frac_1': ('tx_frac_1', 1.0, 0.0), 'sfh_dbp_tx_frac_2': ('tx_frac_2', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='', status='production', short_doc='Dense-basis SFH without GP constraints', doc=''), 'dexp': SFHRegistryEntry(callable=SFHModelSpec(name='dexp', fn=<function delayed_exponential>, params={'sfh_dexp_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_dexp_tau_gyr': ParamDef(description='Timescale (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 10.0), free_prior=None, gyr_twin=None), 'sfh_dexp_start_gyr': ParamDef(description='Start lookback (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(5.0), free_prior=Fixed(5.0), gyr_twin=None), 'sfh_dexp_start_frac': ParamDef(description='Onset as a fraction of age(z) (formation time)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 1.0), free_prior=None, gyr_twin='sfh_dexp_start_gyr')}, settings={}, internal_param_map={'sfh_dexp_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_dexp_tau_gyr': ('tau', 1000000000.0, 0.0), 'sfh_dexp_start_gyr': ('start', 1000000000.0, 0.0), 'sfh_dexp_start_frac': ('sfh_dexp_start_frac', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='', status='production', short_doc='Delayed exponential SFH', doc=''), 'dirichlet': SFHRegistryEntry(callable=SFHModelSpec(name='dirichlet', fn=<function dirichlet>, params={'sfh_dir_log_total_mass': ParamDef(description='log10 total stellar mass formed (Msun)', bound_check=<function <lambda>>, bound_error='', default=Uniform(8.0, 12.0), free_prior=None, gyr_twin=None), 'sfh_dir_z_0': ParamDef(description='Dirichlet stick-breaking variable 0', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.0, 1.0), free_prior=None, gyr_twin=None), 'sfh_dir_z_1': ParamDef(description='Dirichlet stick-breaking variable 1', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.0, 1.0), free_prior=None, gyr_twin=None), 'sfh_dir_z_2': ParamDef(description='Dirichlet stick-breaking variable 2', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.0, 1.0), free_prior=None, gyr_twin=None), 'sfh_dir_z_3': ParamDef(description='Dirichlet stick-breaking variable 3', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.0, 1.0), free_prior=None, gyr_twin=None), 'sfh_dir_z_4': ParamDef(description='Dirichlet stick-breaking variable 4', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.0, 1.0), free_prior=None, gyr_twin=None), 'sfh_dir_z_5': ParamDef(description='Dirichlet stick-breaking variable 5', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.0, 1.0), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_dir_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_dir_z_0': ('z_frac_0', 1.0, 0.0), 'sfh_dir_z_1': ('z_frac_1', 1.0, 0.0), 'sfh_dir_z_2': ('z_frac_2', 1.0, 0.0), 'sfh_dir_z_3': ('z_frac_3', 1.0, 0.0), 'sfh_dir_z_4': ('z_frac_4', 1.0, 0.0), 'sfh_dir_z_5': ('z_frac_5', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Leja et al. 2017 (ApJ 837, 170)', status='production', short_doc='Non-parametric Dirichlet SFH (Leja+17); Uniform(0,1) aux variables mapped to Beta(1, N-1-i) quantiles, stick-broken into SFR fractions with a symmetric Dirichlet(1,...,1) prior', doc=''), 'dpl': SFHRegistryEntry(callable=SFHModelSpec(name='dpl', fn=<function dpl>, params={'sfh_dpl_alpha': ParamDef(description='DPL falling slope', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 5.0), free_prior=None, gyr_twin=None), 'sfh_dpl_beta': ParamDef(description='DPL rising slope', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 3.0), free_prior=None, gyr_twin=None), 'sfh_dpl_tau_gyr': ParamDef(description='DPL turnover time (Gyr), cosmic time since formation', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 12.0), free_prior=None, gyr_twin=None), 'sfh_dpl_age_gyr': ParamDef(description='Cosmic time for SF (Gyr) = lookback of formation; set to age_of_universe(z) for BAGPIPES parity', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(13.787), free_prior=None, gyr_twin=None), 'sfh_dpl_age_frac': ParamDef(description='Cosmic time for SF as a fraction of age(z) (formation time)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 1.0), free_prior=None, gyr_twin='sfh_dpl_age_gyr'), 'sfh_dpl_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_dpl_alpha': ('alpha', 1.0, 0.0), 'sfh_dpl_beta': ('beta', 1.0, 0.0), 'sfh_dpl_tau_gyr': ('tau', 1000000000.0, 0.0), 'sfh_dpl_age_gyr': ('age', 1000000000.0, 0.0), 'sfh_dpl_age_frac': ('sfh_dpl_age_frac', 1.0, 0.0), 'sfh_dpl_log_total_mass': ('log_total_mass', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Carnall et al. 2018 (MNRAS 480, 4379)', status='production', short_doc='Double power-law SFH', doc=''), 'dpl_lookback': SFHRegistryEntry(callable=SFHModelSpec(name='dpl_lookback', fn=<function dpl_lookback>, params={'sfh_dpl_lookback_alpha': ParamDef(description='DPL slope on the old side (large lookback)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 5.0), free_prior=None, gyr_twin=None), 'sfh_dpl_lookback_beta': ParamDef(description='DPL slope on the young side (small lookback)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 3.0), free_prior=None, gyr_twin=None), 'sfh_dpl_lookback_peak_gyr': ParamDef(description='DPL turnover lookback time (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.01, 12.0), free_prior=None, gyr_twin=None), 'sfh_dpl_lookback_age_gyr': ParamDef(description='Older truncation lookback time (Gyr); set to age_of_universe(z) for a galaxy forming at the Big Bang', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(13.787), free_prior=None, gyr_twin=None), 'sfh_dpl_lookback_age_frac': ParamDef(description='Onset as a fraction of age(z) (formation time)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 1.0), free_prior=None, gyr_twin='sfh_dpl_lookback_age_gyr'), 'sfh_dpl_lookback_end_gyr': ParamDef(description='Younger truncation lookback time (Gyr) (0 = star formation continues to the epoch of observation)', bound_check=<function <lambda>>, bound_error='must have lo >= 0', default=Fixed(0.0), free_prior=None, gyr_twin=None), 'sfh_dpl_lookback_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_dpl_lookback_alpha': ('alpha', 1.0, 0.0), 'sfh_dpl_lookback_beta': ('beta', 1.0, 0.0), 'sfh_dpl_lookback_peak_gyr': ('peak', 1000000000.0, 0.0), 'sfh_dpl_lookback_age_gyr': ('age', 1000000000.0, 0.0), 'sfh_dpl_lookback_age_frac': ('sfh_dpl_lookback_age_frac', 1.0, 0.0), 'sfh_dpl_lookback_end_gyr': ('end', 1000000000.0, 0.0), 'sfh_dpl_lookback_log_total_mass': ('log_total_mass', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Carnall et al. 2018 (MNRAS 480, 4379)', status='production', short_doc='Double power-law SFH in lookback time (stellar age, not cosmic time since formation); beta carries the Carnall sign, so a positive beta gives an interior peak', doc=''), 'exp': SFHRegistryEntry(callable=SFHModelSpec(name='exp', fn=<function exponential>, params={'sfh_exp_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_exp_tau_gyr': ParamDef(description='e-folding timescale (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 10.0), free_prior=None, gyr_twin=None), 'sfh_exp_start_gyr': ParamDef(description='Start lookback (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(5.0), free_prior=Fixed(5.0), gyr_twin=None), 'sfh_exp_start_frac': ParamDef(description='Onset as a fraction of age(z) (formation time)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 1.0), free_prior=None, gyr_twin='sfh_exp_start_gyr')}, settings={}, internal_param_map={'sfh_exp_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_exp_tau_gyr': ('tau', 1000000000.0, 0.0), 'sfh_exp_start_gyr': ('start', 1000000000.0, 0.0), 'sfh_exp_start_frac': ('sfh_exp_start_frac', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='', status='production', short_doc='Exponential rise SFH', doc=''), 'field': SFHRegistryEntry(callable=SFHModelSpec(name='field', fn=<function _field_fn_placeholder>, params={'sfh_field_psd_sigma': ParamDef(description='PSD amplitude (dex)', bound_check=<function <lambda>>, bound_error='must have lo >= 0', default=Uniform(0.01, 1.0), free_prior=None, gyr_twin=None), 'sfh_field_psd_tau_myr': ParamDef(description='PSD timescale (Myr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(10.0, 500.0), free_prior=None, gyr_twin=None)}, settings={'sfh_field_ngrid': 256, 'sfh_field_model': 'drw'}, internal_param_map={'sfh_field_psd_sigma': ('psd_sigma', 1.0, 0.0), 'sfh_field_psd_tau_myr': ('psd_tau_yr', 1000000.0, 0.0)}, composition_type='modulator', smooth_base=None), citation='', status='production', short_doc="GP field modulator with DRW power spectrum; sampling coordinates selectable via sfh={'field_centering': a}", doc=''), 'gaussian_burst': SFHRegistryEntry(callable=SFHModelSpec(name='gaussian_burst', fn=<function gaussian_burst>, params={'sfh_gaussian_burst_log_total_mass': ParamDef(description='log10 total stellar mass formed in burst [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(6.0, 11.0), free_prior=None, gyr_twin=None), 'sfh_gaussian_burst_t_peak_gyr': ParamDef(description='Burst peak age / lookback time (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.01, 13.0), free_prior=None, gyr_twin=None), 'sfh_gaussian_burst_sigma_gyr': ParamDef(description='Gaussian width / standard deviation (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.01, 5.0), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_gaussian_burst_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_gaussian_burst_t_peak_gyr': ('t_peak', 1000000000.0, 0.0), 'sfh_gaussian_burst_sigma_gyr': ('sigma', 1000000000.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Robotham et al. 2020 (arXiv:2002.06980) ProSpect', status='production', short_doc='Gaussian-in-age burst (Robotham+2020)', doc=''), 'lnorm': SFHRegistryEntry(callable=SFHModelSpec(name='lnorm', fn=<function lognormal>, params={'sfh_lnorm_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_lnorm_peak_gyr': ParamDef(description='Peak in cosmic time since formation (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.5, 12.0), free_prior=None, gyr_twin=None), 'sfh_lnorm_width_gyr': ParamDef(description='Log-space width (dex)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 2.0), free_prior=None, gyr_twin=None), 'sfh_lnorm_age_gyr': ParamDef(description='Cosmic time for SF (Gyr) = lookback of formation; set to age_of_universe(z) for BAGPIPES direction', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(13.787), free_prior=None, gyr_twin=None), 'sfh_lnorm_age_frac': ParamDef(description='Onset as a fraction of age(z) (formation time)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 1.0), free_prior=None, gyr_twin='sfh_lnorm_age_gyr')}, settings={}, internal_param_map={'sfh_lnorm_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_lnorm_peak_gyr': ('peak', 1000000000.0, 0.0), 'sfh_lnorm_width_gyr': ('width', 1.0, 0.0), 'sfh_lnorm_age_gyr': ('age', 1000000000.0, 0.0), 'sfh_lnorm_age_frac': ('sfh_lnorm_age_frac', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='', status='production', short_doc='Log-normal SFH', doc=''), 'norm': SFHRegistryEntry(callable=SFHModelSpec(name='norm', fn=<function gaussian>, params={'sfh_norm_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_norm_peak_lbt_gyr': ParamDef(description='Peak lookback time (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(5.0), free_prior=None, gyr_twin=None), 'sfh_norm_peak_lbt_frac': ParamDef(description='Peak lookback time as a fraction of age(z)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 0.8703923227329318), free_prior=None, gyr_twin='sfh_norm_peak_lbt_gyr'), 'sfh_norm_width_gyr': ParamDef(description='Gaussian width (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.2, 5.0), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_norm_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_norm_peak_lbt_gyr': ('peak_lbt', 1000000000.0, 0.0), 'sfh_norm_peak_lbt_frac': ('sfh_norm_peak_lbt_frac', 1.0, 0.0), 'sfh_norm_width_gyr': ('width', 1000000000.0, 0.0)}, composition_type='additive', smooth_base=None), citation='', status='production', short_doc='Gaussian SFH', doc=''), 'periodic': SFHRegistryEntry(callable=SFHModelSpec(name='periodic', fn=<function periodic>, params={'sfh_periodic_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_periodic_delta_bursts_gyr': ParamDef(description='Spacing between burst onsets (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.01, 1.0), free_prior=None, gyr_twin=None), 'sfh_periodic_tau_bursts_gyr': ParamDef(description='Duration/e-folding timescale of each burst (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.001, 0.5), free_prior=None, gyr_twin=None), 'sfh_periodic_burst_type': ParamDef(description='Burst type: 0=exponential, 1=delayed, 2=rectangular', bound_check=<function <lambda>>, bound_error='must be 0, 1, or 2', default=Fixed(0.0), free_prior=None, gyr_twin=None), 'sfh_periodic_age_gyr': ParamDef(description='Galaxy age / lookback to formation (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(5.0), free_prior=None, gyr_twin=None), 'sfh_periodic_age_frac': ParamDef(description='Onset as a fraction of age(z) (formation time)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 0.9429250162940094), free_prior=None, gyr_twin='sfh_periodic_age_gyr')}, settings={}, internal_param_map={'sfh_periodic_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_periodic_delta_bursts_gyr': ('delta_bursts_yr', 1000000000.0, 0.0), 'sfh_periodic_tau_bursts_gyr': ('tau_bursts_yr', 1000000000.0, 0.0), 'sfh_periodic_burst_type': ('burst_type', 1.0, 0.0), 'sfh_periodic_age_gyr': ('age_yr', 1000000000.0, 0.0), 'sfh_periodic_age_frac': ('sfh_periodic_age_frac', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='', status='production', short_doc='Periodic SF events (Ciesla et al.)', doc=''), 'prospector_beta': SFHRegistryEntry(callable=SFHModelSpec(name='prospector_beta', fn=<function continuity>, params={'sfh_pbeta_log_total_mass': ParamDef(description='log10 total stellar mass formed (Msun)', bound_check=<function <lambda>>, bound_error='', default=Uniform(8.0, 12.0), free_prior=None, gyr_twin=None), 'sfh_pbeta_ratio_0': ParamDef(description='log10 SFR ratio bin 0/1', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_pbeta_ratio_1': ParamDef(description='log10 SFR ratio bin 1/2', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_pbeta_ratio_2': ParamDef(description='log10 SFR ratio bin 2/3', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_pbeta_ratio_3': ParamDef(description='log10 SFR ratio bin 3/4', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_pbeta_ratio_4': ParamDef(description='log10 SFR ratio bin 4/5', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_pbeta_ratio_5': ParamDef(description='log10 SFR ratio bin 5/6', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_pbeta_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_pbeta_ratio_0': ('ratio_0', 1.0, 0.0), 'sfh_pbeta_ratio_1': ('ratio_1', 1.0, 0.0), 'sfh_pbeta_ratio_2': ('ratio_2', 1.0, 0.0), 'sfh_pbeta_ratio_3': ('ratio_3', 1.0, 0.0), 'sfh_pbeta_ratio_4': ('ratio_4', 1.0, 0.0), 'sfh_pbeta_ratio_5': ('ratio_5', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Wang et al. 2024 (arXiv:2401.12198); SFH shape from Leja+2019', status='production', short_doc='Prospector-beta: continuity SFH with redshift-aware bin edges from make_agebins_from_zred(zred); StudentT(0, 0.3, df=2) on log-SFR ratios', doc=''), 'psb': SFHRegistryEntry(callable=SFHModelSpec(name='psb', fn=<function psb_wild2020>, params={'sfh_psb_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_psb_age_gyr': ParamDef(description='Galaxy age / lookback to formation (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(5.0), free_prior=None, gyr_twin=None), 'sfh_psb_age_frac': ParamDef(description='Onset as a fraction of age(z) (formation time)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 0.9429250162940094), free_prior=None, gyr_twin='sfh_psb_age_gyr'), 'sfh_psb_tau_gyr': ParamDef(description='Old-component e-folding timescale (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 10.0), free_prior=None, gyr_twin=None), 'sfh_psb_burstage_gyr': ParamDef(description='Lookback time of burst onset (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.01, 5.0), free_prior=None, gyr_twin=None), 'sfh_psb_alpha': ParamDef(description='DPL burst falling slope', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.5, 5.0), free_prior=None, gyr_twin=None), 'sfh_psb_beta': ParamDef(description='DPL burst rising slope', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.5, 5.0), free_prior=None, gyr_twin=None), 'sfh_psb_fburst': ParamDef(description='Burst mass fraction', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.01, 0.99), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_psb_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_psb_age_gyr': ('age', 1000000000.0, 0.0), 'sfh_psb_age_frac': ('sfh_psb_age_frac', 1.0, 0.0), 'sfh_psb_tau_gyr': ('tau', 1000000000.0, 0.0), 'sfh_psb_burstage_gyr': ('burstage', 1000000000.0, 0.0), 'sfh_psb_alpha': ('alpha', 1.0, 0.0), 'sfh_psb_beta': ('beta', 1.0, 0.0), 'sfh_psb_fburst': ('fburst', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Wild et al. 2020 (MNRAS 494, 529)', status='production', short_doc='Post-starburst SFH (Wild et al.)', doc=''), 'psb_flex': SFHRegistryEntry(callable=SFHModelSpec(name='psb_flex', fn=<function psb_continuity_flex>, params={'sfh_psb_flex_log_total_mass': ParamDef(description='log10 total stellar mass formed (Msun)', bound_check=<function <lambda>>, bound_error='', default=Uniform(8.0, 12.0), free_prior=None, gyr_twin=None), 'sfh_psb_flex_tlast_gyr': ParamDef(description='Quenching-onset lookback time (Gyr); width of the youngest bin', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(0.2), free_prior=None, gyr_twin=None), 'sfh_psb_flex_tlast_frac': ParamDef(description='Quenching-onset lookback time (youngest-bin width) as a fraction of age(z)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.0007253269356107764, 0.07253269356107765), free_prior=None, gyr_twin='sfh_psb_flex_tlast_gyr'), 'sfh_psb_flex_tflex_gyr': ParamDef(description='Upper boundary of the flexible quenching zone (Gyr); prior floor equals the tlast_gyr ceiling so the zone can never have negative width', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(2.0), free_prior=None, gyr_twin=None), 'sfh_psb_flex_tflex_frac': ParamDef(description='Upper boundary of the flexible quenching zone as a fraction of age(z)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.07253269356107765, 0.3626634678053882), free_prior=None, gyr_twin='sfh_psb_flex_tflex_gyr'), 'sfh_psb_flex_ratio_young': ParamDef(description='log10(SFR_young / SFR_flex_0); large positive = recent burst', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_psb_flex_ratio_flex_0': ParamDef(description='log10 SFR ratio flex bin 0/1', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_psb_flex_ratio_flex_1': ParamDef(description='log10 SFR ratio flex bin 1/2', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_psb_flex_ratio_flex_2': ParamDef(description='log10 SFR ratio flex bin 2/3', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_psb_flex_ratio_flex_3': ParamDef(description='log10 SFR ratio flex bin 3/4', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_psb_flex_ratio_old_0': ParamDef(description='log10 SFR ratio: oldest flex bin / youngest fixed bin (link)', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_psb_flex_ratio_old_1': ParamDef(description='log10 SFR ratio old bin 0/1', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_psb_flex_ratio_old_2': ParamDef(description='log10 SFR ratio old bin 1/2', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_psb_flex_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_psb_flex_tlast_gyr': ('tlast_gyr', 1.0, 0.0), 'sfh_psb_flex_tflex_gyr': ('tflex_gyr', 1.0, 0.0), 'sfh_psb_flex_tlast_frac': ('sfh_psb_flex_tlast_frac', 1.0, 0.0), 'sfh_psb_flex_tflex_frac': ('sfh_psb_flex_tflex_frac', 1.0, 0.0), 'sfh_psb_flex_ratio_young': ('ratio_young', 1.0, 0.0), 'sfh_psb_flex_ratio_flex_0': ('flex_0', 1.0, 0.0), 'sfh_psb_flex_ratio_flex_1': ('flex_1', 1.0, 0.0), 'sfh_psb_flex_ratio_flex_2': ('flex_2', 1.0, 0.0), 'sfh_psb_flex_ratio_flex_3': ('flex_3', 1.0, 0.0), 'sfh_psb_flex_ratio_old_0': ('ratio_old_0', 1.0, 0.0), 'sfh_psb_flex_ratio_old_1': ('ratio_old_1', 1.0, 0.0), 'sfh_psb_flex_ratio_old_2': ('ratio_old_2', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Suess et al. 2022 (ApJ 935, 146); arXiv:2207.02883', status='production', short_doc="Post-starburst non-parametric SFH with a resolved quenching zone (nflex=5, nfixed=3): youngest bin [0, tlast] + five equal-width flex bins out to tflex + three equal-width fixed old bins out to the age of the universe at this model's redshift", doc=''), 'psb_suess2022': SFHRegistryEntry(callable=SFHModelSpec(name='psb_suess2022', fn=<function psb_continuity_flex>, params={'sfh_psb2022_log_total_mass': ParamDef(description='log10 total stellar mass formed (Msun)', bound_check=<function <lambda>>, bound_error='', default=Uniform(8.0, 12.0), free_prior=None, gyr_twin=None), 'sfh_psb2022_tlast_gyr': ParamDef(description='Quenching-onset lookback time (Gyr); width of the youngest bin', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(0.1), free_prior=None, gyr_twin=None), 'sfh_psb2022_tlast_frac': ParamDef(description='Quenching-onset lookback time (youngest-bin width) as a fraction of age(z)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.0007253269356107764, 0.07253269356107765), free_prior=None, gyr_twin='sfh_psb2022_tlast_gyr'), 'sfh_psb2022_tflex_gyr': ParamDef(description='Upper boundary of the flexible quenching zone (Gyr); prior floor equals the tlast_gyr ceiling so the zone can never have negative width', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(2.0), free_prior=None, gyr_twin=None), 'sfh_psb2022_tflex_frac': ParamDef(description='Upper boundary of the flexible quenching zone as a fraction of age(z)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.07253269356107765, 0.3626634678053882), free_prior=None, gyr_twin='sfh_psb2022_tflex_gyr'), 'sfh_psb2022_ratio_young': ParamDef(description='log10(SFR_young / SFR_flex); large positive = recent burst', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_psb2022_ratio_old_0': ParamDef(description='log10 SFR ratio: oldest flex bin / youngest fixed bin (link)', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_psb2022_ratio_old_1': ParamDef(description='log10 SFR ratio old bin 0/1', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None), 'sfh_psb2022_ratio_old_2': ParamDef(description='log10 SFR ratio old bin 1/2', bound_check=<function <lambda>>, bound_error='', default=StudentT(mu=0.0, sigma=0.3, df=2.0), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_psb2022_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_psb2022_tlast_gyr': ('tlast_gyr', 1.0, 0.0), 'sfh_psb2022_tflex_gyr': ('tflex_gyr', 1.0, 0.0), 'sfh_psb2022_tlast_frac': ('sfh_psb2022_tlast_frac', 1.0, 0.0), 'sfh_psb2022_tflex_frac': ('sfh_psb2022_tflex_frac', 1.0, 0.0), 'sfh_psb2022_ratio_young': ('ratio_young', 1.0, 0.0), 'sfh_psb2022_ratio_old_0': ('ratio_old_0', 1.0, 0.0), 'sfh_psb2022_ratio_old_1': ('ratio_old_1', 1.0, 0.0), 'sfh_psb2022_ratio_old_2': ('ratio_old_2', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Suess et al. 2022 (ApJ 935, 146); arXiv:2207.02883', status='production', short_doc="Post-starburst non-parametric SFH (Suess+22, nflex=1, nfixed=3): youngest bin [0, tlast] + a single flex bin [tlast, tflex] + three equal-width fixed old bins out to the age of the universe at this model's redshift, with StudentT(0, 0.3, df=2) ratios", doc=''), 'psb_wild2020': SFHRegistryEntry(callable=SFHModelSpec(name='psb', fn=<function psb_wild2020>, params={'sfh_psb_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_psb_age_gyr': ParamDef(description='Galaxy age / lookback to formation (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(5.0), free_prior=None, gyr_twin=None), 'sfh_psb_age_frac': ParamDef(description='Onset as a fraction of age(z) (formation time)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 0.9429250162940094), free_prior=None, gyr_twin='sfh_psb_age_gyr'), 'sfh_psb_tau_gyr': ParamDef(description='Old-component e-folding timescale (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 10.0), free_prior=None, gyr_twin=None), 'sfh_psb_burstage_gyr': ParamDef(description='Lookback time of burst onset (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.01, 5.0), free_prior=None, gyr_twin=None), 'sfh_psb_alpha': ParamDef(description='DPL burst falling slope', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.5, 5.0), free_prior=None, gyr_twin=None), 'sfh_psb_beta': ParamDef(description='DPL burst rising slope', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.5, 5.0), free_prior=None, gyr_twin=None), 'sfh_psb_fburst': ParamDef(description='Burst mass fraction', bound_check=<function <lambda>>, bound_error='must be in [0, 1]', default=Uniform(0.01, 0.99), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_psb_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_psb_age_gyr': ('age', 1000000000.0, 0.0), 'sfh_psb_age_frac': ('sfh_psb_age_frac', 1.0, 0.0), 'sfh_psb_tau_gyr': ('tau', 1000000000.0, 0.0), 'sfh_psb_burstage_gyr': ('burstage', 1000000000.0, 0.0), 'sfh_psb_alpha': ('alpha', 1.0, 0.0), 'sfh_psb_beta': ('beta', 1.0, 0.0), 'sfh_psb_fburst': ('fburst', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Wild et al. 2020 (MNRAS 494, 529)', status='production', short_doc='Post-starburst SFH (Wild et al.)', doc=''), 'recent': SFHRegistryEntry(callable=SFHModelSpec(name='recent', fn=<function _current_fn_placeholder>, params={'sfh_recent_log_sfr': ParamDef(description='log10 of the constant star-formation rate over the current episode [Msun/yr]', bound_check=<function <lambda>>, bound_error='', default=Uniform(-3.0, 3.0), free_prior=None, gyr_twin=None), 'sfh_recent_timescale_myr': ParamDef(description='Duration of the current episode, Delta t (Myr)', bound_check=<function _recent_timescale_ok>, bound_error='must lie within [1, 1000] Myr', default=Fixed(10.0), free_prior=Uniform(10.0, 100.0), gyr_twin=None)}, settings={}, internal_param_map={'sfh_recent_log_sfr': ('log_sfr', 1.0, 0.0), 'sfh_recent_timescale_myr': ('timescale_yr', 1000000.0, 0.0)}, composition_type='current', smooth_base='delayed'), citation='Chevallard & Charlot 2016, MNRAS 462, 1415', status='production', short_doc='Constant-SFR current episode over the last Delta t, spliced over a smooth SFH', doc="Constant-SFR episode over the last Delta t, spliced over the smooth history. With t the lookback time and psi = 10**log_sfr [Msun/yr], the SFR is psi for 0 <= t <= Delta t, and the smooth history S(t) outside it, rescaled so that its formed mass M_S is kept. The total formed mass is M_S + psi Delta t. Bookkeeping (BEAGLE convention): BEAGLE's ``mass`` includes the episode, so tengri's smooth ``log_total_mass`` is BEAGLE's M - psi Delta t, and BEAGLE's ``mass`` is tengri's derived formed ``stellar_mass``. Cross-code: BEAGLE (Chevallard & Charlot 2016) sets the episode by ``sfr`` or ``specific_sfr`` and ``current_sfr_timescale``; BAGPIPES ``burst`` is set by a mass; CIGALE ``sfhdelayedbq`` by a rate ratio; Prospector has no equivalent."), 'recent_ssfr': SFHRegistryEntry(callable=SFHModelSpec(name='recent_ssfr', fn=<function _current_fn_placeholder>, params={'sfh_recent_ssfr_log_ssfr': ParamDef(description="log10 of the current episode's specific SFR [yr^-1]", bound_check=<function _recent_ssfr_ok>, bound_error='must have hi < -7.0; the joint pole check at build refuses psi_S Delta t >= 1', default=Uniform(-12.0, -7.3), free_prior=None, gyr_twin=None), 'sfh_recent_ssfr_timescale_myr': ParamDef(description='Duration of the current episode, Delta t (Myr)', bound_check=<function _recent_timescale_ok>, bound_error='must lie within [1, 1000] Myr', default=Fixed(10.0), free_prior=Uniform(10.0, 100.0), gyr_twin=None)}, settings={}, internal_param_map={'sfh_recent_ssfr_log_ssfr': ('log_ssfr', 1.0, 0.0), 'sfh_recent_ssfr_timescale_myr': ('timescale_yr', 1000000.0, 0.0)}, composition_type='current', smooth_base='delayed'), citation='Chevallard & Charlot 2016, MNRAS 462, 1415', status='production', short_doc='Current episode set by its specific SFR, spliced over a smooth SFH (BEAGLE)', doc='Current episode set by its specific SFR. psi_S = 10**log_ssfr [yr^-1] is defined against the total formed mass, psi_S = psi / (M_S + psi Delta t), which inverts to psi = psi_S M_S / (1 - psi_S Delta t). The map has a pole at psi_S Delta t = 1, so a prior whose joint upper bound reaches it is refused at build. The spliced SFH is the one ``recent`` gives at the converted psi. Bookkeeping and cross-code notes as for ``recent`` (BEAGLE sets the episode by ``specific_sfr``, Chevallard & Charlot 2016).'), 'sfh2exp': SFHRegistryEntry(callable=SFHModelSpec(name='sfh2exp', fn=<function sfh2exp>, params={'sfh_sfh2exp_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_sfh2exp_tau_main_gyr': ParamDef(description='e-folding timescale of main population (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 10.0), free_prior=None, gyr_twin=None), 'sfh_sfh2exp_tau_burst_gyr': ParamDef(description='e-folding timescale of the burst (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.01, 1.0), free_prior=None, gyr_twin=None), 'sfh_sfh2exp_f_burst': ParamDef(description='Fraction of stellar mass formed in the burst', bound_check=<function <lambda>>, bound_error='must have 0 <= f_burst < 1', default=Uniform(0.0, 0.5), free_prior=None, gyr_twin=None), 'sfh_sfh2exp_age_gyr': ParamDef(description='Age of main population / lookback to formation (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(5.0), free_prior=None, gyr_twin=None), 'sfh_sfh2exp_age_frac': ParamDef(description='Onset as a fraction of age(z) (formation time)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 0.9429250162940094), free_prior=None, gyr_twin='sfh_sfh2exp_age_gyr'), 'sfh_sfh2exp_burst_age_gyr': ParamDef(description='Lookback time of burst onset (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.01, 2.0), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_sfh2exp_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_sfh2exp_tau_main_gyr': ('tau_main_yr', 1000000000.0, 0.0), 'sfh_sfh2exp_tau_burst_gyr': ('tau_burst_yr', 1000000000.0, 0.0), 'sfh_sfh2exp_f_burst': ('f_burst', 1.0, 0.0), 'sfh_sfh2exp_age_gyr': ('age_yr', 1000000000.0, 0.0), 'sfh_sfh2exp_age_frac': ('sfh_sfh2exp_age_frac', 1.0, 0.0), 'sfh_sfh2exp_burst_age_gyr': ('burst_age_yr', 1000000000.0, 0.0)}, composition_type='additive', smooth_base=None), citation='', status='production', short_doc='Double declining exponential: main + recent burst (CIGALE sfh2exp)', doc=''), 'snorm': SFHRegistryEntry(callable=SFHModelSpec(name='snorm', fn=<function skewnormal>, params={'sfh_snorm_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_snorm_peak_lbt_gyr': ParamDef(description='Peak lookback time (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(5.0), free_prior=None, gyr_twin=None), 'sfh_snorm_peak_lbt_frac': ParamDef(description='Peak lookback time as a fraction of age(z)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 0.8703923227329318), free_prior=None, gyr_twin='sfh_snorm_peak_lbt_gyr'), 'sfh_snorm_width_gyr': ParamDef(description='Gaussian width (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.2, 5.0), free_prior=None, gyr_twin=None), 'sfh_snorm_skew': ParamDef(description='Skewness', bound_check=<function <lambda>>, bound_error='', default=Uniform(-1.0, 1.0), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_snorm_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_snorm_peak_lbt_gyr': ('peak_lbt', 1000000000.0, 0.0), 'sfh_snorm_peak_lbt_frac': ('sfh_snorm_peak_lbt_frac', 1.0, 0.0), 'sfh_snorm_width_gyr': ('width', 1000000000.0, 0.0), 'sfh_snorm_skew': ('skew', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Bellstedt et al. 2020 (arXiv:2005.11917)', status='production', short_doc='Skew-normal SFH (Bellstedt+2020)', doc=''), 'snorm_burst': SFHRegistryEntry(callable=SFHModelSpec(name='snorm_burst', fn=<function snorm_burst>, params={'sfh_snorm_burst_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_snorm_burst_peak_lbt_gyr': ParamDef(description='Peak lookback time (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(5.0), free_prior=None, gyr_twin=None), 'sfh_snorm_burst_peak_lbt_frac': ParamDef(description='Peak lookback time as a fraction of age(z)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 0.8703923227329318), free_prior=None, gyr_twin='sfh_snorm_burst_peak_lbt_gyr'), 'sfh_snorm_burst_width_gyr': ParamDef(description='Gaussian width (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.2, 5.0), free_prior=None, gyr_twin=None), 'sfh_snorm_burst_skew': ParamDef(description='Skewness', bound_check=<function <lambda>>, bound_error='', default=Uniform(-1.0, 1.0), free_prior=None, gyr_twin=None), 'sfh_snorm_burst_burst_sfr': ParamDef(description="Burst plateau amplitude relative to the smooth kernel's unit peak [dimensionless]", bound_check=<function <lambda>>, bound_error='must have lo >= 0', default=Fixed(0.0), free_prior=Uniform(0.0, 10.0), gyr_twin=None), 'sfh_snorm_burst_burst_age_gyr': ParamDef(description='Burst lookback duration (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(0.1), free_prior=Uniform(0.01, 2.0), gyr_twin=None)}, settings={}, internal_param_map={'sfh_snorm_burst_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_snorm_burst_peak_lbt_gyr': ('peak_lbt', 1000000000.0, 0.0), 'sfh_snorm_burst_peak_lbt_frac': ('sfh_snorm_burst_peak_lbt_frac', 1.0, 0.0), 'sfh_snorm_burst_width_gyr': ('width', 1000000000.0, 0.0), 'sfh_snorm_burst_skew': ('skew', 1.0, 0.0), 'sfh_snorm_burst_burst_sfr': ('burst_sfr', 1.0, 0.0), 'sfh_snorm_burst_burst_age_gyr': ('burst_age', 1000000000.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Robotham et al. 2020 (arXiv:2002.06980) ProSpect', status='production', short_doc='Skew-normal + flat recent burst (ProSpect)', doc=''), 'table': SFHRegistryEntry(callable=SFHModelSpec(name='table', fn=<function _table_sfh_placeholder>, params={}, settings={}, internal_param_map={}, composition_type='additive', smooth_base=None), citation='', status='production', short_doc='User-supplied tabulated SFH(t)', doc=''), 'top_hat': SFHRegistryEntry(callable=SFHModelSpec(name='top_hat', fn=<function top_hat>, params={'sfh_top_hat_log_total_mass': ParamDef(description='log10 total stellar mass formed in window [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_top_hat_t_start_gyr': ParamDef(description='Older lookback boundary / SF onset (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 13.0), free_prior=None, gyr_twin=None), 'sfh_top_hat_t_end_gyr': ParamDef(description='Younger lookback boundary / SF cessation (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo >= 0', default=Uniform(0.0, 12.0), free_prior=None, gyr_twin=None), 'sfh_top_hat_smooth_width_gyr': ParamDef(description='Sigmoid transition width (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(0.1), free_prior=Uniform(0.01, 2.0), gyr_twin=None)}, settings={}, internal_param_map={'sfh_top_hat_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_top_hat_t_start_gyr': ('t_start', 1000000000.0, 0.0), 'sfh_top_hat_t_end_gyr': ('t_end', 1000000000.0, 0.0), 'sfh_top_hat_smooth_width_gyr': ('smooth_width', 1000000000.0, 0.0)}, composition_type='additive', smooth_base=None), citation='', status='production', short_doc='Constant-SFR window with smooth edges (top-hat)', doc=''), 'trunc_exp': SFHRegistryEntry(callable=SFHModelSpec(name='trunc_exp', fn=<function trunc_exp>, params={'sfh_trunc_exp_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_trunc_exp_tau_gyr': ParamDef(description='e-folding timescale (Gyr); positive declines in cosmic time (SFR rises with lookback age), negative rises', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.1, 10.0), free_prior=None, gyr_twin=None), 'sfh_trunc_exp_age_gyr': ParamDef(description='Galaxy age / lookback time of formation (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(5.0), free_prior=None, gyr_twin=None), 'sfh_trunc_exp_age_frac': ParamDef(description='Onset as a fraction of age(z) (formation time)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 0.9429250162940094), free_prior=None, gyr_twin='sfh_trunc_exp_age_gyr'), 'sfh_trunc_exp_end_gyr': ParamDef(description='Lookback time at which SF ceases (Gyr) (0 = still forming stars)', bound_check=<function <lambda>>, bound_error='must have lo >= 0', default=Fixed(0.0), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_trunc_exp_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_trunc_exp_tau_gyr': ('tau', 1000000000.0, 0.0), 'sfh_trunc_exp_age_gyr': ('age', 1000000000.0, 0.0), 'sfh_trunc_exp_age_frac': ('sfh_trunc_exp_age_frac', 1.0, 0.0), 'sfh_trunc_exp_end_gyr': ('end', 1000000000.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Conroy et al. 2009 (FSPS); Carnall et al. 2018 (Bagpipes)', status='production', short_doc='Exponential SFH truncated at both ends; declining_exp plus a young-end cutoff', doc=''), 'tsnorm': SFHRegistryEntry(callable=SFHModelSpec(name='tsnorm', fn=<function truncated_skewnormal>, params={'sfh_tsnorm_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_tsnorm_peak_lbt_gyr': ParamDef(description='Peak lookback time (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(5.0), free_prior=None, gyr_twin=None), 'sfh_tsnorm_peak_lbt_frac': ParamDef(description='Peak lookback time as a fraction of age(z)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 0.8703923227329318), free_prior=None, gyr_twin='sfh_tsnorm_peak_lbt_gyr'), 'sfh_tsnorm_width_gyr': ParamDef(description='Gaussian width (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.2, 5.0), free_prior=None, gyr_twin=None), 'sfh_tsnorm_skew': ParamDef(description='Skewness', bound_check=<function <lambda>>, bound_error='', default=Uniform(-1.0, 1.0), free_prior=None, gyr_twin=None), 'sfh_tsnorm_trunc': ParamDef(description='Truncation sharpness', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(1.0, 10.0), free_prior=None, gyr_twin=None)}, settings={}, internal_param_map={'sfh_tsnorm_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_tsnorm_peak_lbt_gyr': ('peak_lbt', 1000000000.0, 0.0), 'sfh_tsnorm_peak_lbt_frac': ('sfh_tsnorm_peak_lbt_frac', 1.0, 0.0), 'sfh_tsnorm_width_gyr': ('width', 1000000000.0, 0.0), 'sfh_tsnorm_skew': ('skew', 1.0, 0.0), 'sfh_tsnorm_trunc': ('trunc', 1.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Bellstedt et al. 2020 (arXiv:2005.11917)', status='production', short_doc='Truncated skew-normal SFH (Bellstedt+2020)', doc=''), 'tsnorm_burst': SFHRegistryEntry(callable=SFHModelSpec(name='tsnorm_burst', fn=<function snorm_trunc_burst>, params={'sfh_tsnorm_burst_log_total_mass': ParamDef(description='log10 total stellar mass formed [Msun]', bound_check=<function <lambda>>, bound_error='', default=Uniform(7.0, 12.5), free_prior=None, gyr_twin=None), 'sfh_tsnorm_burst_peak_lbt_gyr': ParamDef(description='Peak lookback time (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(5.0), free_prior=None, gyr_twin=None), 'sfh_tsnorm_burst_peak_lbt_frac': ParamDef(description='Peak lookback time as a fraction of age(z)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.036266346780538826, 0.8703923227329318), free_prior=None, gyr_twin='sfh_tsnorm_burst_peak_lbt_gyr'), 'sfh_tsnorm_burst_width_gyr': ParamDef(description='Gaussian width (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(0.2, 5.0), free_prior=None, gyr_twin=None), 'sfh_tsnorm_burst_skew': ParamDef(description='Skewness', bound_check=<function <lambda>>, bound_error='', default=Uniform(-1.0, 1.0), free_prior=None, gyr_twin=None), 'sfh_tsnorm_burst_trunc': ParamDef(description='Truncation sharpness', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Uniform(1.0, 10.0), free_prior=None, gyr_twin=None), 'sfh_tsnorm_burst_burst_sfr': ParamDef(description="Burst plateau amplitude relative to the smooth kernel's unit peak [dimensionless]", bound_check=<function <lambda>>, bound_error='must have lo >= 0', default=Fixed(0.0), free_prior=Uniform(0.0, 10.0), gyr_twin=None), 'sfh_tsnorm_burst_burst_age_gyr': ParamDef(description='Burst lookback duration (Gyr)', bound_check=<function <lambda>>, bound_error='must have lo > 0', default=Fixed(0.1), free_prior=Uniform(0.01, 2.0), gyr_twin=None)}, settings={}, internal_param_map={'sfh_tsnorm_burst_log_total_mass': ('log_total_mass', 1.0, 0.0), 'sfh_tsnorm_burst_peak_lbt_gyr': ('peak_lbt', 1000000000.0, 0.0), 'sfh_tsnorm_burst_peak_lbt_frac': ('sfh_tsnorm_burst_peak_lbt_frac', 1.0, 0.0), 'sfh_tsnorm_burst_width_gyr': ('width', 1000000000.0, 0.0), 'sfh_tsnorm_burst_skew': ('skew', 1.0, 0.0), 'sfh_tsnorm_burst_trunc': ('trunc', 1.0, 0.0), 'sfh_tsnorm_burst_burst_sfr': ('burst_sfr', 1.0, 0.0), 'sfh_tsnorm_burst_burst_age_gyr': ('burst_age', 1000000000.0, 0.0)}, composition_type='additive', smooth_base=None), citation='Robotham et al. 2020 (arXiv:2002.06980) ProSpect', status='production', short_doc='Truncated skew-normal + flat burst (ProSpect)', doc='')}

Every registered mean-SFH family, keyed by the sfh={'type': ...} name ('dpl', 'tsnorm', 'delayed_tau', 'field', …). Values are the SFHSpec entries that resolve_sfh() dispatches on and that tengri.builders.sfh.* is generated from. Populated at import time by register_sfh(); treat it as read-only.

tengri.components.stellar.sfh.registry.FIELD_MODEL_REGISTRY: dict[str, object] = {'drw': <function compute_sqrt_power_drw>}

Stochastic-field PSD models, keyed by the sfh={'psd': ...} name. Values are the sqrt_power(omega, ...) callables the Gaussian-process field draws its amplitude operator from. 'drw' (damped random walk) is the only entry today.

Power spectral density

DRW (damped random walk) PSD models that govern the burstiness of star formation histories via Gaussian process priors.

tengri.psd_drw(omega: Array, psd_sigma: float, psd_tau_yr: float) → Array[source]

Damped random walk (Lorentzian) power spectral density.

Parameters:
  • omega (array_like, shape (n_freq,)) – Angular frequency [rad/yr].

  • psd_sigma (float) – PSD amplitude (dimensionless).

  • psd_tau_yr (float) – Characteristic damping timescale [yr].

Returns:

Power spectral density at each frequency [dimensionless].

Return type:

ndarray, shape (n_freq,)

Notes

JIT-compatible: yes, all operations use jnp primitives.

The damped random walk (Lorentzian) power spectral density is:

\[\begin{split}P(\\omega) = \\sigma_{\rm PS}^2 \\,\tau_{\rm PS} / (1 + (\tau_{\rm PS} \\omega)^2)\end{split}\]

where \(\\sigma_{\rm PS}\) is the PSD amplitude [dimensionless], \(\tau_{\rm PS}\) is the damping timescale [yr], and \(\\omega\) is the angular frequency [rad/yr].

This is the primary PSD model used in tengri for stochastic SFH modeling.

References

[tengri.psd_drw-1]

J. B. Munoz and K. G. Iyer, “Measuring the Power Spectral Density of Star Formation Histories,” arXiv:2601.07912 (2026).

Examples

>>> import jax.numpy as jnp
>>> from tengri import psd_drw
>>> omega = jnp.linspace(0.0, 2e-7, 128)  # angular frequencies [rad/yr]
>>> psd = psd_drw(omega, psd_sigma=1.0, psd_tau_yr=1e8)
>>> psd.shape
(128,)
>>> float(psd[0])  # peak power at omega=0
1e+08
tengri.drw_acf(delta_t: Array, psd_sigma: float, psd_tau_yr: float) → Array[source]

Analytic autocorrelation function (autocovariance) for DRW.

Parameters:
  • delta_t (array_like, shape (n_lag,)) – Time lag [yr].

  • psd_sigma (float) – PSD amplitude (dimensionless).

  • psd_tau_yr (float) – Damping timescale [yr].

Returns:

Autocovariance at each lag [dimensionless].

Return type:

ndarray, shape (n_lag,)

Notes

JIT-compatible: yes, all operations use jnp primitives.

The autocovariance (autocorrelation function) of the DRW is:

\[\xi(\Delta t) = \frac{\sigma_{\rm PS}^2}{2} \exp\!\left( -\frac{|\Delta t|}{\tau_{\rm PS}} \right)\]

where \(\sigma_{\rm PS}\) is the PSD amplitude, \(\tau_{\rm PS}\) is the damping timescale [yr], and \(\Delta t\) is the time lag [yr].

Examples

>>> import jax.numpy as jnp
>>> from tengri import drw_acf
>>> lags = jnp.array([0.0, 1e7, 1e8, 1e9])  # time lags [yr]
>>> acf = drw_acf(lags, psd_sigma=1.0, psd_tau_yr=1e8)
>>> acf.shape
(4,)
>>> float(acf[0])  # variance at zero lag = sigma^2 / 2
0.5
tengri.drw_variance(psd_sigma: float) → float[source]

Stationary variance of DRW.

Parameters:

psd_sigma (float) – PSD amplitude (dimensionless).

Returns:

Stationary variance [dimensionless].

Return type:

float

Notes

JIT-compatible: yes, scalar arithmetic.

The stationary variance of a DRW is:

\[\sigma_x^2 = \frac{\sigma_{\rm PS}^2}{2}\]

where \(\sigma_{\rm PS}\) is the PSD amplitude.

Examples

>>> from tengri import drw_variance
>>> float(drw_variance(psd_sigma=1.0))
0.5
>>> float(drw_variance(psd_sigma=2.0))
2.0
tengri.compute_sqrt_power_drw(n_points: int, d_log_age: float, psd_sigma: float, psd_tau_yr: float, log_age_ref: float = 8.0) → Array[source]

Pre-compute DRW amplitude operator for log-age grid.

Converts the DRW PSD from physical frequency (rad/yr) to log-age frequency space (rad/dex) using the Jacobian correction for the change of variables from linear time \(t\) to log-time \(u = \log_{10} t\).

Parameters:
  • n_points (int) – Grid size (number of age samples).

  • d_log_age (float) – Grid spacing in dex [dimensionless].

  • psd_sigma (float) – DRW PSD amplitude [dimensionless].

  • psd_tau_yr (float) – DRW damping timescale [yr].

  • log_age_ref (float, optional) – Reference log10(age/yr) for Jacobian correction. Default: 8.0 (100 Myr).

Returns:

Amplitude operator \(\sqrt{P_u(q) / \Delta u}\) at rfft frequencies in log-age space [dimensionless].

Return type:

ndarray, shape (n_freq,)

Notes

JIT-compatible: yes, all operations use jnp primitives.

The Jacobian correction for the change of variables from cosmic time \(t\) (in years) to log-age \(u = \log_{10}(t)\) is:

\[P_u(q) = P_t\left( \frac{q}{t_{\rm ref} \ln 10} \right) / (t_{\rm ref} \ln 10)\]

where \(t_{\rm ref} = 10^{\log_{\rm age, ref}}\) is a reference time, \(q\) is the angular frequency in log-age space [rad/dex], and \(P_t\) is the PSD in physical frequency space.

The reference time scales out in the power spectrum but affects the mapping between physical and log-age frequencies. A typical choice is the midpoint of the age range (e.g., 100 Myr ~ 8 Gyr cosmic age).

Examples

>>> from tengri import compute_sqrt_power_drw, make_log_age_grid
>>> grid = make_log_age_grid(n_grid=64)
>>> d = float(grid[1] - grid[0])
>>> sp = compute_sqrt_power_drw(64, d, psd_sigma=1.0, psd_tau_yr=1e8)
>>> sp.shape
(33,)

GP generation

Functions for generating Gaussian process realizations from PSD parameters and a latent vector.

tengri.compute_field_gp(xi: Array, psd_sigma: float, psd_tau_yr: float, n_grid: int, d_log_age: float, field_model: str = 'drw', log_age_grid: Array | None = None, centering: float = 1.0) → tuple[Array, float][source]

Compute GP realization and lognormal correction for the field component.

Parameters:
  • xi (array, shape (n_grid,)) – Latent vector (xi ~ N(0, I)).

  • psd_sigma (float) – PSD amplitude (dex).

  • psd_tau_yr (float) – PSD timescale (yr).

  • n_grid (int) – Grid size.

  • d_log_age (float) – Grid spacing in dex.

  • field_model (str) – PSD model name. Default “drw”.

  • log_age_grid (array, shape (n_grid,), optional) – log10(age/yr) grid the SFH is sampled on. Required by the drw (linear-time) path to place the covariance in physical time; if omitted it is reconstructed with make_log_age_grid().

Returns:

  • gp_x (array, shape (n_grid,)) – GP realization sampled on the log-age grid. The draw defines the SFR at these lookback nodes; the history between nodes is the linear interpolation of the draw (edge-clamped outside), and both age kernels ('cic' and 'dsps') integrate that one function (#2684).

  • k0_half (float) – Lognormal bias correction K(0)/2 so exp(gp_x - k0_half) is mean-preserving. For drw this is (psd_sigma * ln10)^2 / 2.

Notes

JIT-compatible: yes.

field_model="drw" builds a damped random walk stationary in linear (physical) time: the covariance (sigma ln10)^2 exp(-|t_i-t_j|/tau) at physical times t_i = 10**u_i (#865). psd_sigma is then the modulation std in dex and psd_tau_yr the physical decorrelation timescale. It is realized via the exact OU state-space (innovations) recursion (drw_innovations_gp_from_xi()), which for a Markov covariance is the Cholesky factor: the same xi -> SFH map as a dense Cholesky, computed in O(n) instead of O(n^3) and without the positive-definiteness jitter, so the realized prior is the exact K. The posterior geometry is unchanged by this (#1301 is not addressed by it). Other PSD models keep the Fourier/log-age construction (gp_from_xi()).

Examples

>>> import jax.numpy as jnp
>>> from tengri import compute_field_gp, make_log_age_grid
>>> n = 64
>>> grid = make_log_age_grid(n)
>>> d = float(grid[1] - grid[0])
>>> xi = jnp.zeros(n)
>>> gp_x, k0_half = compute_field_gp(xi, psd_sigma=1.0, psd_tau_yr=1e8, n_grid=n, d_log_age=d)
>>> gp_x.shape
(64,)
tengri.generate_gp_fourier(key: Array, sqrt_power: Array, n_points: int) → Array[source]

Stochastic GP realization for mock galaxy generation.

Draws a random standardized vector and maps it to a correlated GP field.

Parameters:
  • key (jax.random.PRNGKey) – JAX random key for reproducibility.

  • sqrt_power (array_like, shape (n_freq,)) – Amplitude operator \(\sqrt{P(\omega) / d_{\rm grid}}\) at rfft frequencies (pre-compute with psd_to_sqrt_power()). [dimensionless]

  • n_points (int) – Number of grid points.

Returns:

GP realization on the log-age grid [dimensionless].

Return type:

ndarray, shape (n_points,)

Notes

JIT-compatible: yes, uses jax.random.normal and gp_from_xi().

This function is the primary interface for generating mock SFHs with stochastic variability. The random draw is always independent; for reproducibility, pass the same PRNGKey.

See also

gp_from_xi

Deterministic GP mapping (used internally).

generate_gp_batch

Generate multiple independent realizations.

Examples

>>> import jax
>>> from tengri import generate_gp_fourier, make_log_age_grid, compute_sqrt_power_drw
>>> n = 64
>>> grid = make_log_age_grid(n)
>>> d = float(grid[1] - grid[0])
>>> sqrt_power = compute_sqrt_power_drw(n, d, psd_sigma=1.0, psd_tau_yr=1e8)
>>> key = jax.random.PRNGKey(0)
>>> sfh = generate_gp_fourier(key, sqrt_power, n)
>>> sfh.shape
(64,)
tengri.generate_gp_batch(key: Array, sqrt_power: Array, n_points: int, n_realizations: int) → Array[source]

Batch of independent GP realizations via vectorization.

Generates multiple independent SFH realizations in parallel using vmap.

Parameters:
  • key (jax.random.PRNGKey) – JAX random key (will be split into n_realizations independent keys).

  • sqrt_power (array_like, shape (n_freq,)) – Amplitude operator \(\sqrt{P(\omega) / d_{\rm grid}}\) at rfft frequencies. [dimensionless]

  • n_points (int) – Number of grid points.

  • n_realizations (int) – Number of independent realizations to generate.

Returns:

Batch of independent GP realizations [dimensionless].

Return type:

ndarray, shape (n_realizations, n_points)

Notes

JIT-compatible: yes, uses jax.vmap over generate_gp_fourier().

Each realization is independent with the specified PSD structure. This function is useful for generating mock catalogs or computing uncertainties via Monte Carlo sampling.

See also

generate_gp_fourier

Single realization.

Examples

>>> import jax
>>> from tengri import generate_gp_batch, make_log_age_grid, compute_sqrt_power_drw
>>> n = 64
>>> grid = make_log_age_grid(n)
>>> d = float(grid[1] - grid[0])
>>> sqrt_power = compute_sqrt_power_drw(n, d, psd_sigma=1.0, psd_tau_yr=1e8)
>>> key = jax.random.PRNGKey(0)
>>> batch = generate_gp_batch(key, sqrt_power, n_points=n, n_realizations=10)
>>> batch.shape
(10, 64)
tengri.gp_from_xi(xi: Array, sqrt_power: Array, n_points: int) → Array[source]

Deterministic GP realization from standardized latent vector.

Maps a standardized Gaussian random vector to a correlated GP field via Fourier-space multiplication with a spectral amplitude operator. This is the core function used during inference and mock generation.

Parameters:
  • xi (array_like, shape (n_points,)) – Standardized latent vector \(\xi \sim \mathcal{N}(0, I)\) under the prior.

  • sqrt_power (array_like, shape (n_freq,)) – Amplitude operator \(\sqrt{P(\omega) / d_{\rm grid}}\) at rfft frequencies (pre-compute with psd_to_sqrt_power()). [dimensionless]

  • n_points (int) – Number of grid points (should match the length of xi).

Returns:

GP realization on the log-age grid [dimensionless].

Return type:

ndarray, shape (n_points,)

Notes

JIT-compatible: yes, uses jnp.fft.rfft and jnp.fft.irfft.

Gradient-safe: yes, differentiable w.r.t. sqrt_power.

Implements the NIFTy correlated field model:

\[s = \mathrm{IFFT}(\sqrt{P} \cdot \hat{\xi})\]

The rfft (real FFT) preserves Hermitian symmetry for real-valued output and ensures correct variance normalization: \(E[|\mathrm{rfft}(\xi)_k|^2] = N\), so with \(\sqrt{P/\Delta x}\) we recover \(\mathrm{Var}[s] = \int P(f) df\).

This is the primary function called during MCMC inference and mock galaxy generation. The sampler proposes values of \(\xi\) and this function maps them to correlated SFH realizations.

References

[tengri.gp_from_xi-1]

Selig et al., “NIFTY - Numerical Information Field Theory. A versatile PYTHON library for signal inference,” A&A, 554, A26 (2013). arXiv:1301.4499. https://doi.org/10.1051/0004-6361/201321236

Examples

>>> import jax.numpy as jnp
>>> from tengri import gp_from_xi, make_log_age_grid, compute_sqrt_power_drw
>>> n = 64
>>> grid = make_log_age_grid(n)
>>> d = float(grid[1] - grid[0])
>>> sqrt_power = compute_sqrt_power_drw(n, d, psd_sigma=1.0, psd_tau_yr=1e8)
>>> xi = jnp.zeros(n)
>>> sfh = gp_from_xi(xi, sqrt_power, n)
>>> sfh.shape
(64,)

Dust attenuation

Two-component dust attenuation (birth cloud + diffuse ISM) following Charlot & Fall (2000), with pluggable attenuation curves and geometry models.

tengri.two_component_dust(wavelength: Array, younger_fraction: Array, tau_v1: float, tau_v2: float, law_bc: str = 'power_law', law_diff: str = 'power_law', f_obscuration: float = 0.0, bc_params: dict | None = None, diff_params: dict | None = None, lyman_cutoff_aa: float = 0.0, **law_params) → Array[source]

Two-component dust transmission of Charlot & Fall (2000), a mixture of two stellar populations.

Separates dust into a birth-cloud screen (stars younger than the cloud’s lifetime) and a diffuse-ISM screen (all stars), with independent optical depths and attenuation curves. A stellar-population node holds a mixture of the two populations, and its transmission is the mass-weighted mixture of theirs:

\[T(\lambda, a) = y(a)\,T_{\rm young}(\lambda) + [1 - y(a)]\,T_{\rm old}(\lambda)\]

with \(y(a)\) the fraction of node \(a\)’s formed mass younger than the birth-cloud lifetime (the stellar component’s age_boundary_younger_fraction),

\[\begin{split}T_{\rm young} &= f_{\rm obs} + (1 - f_{\rm obs}) \exp[-\tau_{\rm V,BC} k_{\rm BC} - \tau_{\rm V,ISM} k_{\rm ISM}], \\ T_{\rm old} &= f_{\rm obs} + (1 - f_{\rm obs}) \exp[-\tau_{\rm V,ISM} k_{\rm ISM}].\end{split}\]
Parameters:
  • wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

  • younger_fraction (array_like, shape (n_ages,)) – Per-node formed-mass fraction younger than the birth-cloud lifetime [dimensionless, in [0, 1]]: the stellar component publishes it for the attenuator’s boundary (see tengri.components.stellar.age_boundary).

  • tau_v1 (float) – Birth-cloud V-band optical depth (at 5500 Å). [dimensionless]

  • tau_v2 (float) – Diffuse ISM V-band optical depth. [dimensionless]

  • law_bc (str, optional) – Attenuation curve name for birth cloud. Default: “power_law”. Resolved from DUST_LAWS registry.

  • law_diff (str, optional) – Attenuation curve name for diffuse ISM. Default: “power_law”.

  • f_obscuration (float, optional) – Fraction of unattenuated sightlines in clumpy geometry (Lower 2022). [dimensionless, in [0, 1]] Default: 0.0 (uniform screen).

  • bc_params (dict, optional) – Per-component overrides for the birth-cloud law (e.g. {"dust_slope": -1.0}). Merged on top of **law_params, so any key absent here falls back to the shared value. Enables FSPS-style independent indices (birth cloud dust1_index != diffuse dust_index). Default None -> shared parameters.

  • diff_params (dict, optional) – Per-component overrides for the diffuse ISM law. Same merge semantics as bc_params. Default None -> shared parameters.

  • lyman_cutoff_aa (float, optional) – Zero both attenuation curves below this wavelength. [Å] Default 0.0 -> disabled (the polynomial extrapolates through the FUV). Set to 912.0 to match CIGALE’s Lyman-limit clip (see apply_lyman_cutoff()).

  • **law_params – Shared keyword arguments passed to both attenuation curve functions (e.g., dust_slope, dust_bump_strength, dust_delta, dust_Rv). bc_params / diff_params override these per-component.

Returns:

Multiplicative transmission factor T(λ, t_age), where T in [0, 1]. [dimensionless]

Return type:

ndarray, shape (n_ages, n_wave)

Notes

JIT-compatible: yes, all operations are jnp primitives and safe for jax.jit.

Gradient-safe: yes, differentiable in the optical depths, the law parameters and younger_fraction.

Implements the same model as Charlot & Fall (2000) [tengri.two_component_dust-1], whose birth-cloud/diffuse split is a split of the stellar populations by age; the nodes of a discrete SSP grid carry the fraction of each population, rather than a single age. y(a) in {0, 1} (a node wholly inside one population) reduces to that population’s own transmission. The one implementation of the mixture is _age_mixture, shared with age_binned.

References

[tengri.two_component_dust-1]

S. Charlot and S. M. Fall, “A Simple Model for the Absorption of Starlight by Dust in Galaxies,” ApJ, 539, 718 (2000). https://doi.org/10.1086/309250

[tengri.two_component_dust-2]

S. Lower et al., “How Well Can We Measure Galaxy Dust Attenuation Curves? The Impact of the Assumed Star-dust Geometry Model in SED Fitting,” ApJ, 931, 14 (2022). arXiv:2203.00074. https://doi.org/10.3847/1538-4357/ac6959

Examples

>>> import jax.numpy as jnp
>>> from tengri import two_component_dust
>>> wave = jnp.linspace(1000.0, 30000.0, 300)
>>> ages = jnp.logspace(6.0, 10.14, 64)
>>> young = (ages < 1e7).astype(float)
>>> T = two_component_dust(wave, young, tau_v1=1.0, tau_v2=0.3)
>>> T.shape
(64, 300)

Attenuation curves: calzetti, cardelli, kriek_conroy, smc, lmc, power_law, salim, li08.

Dust attenuation model for tengri.

This module provides a generalized two-component dust attenuation framework (Charlot & Fall 2000) with pluggable attenuation curves and clumpy dust geometry (f_obscuration, Lower 2022).

Structure

Two physical components with independent attenuation curves:

  • Birth cloud: affects young stars (age < t_birth), optical depth tau_v1

  • Diffuse ISM: affects all stars, optical depth tau_v2

The wavelength dependence k(lambda) is pluggable per component:

tau(lambda, age) = w(age) * tau_v1 * k_bc(lambda) + tau_v2 * k_diff(lambda)
transmission = f_obs + (1 - f_obs) * exp(-tau)

where w(age) is a smooth sigmoid transition at t_birth.

Available Attenuation Curves

  • power_law: (lambda/5500)^n, original Charlot & Fall (2000)

  • calzetti: Calzetti et al. (2000) starburst polynomial, R_V=4.05

  • leitherer02: Leitherer et al. (2002) UV extension of Calzetti (970-1800 A)

  • kriek_conroy: Calzetti + UV bump + slope delta, the Prospector default

  • noll09: Noll et al. (2009) modified Calzetti+L02: (base+bump)*slope

  • salim_sbl18: Salim+2018 modified Calzetti+L02: base*slope+bump

  • smc: Pei (1992, ApJ 395 130) SMC Bar, steep UV, no 2175A bump

  • cardelli: Cardelli et al. (1989) MW curve with free R_V

  • li08: Li et al. (2008) Eq. (1) four-coefficient curve (continuum + FUV rise + 2175 Å bump)

  • salim: Salim et al. (2018) modified Calzetti (= DSPS default)

  • tea: Haskell et al. (2024) TEA 3-param empirical (NIHAO-SKIRT bump-slope correlation)

  • narayanan_z: Narayanan et al. (2018) redshift-dependent Kriek-Conroy (MUFASA RT)

  • conroy2010: Conroy+2010 CCM89 with scalable 2175 Å bump (FSPS dust_type=1)

  • vw07_bc: Wild+2007 birth cloud power-law (n=-1.3)

  • vw07_diff: Wild+2007 diffuse ISM power-law (n=-0.7)

Dust Geometries (Witt & Gordon 2000)

  • wg00_shell: Foreground screen, standard exp(-tau*k)

  • wg00_cloudy: Homogeneous dust-star mix (slab), grayer than screen

  • wg00_dusty: Clumpy two-phase medium (Natta & Panagia 1984), grayest

References

  • Calzetti et al. 2000, ApJ, 533, 682

  • Cardelli et al. 1989, ApJ, 345, 245

  • Charlot & Fall 2000, ApJ, 539, 718

  • Conroy, White & Gunn 2010, ApJ, 708, 58

  • Gordon et al. 2003, ApJ, 594, 279

  • Haskell et al. 2024, arXiv:2401.11007

  • Hobson & Padman 1993, MNRAS, 264, 161

  • Kriek & Conroy 2013, ApJL, 775, L16

  • Leitherer et al. 2002, ApJS, 140, 303

  • Li et al. 2008, ApJ, 685, 1046

  • Lower et al. 2022, ApJ, 931, 14

  • Narayanan et al. 2018, ApJ, 869, 70

  • Natta & Panagia 1984, ApJ, 287, 228

  • Noll et al. 2009, A&A, 507, 1793

  • Salim, Boquien & Lee 2018, ApJ, 859, 11

  • Wild et al. 2007, MNRAS, 381, 543

  • Witt & Gordon 2000, ApJ, 528, 799

  • Zacharegkas et al. 2025, arXiv:2506.19919

tengri.components.dust.attenuation.calzetti(wavelength: Array) → Array[source]

Calzetti et al. (2000) starburst attenuation curve.

R_V = 4.05 (fixed). Valid: 0.12 - 2.2 μm. Widely used for star-forming galaxies.

Parameters:

wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

Returns:

Normalized attenuation curve k(λ), where k(5500 Å) = 1. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

Uses piecewise polynomials in \(x = 1/\lambda\) [μm⁻¹]:

\[\begin{split}k'(\lambda) = \begin{cases} 2.659(-2.156 + 1.509x - 0.198x^2 + 0.011x^3) + R_V & \lambda < 0.63 \, \mu{\rm m} \\ 2.659(-1.857 + 1.040x) + R_V & \lambda \geq 0.63 \, \mu{\rm m} \end{cases}\end{split}\]

then normalized: \(k(\lambda) = k'(\lambda) / R_V\) with \(R_V = 4.05\).

\(R_V = 4.05 \pm 0.80\) is the value Calzetti et al. (2000) [tengri.components.dust.attenuation.calzetti-1] measure for the starburst sample, and the piecewise polynomial above is fitted at it, so R_V is a constant OF this law rather than a parameter of it. The signature declares no dust_Rv, so dust_attenuation={'law': 'calzetti', 'Rv': ...} raises rather than being accepted and discarded (#2185). Use cardelli or conroy2010 for a free R_V.

References

[tengri.components.dust.attenuation.calzetti-1]

S. Calzetti et al., “The Dust Content and Opacity of Actively Star-forming Galaxies,” ApJ, 533, 682 (2000). https://doi.org/10.1086/308692 bibcode: 2000ApJ…533..682C

tengri.components.dust.attenuation.cardelli(wavelength: Array, dust_Rv: float = 3.1) → Array[source]

Cardelli, Clayton & Mathis (1989) MW extinction with free R_V.

Detailed piecewise fit to Milky Way extinction spanning UV to IR. R_V parameterization allows flexibility for different dust types.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

  • dust_Rv (float) – Total-to-selective extinction ratio. [dimensionless] Default: 3.1.

Returns:

Extinction curve A(λ)/A(V) normalized to k(5500 Å) = 1. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

Uses piecewise polynomials in infrared, optical, UV, and far-UV regimes. Parameterized by \(x = 1/\lambda\) [μm⁻¹] with \(a(x)\) and \(b(x)\) coefficients fitted to extinction curves.

Held constant for \(x > 10\,\mu\mathrm{m}^{-1}\) (\(\lambda < 1000\) Å): this stops at CCM89’s own fitted far-UV domain, unlike conroy2010(), which extrapolates the same polynomial to \(x=12\) to match FSPS’s attn_curve.f90 exactly.

References

[tengri.components.dust.attenuation.cardelli-1]

D. E. Cardelli, G. C. Clayton, and J. S. Mathis, “The Relationship between Infrared, Optical, and Ultraviolet Extinction,” ApJ, 345, 245 (1989). https://doi.org/10.1086/167900

tengri.components.dust.attenuation.chevallard13(wavelength: Array, tau_v: float = 1.0) → Array[source]

Chevallard+2013 quasi-universal diffuse-ISM attenuation curve.

Parameters:
  • wavelength (array_like, shape (n_wave,) [Angstrom]) – Wavelength grid.

  • tau_v (float [dimensionless]) – Diffuse-ISM V-band optical depth \(\hat\tau_V^{\rm ISM}\) of the screen the curve is applied to. Default 1.0, so the registry’s one-argument sweeps evaluate the curve at tau_V = 1.

Returns:

Normalized attenuation curve \(k(\lambda, \tau_V)\), where \(k(5500\,\text{\AA}) = 1\) for every \(\tau_V\). [dimensionless] The attenuation optical depth of the screen is \(\hat\tau_\lambda = \tau_V \, k(\lambda, \tau_V)\); the screen multiplies by its own depth.

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

Gradient-safe: yes (\(\sqrt{\tau_V}\) is floored at \(10^{-10}\), so the gradient with respect to \(\tau_V\) is finite at \(\tau_V = 0\)).

Approximation: the index is held at its 0.1 and 2.5 µm values outside the range fitted by Chevallard et al. (2013) [tengri.components.dust.attenuation.chevallard13-1].

The curve is set by the V-band index \(n_V(\tau_V)\) and a wavelength-dependent index \(n(\lambda, \tau_V)\):

\[n_V(\tau_V) = \frac{2.8}{1 + 3\sqrt{\tau_V}}, \qquad b(\tau_V) = 0.3 - 0.05\,\tau_V\]
\[n(\lambda, \tau_V) = n_V(\tau_V) + b(\tau_V)\,(\lambda/\mu\text{m} - 0.55)\]
\[k(\lambda, \tau_V) = \left(\frac{\lambda}{5500\,\text{\AA}}\right)^{-n(\lambda, \tau_V)}\]

Here \(\lambda\) is the wavelength in Å, and \(\tau_V\) is the dimensionless V-band optical depth. This is Eqs. 9-11 of Chevallard et al. (2013) [tengri.components.dust.attenuation.chevallard13-1], restated as Eqs. 2.11-2.14 of Chevallard & Charlot (2016) [tengri.components.dust.attenuation.chevallard13-2]. The fit is valid for \(0.1 \le \lambda \le 2.5\,\mu\text{m}\); the index \(n\) uses \(\lambda\) clipped to that range.

This law needs the depth of the screen it is applied to (tau_v). The screens offer their own diffuse-ISM V-band depth through offer_screen_depth: the two-component interval transmissions, the energy-balance LUT (evaluated per node at that node’s own depth), and the nebular and line channels, including the nebular dust-grid builder, all pass the diffuse screen’s tau_V, so tau_v here is always the diffuse screen’s depth. The law is accepted as law_diff only (#3178).

Implements the ccww13_universal attenuation option of BEAGLE (Chevallard & Charlot 2016 [tengri.components.dust.attenuation.chevallard13-2]), as published; validated against the equations.

References

[tengri.components.dust.attenuation.chevallard13-1] (1,2)

J. Chevallard, S. Charlot, B. Wandelt, and V. Wild, “Insights into the content and spatial distribution of dust from the integrated spectral properties of galaxies,” MNRAS, 432, 2061 (2013). https://doi.org/10.1093/mnras/stt523 (arXiv:1303.6631)

[tengri.components.dust.attenuation.chevallard13-2] (1,2)

J. Chevallard and S. Charlot, “Modelling and interpreting spectral energy distributions of galaxies with BEAGLE,” MNRAS, 462, 1415 (2016). https://doi.org/10.1093/mnras/stw1756 (arXiv:1603.03037)

tengri.components.dust.attenuation.conroy2010(wavelength: Array, dust_Rv: float = 3.1, dust_bump_strength: float = 1.0) → Array[source]

Conroy+2010 CCM89 attenuation with scalable 2175 Å bump (FSPS dust_type=1).

Cardelli, Clayton & Mathis (1989) Milky Way extinction curve with the 2175 Å UV bump amplitude scaled by a free parameter. This matches FSPS’s dust_type=1 when dust_bump_strength=1.0 (full CCM89 bump) and allows weakening or removing the bump by setting dust_bump_strength < 1.0.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

  • dust_Rv (float) – Total-to-selective extinction ratio. [dimensionless] Default: 3.1.

  • dust_bump_strength (float) – Scaling factor for the 2175 Å UV bump amplitude. 1.0 = unmodified CCM89, 0.0 = no bump. [dimensionless] Default: 1.0.

Returns:

Extinction curve A(λ)/A(V) normalized to k(5500 Å) = 1. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

Near-identity at full strength: At dust_bump_strength=1.0 (the default) this recovers the unmodified Cardelli, Clayton & Mathis (1989) Drude/polynomial coefficients, but is not bit-identical to cardelli(): FSPS’s attn_curve.f90 (dust_type=1) applies the near-UV continuity correction below unconditionally, including at dust_bump_strength=1, where the CCM89 optical polynomial and near-UV Drude profile already fail to meet exactly at \(x=3.3\,\mu\mathrm{m}^{-1}\) (\(k_{\rm opt}(3.3) - k_{\rm uv}(3.3) = -1.80\times 10^{-4}\) at \(R_V=3.1\)). cardelli() has no such correction, so the two curves differ by up to \(\sim 2\times 10^{-4}\) (relative \(\sim 1\times 10^{-4}\)) near \(x=3.3\,\mu\mathrm{m}^{-1}\), even at dust_bump_strength=1.0. This reproduces FSPS’s published behavior deliberately (attn_curve.f90 applies hack for every uvb, not only uvb != 1).

The UV branch (3.3 ≤ x ≤ 8 μm⁻¹) of CCM89 is modified by scaling the two Drude profile coefficients:

\[ \begin{align}\begin{aligned}a(x) = 1.752 - 0.316x - 0.104 \cdot s/((x-4.67)^2+0.341) + F_a(x)\\b(x) = -3.090 + 1.825x + 1.206 \cdot s/((x-4.62)^2+0.263) + F_b(x)\end{aligned}\end{align} \]

where \(s = {\tt dust\_bump\_strength}\) scales only the Drude bump terms (0.104 and 1.206), leaving the polynomial continuum and far-UV corrections unchanged. At \(s=1\), this recovers the exact CCM89 extinction law. At \(s=0\), the 2175 Å feature is suppressed while the overall UV slope remains CCM89-like.

Continuity correction and its residual steps for \(s \neq 1\): the near-UV/optical junction correction (hack in attn_curve.f90) is defined on the near-UV segment \(3.3 \le x < 5.9\,\mu\mathrm{m}^{-1}\) only; the adjoining mid-UV segment (\(5.9 \le x < 8.0\,\mu\mathrm{m}^{-1}\)) carries no such term in FSPS. Two residual discontinuities are therefore properties of the published FSPS dust_type=1 form for \(s \neq 1\), reproduced here deliberately rather than smoothed away:

  • At \(x=5.9\,\mu\mathrm{m}^{-1}\): a step of size \((3.3/5.9)^6 \cdot \Delta \approx 0.0306\,\Delta\), where \(\Delta = k_{\rm opt}(3.3) - k_{\rm uv}(3.3; s)\) is the same near-UV/optical mismatch corrected at \(x=3.3\).

  • At \(x=8\,\mu\mathrm{m}^{-1}\): the far-UV polynomial (CCM89 Table 4) carries no bump-strength scaling of its own (an implicit \(s=1\) continuation), so its junction with the scaled mid-UV segment also steps; \(\approx 0.7\%\) of \(k\) for \(s=0\) at \(R_V=3.1\).

Far-UV domain (x > 10): unlike cardelli(), which stops at CCM89’s own fitted range, this evaluates the far-UV cubic out to \(x=12\,\mu\mathrm{m}^{-1}\) (\(\lambda \approx 833\) Å) before holding it constant, matching FSPS’s attn_curve.f90 (mwdindex(6)) exactly; the two curves therefore differ below 1000 Å even at bump strength 1.

References

[tengri.components.dust.attenuation.conroy2010-1]

D. E. Cardelli, G. C. Clayton, and J. S. Mathis, “The Relationship between Infrared, Optical, and Ultraviolet Extinction,” ApJ, 345, 245 (1989). https://doi.org/10.1086/167900

[tengri.components.dust.attenuation.conroy2010-2]

C. Conroy, R. H. White, and J. S. Gunn, “Recovering the Intergalactic Dust from Galaxies with z < 1,” ApJ, 708, 58 (2010). https://doi.org/10.1088/0004-637X/708/1/58

tengri.components.dust.attenuation.d03_mwrv31(wavelength: Array) → Array[source]

Draine (2003) MW R_V=3.1 updated grain model attenuation curve.

Updated Milky Way grain model incorporating revised PAH properties and emission efficiencies relative to WD01. R_V = 3.1.

Parameters:

wavelength (array_like, shape (n_wave,)) – Wavelength grid [Å].

Returns:

Normalized attenuation curve k(λ), k(5500 Å) = 1 [dimensionless].

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, uses jnp.interp on precomputed curve.

Upstream credit: grain model data from Draine (2003) [tengri.components.dust.attenuation.d03_mwrv31-1], accessed via the dust-extinction astropy-affiliated package. Independent implementation in synthesizer (Wilkins et al. 2025 [tengri.components.dust.attenuation.d03_mwrv31-2]).

References

[tengri.components.dust.attenuation.d03_mwrv31-1]

B. T. Draine, “Interstellar Dust Grains,” ARA&A, 41, 241 (2003). arXiv:astro-ph/0304489. https://doi.org/10.1146/annurev.astro.41.011802.094840

[tengri.components.dust.attenuation.d03_mwrv31-2]

C. C. Lovell et al. 2025, Open J. Astrophys. 8, “Synthesizer: a Software Package for Synthetic Astronomical Observables,” doi:10.33232/001c.145766; W. J. Roper et al. 2026, JOSS 11, 9436, doi:10.21105/joss.09436 (cite both Synthesizer papers).

tengri.components.dust.attenuation.dust_to_gas_scaling_remy_ruyer(logzsol: float) → float[source]

Metallicity-dependent dust-to-gas ratio scaling (Rémy-Ruyer+2014).

Returns multiplicative factor for dust optical depths relative to solar. Broken power law: linear above 0.1 Z_sun, quadratic below.

Parameters:

logzsol (float) – log10(Z / Z_sun). [dimensionless]

Returns:

D/G ratio relative to solar (1.0 at solar metallicity). [dimensionless]

Return type:

float

Notes

JIT-compatible: yes, all operations are jnp primitives.

The scaling is a broken power law:

\[\begin{split}\text{D/G} = \begin{cases} (Z/Z_{\odot})^2 \times 0.1 & (Z/Z_{\odot}) \leq 0.1 \\ (Z/Z_{\odot}) & (Z/Z_{\odot}) > 0.1 \end{cases}\end{split}\]

References

[tengri.components.dust.attenuation.dust_to_gas_scaling_remy_ruyer-1]

S. Rémy-Ruyer, I. Miville-Deschênes, T. Siebel, et al., “Dust and Gas Relationship in Nearby Galaxies,” A&A, 563, A31 (2014). https://doi.org/10.1051/0004-6361/201322803

tengri.components.dust.attenuation.fitzpatrick99(wavelength: Array, dust_Rv: float = 3.1) → Array[source]

Fitzpatrick (1999) Milky Way extinction curve, normalized to k(5500 A) = 1.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Observed wavelength grid. [Angstrom]

  • dust_Rv (float) – Total-to-selective extinction ratio R_V. [dimensionless] Default: 3.1.

Returns:

Extinction curve k(lambda) = A(lambda)/A(5500 A), normalized so that k(5500 A) = 1. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes. Gradient-safe: yes, with respect to wavelength and dust_Rv. Vmap-safe: yes.

Divides fitzpatrick99_unnormalized() by its own value at 5500 Angstrom, which is the V-band convention every registered dust law follows (cardelli normalizes the same way). The foreground screen does not use this form.

tengri.components.dust.attenuation.fitzpatrick99_unnormalized(wave_obs: Array, dust_Rv: float = 3.1) → Array[source]

Fitzpatrick (1999) Milky Way extinction law in the paper’s own convention.

Returns \(A(\lambda)/A(V)\) with \(A(V) = R_V\,E(B-V)\) taken from the paper’s spline, without renormalizing at 5500 Angstrom. The foreground screen uses this form, so its transmission is the tabulated \(A(\lambda)/E(B-V)\) times \(E(B-V)\). The registered dust law fitzpatrick99() divides this curve by its own value at 5500 Angstrom.

Optical and infrared from a natural cubic spline through the paper’s anchor points; ultraviolet (lambda at or below 2700 Angstrom) from the Fitzpatrick & Massa (1990) parameterization. Both branches meet at 2700 Angstrom.

Parameters:
  • wave_obs (array_like, shape (n_wave,)) – Observed wavelength grid. [Angstrom]

  • dust_Rv (float) – Total-to-selective extinction ratio R_V = A(V)/E(B-V). [dimensionless] Default: 3.1.

Returns:

Extinction curve A(lambda)/A(V) = (E(lambda-V)/E(B-V) + R_V) / R_V. [dimensionless]. Table 3 of Fitzpatrick (1999) gives A(lambda)/E(B-V), so the tabulated values equal this output multiplied by R_V.

Return type:

ndarray, shape (n_wave,)

Notes

The returned curve follows

\[\frac{A(\lambda)}{A(V)} = \frac{E(\lambda - V)/E(B-V) + R_V}{R_V}, \qquad \frac{E(\lambda - V)}{E(B-V)} = c_1 + c_2 x + c_3 D(x) + c_4 F(x)\]

for \(x \ge 1/0.27\,\mu\mathrm{m}^{-1}\), with the Drude profile \(D(x) = x^2 / [(x^2 - x_0^2)^2 + x^2 \gamma^2]\) and the far-UV term \(F(x) = 0.5392\,(x - 5.9)^2 + 0.05644\,(x - 5.9)^3\) for \(x \ge 5.9\,\mu\mathrm{m}^{-1}\) (zero below). Here \(x = 10^4/\lambda\) [\(\mu\mathrm{m}^{-1}\)] with \(\lambda\) in Angstrom, \(R_V\) is dimensionless, \(c_2 = -0.824 + 4.717/R_V\) and \(c_1 = 2.030 - 3.007\,c_2\) are dimensionless, \(x_0 = 4.596\,\mu\mathrm{m}^{-1}\) and \(\gamma = 0.99\,\mu\mathrm{m}^{-1}\) are the bump center and width, and \(c_3 = 3.23\), \(c_4 = 0.41\) are the bump and far-UV strengths. At longer wavelengths the natural cubic spline in \(x\) through the nine anchors replaces the expression.

JIT-compatible: yes, fixed knots and jnp primitives. The spline curvature matrix is computed once on the host at import. Gradient-safe: yes; both branches are finite for every wavelength in the optical to far-UV range, and the gradient with respect to dust_Rv is nonzero. Vmap-safe: yes, no Python branching on traced values.

The optical and infrared anchors follow Table 3 at R_V = 3.1, and Table 4 gives the R_V dependence of the optical anchors. The infrared anchors scale with R_V / 3.1. The 2700 and 2600 Angstrom anchors are the FM90 curve. The spline uses natural boundary conditions, which the paper does not specify.

The far-UV term F(x) is FM90 Eq. (4) as printed. None of the tabulated anchors lies at x >= 5.9 1/um, so the tables do not test its coefficients. The paper’s mean values are x0 = 4.596 1/um, gamma = 0.99 1/um, c3 = 3.23 and c4 = 0.41; c2 and c1 follow from R_V through Eqs. (A1)-(A2).

Use with the Schlafly & Finkbeiner (2011) recalibration of the Schlegel et al. (1998) dust map by multiplying the map E(B-V) by 0.86 before it enters this law. This function applies the E(B-V) it is given.

References

[tengri.components.dust.attenuation.fitzpatrick99_unnormalized-1]

E. L. Fitzpatrick, “Correcting for the Effects of Interstellar Extinction,” PASP, 111, 63 (1999). https://doi.org/10.1086/316293

[tengri.components.dust.attenuation.fitzpatrick99_unnormalized-2]

E. L. Fitzpatrick and D. Massa, “An Analysis of the Shapes of Ultraviolet Extinction Curves. III - an Atlas of Ultraviolet Extinction Curves,” ApJS, 72, 163 (1990). https://doi.org/10.1086/191413

tengri.components.dust.attenuation.gordon03_smcbar(wavelength: Array) → Array[source]

Gordon et al. (2003) SMC-bar average extinction curve.

Empirically-derived SMC-bar average extinction curve from direct observations of SMC stars: steep ultraviolet rise, no 2175 Å bump. Represents the Magellanic Cloud population most relevant for high-redshift star-forming galaxies.

The attenuation curve is evaluated from the dust_extinction model on a fine grid (4001 points) spanning the model’s native wavenumber domain and interpolated via jnp.interp with linear interpolation.

Parameters:

wavelength (array_like, shape (n_wave,)) – Wavelength grid [Å].

Returns:

Normalized attenuation curve k(λ), k(5500 Å) = 1 [dimensionless].

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, uses jnp.interp on precomputed curve.

Precomputed from dust_extinction.averages.G03_SMCBar at module import time by evaluating the model on a fine grid spanning exactly 1000–33333 Å (0.3 µm⁻¹ ≤ x ≤ 10 µm⁻¹). For x ≥ 3.70 µm⁻¹ (λ ≤ 2700 Å) the model is the FM90 form; redward of 2700 Å it is a cubic spline through the Table 4 optical/NIR nodes anchored on FM90 at 2700 and 2600 Å (the spline sits 3.5 % above pure FM90 at x = 3.3 µm⁻¹). Redward of 33333 Å the curve holds its end value 0.0624; blueward of 1000 Å it holds 9.6346.

For x ≥ 3.70 µm⁻¹ (λ ≤ 2700 Å), the model implements the Fitzpatrick & Massa (1990) form with SMC-bar FM90 parameters: c1 = −4.959, c2 = 2.264, c3 = 0.389, c4 = 0.461, x0 = 4.600 µm⁻¹, γ = 1.000 µm⁻¹, R_V = 2.74.

Repackaged from the dust_extinction package (astropy-affiliated). The same curve is shipped by FSPS as dust_type=5 and by BAGPIPES as "SMC" type.

References

[tengri.components.dust.attenuation.gordon03_smcbar-1]

K. D. Gordon, G. C. Clayton, K. A. Misselt, A. U. Landolt, and M. J. Wolff, “A Quantitative Comparison of the Small Magellanic Cloud, Large Magellanic Cloud, and Milky Way Ultraviolet to Near-Infrared Extinction Curves,” ApJ, 594, 279 (2003). arXiv:astro-ph/0305257. https://doi.org/10.1086/376774

[tengri.components.dust.attenuation.gordon03_smcbar-2]

E. L. Fitzpatrick and D. Massa, “An analysis of the shapes of ultraviolet extinction curves. III - an atlas of ultraviolet extinction curves,” ApJS, 72, 163 (1990). https://doi.org/10.1086/191413

tengri.components.dust.attenuation.hd23_mwrv31(wavelength: Array) → Array[source]

Hensley & Draine (2023) astrodust+PAH MW R_V=3.1 grain model.

State-of-the-art MW grain model combining astrodust grains with PAH emission. R_V = 3.1. Supersedes WD01/D03 for the diffuse MW ISM.

Parameters:

wavelength (array_like, shape (n_wave,)) – Wavelength grid [Å].

Returns:

Normalized attenuation curve k(λ), k(5500 Å) = 1 [dimensionless].

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, uses jnp.interp on precomputed curve.

Upstream credit: grain model data from Hensley & Draine (2023) [tengri.components.dust.attenuation.hd23_mwrv31-1], accessed via the dust-extinction astropy-affiliated package. Independent implementation in synthesizer (Wilkins et al. 2025 [tengri.components.dust.attenuation.hd23_mwrv31-2]).

References

[tengri.components.dust.attenuation.hd23_mwrv31-1]

B. S. Hensley & B. T. Draine, “The Astrodust+PAH Model: A Unified Description of the Dust of the Diffuse Milky Way,” ApJ, 948, 55 (2023). arXiv:2208.12365. https://doi.org/10.3847/1538-4357/acc4c2

[tengri.components.dust.attenuation.hd23_mwrv31-2]

C. C. Lovell et al. 2025, Open J. Astrophys. 8, “Synthesizer: a Software Package for Synthetic Astronomical Observables,” doi:10.33232/001c.145766; W. J. Roper et al. 2026, JOSS 11, 9436, doi:10.21105/joss.09436 (cite both Synthesizer papers).

tengri.components.dust.attenuation.kriek_conroy(wavelength: Array, dust_bump_strength: float = 1.0, dust_delta: float = 0.0) → Array[source]

Kriek & Conroy (2013) modified Calzetti + UV bump + slope delta.

Default attenuation law in Prospector, applied there through FSPS (dust_type=4). Reproduces FSPS’ construction: a Calzetti baseline tilted by a power law in \(\lambda\), plus a 2175 Å Drude bump whose amplitude is coupled to the slope via Kriek & Conroy (2013) Eqn 3, with the bump divided by \(R_V = 4.05\).

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

  • dust_bump_strength (float) – Multiplier on the KC13-derived bump amplitude \(E_b = 0.85 - 1.9\,\delta\). [dimensionless] Default: 1.0, which reproduces FSPS dust_type=4 exactly; set to 0.0 to remove the bump, or scale to weaken/strengthen it.

  • dust_delta (float) – Power-law slope modification \(\delta\). [dimensionless] Default: 0.0. Steeper (more negative) \(\delta\) gives a stronger bump, per KC13 Eqn 3.

Returns:

Normalized attenuation curve k(λ), where k(5500 Å) = 1. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

Following FSPS attn_curve.f90 (dust_type=4), the unnormalized curve is:

\[k'(\lambda) = \left[ k_{\rm Calz}(\lambda) + \frac{E_b}{R_V}\,D(\lambda; \lambda_0 = 2175\,\text{\AA}) \right] \left(\frac{\lambda}{5500\,\text{\AA}}\right)^{\delta}, \qquad E_b = 0.85 - 1.9\,\delta\]

with \(R_V = 4.05\), \(k_{\rm Calz}\) the Calzetti et al. (2000) curve, and \(D\) the unit-peak Drude profile. The result is renormalized to \(k(5500\,\text{\AA}) = 1\). The dust_bump_strength multiplier scales \(E_b\).

Upstream: follows the FSPS dust_type=4 branch (Conroy, Gunn & White 2009); the slope–bump coupling is Kriek & Conroy (2013) Eqn 3.

References

[tengri.components.dust.attenuation.kriek_conroy-1]

M. Kriek and C. Conroy, “The Dust Attenuation Law in Distant Galaxies: Evidence for Variation with Spectral Type,” ApJL, 775, L16 (2013). https://doi.org/10.1088/2041-8205/775/1/L16

[tengri.components.dust.attenuation.kriek_conroy-2]

C. Conroy, J. E. Gunn, M. White, “The Propagation of Uncertainties in Stellar Population Synthesis Modeling. I.,” ApJ, 699, 486 (2009). https://doi.org/10.1088/0004-637X/699/1/486

tengri.components.dust.attenuation.leitherer02(wavelength: Array) → Array[source]

Leitherer et al. (2002) UV starburst attenuation curve.

Far-UV extension of the Calzetti (2000) law, valid 970-1800 Å. Uses R_V = 4.05 (same as Calzetti). For wavelengths outside the L02 range, falls back to Calzetti (2000).

Parameters:

wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

Returns:

Attenuation curve k(λ), normalized to k(5500 Å) = 1. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

The reddening curve k’(λ) = A(λ)/E(B−V) follows:

\[k'(\lambda) = 5.472 + 0.671x - 9.218 \times 10^{-3} x^2 + 2.620 \times 10^{-3} x^3\]

where \(x = 1/\lambda\) [μm⁻¹], valid for 970–1800 Å (0.097–0.18 μm). The final k(λ) = k’(λ) / R_V with R_V = 4.05.

References

[tengri.components.dust.attenuation.leitherer02-1]

C. Leitherer et al., “Global Far-Ultraviolet (912–1800 Å) Properties of Star-forming Galaxies,” ApJS, 140, 303 (2002). https://doi.org/10.1086/342486

tengri.components.dust.attenuation.li08(wavelength: Array, dust_c1: float = 14.4, dust_c2: float = 6.52, dust_c3: float = 2.04, dust_c4: float = 0.0519) → Array[source]

Li et al. (2008) analytical dust attenuation/extinction curve.

A flexible 4-parameter analytical model that can reproduce MW, LMC, SMC, and Calzetti-like curves through a single functional form. The three terms represent a UV/optical continuum, a far-UV rise, and the 2175 Angstrom UV bump respectively.

The normalized attenuation is (Li et al. 2008, Eq. 1):

A_lam/A_V = c1 / [(lam/0.08)^c2 + (0.08/lam)^c2 + c3]
          + 233 * [1 - c1/(6.88^c2 + 0.145^c2 + c3) - c4/4.60]
            / [(lam/0.046)^2 + (0.046/lam)^2 + 90]
          + c4 / [(lam/0.2175)^2 + (0.2175/lam)^2 - 1.95]

where lam is the wavelength in micron and c1-c4 are dimensionless.

Parameters:
  • wavelength (array, shape (n_wave,)) – Wavelength grid in Angstrom.

  • dust_c1 (float) – Continuum amplitude. Controls overall UV-optical shape. Default 14.4 is the Li et al. (2008) Table 1 Milky Way (R_V=3.1) value.

  • dust_c2 (float) – Continuum curvature. Higher values produce steeper UV rises. Default 6.52 is the Li et al. (2008) Table 1 Milky Way (R_V=3.1) value.

  • dust_c3 (float) – Continuum offset. Shifts the overall curve level. Default 2.04 is the Li et al. (2008) Table 1 Milky Way (R_V=3.1) value.

  • dust_c4 (float) – UV bump amplitude at 2175 Angstrom. Set to 0 for bump-free. Default 0.0519 is the Li et al. (2008) Table 1 Milky Way (R_V=3.1) value.

Returns:

Attenuation curve k(lambda), normalized to k(5500 A) = 1.

Return type:

array, shape (n_wave,)

Notes

Templates for common curves (Li et al. 2008, Table 1):

  • Calzetti: c1=44.9, c2=7.56, c3=61.2, c4=0.0

  • SMC: c1=38.7, c2=3.83, c3=6.34, c4=0.0

  • Milky Way (R_V=3.1): c1=14.4, c2=6.52, c3=2.04, c4=0.0519 (the default)

  • LMC: c1=4.47, c2=2.39, c3=-0.988, c4=0.0221

References

Li, A., Liang, S. L., Kann, D. A., et al. 2008, ApJ, 685, 1046, Table 1

tengri.components.dust.attenuation.lmc(wavelength: Array) → Array[source]

LMC average extinction curve (Pei 1992, ApJ, 395, 130).

Weak 2175 Å bump, intermediate between MW and SMC. R_V = 3.16. Uses generalized Drude profile sum: fully continuous.

Parameters:

wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

Returns:

Normalized extinction curve k(λ). [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

From Pei (1992) Table 4: Large Magellanic Cloud average parameters, 6 Drude components with R_V = 3.16. Shows weak 2175 Å bump feature.

References

P. G. Pei, “Interstellar Dust from the Ultraviolet to the Infrared,” ApJ, 395, 130 (1992).

tengri.components.dust.attenuation.narayanan_z(wavelength: Array, redshift: float = 0.0) → Array[source]

Narayanan+2018 redshift-dependent attenuation.

Evaluates the Kriek & Conroy (2013) curve [tengri.components.dust.attenuation.narayanan_z-2] at slope and bump values interpolated in redshift from a table fitted to the median attenuation curves Narayanan et al. (2018) [tengri.components.dust.attenuation.narayanan_z-1] publish for their 25 Mpc MUFASA cosmological radiative-transfer run. The curve gets grayer with redshift, which is the trend the paper reports in its Section 5.1.

Redshift is the only knob. This law is the published median at z; a slope or bump of your own is a different model, and it is kriek_conroy(), which takes exactly those two parameters. The grammar refuses dust_delta and dust_bump_strength on this law and says so.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

  • redshift (float) – Galaxy redshift. [dimensionless] Default: 0.0. Supplied by the model, not by the dust_attenuation group.

Returns:

Attenuation curve k(λ), normalized to k(5500 Å) = 1. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

Gradient-safe: yes, and continuous in redshift: the table is read with jnp.interp, which is piecewise linear. The gradient is identically zero above z = 6 and below z = 0, where the end node is held rather than extrapolated, so a photometric-redshift fit that wanders past z = 6 gets no curve-shape information from this law there; and it is discontinuous in the second derivative at the seven integer nodes.

\[k(\lambda, z) = k_{\rm KC13}\bigl(\lambda;\ \delta(z),\ m(z)\bigr),\]

where \(\delta(z)\) and \(m(z)\) are linear interpolations of the module tables _NARAYANAN_DELTA and _NARAYANAN_BUMP_STRENGTH in \(z\) [dimensionless], \(k_{\rm KC13}\) is kriek_conroy(), and \(m\) multiplies that curve’s bump amplitude \(E_b = 0.85 - 1.9\,\delta\). Outside \(0 \le z \le 6\) the table is held at its end node rather than extrapolated.

Approximation: the Kriek & Conroy form fitted to published median curves, not a formula the paper states. Narayanan et al. (2018) give the redshift dependence as median curves (their Figure 9) and publish them at the data URL below; scripts/fit_narayanan2018_medians.py fits three parameters per redshift (\(\delta\), the bump multiplier and a normalization) to the repackaged copy at data/attenuation/narayanan2018_median_curves.dat, and every number in the tables above comes from that fit. Residual rms over the fit window 1250 Å to 1 μm is 0.018, 0.024, 0.014, 0.011, 0.012, 0.019 and 0.010 at z = 0 to 6, against curves of order unity there, so the form reproduces the medians to a few percent and no better. Valid over \(0 \le z \le 6\) and 1250 Å to 1 μm; blueward of 1250 Å the Calzetti (2000) baseline the KC13 form tilts is itself an extrapolation, and the fit excludes that region.

The published curves are normalized by the 3000 Å optical depth rather than by A_V, so each fit carries a free normalization; that factor is not applied here, because this function returns k(5500 Å) = 1 like every other registered law and the overall depth is the model’s dust_tau_v.

References

[tengri.components.dust.attenuation.narayanan_z-1]

D. Narayanan, C. Conroy, R. Davé, B. D. Johnson and G. Popping, “A Theory for the Variation of Dust Attenuation Laws in Galaxies,” ApJ, 869, 70 (2018). arXiv:1805.06905. https://doi.org/10.3847/1538-4357/aaed25 Median curves: https://bitbucket.org/desika/narayanan_attenuation_laws/

[tengri.components.dust.attenuation.narayanan_z-2]

M. Kriek and C. Conroy, “The Dust Attenuation Law in Distant Galaxies: Evidence for Variation with Spectral Type,” ApJL, 775, L16 (2013). https://doi.org/10.1088/2041-8205/775/1/L16

tengri.components.dust.attenuation.noll09(wavelength: Array, dust_bump_strength: float = 0.0, dust_delta: float = 0.0, dust_bump_x0: float = 0.2175, dust_bump_gamma: float = 0.035) → Array[source]

Noll et al. (2009) modified Calzetti + L02 with UV bump + slope delta.

This is the N09 model from the dust_attenuation package. Uses Leitherer (2002) for λ < 1800 Å (0.18 µm) and Calzetti (2000) above. The modification order is: (base + bump) × power_law.

This differs from kriek_conroy which does NOT use L02 and applies the bump AFTER the slope: base × power_law + bump.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

  • dust_bump_strength (float) – Amplitude of 2175 Å UV bump (E_b). [dimensionless] Default: 0.0 (no bump).

  • dust_delta (float) – Power-law slope modification. [dimensionless] Default: 0.0 (pure Calzetti+L02).

  • dust_bump_x0 (float) – Central wavelength of UV bump. [μm] Default: 0.2175.

  • dust_bump_gamma (float) – FWHM of UV bump. [μm] Default: 0.035.

Returns:

Attenuation curve k(λ) = k’(λ) / R_V with R_V = 4.05. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

The attenuation is:

\[k(\lambda) = [k_{\rm L02+C00}(\lambda) + E_b D(\lambda; \lambda_0, \gamma)] \times \left(\frac{\lambda}{5500 \, \text{\AA}}\right)^\delta / R_V\]

Normalization follows the dust_attenuation package convention: k(λ) = k’(λ)/R_V where R_V = 4.05 is fixed. This means k(V) is NOT exactly 1.0 when bump or slope modifications are applied.

References

[tengri.components.dust.attenuation.noll09-1]

S. Noll, S. Pierini, B. Coles, et al., “On the link between galaxy morphology and supermassive black holes in the nearby Universe,” A&A, 507, 1793 (2009). https://doi.org/10.1051/0004-6361/200912497

tengri.components.dust.attenuation.power_law(wavelength: Array, dust_slope: float = -0.7, dust_bump_strength: float = 0.0, dust_bump_x0: float = 0.2175, dust_bump_gamma: float = 0.035) → Array[source]

Power-law dust attenuation curve following Charlot & Fall (2000), with an optional UV bump.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

  • dust_slope (float, optional) – Power-law slope. Default: -0.7 (standard Charlot & Fall). [dimensionless]

  • dust_bump_strength (float, optional) – Amplitude of the Drude UV bump relative to the power law. [dimensionless] Default: 0.0 (no bump), which returns the bare power law.

  • dust_bump_x0 (float, optional) – Central wavelength of the UV bump. [μm] Default: 0.2175.

  • dust_bump_gamma (float, optional) – FWHM of the UV bump. [μm] Default: 0.035.

Returns:

Normalized attenuation curve k(λ), where k(5500 Å) = 1. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

The unnormalized curve is the Charlot & Fall power law plus a Drude bump, in the functional form of CIGALE’s dustatt_powerlaw module [tengri.components.dust.attenuation.power_law-2], with the bump amplitude \(E_b\) written as dust_bump_strength:

\[a(\lambda) = \left(\frac{\lambda}{5500 \, \text{\AA}}\right)^n + E_b \, D(\lambda; \lambda_0, \gamma)\]

where \(n\) is dust_slope, \(D\) is the Drude profile \((\lambda\gamma)^2 / [(\lambda^2 - \lambda_0^2)^2 + (\lambda\gamma)^2]\), and \(\lambda_0\), \(\gamma\) are dust_bump_x0 and dust_bump_gamma. The returned curve is normalized so that \(k(\lambda) = a(\lambda)/a(5500 \, \text{\AA})\), which keeps \(\tau_V\) the optical depth at 5500 Å. The normalization is a scalar, so the bump’s shape is unchanged.

With dust_bump_strength = 0 the bump term is exactly zero and the normalization divides by one, so the result is the bare power law bit for bit.

References

[tengri.components.dust.attenuation.power_law-1]

S. Charlot and S. M. Fall, “A Simple Model for the Absorption of Starlight by Dust in Galaxies,” ApJ, 539, 718 (2000). https://doi.org/10.1086/309250

[tengri.components.dust.attenuation.power_law-2]

Boquien, M. et al. 2019, “CIGALE: a python Code Investigating GALaxy Emission”, A&A 622, A103, arXiv:1811.03094, doi:10.1051/0004-6361/201834156. The power law with a UV bump is the pcigale dustatt_powerlaw module (alambda_av, uv_bump), which this curve reproduces up to the normalization above.

tengri.components.dust.attenuation.prevot_smc(wavelength: Array) → Array[source]

Prevot et al. (1984) SMC extinction law for AGN obscuration.

Analytic SMC extinction curve from the UV to near-infrared, used in AGNfitter for AGN disc reddening. The analytic Prevot+1984 fit \(k_{\rm raw}(\lambda) = 1.39\,\lambda_{\mu m}^{-1.2} - 0.38\) evaluates to \(k_{\rm raw}(0.55\,\mu m) \approx 2.468\) at V; this function returns the V-band-normalized shape \(k(\lambda) = k_{\rm raw}(\lambda)/k_{\rm raw}(V)\) (so k(V)=1), matching the convention used by cardelli and the rest of the components.dust.attenuation registry. The measured SMC ratio \(R_V = 2.72\) (Prevot+1984) is applied separately by tengri.components.agn.reddening.redden_disc() as \(A(\lambda) = k(\lambda)\,R_V\,E(B-V)\). AGNfitter’s BBBred_Prevot instead applies the bare \(k_{\rm raw}\) (its function_prevot declares RV=2.72 but does not use the argument), so its effective ratio is 2.468 and its EBVbbb maps onto tengri’s as \(E(B-V)_{\rm tengri} \approx E(B-V)_{\rm AGNfitter} / 1.102\).

Parameters:

wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

Returns:

Extinction curve \(k(\lambda) = A(\lambda)/A(V)\) normalized to k(5500 A) = 1. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

\[k_{\rm raw}(\lambda) = 1.39 \, \lambda_{\mu m}^{-1.2} - 0.38, \qquad k(\lambda) = k_{\rm raw}(\lambda) / k_{\rm raw}(0.55\,\mu m)\]

where \(\lambda_{\mu m}\) is wavelength in micrometers and \(k_{\rm raw}(0.55) \approx 2.468\).

For wavelengths below 62 Å, reddening is ramped to zero using a smooth sigmoid (no hard discontinuity) to suppress extinction in the X-ray regime where dust is ineffective.

Gradient-compatible: yes, enables optimization of extinction parameters.

References

[tengri.components.dust.attenuation.prevot_smc-1]

M. Prevot et al., “The Ultraviolet Extinction Curve in the Small Magellanic Cloud from 1200 Å to 3200 Å,” A&A, 132, 389 (1984).

[tengri.components.dust.attenuation.prevot_smc-2]

J. Calistro Rivera et al., “AGNfitter: A Bayesian MCMC approach to fitting spectral energy distributions of Active Galactic Nuclei,” ApJ, 863, 56 (2018). arXiv:1808.04989. https://doi.org/10.3847/1538-4357/aad235

tengri.components.dust.attenuation.reddy15(wavelength: Array) → Array[source]

Reddy et al. (2015) MOSDEF dust attenuation curve.

High-redshift (z~1.4-2.6) attenuation curve derived from MOSDEF galaxies using Balmer decrements. R_V = 2.505 (lower than Calzetti). Valid: 0.15 - 2.85 μm. Similar to SMC at long wavelengths.

Parameters:

wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

Returns:

Normalized attenuation curve k(λ), where k(5500 Å) = 1. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

Uses piecewise polynomials in \(x = 1/\lambda\) [μm⁻¹]:

\[\begin{split}k(\lambda) = \begin{cases} -5.726 + 4.004 x - 0.525 x^2 + 0.029 x^3 + R_V & 0.15 \leq \lambda < 0.60 \, \mu{\rm m} \\ -2.672 - 0.010 x + 1.532 x^2 - 0.412 x^3 - 0.0362 + R_V & 0.60 \leq \lambda \leq 2.85 \, \mu{\rm m} \end{cases}\end{split}\]

then normalized: \(k(\lambda) = k(\lambda) / R_V\) with \(R_V = 2.505\). The normalization ensures \(k(5500 \, \text{\AA}) = 1\).

The red-branch polynomial carries an additive −0.036221981 that is not in Reddy et al. (2015) Eq. 8; it makes the two published branches meet at 0.6 μm (the unmodified branches differ by 0.0362 there). FSPS dust_type=6 applies the same constant. For λ < 1500 Å, the blue branch value is held constant rather than extrapolated.

Approximation: The polynomial form is valid over 0.15–2.85 μm. Extrapolation beyond this range follows the functional form but is not empirically constrained (Reddy et al. 2015, Section 3.6.1). Below 1500 Å the curve is held at its 1500 Å value rather than extrapolated.

References

[tengri.components.dust.attenuation.reddy15-1]

N. A. Reddy, M. Kriek, A. E. Shapley, W. R. Freeman, B. Siana, A. L. Coil, B. Mobasher, S. H. Price, R. L. Sanders, and I. Shivaei, “The MOSDEF Survey: Measurements of Balmer Decrements and the Dust Attenuation Curve at Redshifts z ~ 1.4–2.6,” ApJ, 806, 259 (2015). arXiv:1504.02782. https://doi.org/10.1088/0004-637X/806/2/259

tengri.components.dust.attenuation.salim(wavelength: Array, dust_bump_strength: float = 0.0, dust_delta: float = 0.0) → Array[source]

Salim et al. (2018) modified Calzetti law (DSPS/Zacharegkas+2025 default).

Same functional form as kriek_conroy(); aliased here as the default Zacharegkas+2025 diffuse ISM attenuation law.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelengths. [Angstrom]

  • dust_bump_strength (float) – Amplitude of the 2175 Angstrom UV bump. [dimensionless]

  • dust_delta (float) – Power-law tilt relative to Calzetti slope. [dimensionless]

Returns:

Attenuation curve k(lambda) normalized to k(5500 A) = 1. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, uses only jnp primitives.

Gradient-safe: yes, differentiable everywhere.

This is the default attenuation law in DSPS and Zacharegkas+2025 simulations. It combines Calzetti et al. (2000) optical/NIR continuum with Leitherer et al. (2002) UV extension, plus a variable 2175 Å bump and power-law tilt.

tengri.components.dust.attenuation.salim_sbl18(wavelength: Array, dust_bump_strength: float = 0.0, dust_delta: float = 0.0, dust_bump_x0: float = 0.2175, dust_bump_gamma: float = 0.035) → Array[source]

Salim, Boquien & Lee (2018) modified Calzetti + L02 with UV bump + slope.

This is the SBL18 model from the dust_attenuation package. Uses Leitherer (2002) for λ < 1800 Å (0.18 µm) and Calzetti (2000) above. The modification order is: (base × power_law) + bump.

This differs from noll09 and kriek_conroy, which both apply: (base + bump) × power_law. The SBL18 order applies the power-law tilt to the base curve only, then adds the untilted UV bump.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

  • dust_bump_strength (float) – Amplitude of 2175 Å UV bump (E_b). [dimensionless] Default: 0.0 (no bump).

  • dust_delta (float) – Power-law slope modification. [dimensionless] Default: 0.0 (pure Calzetti+L02).

  • dust_bump_x0 (float) – Central wavelength of UV bump. [μm] Default: 0.2175.

  • dust_bump_gamma (float) – FWHM of UV bump. [μm] Default: 0.035.

Returns:

Normalized attenuation curve k(λ), with k(5500 Å) = 1. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, implementation is safe under jax.jit and jax.grad via tracer dispatch.

Normalization: The UV bump and tilted base are normalized by different divisors: R_V,Cal for the tilted base, and R_V,mod(δ) (Eq. 4) for the bump. This implements Salim, Boquien & Lee (2018) Eq. 3, correcting the pre-v0.12 CIGALE method described in footnote 7, which used a single fixed R_V for both terms.

The attenuation is built from Eq. 3 and Eq. 4. Eq. 3 gives k_mod before the k(5500) normalization:

\[k_{\rm mod}(\lambda) = k_{\rm L02+C00}(\lambda) \left(\frac{R_{V,\rm mod}}{R_{V,\rm Cal}}\right) \left(\frac{\lambda}{5500 \, \text{\AA}}\right)^\delta + E_b D(\lambda; \lambda_0, \gamma)\]

where the slope modification exponent is δ, and

\[R_{V,\rm mod} = \frac{R_{V,\rm Cal}}{(R_{V,\rm Cal} + 1) \left(\frac{4400}{5500}\right)^\delta - R_{V,\rm Cal}}\]

with R_V,Cal = 4.05 (Calzetti 2000). Dividing Eq. 3 by R_V,mod gives the form the code evaluates, k' = k_base * slope / R_V,Cal + bump / R_V,mod: the R_V,mod factor on the tilted base cancels, leaving R_V,Cal as its divisor, while the bump keeps R_V,mod. The result is then divided by k’(5500) so that k(5500 Å) = 1.

Validity: R_V,mod is well-defined for δ < 0.989; the denominator in Eq. 4 passes through zero near δ ≈ 0.989. The declared prior Uniform(-1.0, 0.4) is safe.

References

[tengri.components.dust.attenuation.salim_sbl18-1]

S. Salim, M. Boquien, and J. C. Lee, “Dust Attenuation Curves in the Local Universe: Demographics and New Laws for Star-forming Galaxies and High-redshift Analogs,” ApJ, 859, 11 (2018). arXiv:1804.05850. https://doi.org/10.3847/1538-4357/aabf3c

tengri.components.dust.attenuation.smc(wavelength: Array) → Array[source]

SMC Bar extinction curve (Pei 1992, ApJ, 395, 130).

Steep UV rise, NO 2175 Å bump. Common at high redshift. R_V = 2.93. Uses generalized Drude profile sum: fully continuous, no piecewise boundaries.

Parameters:

wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

Returns:

Normalized extinction curve k(λ). [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

From Pei (1992) Table 4: Small Magellanic Cloud Bar parameters, 6 Drude components with R_V = 2.93 (relatively gray).

References

P. G. Pei, “Interstellar Dust from the Ultraviolet to the Infrared,” ApJ, 395, 130 (1992).

tengri.components.dust.attenuation.tea(wavelength: Array, dust_delta: float = -0.2, dust_tea_scatter: float = 0.0) → Array[source]

TEA attenuation curve (Haskell+2024, NIHAO-SKIRT).

Three-parameter empirical attenuation with physically motivated bump-slope correlation from radiative transfer simulations. The functional form is identical to Kriek & Conroy (2013), but E_b is derived from delta via a tight relation calibrated on NIHAO-SKIRT.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

  • dust_delta (float) – Power-law slope modification. [dimensionless] Default: -0.2. Steeper (more negative) = weaker bump.

  • dust_tea_scatter (float) – Scatter in E_b around the median relation. [dex] Default: 0.0 (median).

Returns:

Attenuation curve k(λ), normalized to k(5500 Å) = 1. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

The bump amplitude is derived from the slope via:

\[E_b = 2.5 \times \exp(3.5 \times \delta) \times 10^{\text{scatter}}\]

then uses Kriek & Conroy (2013) functional form with the derived E_b.

References

[tengri.components.dust.attenuation.tea-1]

A. Haskell, C. L. Steinhardt, C. Conselice, et al., “The Evolution of the Dust Attenuation Curve with Redshift from SIMULATIONS,” arXiv:2401.11007 (2024). https://arxiv.org/abs/2401.11007

tengri.components.dust.attenuation.vw07_bc(wavelength: Array) → Array[source]

Wild+2007 birth cloud: power-law with n = -1.3 (steep UV).

Steeper than the diffuse ISM curve, reflecting the denser dust geometry around young stellar populations.

Parameters:

wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

Returns:

Normalized attenuation curve k(λ), where k(5500 Å) = 1. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

The attenuation is:

\[k(\lambda) = \left(\frac{\lambda}{5500 \, \text{\AA}}\right)^{-1.3}\]

\(n = -1.3\) is the Charlot & Fall (2000) [tengri.components.dust.attenuation.vw07_bc-2] birth-cloud slope and is a constant OF this law, not a parameter of it: the signature declares no dust_slope, so dust_attenuation={'law': 'vw07_bc', 'slope': ...} raises rather than being accepted and discarded (#2185). Use power_law, which is the same curve with the slope free.

References

[tengri.components.dust.attenuation.vw07_bc-1]

V. Wild, G. Kauffmann, T. Heckman, S. Charlot, G. Lemson, J. Brinchmann, T. Reichard, and A. Pasquali, “Bursty stellar populations and obscured active galactic nuclei in galaxy bulges,” MNRAS, 381, 543 (2007). https://doi.org/10.1111/j.1365-2966.2007.12256.x

[tengri.components.dust.attenuation.vw07_bc-2]

S. Charlot and S. M. Fall, “A Simple Model for the Absorption of Starlight by Dust in Galaxies,” ApJ, 539, 718 (2000). https://doi.org/10.1086/309250

tengri.components.dust.attenuation.vw07_diff(wavelength: Array) → Array[source]

Wild+2007 diffuse ISM: power-law with n = -0.7 (standard CF00).

Parameters:

wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

Returns:

Normalized attenuation curve k(λ), where k(5500 Å) = 1. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

The attenuation is:

\[k(\lambda) = \left(\frac{\lambda}{5500 \, \text{\AA}}\right)^{-0.7}\]

\(n = -0.7\) is the Charlot & Fall (2000) [tengri.components.dust.attenuation.vw07_diff-2] effective absorption curve and is a constant OF this law, not a parameter of it: the signature declares no dust_slope, so dust_attenuation={'law': 'vw07_diff', 'slope': ...} raises rather than being accepted and discarded (#2185). Use power_law, which is the same curve with the slope free and the same -0.7 default.

References

[tengri.components.dust.attenuation.vw07_diff-1]

V. Wild, G. Kauffmann, T. Heckman, S. Charlot, G. Lemson, J. Brinchmann, T. Reichard, and A. Pasquali, “Bursty stellar populations and obscured active galactic nuclei in galaxy bulges,” MNRAS, 381, 543 (2007). https://doi.org/10.1111/j.1365-2966.2007.12256.x

[tengri.components.dust.attenuation.vw07_diff-2]

S. Charlot and S. M. Fall, “A Simple Model for the Absorption of Starlight by Dust in Galaxies,” ApJ, 539, 718 (2000). https://doi.org/10.1086/309250

tengri.components.dust.attenuation.wd01_mwrv31(wavelength: Array) → Array[source]

Weingartner & Draine (2001) MW R_V=3.1 grain model attenuation curve.

Physically motivated dust grain-size + composition distribution for Milky Way diffuse ISM dust: prominent 2175 Å bump, R_V = 3.1.

Parameters:

wavelength (array_like, shape (n_wave,)) – Wavelength grid [Å].

Returns:

Normalized attenuation curve k(λ), k(5500 Å) = 1 [dimensionless].

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, uses jnp.interp on precomputed curve.

Upstream credit: grain model data from Weingartner & Draine (2001) [tengri.components.dust.attenuation.wd01_mwrv31-1], accessed via the dust-extinction astropy-affiliated package. Independent implementation in synthesizer (Wilkins et al. 2025 [tengri.components.dust.attenuation.wd01_mwrv31-2]).

References

[tengri.components.dust.attenuation.wd01_mwrv31-1]

J. C. Weingartner & B. T. Draine, “Dust Grain-Size Distributions and Extinction in the Milky Way, Large Magellanic Cloud, and Small Magellanic Cloud,” ApJ, 548, 296 (2001). arXiv:astro-ph/0008146. https://doi.org/10.1086/318651

[tengri.components.dust.attenuation.wd01_mwrv31-2]

C. C. Lovell et al. 2025, Open J. Astrophys. 8, “Synthesizer: a Software Package for Synthetic Astronomical Observables,” doi:10.33232/001c.145766; W. J. Roper et al. 2026, JOSS 11, 9436, doi:10.21105/joss.09436 (cite both Synthesizer papers).

tengri.components.dust.attenuation.wd01_smcbar(wavelength: Array) → Array[source]

Weingartner & Draine (2001) SMC Bar grain model attenuation curve.

Physically motivated dust grain-size + composition distribution for SMC-like dust: steep UV rise, no 2175 Å bump. Most relevant for high-redshift galaxies.

Parameters:

wavelength (array_like, shape (n_wave,)) – Wavelength grid [Å].

Returns:

Normalized attenuation curve k(λ), k(5500 Å) = 1 [dimensionless].

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, uses jnp.interp on precomputed curve.

Precomputed from dust_extinction.grain_models.WD01("SMCBar") at module import time. Data cover ~100–107 Å. Values outside the tabulated range are held constant at boundary values.

Upstream credit: grain model data from Weingartner & Draine (2001) [tengri.components.dust.attenuation.wd01_smcbar-1], accessed via the dust-extinction astropy-affiliated package. Independent implementation in synthesizer (Wilkins et al. 2025 [tengri.components.dust.attenuation.wd01_smcbar-2]).

References

[tengri.components.dust.attenuation.wd01_smcbar-1]

J. C. Weingartner & B. T. Draine, “Dust Grain-Size Distributions and Extinction in the Milky Way, Large Magellanic Cloud, and Small Magellanic Cloud,” ApJ, 548, 296 (2001). arXiv:astro-ph/0008146. https://doi.org/10.1086/318651

[tengri.components.dust.attenuation.wd01_smcbar-2]

C. C. Lovell et al. 2025, Open J. Astrophys. 8, “Synthesizer: a Software Package for Synthetic Astronomical Observables,” doi:10.33232/001c.145766; W. J. Roper et al. 2026, JOSS 11, 9436, doi:10.21105/joss.09436 (cite both Synthesizer papers).

tengri.components.dust.attenuation.wg00_cloudy(wavelength: Array, tau_v: float, law: str = 'cardelli', **law_params) → Array[source]

Witt & Gordon (2000) CLOUDY dust geometry: homogeneous dust-star mix.

Stars and dust are uniformly mixed throughout a slab of total V-band optical depth. The analytic solution integrates radiative transfer, producing a wavelength-dependent transmission that is grayer (less wavelength-dependent) than a foreground screen. Realistic for galaxies with well-mixed ISM (e.g., starburst regions).

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

  • tau_v (float) – Total V-band optical depth through the slab. [dimensionless]

  • law (str, optional) – Underlying attenuation curve name, from DUST_LAWS registry. Default: “cardelli” (MW).

  • **law_params – Keyword arguments passed to the attenuation curve function (e.g., dust_Rv).

Returns:

Transmission T(λ) ∈ [0, 1]. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives, with numerically stable Taylor expansion for small optical depth.

Gradient-safe: yes, differentiable everywhere via smooth blending between exact and Taylor regimes.

The transmission for a homogeneous slab is:

\[T(\lambda) = \frac{1 - \exp[-\tau_V \, k(\lambda)]}{\tau_V \, k(\lambda)}\]

where \(k(\lambda)\) is the normalized attenuation curve. This follows the solution of radiative transfer in a uniform dust-star slab (Natta & Panagia 1984, Section 3.1; Calzetti et al. 1994).

Limiting behavior: At low optical depth (\(\tau_V k \ll 1\)), \(T \to 1\) (transparent). At high optical depth, \(T \approx 1/(\tau_V k)\), producing a grayer (less wavelength-dependent) effective attenuation than the foreground screen because stars near the observer-facing side suffer less extinction.

Numerical stability: Uses a Taylor expansion (correct to order \(\tau^3\)) for \(\tau_V k < 10^{-4}\) to avoid division-by-zero, preserving gradients throughout.

Approximation: The analytic solution assumes pure absorption (zero scattering). Witt & Gordon (2000) Monte Carlo simulations including scattering find the effective attenuation is slightly grayer still. The analytic form captures the dominant geometric effect and is widely used in SED fitting codes (e.g., Synthesizer, CIGALE).

References

[tengri.components.dust.attenuation.wg00_cloudy-1]

A. Natta and N. Panagia, “Extinction in inhomogeneous clouds,” ApJ, 287, 228 (1984). https://doi.org/10.1086/162686

[tengri.components.dust.attenuation.wg00_cloudy-2]

D. Calzetti, A. L. Kinney, and T. Storchi-Bergmann, “Dust Extinction of the Stellar Continua in Starburst Galaxies: The Ultraviolet and Optical Extinction Law,” ApJ, 429, 582 (1994). https://doi.org/10.1086/174348

[tengri.components.dust.attenuation.wg00_cloudy-3]

A. N. Witt and K. D. Gordon, “Multiple Scattering in Clumpy Media. II. Galactic Environments,” ApJ, 528, 799 (2000). Section 3.2, “homogeneous” model. https://doi.org/10.1086/308197

tengri.components.dust.attenuation.wg00_dusty(wavelength: Array, tau_v: float, law: str = 'cardelli', n_clumps: float = 10.0, **law_params) → Array[source]

Witt & Gordon (2000) DUSTY geometry: clumpy two-phase medium.

The ISM is modeled as n_clumps identical clumps, each with optical depth tau_clump = tau_V / n_clumps, distributed along random sightlines (Natta & Panagia 1984; Hobson & Padman 1993). The probability of a photon traversing N clumps follows a Poisson distribution, giving the mean transmission.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

  • tau_v (float) – Total V-band optical depth (= n_clumps × tau_clump). [dimensionless]

  • law (str) – Underlying extinction curve name. Default: “cardelli” (MW).

  • n_clumps (float) – Mean number of clumps along a sightline. [dimensionless] Default: 10.0. Higher values approach the homogeneous limit. Typical range: 1–40.

  • **law_params – Passed to the extinction curve function (e.g., dust_Rv).

Returns:

Transmission T(λ) in [0, 1]. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

Gradient-safe: yes, differentiable everywhere.

The transmission is:

\[T(\lambda) = \exp[-n_{\rm clumps} (1 - \exp[-\tau_{\rm clump} \, k(\lambda)])]\]

where \(\tau_{\rm clump} = \tau_V / n_{\rm clumps}\).

This produces the grayest (least wavelength-dependent) effective attenuation of the three WG00 geometries because photons preferentially escape through low-column channels between clumps.

Limiting behavior:

  • \(n_{\rm clumps} \to \infty\) (fixed \(\tau_V\)): recovers the homogeneous slab.

  • \(n_{\rm clumps} = 1\): single clump with Poisson averaging.

  • \(\tau_V = 0\): T = 1 (transparent), regardless of n_clumps.

References

[tengri.components.dust.attenuation.wg00_dusty-1]

A. Natta and N. Panagia, “Extinction in Inhomogeneous Clouds,” ApJ, 287, 228 (1984). https://doi.org/10.1086/162686

[tengri.components.dust.attenuation.wg00_dusty-2]

M. P. Hobson and L. Padman, “A Probabilistic Approach to Extinction in Irregular Media,” MNRAS, 264, 161 (1993). https://doi.org/10.1093/mnras/264.1.161

[tengri.components.dust.attenuation.wg00_dusty-3]

A. N. Witt and K. D. Gordon, “Multiple Scattering in Clumpy Media. I. Point Source Embedded in a Clumpy Medium,” ApJ, 528, 799 (2000). https://doi.org/10.1086/308197

tengri.components.dust.attenuation.wg00_shell(wavelength: Array, tau_v: float, law: str = 'cardelli', **law_params) → Array[source]

Witt & Gordon (2000) SHELL geometry: foreground screen.

The simplest geometry: a uniform dust slab in front of all stars. Transmission is the standard Beer-Lambert law.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Wavelength grid. [Å]

  • tau_v (float) – V-band optical depth (at 5500 Å). [dimensionless]

  • law (str) – Underlying extinction curve name. Default: “cardelli” (MW).

  • **law_params – Passed to the extinction curve function (e.g., dust_Rv).

Returns:

Transmission T(λ) in [0, 1]. [dimensionless]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives.

Gradient-safe: yes, differentiable everywhere.

The transmission is:

\[T(\lambda) = \exp[-\tau_V k(\lambda)]\]

This is identical to single_component_dust with f_obscuration=0 and is included for completeness alongside the CLOUDY and DUSTY models.

References

[tengri.components.dust.attenuation.wg00_shell-1]

A. N. Witt and K. D. Gordon, “Multiple Scattering in Clumpy Media. I. Point Source Embedded in a Clumpy Medium,” ApJ, 528, 799 (2000). https://doi.org/10.1086/308197

Dust emission

Energy-balanced IR dust emission models.

Dust emission package.

Transitional layout (ADR-0019): the historical emission.py module now lives at emission/emission.py so the analytic/ subpackage can host the SEDModelComponents. This __init__ preserves the full public + used surface of the old flat module, so every existing from tengri.components.dust.emission import X keeps working unchanged (the closures, registries, and template loaders).

The grain-physics templates behind the library-backed emission models are loaded from bundled data files.

tengri.load_astrodust_hd23(template_path: str | None = None) → AstrodustHD23Templates[source]

Load the Hensley & Draine 2023 Astrodust+PAH emission grid.

Public entry point for the bundled Astrodust+PAH templates: emission (\(L_\nu\) per H for total / astrodust / PAH / spinning-dust components), extinction / scattering / polarization per H, and the fiducial grain size_distribution. Use it instead of opening data/astrodust_templates.h5 by hand.

Parameters:

template_path (str or None, optional) – Override the grid location. When None (default), resolves the ASTRODUST_HD23_PATH_ENV env var, then the bundled ASTRODUST_HD23_DEFAULT_PATH (data/astrodust_templates.h5).

Returns:

Frozen container of JAX arrays (see the class for the full field list).

Return type:

AstrodustHD23Templates

Raises:

FileNotFoundError – When the resolved path does not exist on disk.

Notes

JIT-compatible: no, file I/O. Call once at setup, then pass the returned arrays into JIT-compiled code.

References

[tengri.load_astrodust_hd23-1]

Hensley, B. S. & Draine, B. T. 2023, ApJ, 948, 55. The Astrodust+PAH Model. arXiv:2208.12365. doi:10.7910/DVN/3B6E6S.

Examples

>>> import tengri
>>> tpl = tengri.load_astrodust_hd23()
>>> tpl.wavelength_um.shape
(...,)
tengri.load_pahspec_draine2021(template_path: str | None = None) → Draine2021PAHTemplates[source]

Load the Draine 2021 PAH emission-spectrum templates.

Public entry point for the bundled Draine (2021) PAHspec grid. Use it instead of opening data/pahspec_draine2021.h5 by hand; pair it with select_pahspec_axes() to pick a (starlight, ionization, size-distribution, slab) slice.

Parameters:

template_path (str or None, optional) – Override the grid location. When None (default), resolves the PAHSPEC_PATH_ENV env var, then the bundled DRAINE2021_PAH_DEFAULT_PATH (data/pahspec_draine2021.h5).

Returns:

Frozen container of JAX arrays.

Return type:

Draine2021PAHTemplates

Raises:

FileNotFoundError – When the resolved path does not exist on disk.

Notes

JIT-compatible: no, file I/O. Call once at setup.

References

[tengri.load_pahspec_draine2021-1]

Draine, B. T., et al. 2021, ApJ, 917, 3. Excitation of Polycyclic Aromatic Hydrocarbon Emission. arXiv:2106.07415.

Dust priors

Redshift-dependent attenuation priors from cosmological simulations.

Redshift-dependent dust attenuation priors from Narayanan+2018.

Narayanan, Conroy, Davé, Johnson & Popping (2018) post-process the 25 Mpc MUFASA cosmological hydrodynamic simulation with dust radiative transfer and publish a median attenuation curve at each integer redshift 0 to 6. Their Section 5.1 reports two trends across that range:

  • the median curves become grayer with redshift (the slope grows less negative);

  • the 2175 Å bump weakens with redshift.

narayanan_prior() centers Gaussians on those published medians, so a fit that frees kriek_conroy()’s slope and bump starts where the simulation says a galaxy at that redshift sits. The centers come from the same fitted table narayanan_z() interpolates, produced by scripts/fit_narayanan2018_medians.py; there is one source, not two.

These functions return dicts of Gaussian distributions suitable for direct use in Parameters kwargs.

References

  1. Narayanan, C. Conroy, R. Davé, B. D. Johnson and G. Popping (2018).

    “A Theory for the Variation of Dust Attenuation Laws in Galaxies”, ApJ, 869, 70. arXiv:1805.06905. https://doi.org/10.3847/1538-4357/aaed25 Median curves: https://bitbucket.org/desika/narayanan_attenuation_laws/

tengri.components.dust.priors.narayanan_prior(z: float) → dict[source]

Kriek & Conroy slope and bump priors centered on the MUFASA median at z.

Both keys are kriek_conroy() parameters: dust_delta is its power-law slope and dust_bump_strength the multiplier on its Drude amplitude \(E_b = 0.85 - 1.9\,\delta\). The Gaussian centers are the published Narayanan et al. (2018) medians at z, linearly interpolated between the integer nodes and held at the end node outside 0 to 6.

Parameters:

z (float) – Source redshift [dimensionless]. Values outside 0 to 6 take the end node; the paper tabulates no median beyond that range.

Returns:

Keys "dust_delta" and "dust_bump_strength", each mapping to a Gaussian distribution [dimensionless]. Suitable for direct use in Parameters(..., **narayanan_prior(z)). dust_bump_strength is truncated at zero (lo=0.0) – it declares a bound_check requiring non-negative bounds, so an unbounded prior fails at construction (#2226). dust_delta has no such constraint (its fitted means straddle zero) and stays a plain, unbounded Gaussian.

Return type:

dict

Examples

>>> from tengri import Parameters
>>> from tengri.components.dust.priors import narayanan_prior
>>> spec = Parameters(
...     mean_sfh_type="dpl",
...     dust_model="single_component",
...     dust_law_bc="kriek_conroy",
...     redshift=2.0,
...     **narayanan_prior(z=2.0),
... )

Notes

JIT-compatible: no, prior specification is a factory-time operation.

Gradient-safe: no, returns static prior distributions.

The centers move with redshift the way the paper’s Section 5.1 says: the slope grows less negative (the curve gets grayer), from -0.556 at z = 0 to +0.080 at z = 6, and the implied bump amplitude weakens, from \(E_b\) = 6.36 to 1.96. Before #2199 this function centered dust_delta on -0.2 - 0.1 z, which steepened with redshift, and dust_bump_strength on max(0, 1 - 0.15 z); neither closed form appears in the paper and the slope one had the reported trend backwards.

Use these with law='kriek_conroy'. Pairing them with law='narayanan_z' is not possible and not needed: that law reads no slope or bump at all, because it is the median curve at z.

The widths (0.15 in \(\delta\), 0.3 in the bump multiplier) are unchanged from before #2199 and are not from the paper, which publishes a median curve rather than a dispersion in these two parameters. They are deliberately narrower than the curve-to-curve scatter the paper describes; widen them for a fit meant to explore it.

References

[tengri.components.dust.priors.narayanan_prior-1]

D. Narayanan, C. Conroy, R. Davé, B. D. Johnson and G. Popping, “A Theory for the Variation of Dust Attenuation Laws in Galaxies,” ApJ, 869, 70 (2018). arXiv:1805.06905. https://doi.org/10.3847/1538-4357/aaed25 Median curves: https://bitbucket.org/desika/narayanan_attenuation_laws/

tengri.components.dust.priors.narayanan_tau_prior(z: float, log_mstar: float = 10.0) → dict[source]

Recommended dust optical depth prior based on Narayanan+2018 scaling.

The diffuse-ISM optical depth tau_diff scales with stellar mass and redshift, reflecting the higher dust content in massive, high-z galaxies.

Parameters:
  • z (float) – Source redshift [dimensionless].

  • log_mstar (float, optional) – log₁₀(M_star / M_sun) [dimensionless]. Default: 10.0.

Returns:

Key "dust_tau_diff" mapping to a Gaussian distribution [dimensionless]. Suitable for direct use in Parameters(..., **narayanan_tau_prior(z, log_mstar)). The distribution is truncated at zero (lo=0.0) – dust_tau_diff declares a bound_check requiring non-negative bounds, so an unbounded prior fails at construction (#2226).

Return type:

dict

Examples

>>> from tengri import Parameters
>>> from tengri.components.dust.priors import narayanan_tau_prior
>>> spec = Parameters(
...     mean_sfh_type="dpl",
...     redshift=1.5,
...     **narayanan_tau_prior(z=1.5, log_mstar=10.5),
... )

Notes

JIT-compatible: no, prior specification is a factory-time operation.

Gradient-safe: no, returns static prior distributions.

Unverified scaling. Unlike narayanan_prior(), whose centers are the paper’s own published median curves, the \(\tau \propto M_*^{1/2}(1+z)^{1/2}\) form here matches no equation in Narayanan et al. (2018), which publishes attenuation curve shapes and not an optical-depth scaling. Treat it as a rough starting point, not a result; it is left as it was because #2199 fixed the curve shape and found no published number to replace this with.

AGN

Accretion disc, torus, BLR, NLR, and unified AGN models.

Accretion disc models for AGN emission.

Four models are provided:

  1. Simple power-law + UV cutoff: minimal AGN disc with 3 parameters.

  2. Multi-color disc (Shakura-Sunyaev): physically-motivated standard thin disc following Kubota & Done (2018), simplified to the key parameters. Implements the outer standard disc zone only.

  3. Kubota & Done 3-zone disc: full K&D (2018) model with outer standard disc, warm Comptonization (soft X-ray excess), and hot corona (hard X-ray power law). Three radially-stratified zones with self-consistent radii.

  4. ADAF + truncated disc, for low-luminosity AGN (L/L_Edd < 0.01). The inner disc transitions to an advection-dominated accretion flow (optically thin, radiatively inefficient). Based on Mahadevan (1997) and Nemmen+2014.

All return specific luminosity L_nu in erg/s/Hz as a function of rest-frame wavelength. All functions are pure JAX and JIT-compilable.

Physical constants are in CGS. Wavelength inputs are in Angstrom.

References

  • Shakura & Sunyaev 1973, A&A, 24, 337

  • Kubota & Done 2018, MNRAS, 480, 1247

  • Nandra & Pounds 1994, MNRAS, 268, 405 (power-law slopes)

  • Done et al. 2012, MNRAS, 420, 1848 (QSOSED)

  • Mahadevan 1997, ApJ, 477, 585 (ADAF spectra)

  • Nemmen et al. 2014, MNRAS, 438, 2804 (ADAF modeling)

  • Lopez et al. 2024 (ADAF + truncated disc for LLAGN)

  • Beloborodov 1999, ApJ, 510, L123 (self-consistent Gamma_hot)

tengri.components.agn.disc.adaf_disc(wavelength, agn_log_lbol, agn_lum_ratio=1.0, agn_log_mbh=7.0, agn_adaf_beta=0.5, agn_adaf_delta=0.1, agn_adaf_alpha=0.3, **_legacy_kwargs)[source]

DEPRECATED thin alias for the faithful Mahadevan 1997 ADAF (#898).

The old adaf_disc (which misapplied Eq. 49 and bundled an ad-hoc truncated outer disc) was removed; this delegates to adaf_spectrum(). The retired arguments agn_log_ledd / agn_r_tr / agn_cos_inc are accepted for backward compatibility but ignored (mdot is now derived from agn_log_lbol). New code should call adaf_spectrum directly. Slated for removal once its remaining callers/tests migrate (see #898 follow-up).

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength [Angstrom].

  • agn_log_lbol (float) – log10 of bolometric luminosity [Lsun].

  • agn_lum_ratio – Forwarded to adaf_spectrum() (see there).

  • agn_log_mbh – Forwarded to adaf_spectrum() (see there).

  • agn_adaf_beta – Forwarded to adaf_spectrum() (see there).

  • agn_adaf_delta – Forwarded to adaf_spectrum() (see there).

  • agn_adaf_alpha – Forwarded to adaf_spectrum() (see there).

Returns:

L_nu [erg/s/Hz], the faithful Mahadevan 1997 ADAF.

Return type:

ndarray, shape (n_wave,)

tengri.components.agn.disc.beloborodov_gamma_hot(l_diss_hot: float, l_seed: float) → float[source]

Self-consistent hard X-ray photon index (Beloborodov 1999).

Derives the spectral index of the hot corona from the ratio of dissipated luminosity to seed photon luminosity.

Kubota & Done (2018, MNRAS 480 1247) Eq. 6 rewrites the Beloborodov (1999, ApJ 510 L123) Compton-amplification result as:

Gamma_hot = (7/3) * (L_diss / L_seed)^{-0.1}

The exponent -0.1 is the K&D 2018 formulation of Beloborodov (1999).

Parameters:
  • l_diss_hot (float) – Luminosity dissipated in the hot corona [any units].

  • l_seed (float) – Soft photon luminosity intercepted by the corona [same units].

Returns:

Hard X-ray photon index, clipped to [1.4, 3.0].

Return type:

float

Notes

JIT-compatible: yes, uses only jnp primitives.

This implementation follows Kubota & Done (2018, MNRAS 480 1247, Eq. 6), which rewrites the Beloborodov (1999) Compton-amplification result as a power law in the luminosity ratio. The exponent -0.1 encodes the energy-balance relation between the dissipated power in the corona and the seed photon luminosity intercepted from the disc. Output is clipped to [1.4, 3.0] to match the physical range of typical AGN.

References

[tengri.components.agn.disc.beloborodov_gamma_hot-1]

A. M. Beloborodov, “Plasma Ejection from Magnetic Flares and the X-Ray Spectrum of Cygnus X-1,” ApJL, 510, L123 (1999). arXiv:astro-ph/9809383. https://doi.org/10.1086/311810

[tengri.components.agn.disc.beloborodov_gamma_hot-2]

A. Kubota and C. Done, “A physical model of the broad-band continuum of AGN and its implications for the UV/X relation and optical variability,” MNRAS, 480, 1247 (2018). arXiv:1804.00171. https://doi.org/10.1093/mnras/sty1890

tengri.components.agn.disc.compute_l2500(wavelength: Array, l_nu: Array) → float[source]

Extract monochromatic luminosity at rest-frame 2500 Angstrom.

Linearly interpolates L_nu onto 2500 A. Useful for computing alpha_ox and other AGN diagnostics.

Parameters:
  • wavelength (array, shape (n_wave,)) – Rest-frame wavelength [Angstrom], need not be sorted.

  • l_nu (array, shape (n_wave,)) – Specific luminosity [erg s^-1 Hz^-1].

Returns:

L_nu at 2500 A [erg s^-1 Hz^-1].

Return type:

float

Notes

JIT-compatible: yes, uses jnp primitives.

The 2500 Å point is a canonical AGN diagnostic wavelength, used to compute the optical-to-X-ray spectral index (alpha_ox) and as a benchmark for intrinsic AGN continuum comparisons. Linear interpolation in wavelength space is sufficient for the optical/UV continuum variability timescales. The wavelength array need not be pre-sorted; this function sorts internally before interpolation.

tengri.components.agn.disc.create_relagn_disc_from_grid(grid_path: str) → Callable[source]

Return a JIT-compatible RELAGN disc SED function from a precomputed grid.

The grid was built with the real RELAGN Python class (Hagen & Done 2023) using KYCONV (Dovciak, Karas & Yaqoob 2004) per-annulus Kerr ray-tracing. It stores the outer disc alone (no warm zone, no corona) as absolute L_ν (erg/s/Hz) at cos_inc = 0.5; the inclination correction is applied analytically as 2·cos_inc (valid for the non-relativistic outer disc; approximate for the GR inner disc).

Parameters:

grid_path (str) – Path to data/relagn_disc_grid.h5.

Returns:

Function with signature:

fn(wavelength, agn_log_mbh, agn_log_mdot, agn_astar,
   agn_cos_inc, **kwargs) -> L_nu [erg s^-1 Hz^-1]

Return type:

callable

Raises:

FileNotFoundError – If grid_path does not exist.

Notes

JIT-compatible: yes, the returned function is pure JAX. Grid loading is cached via @functools.cache.

Gradient-safe: yes, triweight interpolation is C²-continuous.

Inclination: grid stored at cos_inc = 0.5, where the line-of-sight power equals the angle-integrated power; scaled by 2·cos_inc. This is exact for r > 1000 r_g (non-relativistic regime) and approximate for the GR inner disc where KYCONV applies full Kerr ray-tracing.

Grid axes: log_mbh ∈ [7, 10], log_mdot ∈ [−1.5, 0.3], astar ∈ [0, 0.998] (prograde only; KYCONV rejects retrograde spins).

References

[tengri.components.agn.disc.create_relagn_disc_from_grid-1]

Dovciak, M., Karas, V., & Yaqoob, T. (2004). ApJS, 153, 205. doi:10.1086/421115

[tengri.components.agn.disc.create_relagn_disc_from_grid-2]

Hagen, S. & Done, C. (2023). MNRAS, 525, 3455-3467. doi:10.1093/mnras/stad2499

tengri.components.agn.disc.kubota_done_disc(wavelength: Array, agn_log_lbol: float, agn_lum_ratio: float = 1.0, agn_log_mbh: float = 7.0, agn_log_ledd: float = -1.0, agn_a_spin: float = 0.0, agn_cos_inc: float = 0.8660254037844386, agn_f_hard: float = 0.02, agn_gamma_warm: float = 2.5, agn_kt_warm: float = 0.2, agn_gamma_hard: float = 1.8, agn_kt_hot: float = 100.0, agn_r_warm_ratio: float = 2.0, n_radii: int = 50, agn_self_consistent_gamma: bool = False, agn_log_lbol_shape: float | None = None, _template=None, _return_parts: bool = False, **_kwargs) → Array[source]

Kubota & Done (2018) three-zone accretion disc with self-consistent corona.

Model a physically stratified AGN accretion disc as three radially distinct zones, each with different physics and electron temperatures. This is the reference model for intermediate to high accretion rates and is used in tengri’s default AGN configuration.

The three zones share a single Novikov-Thorne temperature profile but have different radiation mechanisms:

  1. Outer standard disc (r > R_warm): Optically thick, geometrically thin. Temperature decreases with radius (∝ r^{-3/4}). Radiates as multi-color blackbody. Dominates the optical/UV “big blue bump.”

  2. Warm Comptonization zone (R_hot < r < R_warm): Optically thick, warm electrons (kT_e ~ 0.2 keV, τ ~ 10-20). Inverse Compton-scattered disc photons plus thermal radiation. Produces the soft X-ray excess. Computed via precomputed nthcomp Kompaneets templates (when available) or a simplified modified-blackbody proxy.

  3. Hot corona (R_ISCO < r < R_hot): Optically thin, hot electrons (kT_e ~ 100 keV, τ ~ 1). Inverse Compton scatters disc seed photons to produce hard X-ray power-law spectrum with exponential cutoff.

Zone boundaries are determined self-consistently:

  • R_hot: Solved via bisection from the energy-balance constraint that the dissipated power in the corona equals f_hard × L_Edd. Uses the Page-Thorne dissipation integral (Eq. 2), spin included.

  • R_warm: Parameterized as a multiple of R_hot (default 2, per K&D).

  • R_out: Set to the Laor & Netzer (1989) self-gravity (Toomre) radius, beyond which the disc becomes unstable and fragments.

The radii obey \(R_{\rm ISCO} < R_{\rm hot} \le R_{\rm out}\) and \(R_{\rm hot} < R_{\rm warm} \le R_{\rm out}\). Where the disc cannot dissipate \(f_{\rm hard} L_{\rm Edd}\) inside \(R_{\rm out}\), \(R_{\rm hot} = R_{\rm out}\) and the whole flow is hot, as in the RELQSO source of Hagen & Done (see _clip_zone_radii()). The corona power then saturates at the disc’s dissipation inside \(R_{\rm out}\), which gives a slope change in \(L_{\rm hot}\) at \(f_{\rm hard}/\lambda_{\rm Edd} = h(R_{\rm out}/R_{\rm ISCO})/h(\infty)\) (about 0.93); the steep optical disc share just above that point is the corona taking most of \(L_{\rm bol}\).

Emission per zone (no rescale, #3015). Each zone emits its own Page-Thorne dissipation (Kubota & Done 2018, Sec. 2.2): the corona \(L_{\rm hot}\), the warm zone and the outer disc \(L_0\,[h(x_{\rm out}) - h(x_{\rm hot})]\), with \(x = R/R_{\rm ISCO}\) and \(L_0 h(\infty) = L_{\rm bol}\). Their sum is \(L_{\rm bol}\) less the unemitted share

\[L_{\rm unemitted} = L_0\,[h(\infty) - h(x_{\rm out})] = L_{\rm bol}\,\frac{h(\infty) - h(R_{\rm out}/R_{\rm ISCO})}{h(\infty)},\]

the dissipation the disc would have beyond its self-gravity radius, which K&D do not emit. It is published as log_L_agn_disc_unemitted (kubota_done_unemitted_fraction()).

Validity domain. The three-zone geometry of Kubota & Done (2018) applies for \(\lambda_{\rm Edd}\) above about \(f_{\rm hard}\) (~0.02), where the disc can dissipate \(f_{\rm hard} L_{\rm Edd}\) inside \(R_{\rm out}\). Below it the disc truncates: there are no disc or warm zones, as in RELQSO, and the hot flow is modeled as radiatively efficient Comptonization of all the dissipation inside \(R_{\rm out}\) (K&D 2018 do not model radiative inefficiency). For that regime disc='adaf' is the radiatively inefficient alternative. No warning is issued.

The hard X-ray photon index Γ_hot is derived self-consistently from the Beloborodov (1999) energy-balance relation if requested; otherwise uses the input value.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength grid. [Angstrom]

  • agn_log_lbol (float) – Accretion power of all three zones, integrated over all directions (both faces of the disc); independent of the inclination. The line-of-sight luminosity is \(\int L_\nu(i)\,d\nu\), a derived quantity. [log10(L_sun)]

  • agn_lum_ratio (float, optional) – Fraction of the accretion power emitted by the disc system (all zones). Default: 1.0. [dimensionless, 0–1]

  • agn_log_mbh (float, optional) – Black hole mass. Determines the Eddington luminosity and temperature scaling. Default: 8.0. [log10(M_sun)]

  • agn_log_ledd (float, optional) – DEPRECATED / IGNORED (#846). The Eddington ratio, and hence the inner temperature, accretion rate, and zone radii: is now DERIVED from agn_log_lbol and agn_log_mbh (lambda_Edd = L_bol / L_Edd), so the 3-zone structure is self-consistent with the requested L_bol. Retained for backward compatibility but has no effect; setting or freeing it emits a build-time warning. Default: -1.0.

  • agn_a_spin (float, optional) – Dimensionless black hole spin parameter (Kerr, prograde). Range: [0, 0.998]. Higher spin → smaller R_ISCO, higher η. Default: 0.0 (Schwarzschild). [dimensionless]

  • agn_cos_inc (float, optional) – Cosine of the inclination angle between the disc normal and the line of sight. Range: [0, 1]. The disc and warm zones radiate \(\propto\cos i\) (Kubota & Done 2018, Sect. 2.1) and the returned spectrum is \(L_\nu(i) = 2\cos i\,D_\nu + H_\nu\), with \(D_\nu\) the angle-integrated spectrum of the disc and warm zones and \(H_\nu\) that of the isotropic corona (Sect. 2.2). The zone radii, temperatures and \(\dot m\) do not depend on it. Default: 0.866 (30°). [dimensionless]

  • agn_f_hard (float, optional) – Fraction of Eddington luminosity dissipated in the hot corona. Controls the corona zone extent R_hot. Typical range: 0.01–0.1. Default: 0.02. [dimensionless, 0–0.5]

  • agn_gamma_warm (float, optional) – Photon index of the warm Comptonization zone (nthcomp). Range: ~1.5–3.5. Default: 2.5. [dimensionless]

  • agn_kt_warm (float, optional) – Electron temperature in the warm Comptonization zone. Default: 0.2. [keV]

  • agn_gamma_hard (float, optional) – Photon index of the hard X-ray power law (hot corona). Typical range: 1.5–2.5. Default: 1.8. Ignored if agn_self_consistent_gamma=True. [dimensionless]

  • agn_kt_hot (float, optional) – Electron temperature in the hot corona. Default: 100.0. [keV]

  • agn_r_warm_ratio (float, optional) – Radius ratio R_warm / R_hot. Controls the warm zone extent. Default: 2.0 (per K&D 2018). [dimensionless, ≥ 1.1]

  • n_radii (int, optional) – Number of radial integration points per zone. Default: 50. Higher values increase accuracy at computational cost.

  • agn_self_consistent_gamma (bool, optional) – If True, compute agn_gamma_hard self-consistently from the Beloborodov (1999) energy-balance relation: Γ = 7/3 × (L_diss / L_seed)^{-0.1} If False, use the input agn_gamma_hard value. Default: False.

Returns:

Spectral luminosity density L_ν. [erg/s/Hz]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, uses jnp primitives and jax.vmap.

Gradient-safe: yes, fully differentiable w.r.t. all parameters, including the bisection-solved R_hot.

Key self-consistent physics:

All three zones share the relativistic Page & Thorne (1974) thin-disc temperature profile (as K&D 2018 and QSOSED/RELQSO; tengri.components.agn._nt_emissivity):

\[T(r) = T_{\rm in} \left(\frac{r}{r_{\rm ISCO}}\right)^{-3/4} R_t(r; a)^{1/4}\]

with \(R_t = C/B \to 0\) at the ISCO and \(\to 1\) far out (the Newtonian zero-torque form \(1-\sqrt{r_{\rm ISCO}/r}\) dissipates 1.46 \(L_{\rm bol}\) at a=0 instead of 1.02).

where \(T_{\rm in} = (3 G M M_{\rm dot} / 8\pi \sigma_{\rm SB} r_{\rm ISCO}^3)^{1/4}\), and the inner temperature increases with accretion rate. The radii are ordered as R_ISCO < R_hot < R_warm < R_out.

Zone luminosity computation:

Each zone is divided into annuli at radii {r_i}, each of which contributes L_ν from its local Planck function (outer disc), nthcomp prescription (warm zone), or hot-corona power law (inner zone). All zones are summed and renormalized so that \(\int (D_\nu + H_\nu)\,d\nu\) equals the accretion power.

Inclination and energy (K&D 2018, Sects. 2.1 and 2.2): the disc and warm zones are optically thick and radiate \(\propto\cos i\); the corona is optically thin and isotropic. With \(D_\nu\) the angle-integrated (two-face) spectrum of the disc and warm zones and \(H_\nu\) that of the corona, the model returns

\[L_\nu(i) = 2\cos i\, D_\nu + H_\nu , \qquad \int (D_\nu + H_\nu)\,d\nu = L_{\rm acc} = 10^{\mathtt{agn\_log\_lbol}} L_\odot ,\]

the luminosity density an observer at inclination \(i\) assigns assuming isotropy (AGNSED’s \(\cos i / 0.5\)). The mean of \(\int L_\nu(i)\,d\nu\) over \(\cos i \in [0, 1]\) is \(L_{\rm acc}\), and at \(\cos i = 0.5\) the line-of-sight power equals it; face-on the disc is twice as luminous. The corona’s power \(H\) is the hot-flow dissipation \(f_{\rm hard} L_{\rm Edd}\) (the Page-Thorne dissipation inside \(R_{\rm hot}\)), and \(D\) is the dissipation of the thin disc outside it, so the split follows K&D’s energy budget. The shape quantities (\(\dot m\), \(T(r)\), \(R_{\rm hot}\), \(R_{\rm warm}\)) follow from \(L_{\rm acc}\) and do not depend on \(i\).

Seed photon calculation (K&D 2018 Eq. 3): The hot corona inverse-Compton scatters disc seed photons. The seed photon luminosity is computed from the geometric integral of the warm-zone blackbody flux intercepted by the corona geometry:

\[L_{\rm seed} = 2 \int_{R_{\rm hot}}^{R_{\rm out}} F_{\rm NT}(r) \cdot \frac{\Theta(r)}{\pi} \cdot 2\pi r \, dr\]

where \(\Theta(r) = \theta_0 - \sin(2\theta_0)/2\) and \(\sin\theta_0 = R_{\rm hot}/r\). This drives the self-consistent Γ_hot via Beloborodov.

Precomputed nthcomp templates: For maximum speed and accuracy, the warm Comptonization is computed via interpolation in precomputed nthcomp Kompaneets templates (see scripts/build_nthcomp_templates.py). These templates span (Γ_warm, kT_e) parameter space and return (Γ_warm, kT_e, normalization)-dependent SED at each radius. If templates are unavailable, a simplified modified-blackbody proxy is used, which has ~5–10% shape error but allows offline computation.

Approximations and accuracy:

The reference QSOSED/RELAGN codes use non-differentiable operations (root solvers, C implementations). Tengri’s JAX reimplementation makes key approximations documented in the code (see docs/dev/archive/design/agn_kd_model.md):

  • R_hot: 40-step JAX-compatible bisection (exact to ~10^{-12}).

  • Warm zone: precomputed nthcomp templates with (Γ_w, kT_e) interpolation (accuracy: ≲ 2% in flux density).

  • Seed photons: K&D Eq. 3 integrated on 100-point log grid (exact).

  • Outer radius: Laor & Netzer self-gravity radius (2–4× improvement over fixed 1000 r_ISCO).

References

[tengri.components.agn.disc.kubota_done_disc-1]

A. Kubota and C. Done, “A physical model of the broad-band continuum of AGN and its implications for the UV/X relation and optical variability,” MNRAS, 480, 1247 (2018). arXiv:1804.00171. https://doi.org/10.1093/mnras/sty1890

[tengri.components.agn.disc.kubota_done_disc-2]

C. Done et al., “Intrinsic disc emission and the soft X-ray excess in active galactic nuclei,” MNRAS, 420, 1848 (2012). arXiv:1107.5429. https://doi.org/10.1111/j.1365-2966.2011.19779.x

[tengri.components.agn.disc.kubota_done_disc-3]

A. M. Beloborodov, “Plasma Ejection from Magnetic Flares and the X-Ray Spectrum of Cygnus X-1,” ApJL, 510, L123 (1999). arXiv:astro-ph/9809383. https://doi.org/10.1086/311810

tengri.components.agn.disc.kubota_done_disc_split(wavelength: Array, agn_log_lbol: float, agn_lum_ratio: float = 1.0, agn_log_mbh: float = 7.0, agn_log_ledd: float = -1.0, agn_a_spin: float = 0.0, agn_cos_inc: float = 0.8660254037844386, agn_f_hard: float = 0.02, agn_gamma_warm: float = 2.5, agn_kt_warm: float = 0.2, agn_gamma_hard: float = 1.8, agn_kt_hot: float = 100.0, agn_r_warm_ratio: float = 2.0, n_radii: int = 50, agn_self_consistent_gamma: bool = False, agn_log_lbol_shape: float | None = None, _template=None, **_kwargs) → tuple[source]

Kubota & Done (2018) disc and corona, returned apart (for the SKIRTOR tie).

The same model as kubota_done_disc() (see there for the physics and the parameters), with the two parts of its line-of-sight spectrum \(L_\nu(i) = 2\cos i\, D_\nu + H_\nu\) separated: the optically thick disc and warm Comptonization zones \(2\cos i\, D_\nu\) and the isotropic corona \(H_\nu\), and the corona’s share of the accretion power in closed form.

Returns:

  • l_nu_total (ndarray, shape (n_wave,)) – \(L_\nu(i)\), identical to kubota_done_disc() [erg/s/Hz].

  • l_nu_disc (ndarray, shape (n_wave,)) – The disc and warm-zone part \(2\cos i\, D_\nu\) [erg/s/Hz].

  • l_nu_hot (ndarray, shape (n_wave,)) – The corona \(H_\nu\) [erg/s/Hz].

  • corona_fraction (float) – \(P_H / L_{\rm bol}\), the corona’s share of the accretion power, with \(P_H = \int H_\nu\,d\nu\) the angle-integrated corona power. It is the closed-form hot-flow share (_hot_flow_fraction()) and is independent of the wavelength grid and of agn_cos_inc. The disc and warm zones carry their own dissipation, so P_D + P_H is below L_bol by the unemitted share [dimensionless].

Notes

JIT-compatible: yes. l_nu_disc + l_nu_hot equals l_nu_total exactly.

tengri.components.agn.disc.kubota_done_unemitted_fraction(agn_log_mbh: float, agn_log_lbol: float, agn_a_spin: float = 0.0) → float[source]

Share of the accretion power the K&D disc does not emit, \(R_{\rm unem}/L_{\rm bol}\).

The disc’s total Page-Thorne dissipation is \(L_0 h(\infty)\) and equals \(L_{\rm bol}\) (_disc_dissipation_per_mdot_c2()). The zones emit down to \(R_{\rm out}\), so the dissipation beyond it is not emitted (K&D 2018 Sec. 2.2, which stops the disc at the self-gravity radius):

\[\frac{R_{\rm unem}}{L_{\rm bol}} = 1 - \frac{h(R_{\rm out}/R_{\rm ISCO})}{h(\infty)},\]

with \(h\) the dimensionless Novikov-Thorne integral (_nt_h()) and \(R_{\rm out} = R_{\rm sg}\) as in _compute_zone_radii(). The remainder is published as log_L_agn_disc_unemitted by the composable runner (#3015).

Parameters:
  • agn_log_mbh (float) – log10 black hole mass [log10(Msun)].

  • agn_log_lbol (float) – log10 bolometric (accretion) power [log10(Lsun)].

  • agn_a_spin (float, optional) – Dimensionless spin [dimensionless].

Returns:

\(R_{\rm unem}/L_{\rm bol}\) [dimensionless], in [0, 1).

Return type:

float

Notes

JIT/grad/vmap-safe: yes. The Eddington ratio is formed in log space, as in _compute_zone_radii().

References

[tengri.components.agn.disc.kubota_done_unemitted_fraction-1]
  1. Kubota and C. Done, MNRAS, 480, 1247 (2018), arXiv:1804.00171.

tengri.components.agn.disc.load_relagn_default_grid() → dict[source]

Load the packaged RELAGN disc grid (discovery + cache).

This is the template_loader the RELAGN disc block registers, so the forward model can hoist the ~27 MB library out of the JIT trace and hand it to the block as an argument.

Returns:

Template arrays; see _load_relagn_disc_grid().

Return type:

dict

Raises:

FileNotFoundError – If data/relagn_disc_grid.h5 is not present.

Notes

_find_relagn_grid is imported inside the body on purpose: tengri.components.agn.unified imports this module, so a module-level import would close the cycle.

tengri.components.agn.disc.multicolor_disc(wavelength: Array, agn_log_lbol: float, agn_lum_ratio: float = 1.0, agn_log_mbh: float = 7.0, agn_log_ledd: float = -1.0, agn_a_spin: float = 0.0, agn_cos_inc: float = 0.8660254037844386, n_radii: int = 50, euv_tail: str | float | None = 'powerlaw', agn_log_lbol_shape: float | None = None, **_kwargs) → Array[source]

Shakura-Sunyaev thin accretion disc with multi-color blackbody emission.

Compute the SED of a standard geometrically thin, optically thick accretion disc via the Shakura-Sunyaev model. The disc is stratified into radial annuli, each radiating as a blackbody at its local temperature. This is the outer-disc component of the Kubota & Done (2018) three-zone model (see kubota_done_disc() for the full model including corona).

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength grid. [Angstrom]

  • agn_log_lbol (float) – Accretion power of the disc, integrated over all directions (both faces); independent of the inclination. [log10(L_sun)]

  • agn_lum_ratio (float, optional) – Fraction of the accretion power emitted by the disc. Default: 1.0. [dimensionless, 0–1]

  • agn_log_mbh (float, optional) – Black hole mass. Default: 8.0. [log10(M_sun)]

  • agn_log_ledd (float, optional) – DEPRECATED / IGNORED (#846). The Eddington ratio is now DERIVED from agn_log_lbol and agn_log_mbh (lambda_Edd = L_bol / L_Edd), so the disc shape is self-consistent with the requested L_bol. This parameter is retained for backward compatibility but has no effect; setting or freeing it emits a build-time warning. Default: -1.0.

  • agn_a_spin (float, optional) – Dimensionless black hole spin parameter (prograde). Range: [0, 0.998]. Default: 0.0 (Schwarzschild). [dimensionless]

  • agn_cos_inc (float, optional) – Cosine of the inclination angle. Range: [0, 1]. The returned spectrum scales as \(2\cos i\); the shape does not depend on it. Default: 0.866 (30°). [dimensionless]

  • n_radii (int, optional) – Number of radial bins for numerical integration. Default: 50.

  • euv_tail ({"powerlaw", "both", "wien"}, float, or None, optional) –

    EUV / soft-X-ray behavior below the Lyman limit (912 A).

    • "powerlaw" (default) / "both": blend a CIGALE-like power-law tail onto the Wien core so the disc carries flux below ~100 A.

    • "wien" / None: pure Shakura-Sunyaev Wien cutoff (the bare thin disc; emission below ~150 A is negligible and the EUV / soft X-ray is supplied by the corona instead).

    • float: user-defined slope \(s\) with \(L_\nu \propto \nu^s\).

    Default: "powerlaw". The tail only fills the EUV where the Wien spectrum has already dropped below it, so the UV/optical is unchanged to sub-percent after the bolometric renormalization. See _apply_euv_tail().

Returns:

Spectral luminosity density L_ν. [erg/s/Hz]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, uses jnp primitives and jax.vmap. euv_tail is a static (trace-time) selector, not a traced argument.

The temperature profile is the Shakura-Sunyaev thin disc with a zero-torque inner boundary at the ISCO (a Newtonian-flux form with the Bardeen ISCO radius), not the relativistic Page & Thorne (1974) emissivity: that is used by the Kubota & Done family (kubota_done_disc(), see tengri.components.agn._nt_emissivity), whose reference model defines it. Its total dissipation is 1.46 eta Mdot c^2 at a=0 (1.0 for Page-Thorne), so L_bol here is a normalization, not an energy balance:

\[T(r) = T_{\rm in} \left(\frac{r}{r_{\rm ISCO}}\right)^{-3/4} \left[1 - \sqrt{\frac{r_{\rm ISCO}}{r}}\right]^{1/4}\]

where \(T_{\rm in}\) is the inner temperature determined by the accretion rate and \(r_{\rm ISCO}\) is the innermost stable circular orbit (radius from Bardeen et al. 1972, depends on spin).

The disc luminosity is the luminosity density an observer at inclination \(i\) assigns assuming isotropy:

\[L_\nu(i) = \sum_{j=1}^{N_r} 4\pi B_\nu(T_j)\, 2\pi r_j \, dr_j \cos i = 2\cos i\; D_\nu ,\]

where \(B_\nu(T)\) is the Planck function, \(r_j\) is the ring radius [cm], \(dr_j\) is the ring width [cm] and \(D_\nu\) is the angle-integrated (two-face) spectral luminosity. agn_log_lbol fixes \(\int D_\nu\,d\nu\): the mean of \(\int L_\nu(i)\,d\nu\) over \(\cos i \in [0, 1]\) is \(L_{\rm bol}\), and at \(\cos i = 0.5\) the line-of-sight power equals it.

Key physics:

  • Radiative efficiency: \(\eta = 1 - \sqrt{1 - 2/(3 r_{\rm ISCO})}\), computed from Novikov-Thorne theory. For Schwarzschild (a=0): η ≈ 0.057; for maximally spinning (a→0.998): η ≈ 0.32.

  • Outer radius: Uses the Laor & Netzer (1989) self-gravity (Toomre) radius, beyond which the disc fragments. This is an improvement over fixed approximations (e.g., 1000 r_ISCO) that can err by factors of a few at extreme masses or accretion rates.

  • Eddington ratio clamping: The accretion luminosity is capped at \(L_{\rm Edd}\) (i.e., log(L/L_Edd) is clipped to [0, 1] in linear space), reflecting the physical limit of radiatively efficient accretion.

Numerical method: Radii are logarithmically spaced to ensure fine resolution at small radii where the temperature gradient is steep. Integration uses summation; the trapezoidal rule is applied in log-radius space via the spacing \(d\log r = \Delta(\log r)\).

References

[tengri.components.agn.disc.multicolor_disc-1]

A. Kubota and C. Done, “A physical model of the broad-band continuum of AGN and its implications for the UV/X relation and optical variability,” MNRAS, 480, 1247 (2018). arXiv:1804.00171. https://doi.org/10.1093/mnras/sty1890

[tengri.components.agn.disc.multicolor_disc-2]

J. M. Bardeen, W. H. Press, and S. A. Teukolsky, “Rotating black holes: Locally nonrotating frames, energy extraction, and scalar synchrotron radiation,” ApJ, 178, 347 (1972). https://doi.org/10.1086/151796

[tengri.components.agn.disc.multicolor_disc-3]

A. Laor and H. Netzer, “Massive thin accretion discs – I. Calculated spectra,” MNRAS, 238, 897 (1989). https://doi.org/10.1093/mnras/238.3.897

tengri.components.agn.disc.powerlaw_disc(wavelength: Array, agn_log_lbol: float, agn_lum_ratio: float = 1.0, agn_alpha: float = -1.0, agn_T_max: float = 100000.0, **_kwargs) → Array[source]

Simple power-law accretion disc with exponential UV cutoff (deprecated).

A phenomenological single-component AGN disc model that approximates the optical/UV emission as a power law with an exponential cutoff at high frequencies. This is a faster alternative to multi-color disc models when fine spectral details are not required.

Deprecated since version This: bare power-law disc lacks physical motivation and citations. For science fits, use multicolor_disc() (Shakura-Sunyaev thin disc) or kubota_done_disc() (K&D 3-zone model) instead. Will be removed in tengri v1.0.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength grid. [Angstrom]

  • agn_log_lbol (float) – Total AGN bolometric luminosity. [log10(L_sun)]

  • agn_lum_ratio (float, optional) – Fraction of bolometric luminosity emitted by this disc component. Default: 1.0. [dimensionless, 0–1]

  • agn_alpha (float, optional) – Power-law spectral index. Typical range: -1.5 to -0.5. Default: -1.0 (flat in nu*L_nu). [dimensionless]

  • agn_T_max (float, optional) – Maximum blackbody temperature, setting the UV cutoff frequency. Typical range: 10^4 to 10^6. Default: 10^5. [K]

Returns:

Spectral luminosity density L_ν [erg/s/Hz]; exactly zero outside 10 A - 1e8 A.

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations use jnp primitives; the band truncation is a jnp.where on the wavelength.

The unnormalized spectral shape is:

\[L_\nu^{\rm unnorm} = \nu^\alpha \exp\left(-\frac{h\nu}{k_B T_{\rm max}}\right)\]

where \(\alpha\) is the spectral index, \(h\) is Planck’s constant, \(\nu\) is frequency [Hz], \(k_B\) is Boltzmann’s constant, and \(T_{\rm max}\) is the cutoff temperature [K].

The normalization constant \(C\) is computed numerically by integrating the shape over the fixed band 10 A - 1e8 A (8001 log-spaced internal nodes, a power law between nodes; the caller’s wavelength grid plays no part), so that the integral over frequency of the shape over that band equals the target luminosity \(L_{\rm bol} \cdot f_{\rm disc}\) and the SED is the same on any grid.

The SED is zero outside that band (both edges inclusive), so its frequency integral is the whole budget \(L_{\rm bol} \cdot f_{\rm disc}\). This is by design: the band is the model’s definition, the power law does not converge beyond it (\(\nu L_\nu\) is constant at long wavelength for \(\alpha = -1\)), and other components own the radio (> 1e8 A) and hard X-ray (< 10 A) regimes. A disc of this type contributes nothing to either.

Approximation: This model is a simplified representation of the true accretion disc spectrum, which consists of multiple temperature zones (see multicolor_disc() and kubota_done_disc() for more realistic models). The power-law form breaks down at low frequencies (radio/submm) where the SED transitions to a different regime, and does not capture the soft X-ray excess or hard X-ray corona. Use this model only when computational speed is prioritized over spectral fidelity.

tengri.components.agn.disc.relagn_disc_from_grid(grid: dict, wavelength: Array, agn_log_lbol: float = 10.0, agn_log_mbh: float = 7.0, agn_log_mdot: float = -1.0, agn_astar: float = 0.0, agn_cos_inc: float = 0.8660254037844386, **_kwargs) → Array[source]

RELAGN outer disc from the relativistic template grid.

Parameters:
  • grid (dict) – Template arrays from _load_relagn_disc_grid(). Taken as an argument rather than closed over, so the forward model can thread the ~27 MB library through jax.jit as a Parameter instead of baking it into the graph as Constant ops (#1383).

  • wavelength (ndarray, shape (n_wave,)) – Rest-frame wavelength. [Å]

  • agn_log_lbol (float) – \(\log_{10}(L_{\rm acc}/L_\odot)\), the accretion power the template is normalized to, integrated over all directions. [dimensionless]

  • agn_log_mbh (float) – \(\log_{10}(M_{\rm BH}/M_\odot)\). [dimensionless]

  • agn_log_mdot (float) – \(\log_{10}(\dot M / \dot M_{\rm Edd})\). [dimensionless]

  • agn_astar (float) – Dimensionless BH spin, prograde only (0 to 0.998). [dimensionless]

  • agn_cos_inc (float) – Cosine of inclination (1 = face-on). [dimensionless]

Returns:

Disc \(L_\nu\). [erg/s/Hz]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes. Gradient-safe: yes, triweight kernel, C²-continuous.

Normalization (behavior change, #1206). The template shape comes from (M_BH, Ṁ, a*); its normalization is set by agn_log_lbol, matching every other disc in the composable menu (multicolor, kubota_done, slone_netzer, …). Previously the grid’s own absolute normalization was used and agn_log_lbol had no effect, which both surprised users who set it and made the disc unusable in float32, since the grid’s absolute λL_λ(5100 Å) ≈ 2.6e44 erg/s exceeds the float32 maximum (3.4e38).

The normalization integral is taken over the template’s own native wavelength grid, before resampling, so the output does not depend on the caller’s wavelength sampling and a grid that stops short of the template carries only the part of L_bol that falls inside it.

Inclination: the grid holds the disc alone at cos_inc = 0.5, where the line-of-sight power is the angle-integrated power. The template is normalized to agn_log_lbol at that reference and the spectrum is then scaled by \(2\cos i\): the returned \(L_\nu(i) = 2\cos i\,D_\nu\) with \(\int D_\nu\,d\nu = L_{\rm bol}\), as for multicolor_disc. The mean of its power over \(\cos i \in [0, 1]\) is \(L_{\rm bol}\).

Broad Line Region (BLR) emission model.

The BLR is dense gas close to the black hole producing broad permitted emission lines with FWHM ~ 1000-10000 km/s. The BLR is geometrically compact and lies within the torus, so it is obscured at high inclinations (Type 2 AGN).

This module provides an analytic BLR template using broad Gaussian profiles calibrated to the Vanden Berk et al. (2001) SDSS composite quasar spectrum. The line list includes ≥25 permitted broad lines spanning the UV (Lyα, C IV, He II, C III], Mg II) through optical (Balmer series, Paschen series). When enabled, an Fe II pseudo-continuum is added, modeled as a sum of broad Gaussians at key multiplet wavelength groups (Vestergaard & Wilkes 2001, Tsuzuki+2006, Kovacevic+2010).

All functions are pure JAX and JIT-compilable.

References

tengri.components.agn.blr.compute_blr_sed(wavelength: Array, l_disc_bol_erg: float, covering_fraction: float = 0.1, fwhm_kms: float = 5000.0, agn_fe2_strength: float = 0.0, line_efficiency: float = 0.08, **_kwargs) → Array[source]

BLR emission spectrum: broad permitted lines + Fe II pseudo-continuum.

The BLR receives covering_fraction * L_disc and converts a fraction into broad emission lines. When agn_fe2_strength > 0, an Fe II pseudo-continuum is added, scaled relative to H-beta luminosity using the standard R_Fe ratio.

Note: geometric masking by the torus is NOT applied here; it must be applied by the caller.

Parameters:
  • wavelength (array, shape (n_wave,)) – Rest-frame wavelength [Angstrom].

  • l_disc_bol_erg (float) – Bolometric disc luminosity [erg s^-1].

  • covering_fraction (float) – BLR covering fraction (0 to 1). Default 0.1.

  • fwhm_kms (float) – Line FWHM [km/s]. Default 5000.

  • agn_fe2_strength (float) – Fe II to H-beta flux ratio R_Fe = F(Fe II 4434-4684)/F(H-beta). Typical range 0.5-2.0. Default 0.0 (disabled).

  • line_efficiency (float) – Fraction of intercepted luminosity converted to line emission. Default 0.08.

Returns:

BLR L_nu [erg s^-1 Hz^-1] (before torus masking).

Return type:

array, shape (n_wave,)

Notes

Traced FeII width: the FeII broadening is evaluated by a band-limited synthesis that is valid for a width of 500 km/s or more. A concrete width (a Python or NumPy scalar, as every model build passes: the width is a block keyword, not a fit parameter) below 500 km/s takes the exact full-lattice convolution, with no lower limit. A traced width (fwhm_kms) below 500 km/s cannot raise inside a trace and returns NaN for the FeII spectrum and power, rather than a silently low-passed spectrum, so the same value is finite eager and NaN under jax.jit. Keep a traced width >= 500 km/s.

JIT-compatible: yes, uses jnp primitives and jax.vmap.

The broad emission lines are modeled as Gaussian profiles at rest-frame wavelengths. The line list (≥25 lines) is calibrated to the Vanden Berk et al. (2001) SDSS composite quasar spectrum, including:

  • UV lines: Lyα, Lyβ, N V, Si IV, C IV, He II, C III], Mg II

  • Optical lines: Balmer series (H-α, H-β, H-γ, H-δ, H-ε) and higher-order Paschen series

The Fe II pseudo-continuum follows the Tsuzuki+2006 / Kovacevic+2010 approach: broad Gaussians at UV and optical multiplet centers, normalized to the standard R_Fe ratio.

Torus geometry: This function returns the “bare” BLR spectrum without geometric masking by the dusty torus. The caller is responsible for applying inclination-dependent torus obscuration if using a torus model.

References

[tengri.components.agn.blr.compute_blr_sed-1]

D. E. Vanden Berk et al., “Composite Quasar Spectra from the Sloan Digital Sky Survey,” AJ, 122, 549 (2001). https://doi.org/10.1086/321167

[tengri.components.agn.blr.compute_blr_sed-2]

H. Netzer, “Accretion Power in Astrophysics,” Cambridge University Press (1990). Chapter 2: Broad-line region models.

[tengri.components.agn.blr.compute_blr_sed-3]

T. A. Boroson and R. F. Green, “The Emission-Line Properties of Low-Redshift Quasi-stellar Objects,” ApJS, 80, 109 (1992). https://doi.org/10.1086/191679

[tengri.components.agn.blr.compute_blr_sed-4]

Y. Tsuzuki et al., “Very Large Array Imaging of Submillimeter Galaxies,” ApJ, 650, 57 (2006). https://doi.org/10.1086/506270

[tengri.components.agn.blr.compute_blr_sed-5]

M. Vestergaard and R. F. Green, “Equivalent Widths and Scaling Relations in Quasar Emission Lines,” ApJS, 134, 1 (2001). https://doi.org/10.1086/320360

Narrow Line Region (NLR) emission model.

The NLR is photoionized gas illuminated by the AGN accretion disc. It produces forbidden-line emission at key wavelengths.

The NLR emission is isotropic (not masked by the torus) because it extends on kpc scales beyond the torus opening angle.

For computational efficiency this module uses analytic line profiles rather than full CLOUDY grids. Each emission line is a Gaussian with FWHM ~ 500 km/s (narrow lines) placed at the rest-frame wavelength.

Line ratios come from Richardson et al. (2014) Table 3, column ‘a42’: dereddened emission-line strengths for the AGN locus, relative to Hbeta. Richardson et al. selected SDSS galaxies whose spectra are not dominated by star formation, then co-added them into fifteen high-S/N composite spectra (a00 … a42) forming a sequence in NLR ionization level. The column label is a position on that ionization sequence: it is not a luminosity, an inclination, or a photoionization-model grid point. The numbers are measurements off stacked observed spectra, which is what makes them empirical rather than theoretical (see the doublet note below).

All functions are pure JAX and JIT-compilable.

NLR module map (#897): these are distinct, not duplicates

  • nlr.py (this module), the single-source analytic NLR physics kernel (compute_nlr_sed, Richardson+2014 line ratios). Consumed by the composable block blocks/nlr_analytic.py (the canonical, grammar-reachable path via agn={'nlr': {'type': 'analytic'}}).

  • nlr_cloudy.py: grid-backed (Feltre / Synthesizer CLOUDY) NLR adapters. A different physics source (photoionization grids, not analytic line ratios), consumed by blocks/nlr_synthesizer*.py. Not a duplicate.

  • (removed) nlr_model.py, a one-file SEDModelComponent that wrapped this kernel but was a grammar-unreachable orphan with drifted param names (agn_nlr_cov_frac vs the canonical agn_nlr_cf); deleted in #897 since blocks/nlr_analytic already delivers this physics bit-identically.

References

  • Richardson et al. 2014, MNRAS, 437, 2376 (NLR emission-line template)

  • Feltre et al. 2016, MNRAS, 456, 3354 (NLR emission-line diagnostics)

tengri.components.agn.nlr.compute_nlr_sed(wavelength: Array, l_disc_bol_erg: float, covering_fraction: float = 0.1, fwhm_kms: float = 500.0, line_efficiency: float = 0.1, **_kwargs) → Array[source]

NLR emission spectrum using Richardson+2014 AGN template.

Thin wrapper delegating to compute_nlr_sed_richardson2014(). Kept for backward compatibility; new code should call compute_nlr_sed_richardson2014 directly.

The NLR receives covering_fraction * L_disc and re-emits a fraction as emission lines (line-only; no power-law continuum).

Parameters:
  • wavelength (array, shape (n_wave,)) – Rest-frame wavelength [Angstrom].

  • l_disc_bol_erg (float) – Bolometric disc luminosity [erg s^-1].

  • covering_fraction (float) – NLR covering fraction (0 to 1). Default 0.1.

  • fwhm_kms (float) – Line FWHM [km/s]. Default 500.

  • line_efficiency (float) – Fraction of intercepted luminosity converted to line emission. Default 0.10.

Returns:

NLR L_nu [erg s^-1 Hz^-1].

Return type:

array, shape (n_wave,)

Notes

JIT-compatible: yes, uses jnp primitives and jax.vmap.

tengri.components.agn.nlr.compute_nlr_sed_richardson2014(wavelength: Array, l_disc_bol_erg: float, covering_fraction: float = 0.1, fwhm_kms: float = 500.0, line_efficiency: float = 0.1, **_kwargs) → Array[source]

AGN NLR spectrum using Richardson+2014 Table 3 ‘a42’ line template.

The narrow-line region (NLR) is photoionized gas illuminated by the AGN accretion disc. This function synthesizes the NLR emission spectrum using the emission-line template from Richardson et al. (2014), which provides AGN-specific line ratios derived from the ‘a42’ column of Table 3: one of fifteen composite SDSS spectra forming a sequence in NLR ionization level.

The NLR receives covering_fraction * L_disc and converts a fraction into line emission only (no power-law continuum). Each line is modeled as a Gaussian profile at the rest-frame wavelength.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength [Angstrom].

  • l_disc_bol_erg (float) – Bolometric disc luminosity [erg s^-1].

  • covering_fraction (float, optional) – NLR covering fraction (0 to 1). Default 0.1.

  • fwhm_kms (float, optional) – Line FWHM [km/s]. Default 500.

  • line_efficiency (float, optional) – Fraction of intercepted luminosity converted to line emission. Default 0.10.

Returns:

l_nu – NLR L_nu [erg s^-1 Hz^-1].

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, uses jnp primitives and jax.vmap.

The Richardson+2014 ‘a42’ template uses 23 emission lines normalized to H-beta = 1. The strongest line is [O III] 5007 at 8.53× H-beta, consistent with typical Seyfert 2 AGN narrow-line ratios. Line profiles are Gaussian with fixed FWHM (narrow lines, ~500 km/s).

Empirical, not theoretical. Table 3 lists dereddened strengths measured off stacked observed spectra, so the forbidden doublets do not reproduce their atomic branching ratios exactly ([N II] 6584/6548 = 2.70 against an atomic ~2.94). Those deviations are inherited from the measurement and are deliberately preserved: see the note above _RICHARDSON_FLUXES. For a template whose doublets are tied by construction, use a photoionization backend (agn={'nlr': {'type': 'synthesizer'}}) instead.

Implements the same AGN NLR line table as Prospector (Johnson et al. 2021 [tengri.components.agn.nlr.compute_nlr_sed_richardson2014-2]); validated against its output.

References

[tengri.components.agn.nlr.compute_nlr_sed_richardson2014-1]

C. T. Richardson, J. T. Allen, J. A. Baldwin, P. C. Hewett, and G. J. Ferland, “Interpreting the ionization sequence in AGN emission-line spectra,” MNRAS, 2014, 437, 3, 2376-2403. Table 3, column ‘a42’. https://doi.org/10.1093/mnras/stt2056

[tengri.components.agn.nlr.compute_nlr_sed_richardson2014-2]

B. D. Johnson, et al., “Prospector: Inferring the Star Formation Histories of Galaxies from Observed Spectral Energy Distributions,” ApJS, 254, 22, 2021. https://doi.org/10.3847/1538-4365/abef67

Unified AGN SED: combined disc + torus + NLR + BLR emission.

Combines accretion disc and dust torus models into a single AGN SED. The disc emission is partly absorbed by the torus (via covering factor) and re-emitted in the IR.

Architecture overview

The component tree and geometric masking design in this module is inspired by the UnifiedAGN class in the Synthesizer package (Lovell et al. 2025, Open J. Astrophys. 8, doi:10.33232/001c.145766; Roper et al. 2026, JOSS 11, 9436, doi:10.21105/joss.09436; https://github.com/synthesizer-project/synthesizer). Per the Synthesizer citation policy, BOTH papers must be cited together.

Synthesizer’s model defines:

  • An accretion disc whose inclination-dependent emission is extracted from precomputed photoionization grids (CLOUDY-based).

  • NLR emission as grid-extracted nebular spectra, not masked by the torus (isotropic: always visible at all inclinations).

  • BLR emission as grid-extracted nebular spectra, masked by the torus using a hard binary condition: inclination + theta_torus > 90° → zeroed.

  • A torus that reprocesses the isotropic disc emission, scaled by torus_fraction = theta_torus / 90° (geometric fraction of sky covered).

  • Optional diffuse dust attenuation layered on top.

Differences in this implementation

tengri adopts the same conceptual decomposition but diverges in several ways for compatibility with gradient-based inference (VI, HMC):

  1. Analytic disc models, not grids: disc emission uses the closed-form multicolor/Shakura-Sunyaev or power-law models from disc.py rather than a photoionization grid. This makes the disc JIT/grad-compatible.

  2. Analytic NLR/BLR templates, not grids: NLR and BLR use empirically calibrated Gaussian line templates (Vanden Berk et al. 2001; Groves et al. 2004) rather than CLOUDY-generated photoionization grids. Grids would require non-differentiable table look-ups over (U, n_H) axes.

  3. Smooth sigmoid geometric mask, not a hard binary: Synthesizer zeros the disc/BLR whenever inclination + theta_torus > 90°. tengri replaces this with a smooth sigmoid centered at the critical angle (see _sigmoid_mask). The sigmoid preserves the gradient through the inclination parameter, which would otherwise be zero almost everywhere under the hard mask.

  4. Explicit ``agn_torus_frac`` parameter, not derived from theta_torus: Synthesizer internally computes torus_fraction = theta_torus / 90°, coupling the torus covering factor to the opening angle. tengri keeps agn_torus_frac as an independent free parameter. This decoupling is intentional: deriving the covering factor from cos(theta_torus) in the forward pass introduces a gradient discontinuity at theta_torus=0 and at theta_torus=90° (see CLAUDE.md gotcha).

  5. Polar dust reddening (SMC law): an optional agn_polar_ebv parameter applies SMC-law extinction to the disc and BLR for Type 1 sightlines. This is absent from Synthesizer’s basic UnifiedAGN but present in the CIGALE skirtor2016 module (Yang et al. 2020, MNRAS, 491, 740).

Pre-registered configurations

  • multicolor_agn (= deprecated alias kubota_done): multi-color disc with BH physics + 2-T torus (8+ params).

  • kubota_done_full: full Kubota & Done 3-zone disc + 2-T torus (13+ params).

  • adaf: faithful Mahadevan 1997 ADAF + Silva+04 IR torus for LLAGN.

  • unified_nlr_blr: full Synthesizer-inspired model with NLR/BLR + polar dust.

  • skirtor: power-law disc + SKIRTOR clumpy torus (Stalevski+2012, 2016).

  • silva04: power-law disc + Silva+04 smooth torus.

  • cat3d_wind: power-law disc + CAT3D-Wind clumpy torus.

  • relagn: RELAGN relativistic disc + 2-T torus.

Warning

agn_log_lbol is log10(L_bol / L_sun), not log10(L_bol / [erg/s]). See the convention note below before setting this parameter.

Convention for agn_log_lbol

agn_log_lbol is \(\log_{10}(L_{\rm bol} / L_\odot)\): the bolometric luminosity expressed in solar luminosities, not erg/s. This matches the internal computation in components/agn/_phys.py (l_bol_erg = 10**agn_log_lbol * L_SUN).

  • Typical bright Seyfert: \(L_{\rm bol}\!\sim\!10^{44}\) erg/s \(\Rightarrow\) agn_log_lbol = 10.5.

  • Bright quasar: \(L_{\rm bol}\!\sim\!10^{46}\) erg/s \(\Rightarrow\) agn_log_lbol = 12.5.

  • Synthesizer’s bolometric_luminosity is in erg/s; convert with agn_log_lbol = log10(L_bol_erg) - log10(L_SUN_erg), i.e. subtract \(\approx 33.58\) from synthesizer’s value.

Default agn_log_lbol=11.0 in the function signatures of this module corresponds to a bolometric luminosity of ~10^44 erg/s, a typical bright Seyfert nucleus. This is a physically reasonable default for AGN fitting; always set this parameter explicitly in production to match your target.

Usage:

from tengri.components.agn.unified import unified_agn, resolve_agn_model

# Use a named configuration. agn_log_lbol = 11 → L_bol ≈ 4e44 erg/s
# (a typical bright Seyfert nucleus).
model_fn = resolve_agn_model("multicolor_agn")
l_nu = model_fn(wavelength, agn_log_lbol=11.0, agn_lum_ratio=0.1, ...)

# Or use the generic combiner directly.
l_nu = unified_agn(wavelength, agn_log_lbol=11.0, disc_model="multicolor", ...)

References

[tengri.components.agn.unified-1]

Lovell C. C. et al. 2025, Open Journal of Astrophysics, 8, “Synthesizer: a Software Package for Synthetic Astronomical Observables”, https://doi.org/10.33232/001c.145766

[tengri.components.agn.unified-2]

Roper W. J. et al. 2026, Journal of Open Source Software, 11, 9436, “Synthesizer: Synthetic Observables for Modern Astronomy”, https://doi.org/10.21105/joss.09436 (Both Synthesizer papers [tengri.components.agn.unified-1] [tengri.components.agn.unified-2] must be cited together.)

[tengri.components.agn.unified-3]

synthesizer source: https://github.com/synthesizer-project/synthesizer (src/synthesizer/emission_models/agn/unified_agn.py)

class tengri.components.agn.unified.AGNRegistryEntry(callable: Callable, citation: str = '', status: str = 'production', short_doc: str = '')[source]

Bases: object

Registry entry for an AGN model with optional metadata.

Variables:
  • callable (Callable) – The AGN model function.

  • citation (str) – Optional academic citation. Default empty string.

  • status (str) – Model status: “production”, “experimental”, “demo”, or “deprecated”. Default “production”.

  • short_doc (str) – Optional one-line description. Default empty string.

Notes

JIT-compatible: no, class for registry initialization.

tengri.components.agn.unified.adaf_agn(wavelength: Array, agn_log_lbol: float, agn_lum_ratio: float = 1.0, agn_log_mbh: float = 7.0, agn_adaf_alpha: float = 0.3, agn_adaf_beta: float = 0.5, agn_adaf_delta: float = 0.1, agn_torus_frac: float = 0.5, agn_log_nh_silva: float = 23.0, agn_ebv_disc: float = 0.0, **_kwargs) → Array[source]

Faithful ADAF (Mahadevan 1997) + Silva+04 torus for low-luminosity AGN.

The inner flow is an advection-dominated accretion flow; a Silva+04 smooth torus re-emits a fraction of the bolometric luminosity in the IR. As of #898 the disc is the faithful Mahadevan 1997 model (adaf_spectrum()): agn_log_lbol is the canonical luminosity and the accretion rate is derived from it (the radiated power Q_ie + delta Q+ of Sect. 5.2; Eq. 49 is its high-rate limit), so agn_log_ledd is retired; the ad-hoc truncated outer disc is dropped.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength [Angstrom].

  • agn_log_lbol (float) – log10 of bolometric luminosity [Lsun].

  • agn_lum_ratio (float, optional) – AGN luminosity fraction [dimensionless]. Default 0.1.

  • agn_log_mbh (float, optional) – log10 of black hole mass [Msun]. Default 8.0.

  • agn_adaf_alpha (float, optional) – ADAF viscosity parameter alpha. Default 0.3.

  • agn_adaf_beta (float, optional) – Gas-to-total pressure ratio (magnetic fraction is 1-beta). Default 0.5.

  • agn_adaf_delta (float, optional) – Electron viscous-heating fraction (default 0.1 = modern preference; Mahadevan 1997 fiducial is 1/2000). Default 0.1.

  • agn_torus_frac (float, optional) – Torus covering factor [dimensionless]. Default 0.5.

  • agn_log_nh_silva (float, optional) – Torus hydrogen column density, log10(N_H / cm^-2). Default 23.0.

  • agn_ebv_disc (float, optional) – SMC-law color excess on disc [mag]. Default 0.0.

Returns:

L_nu [erg/s/Hz].

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, uses adaf_spectrum() and silva04_sed().

References

[tengri.components.agn.unified.adaf_agn-1]

Mahadevan, R. 1997, ApJ, 477, 585. arXiv:astro-ph/9609107.

[tengri.components.agn.unified.adaf_agn-2]

Silva, L., Maiolino, R., & Granato, G. L. (2004). MNRAS, 355, 973. arXiv:astro-ph/0403425. AGN torus radiative transfer.

tengri.components.agn.unified.cat3d_wind_agn(wavelength: Array, agn_log_lbol: float = 10.0, agn_lum_ratio: float = 1.0, agn_cos_inc: float = 0.8660254037844386, agn_a_cat3d: float = -2.0, agn_fwd_cat3d: float = 1.0, agn_torus_frac: float = 0.5, agn_ebv_disc: float = 0.0, **_kwargs) → Array[source]

CAT3D-Wind AGN: power-law disc + clumpy-disc + polar-wind torus.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength. [Å]

  • agn_log_lbol (float, optional) – log10(L_bol / L_sun). Default 11.0.

  • agn_lum_ratio (float, optional) – Overall AGN luminosity fraction applied on top of the disc-plus-torus sum. Default 0.1.

  • agn_cos_inc (float, optional) – Cosine of inclination. Default 0.5.

  • agn_a_cat3d (float, optional) – Radial power-law index of the clumpy-cloud distribution. Default −2.0.

  • agn_fwd_cat3d (float, optional) – Polar-wind mass fraction. Default 1.0.

  • agn_torus_frac (float, optional) – Fraction of L_bol reprocessed by the torus. Disc receives 1 - agn_torus_frac. Default 0.5.

Returns:

Combined AGN SED. [erg/s/Hz]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes.

Grid templates published with AGNfitter-rX (Martínez-Ramírez et al. 2024, A&A 688, A46, arXiv:2405.12111), a Hönig & Kishimoto 2017 CAT3D-Wind three-parameter projection. See tengri.components.agn.cat3d_wind and scripts/build_cat3d_wind_grid.py.

tengri.components.agn.unified.is_composable_recipe(name: str) → bool[source]

Whether agn={'type': name} runs through the composable block runner.

"composable" and every deprecated preset name qualify: a preset is a fixed choice of block selectors and normalization over that runner (see resolve_agn_model()). The self-contained models (grahsp, skirtor_stalevski) do not.

Parameters:

name (str) – AGN model name (the component’s config.model).

Return type:

bool

tengri.components.agn.unified.kubota_done_full_agn(wavelength: Array, agn_log_lbol: float, agn_lum_ratio: float = 1.0, agn_log_mbh: float = 7.0, agn_log_ledd: float = -1.0, agn_a_spin: float = 0.0, agn_cos_inc: float = 0.8660254037844386, agn_f_hard: float = 0.02, agn_gamma_warm: float = 2.5, agn_kt_warm: float = 0.2, agn_gamma_hard: float = 1.8, agn_kt_hot: float = 100.0, agn_r_warm_ratio: float = 2.0, agn_log_nh_silva: float = 23.0, agn_torus_frac: float = 0.5, agn_ebv_disc: float = 0.0, **_kwargs) → Array[source]

Full Kubota & Done (2018) 3-zone disc + Silva+04 torus.

Extends multicolor_agn with the full K&D 3-zone disc model: outer standard disc, warm Comptonization (soft X-ray excess), and hot corona (hard X-ray power law). Combined with a Silva+04 smooth dust torus using radiative-transfer geometry.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength [Angstrom].

  • agn_log_lbol (float) – log10 of bolometric luminosity [Lsun].

  • agn_lum_ratio (float, optional) – AGN luminosity fraction [dimensionless]. Default 0.1.

  • agn_log_mbh (float, optional) – log10 of black hole mass [Msun]. Default 8.0.

  • agn_log_ledd (float, optional) – log10 of Eddington ratio [dimensionless]. Default -1.0.

  • agn_a_spin (float, optional) – Black hole spin [dimensionless], range [0, 0.998]. Default 0.0.

  • agn_cos_inc (float, optional) – cos(inclination) [dimensionless]. Default 0.5.

  • agn_f_hard (float, optional) – Fraction of L_Edd in corona [dimensionless]. Default 0.02.

  • agn_gamma_warm (float, optional) – Warm Comptonization photon index [dimensionless]. Default 2.5.

  • agn_kt_warm (float, optional) – Warm electron temperature [keV]. Default 0.2.

  • agn_gamma_hard (float, optional) – Hard X-ray photon index [dimensionless]. Default 1.8.

  • agn_kt_hot (float, optional) – Hot corona temperature [keV]. Default 100.0.

  • agn_r_warm_ratio (float, optional) – R_warm / R_hot ratio [dimensionless]. Default 2.0.

  • agn_log_nh_silva (float, optional) – Torus hydrogen column density, log10(N_H / cm^-2). Default 23.0.

  • agn_torus_frac (float, optional) – Torus covering factor [dimensionless]. Default 0.5.

  • agn_ebv_disc (float, optional) – SMC-law color excess on disc [mag]. Default 0.0.

Returns:

L_nu [erg/s/Hz].

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, uses kubota_done_disc() and silva04_sed().

References

[tengri.components.agn.unified.kubota_done_full_agn-1]

Silva, L., Maiolino, R., & Granato, G. L. (2004). MNRAS, 355, 973. arXiv:astro-ph/0403425. AGN torus radiative transfer.

[tengri.components.agn.unified.kubota_done_full_agn-2]

Kubota, A. & Done, C. (2018). MNRAS, 480, 1247. Disc model.

tengri.components.agn.unified.monolithic_agn_model_names() → frozenset[str][source]

Every non-composable AGN model name agn={'type': ...} accepts.

The two halves of the monolithic menu: the deprecated preset names, which route through the composable runner with fixed block selectors, and the self-contained models, which resolve to their own forward function.

Returns:

Model names, excluding "composable".

Return type:

frozenset of str

Notes

JIT-compatible: no, reads module-level registries at call time.

tengri.components.agn.unified.monolithic_models_with_line_components() → frozenset[str][source]

Monolithic AGN model names whose forward function returns a line-only array.

Every deprecated preset routes through the composable runner and the self-contained grahsp model separates its Gaussian lines and FeII forest; both accept return_components=True and return (L_nu, {"lines": ...}). The other self-contained models (skirtor_stalevski) paint no emission lines.

Returns:

Model names, a subset of monolithic_agn_model_names().

Return type:

frozenset of str

Notes

JIT-compatible: no, reads module-level registries at call time.

tengri.components.agn.unified.multicolor_agn(wavelength: Array, agn_log_lbol: float, agn_lum_ratio: float = 1.0, agn_log_mbh: float = 7.0, agn_log_ledd: float = -1.0, agn_a_spin: float = 0.0, agn_cos_inc: float = 0.8660254037844386, agn_log_nh_silva: float = 23.0, agn_torus_frac: float = 0.5, **_kwargs) → Array[source]

Multicolor Shakura-Sunyaev disc + Silva+04 smooth AGN torus.

Standard thin-disc SED with spin-dependent ISCO and Novikov-Thorne radiative efficiency. This is the outer standard disc only: no warm Comptonization or hot corona (for the full 3-zone model, see kubota_done_full). The torus uses the Silva+04 radiative-transfer solution for smooth dust geometry.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength [Angstrom].

  • agn_log_lbol (float) – log10 of bolometric luminosity [Lsun].

  • agn_lum_ratio (float, optional) – AGN luminosity fraction [dimensionless]. Default 0.1.

  • agn_log_mbh (float, optional) – log10 of black hole mass [Msun]. Default 8.0.

  • agn_log_ledd (float, optional) – log10 of Eddington ratio [dimensionless]. Default -1.0.

  • agn_a_spin (float, optional) – Black hole spin [dimensionless], range [0, 0.998]. Default 0.0.

  • agn_cos_inc (float, optional) – cos(inclination) [dimensionless], range [0, 1]. Default 0.5.

  • agn_log_nh_silva (float, optional) – Torus hydrogen column density, log10(N_H / cm^-2). Default 23.0.

  • agn_torus_frac (float, optional) – Torus covering factor [dimensionless]. Default 0.5.

Returns:

L_nu [erg/s/Hz].

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, uses multicolor_disc() and silva04_sed().

Also registered as “kubota_done” (deprecated alias).

References

[tengri.components.agn.unified.multicolor_agn-1]

Silva, L., Maiolino, R., & Granato, G. L. (2004). MNRAS, 355, 973. arXiv:astro-ph/0403425. AGN torus radiative transfer.

[tengri.components.agn.unified.multicolor_agn-2]

Kubota, A. & Done, C. (2018). MNRAS, 480, 1247. Disc model.

tengri.components.agn.unified.preset_overrides(name: str) → dict[str, str][source]

Block selectors and normalization a deprecated preset forces over the component config.

preset_wrapper in resolve_agn_model() lets the preset win over the config, so the config’s selectors (the grammar’s "none" for a preset build) are not what runs.

Parameters:

name (str) – AGN model name.

Returns:

{"agn_<stage>_block": ..., "agn_norm": ...} for the keys the preset sets; empty for "composable" and for any name that is not a preset.

Return type:

dict of str to str

tengri.components.agn.unified.register_agn_model(name: str, *, citation: str = '', status: str = 'production', short_doc: str = '') → Callable[source]

Register an AGN model function (decorator factory).

Parameters:
  • name (str) – Unique model name for the registry.

  • citation (str, optional) – Academic citation for the model. Default empty string.

  • status (str, optional) – Model status (“production”, “experimental”, “demo”, “deprecated”). Default “production”.

  • short_doc (str, optional) – One-line description. Default empty string.

Returns:

Decorator that registers the decorated function in AGN_MODELS.

Return type:

callable

Notes

JIT-compatible: no, registers at module load time (not JIT-compilable).

The registered function must have signature:

fn(wavelength, agn_log_lbol, **kwargs) -> L_nu [erg/s/Hz]

Metadata is stored in an AGNRegistryEntry for introspection via the registry.list_agn_models() façade.

tengri.components.agn.unified.relagn_agn(wavelength: Array, agn_log_mbh: float = 7.0, agn_log_mdot: float = -1.0, agn_astar: float = 0.0, agn_cos_inc: float = 0.8660254037844386, agn_torus_frac: float = 0.5, agn_log_nh_silva: float = 23.0, agn_ebv_disc: float = 0.0, **_kwargs) → Array[source]

RELAGN relativistic outer disc + Silva+04 dust torus.

Uses the precomputed RELAGN grid (Hagen & Done 2023) with KYCONV (Dovciak, Karas & Yaqoob 2004) per-annulus Kerr ray-tracing for the disc, and a Silva+04 smooth dust torus for radiative-transfer reprocessing.

The disc luminosity is self-consistent with BH mass and accretion rate; the torus re-emits agn_torus_frac of the disc bolometric output.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength. [Å]

  • agn_log_mbh (float, optional) – log10(M_BH / M_sun), range [7, 10]. Default 8.0.

  • agn_log_mdot (float, optional) – log10(Ṁ / Ṁ_Edd), range [−1.5, 0.3]. Default −1.0.

  • agn_astar (float, optional) – Dimensionless BH spin, prograde only, range [0, 0.998]. Default 0.0.

  • agn_cos_inc (float, optional) – Cosine of inclination (1 = face-on). Default 0.5.

  • agn_torus_frac (float, optional) – Torus covering factor; torus re-emits this fraction of disc L_bol. Disc is attenuated by (1 − agn_torus_frac). Default 0.5.

  • agn_log_nh_silva (float, optional) – Torus hydrogen column density, log10(N_H / cm^-2). Default 23.0.

  • agn_ebv_disc (float, optional) – SMC-law color excess applied to disc [mag]. Default 0.0.

Returns:

Total AGN L_ν. [erg s⁻¹ Hz⁻¹]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, disc interpolation is pure JAX triweight kernel.

Gradient-safe: yes, C²-continuous triweight kernel on all grid axes.

Grid required: data/relagn_disc_grid.h5 built by scripts/build_relagn_disc_grid.py (requires HEASOFT/XSPEC + KYCONV).

Torus normalization: derived by integrating the reddened disc L_ν over frequency on the disc template’s own native wavelength grid (not on wavelength, so it does not depend on the caller’s sampling or range): no separate agn_log_lbol parameter needed.

References

[tengri.components.agn.unified.relagn_agn-1]

Dovciak, M., Karas, V., & Yaqoob, T. (2004). ApJS, 153, 205. doi:10.1086/421115 [KYCONV]

[tengri.components.agn.unified.relagn_agn-2]

Hagen, S. & Done, C. (2023). MNRAS, 525, 3455-3467. doi:10.1093/mnras/stad2499 [RELAGN disc]

[tengri.components.agn.unified.relagn_agn-3]

Silva, L., Maiolino, R., & Granato, G. L. (2004). MNRAS, 355, 973. arXiv:astro-ph/0403425. AGN torus radiative transfer.

tengri.components.agn.unified.resolve_agn_model(name: str) → Callable[source]

Retrieve a registered AGN model by name.

All monolithic AGN models have been migrated to composable presets. This function accepts old model names (with deprecation warning) and routes them through the composable runner with the appropriate block selectors.

Parameters:

name (str) – Model name. Both old monolithic names (deprecated) and "composable" are supported.

Returns:

Either the composable runner (for new code) or a preset-routed wrapper for deprecated names.

Return type:

callable

Notes

JIT-compatible: no, performs dictionary lookup at initialization time. Old monolithic model names still work but emit DeprecationWarning.

tengri.components.agn.unified.silva04_agn(wavelength: Array, agn_log_lbol: float = 10.0, agn_lum_ratio: float = 1.0, agn_log_nh_silva: float = 23.0, agn_torus_frac: float = 0.5, agn_ebv_disc: float = 0.0, **_kwargs) → Array[source]

Silva+04 smooth-torus AGN: power-law disc + Silva+04 torus.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength. [Å]

  • agn_log_lbol (float, optional) – log10(L_bol / L_sun). Default 11.0.

  • agn_lum_ratio (float, optional) – Overall AGN luminosity fraction applied on top of the disc-plus-torus sum. Default 0.1.

  • agn_log_nh_silva (float, optional) – Hydrogen column density, log10(N_H / cm^-2). Default 23.0.

  • agn_torus_frac (float, optional) – Fraction of L_bol reprocessed by the torus. Disc receives 1 - agn_torus_frac. Default 0.5.

Returns:

Combined AGN SED. [erg/s/Hz]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, both the power-law disc and the Silva+04 grid interpolation are pure JAX.

Grid templates published with AGNfitter (Calistro Rivera et al. 2016); see tengri.components.agn.silva04 and scripts/build_silva04_grid.py.

tengri.components.agn.unified.skirtor_agn(wavelength: Array, agn_log_lbol: float = 10.0, agn_lum_ratio: float = 1.0, agn_tau_skirtor: float = 7.0, agn_p_skirtor: float = 1.0, agn_q_skirtor: float = 1.0, agn_oa_skirtor: float = 40.0, agn_cos_inc: float = 0.8660254037844386, agn_torus_frac: float = 0.5, agn_ebv_disc: float = 0.0, **_kwargs) → Array[source]

SKIRTOR clumpy torus AGN: power-law disc + SKIRTOR torus (analytic).

Uses the analytic SKIRTOR approximation (Stalevski et al. 2012, 2016) for the torus emission, combined with a power-law accretion disc.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength [Angstrom].

  • agn_log_lbol (float, optional) – log10 of bolometric luminosity [Lsun]. Default 11.0.

  • agn_lum_ratio (float, optional) – AGN luminosity fraction [dimensionless]. Default 0.1.

  • agn_tau_skirtor (float, optional) – Optical depth at 9.7 um [dimensionless], range [3, 11]. Default 7.0.

  • agn_p_skirtor (float, optional) – Radial density gradient [dimensionless], range [0, 1.5]. Default 1.0.

  • agn_q_skirtor (float, optional) – Polar density gradient [dimensionless], range [0, 1.5]. Default 1.0.

  • agn_oa_skirtor (float, optional) – Opening angle [degrees], range [20, 60]. Default 40.0.

  • agn_cos_inc (float, optional) – cos(inclination) [dimensionless], 0=edge-on, 1=face-on. Default 0.5.

  • agn_torus_frac (float, optional) – Torus covering factor [dimensionless]. Default 0.5.

Returns:

L_nu [erg/s/Hz].

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: no, requires SKIRTOR template interpolation (non-differentiable).

tengri.components.agn.unified.skirtor_stalevski_agn(wavelength: Array, agn_log_lbol: float = 10.0, agn_lum_ratio: float = 1.0, agn_tau_skirtor: float = 7.0, agn_p_skirtor: float = 1.0, agn_q_skirtor: float = 1.0, agn_oa_skirtor: float = 40.0, agn_radius_ratio: float = 20.0, agn_cos_inc: float = 0.8660254037844386, **_kwargs) → Array[source]

Raw Stalevski (2016) SKIRTOR SED, the published radiative-transfer output.

Returns the SKIRTOR template’s total SED (accretion disc + clumpy torus + scattered light) exactly as the Stalevski et al. (2016) radiative-transfer grid computed it at the requested viewing angle, scaled to the requested bolometric luminosity. Unlike the skirtor model (power-law disc) and the composable disc.skirtor block (CIGALE’s analytic disc + norm=1/∫dust energy balance), this applies no analytic-disc substitution and no re-normalization: it is the faithful SKIRTOR template, matching codes that read SKIRTOR directly (e.g. ProSpect’s SKIRTOR_interp) rather than CIGALE’s reconstruction.

Use this model to reproduce the raw SKIRTOR SED; use the composable disc.skirtor + torus.skirtor blocks (norm='cigale_joint') to reproduce CIGALE’s skirtor2016 instead. The two answer different questions, the raw template vs CIGALE’s tunable-disc variant.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength [Angstrom].

  • agn_log_lbol (float, optional) – log10 of bolometric luminosity [Lsun]. Default 11.0.

  • agn_lum_ratio (float, optional) – AGN luminosity fraction (host scaling) [dimensionless]. Default 0.1.

  • agn_tau_skirtor (float, optional) – Optical depth at 9.7 um [dimensionless], grid range [3, 11]. Default 7.0.

  • agn_p_skirtor (float, optional) – Radial / polar dust-density gradients [dimensionless]. Default 1.0.

  • agn_q_skirtor (float, optional) – Radial / polar dust-density gradients [dimensionless]. Default 1.0.

  • agn_oa_skirtor (float, optional) – Half-opening angle of the dust-free cone [degrees]. Default 40.0.

  • agn_cos_inc (float, optional) – cos(inclination); 1 = face-on (Type 1), 0 = edge-on. Default cos(30 deg).

Returns:

L_nu [erg/s/Hz], total SKIRTOR SED scaled to 10**agn_log_lbol * L_sun * agn_lum_ratio.

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: no, requires SKIRTOR grid interpolation.

Grid caveat: tengri ships the SKIRTOR v3 grid (tau in {3,5,7,9,11}); a requested agn_tau_skirtor outside that range is clamped. Bit-for-bit agreement with another code additionally requires the same SKIRTOR grid version.

References

[S16]

Stalevski, M. et al. 2016, MNRAS, 458, 2288. arXiv:1602.06954. https://doi.org/10.1093/mnras/stw444

tengri.components.agn.unified.unified_agn(wavelength: Array, agn_log_lbol: float, disc_model: str = 'powerlaw', torus_model: str = 'silva04', agn_torus_frac: float = 0.5, agn_ebv_disc: float = 0.0, **kwargs) → Array[source]

Compute unified AGN SED: disc + torus.

The torus re-emits a fraction agn_torus_frac of the bolometric luminosity, while the disc emits the remaining (1 - agn_torus_frac).

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength [Angstrom].

  • agn_log_lbol (float) – log10 of bolometric luminosity [Lsun].

  • disc_model (str, optional) – Disc model name: “powerlaw”, “multicolor”, “kubota_done_3zone”, “adaf”. Default “powerlaw”.

  • torus_model (str, optional) – Torus model name: “silva04” (production, default), “skirtor”. Default “silva04” (radiative-transfer based Silva+04 smooth torus).

  • agn_torus_frac (float, optional) – Torus covering factor [dimensionless], range [0, 1]. Disc gets (1 - agn_torus_frac). Default 0.5.

  • **kwargs – Additional parameters passed to disc and torus functions (they ignore unrecognized kwargs).

Returns:

Total AGN L_nu [erg/s/Hz] = L_disc + L_torus.

Return type:

ndarray, shape (n_wave,)

References

[tengri.components.agn.unified.unified_agn-1]

See tengri.components.agn.disc and tengri.components.agn.torus for individual model references.

Notes

JIT-compatible: depends on disc and torus models (mostly yes for analytic).

Gradient-safe: yes when using analytic disc and torus models.

tengri.components.agn.unified.unified_nlr_blr(wavelength: Array, agn_log_lbol: float = 10.0, agn_cos_inc: float = 0.8660254037844386, agn_theta_torus: float = 30.0, agn_nlr_cf: float = 0.1, agn_blr_cf: float = 0.1, agn_log_mbh: float = 7.0, agn_log_ledd: float = -1.0, agn_a_spin: float = 0.0, agn_log_nh_silva: float = 23.0, agn_torus_frac: float = 0.5, agn_lum_ratio: float = 1.0, agn_blr_fwhm: float = 5000.0, agn_nlr_fwhm: float = 500.0, agn_polar_ebv: float = 0.0, nlr_fn: Callable | None = None, blr_fn: Callable | None = None, include_xray: bool = False, xray_gamma_agn: float = 1.8, xray_alpha_ox: float = 0.0, xray_E_cut: float = 300.0, include_radio: bool = False, radio_q_ir: float = 2.64, radio_alpha_sf: float = 0.8, radio_loudness: float = 0.0, radio_alpha_agn: float = 0.7, **_kwargs) → Array[source]

Unified AGN SED with NLR/BLR decomposition and geometric masking.

Implements the same conceptual decomposition as the UnifiedAGN class in Synthesizer (Lovell et al. 2025 [tengri.components.agn.unified.unified_nlr_blr-1], Roper et al. 2026 [tengri.components.agn.unified.unified_nlr_blr-2]): an accretion disc, dusty torus, narrow line region (NLR), and broad line region (BLR), combined with inclination-dependent geometric masking. Polar dust reddening (SMC law) additionally follows CIGALE’s skirtor2016 module [tengri.components.agn.unified.unified_nlr_blr-3].

Correspondence with Synthesizer’s UnifiedAGN

The following table maps tengri parameters to Synthesizer attributes (synthesizer.components.blackhole.BlackholeComponent):

tengri

Synthesizer

Note

agn_cos_inc

cos(inclination)

Synth uses inclination [deg]

agn_theta_torus

theta_torus [deg]

Same meaning

agn_nlr_cf

covering_fraction_nlr

Identical semantics

agn_blr_cf

covering_fraction_blr

Identical semantics

agn_torus_frac

torus_fraction = theta_torus/90°

Different: independent param

agn_blr_fwhm

velocity_dispersion_blr [km/s]

tengri uses FWHM directly

agn_nlr_fwhm

velocity_dispersion_nlr [km/s]

Same

Deliberate differences from Synthesizer

  1. Analytic disc, not a grid: Synthesizer extracts disc emission from precomputed CLOUDY photoionization grids. tengri uses the closed-form multicolor_disc (Shakura-Sunyaev, zero-torque) from disc.py. Rationale: grid look-ups are not JAX-jittable under gradient tape; analytic models are differentiable by construction.

  2. Analytic NLR/BLR templates, not grids: Synthesizer uses CLOUDY grids over (logU, log n_H) for both NLR and BLR emission. tengri uses empirically calibrated Gaussian line templates (Vanden Berk et al. 2001 for BLR; Groves et al. 2004 for NLR). Rationale: same as above.

  3. Smooth sigmoid mask, not a hard binary: Synthesizer zeros the disc and BLR when inclination + theta_torus > 90°, a hard step function. tengri replaces this with a smooth sigmoid (see _sigmoid_mask) centered at the same critical angle with a ~2° transition width. Rationale: the hard mask has zero gradient with respect to inclination almost everywhere, making gradient-based VI and HMC blind to inclination information near the critical angle.

  4. ``agn_torus_frac`` decoupled from ``theta_torus``: Synthesizer internally sets torus_fraction = theta_torus / 90°, coupling the reprocessed fraction to the geometric opening angle. tengri keeps agn_torus_frac as an independent free parameter. Rationale: auto-deriving from cos(theta_torus) in the forward pass introduces a gradient discontinuity at the poles (CLAUDE.md gotcha). The coupling can be enforced at the Parameters level via a fixed/derived param.

  5. Polar dust reddening (SMC law): agn_polar_ebv applies SMC extinction to the disc and BLR for Type 1 sightlines (mask > 0). Absent from Synthesizer’s basic UnifiedAGNIntrinsic; follows CIGALE skirtor2016 (Yang et al. 2020 [tengri.components.agn.unified.unified_nlr_blr-3]).

Geometry summary

\[L_{\rm AGN}(\lambda) = \sigma(i, \theta_t)\, A_{\rm pol,eff}(\lambda)\, L_{\rm disc}(\lambda) + L_{\rm torus}(\lambda) + f_{\rm NLR}\, \eta_{\rm NLR}(\lambda)\, L_{\rm bol,disc} + \sigma(i, \theta_t)\, A_{\rm pol,eff}(\lambda)\, f_{\rm BLR}\, \eta_{\rm BLR}(\lambda)\, L_{\rm bol,disc} + \mathbb{1}_{\rm X-ray} \, L_{\rm X-ray}(\lambda) + \mathbb{1}_{\rm radio} \, L_{\rm radio}(\lambda)\]

where \(\sigma(i, \theta_t)\) is the smooth sigmoid mask (1 = visible, 0 = obscured), \(A_{\rm pol,eff}(\lambda) = 1 + \sigma(i, \theta_t) \, (A_{\rm pol}(\lambda) - 1)\) is the visibility-weighted SMC polar dust transmission (SMC law; only reddens when disc is visible to the observer), \(f_{\rm NLR/BLR}\) are the covering fractions, \(\eta_{\rm NLR/BLR}\) are the normalized line templates, and \(\mathbb{1}_{\rm X-ray/radio}\) are indicator functions controlling whether X-ray and radio components are included.

Parameters:
  • wavelength (array, shape (n_wave,)) – Rest-frame wavelength [Angstrom].

  • agn_log_lbol (float) – \(\log_{10}(L_{\rm bol} / L_\odot)\): total AGN bolometric luminosity expressed in solar luminosities (not erg/s). Convert from synthesizer’s bolometric_luminosity [erg/s] via agn_log_lbol = log10(L_bol_erg) - log10(L_SUN_erg), i.e. subtract \(\approx 33.58\). Typical bright Seyfert: 10.5; bright quasar: 12.5. The default 44.0 is a legacy test fixture that is not a physical AGN luminosity: set this parameter explicitly. See module-level “Convention” note. Default 11.0.

  • agn_cos_inc (float) – Cosine of inclination angle (0 = edge-on/Type 2, 1 = face-on/Type 1). Synthesizer uses inclination in degrees; tengri uses cos(inclination). Default 0.5.

  • agn_theta_torus (float) – Torus half-opening angle [degrees]. Controls the critical inclination above which the disc and BLR are obscured. Same meaning as theta_torus in Synthesizer. Default 30.0.

  • agn_nlr_cf (float) – NLR covering fraction (0 to 1). Fraction of disc luminosity reprocessed into NLR emission. Synthesizer: covering_fraction_nlr. Default 0.1.

  • agn_blr_cf (float) – BLR covering fraction (0 to 1). Fraction of disc luminosity reprocessed into BLR emission. Synthesizer: covering_fraction_blr. Default 0.1.

  • agn_log_mbh (float) – log10(M_BH / Msun). Default 7.0.

  • agn_log_ledd (float) – log10(L/L_Edd). Default -1.0.

  • agn_a_spin (float) – BH spin (0 to 0.998). Default 0.0.

  • agn_T_hot (float) – Hot dust temperature [K]. Default 1200.

  • agn_T_warm (float) – Warm dust temperature [K]. Default 300.

  • agn_frac_hot (float) – Hot-to-warm dust fraction. Default 0.3.

  • agn_tau_torus (float) – Torus optical depth at 9.7 um. Default 5.

  • agn_torus_frac (float) – Torus covering factor (fraction of L_bol intercepted by torus). In Synthesizer this is derived as theta_torus / 90°; here it is an independent free parameter. Default 0.5.

  • agn_lum_ratio (float) – Overall AGN fraction scaling. Default 0.1.

  • agn_blr_fwhm (float) – BLR line FWHM [km/s]. Synthesizer uses velocity_dispersion_blr; tengri uses FWHM directly. Default 5000.

  • agn_nlr_fwhm (float) – NLR line FWHM [km/s]. Default 500.

  • agn_polar_ebv (float) – Polar dust E(B-V) applied to disc + BLR for Type 1 views (SMC law). Follows CIGALE skirtor2016 [tengri.components.agn.unified.unified_nlr_blr-3]. Not in Synthesizer’s basic UnifiedAGN. Default 0.0 (no reddening).

  • nlr_fn (callable or None) –

    NLR emission backend. Signature:

    nlr_fn(wavelength, l_disc_bol_erg, covering_fraction,
           fwhm_kms=500.0, **kwargs) -> ndarray, shape (n_wave,)
    

    where the return value is L_nu [erg/s/Hz]. Default None uses the built-in analytic template from compute_nlr_sed(). To use the Cue neural-net emulator, pass the result of make_cue_nlr_fn().

  • blr_fn (callable or None) – BLR emission backend. Same signature as nlr_fn. Default None uses the built-in analytic template from compute_blr_sed().

  • include_xray (bool) – If True, include X-ray corona emission. Default False (UV-optical-IR only).

  • xray_gamma_agn (float) – X-ray photon index (power-law slope). Default 1.8. Valid range: 1.4–2.4.

  • xray_alpha_ox (float) – Offset [dex] to the empirical alpha_OX (Just+2007). Default 0.0 (pure empirical). Negative values harden the corona, positive soften it. Valid range: -2.0 to -1.0 for typical AGN.

  • xray_E_cut (float) – X-ray exponential cutoff energy [keV]. Default 300.0.

  • include_radio (bool) – If True, include radio synchrotron + AGN radio jet emission. Default False.

  • radio_q_ir (float) – FIR–radio correlation parameter (Bell+2003 mode). Default 2.64.

  • radio_alpha_sf (float) – Star-forming synchrotron spectral index. Default 0.8.

  • radio_loudness (float) – AGN radio-loudness log10(L_5GHz/L_B). Default 0.0 (no radio AGN).

  • radio_alpha_agn (float) – AGN radio spectral index. Default 0.7.

Returns:

Total AGN L_nu [erg s^-1 Hz^-1].

Return type:

array, shape (n_wave,)

Notes

Traced FeII width: the FeII broadening is evaluated by a band-limited synthesis that is valid for a width of 500 km/s or more. A concrete width (a Python or NumPy scalar, as every model build passes: the width is a block keyword, not a fit parameter) below 500 km/s takes the exact full-lattice convolution, with no lower limit. A traced width (agn_blr_fwhm) below 500 km/s cannot raise inside a trace and returns NaN for the FeII spectrum and power, rather than a silently low-passed spectrum, so the same value is finite eager and NaN under jax.jit. Keep a traced width >= 500 km/s.

JIT/grad/vmap compatible when nlr_fn and blr_fn are JIT-compatible (the default analytic templates are; Cue-backed closures are also JIT-safe since the weights are closed over as static pytree leaves).

X-ray and radio components (when included):

When both include_xray=False and include_radio=False, the function returns the UV-optical-FIR unified AGN SED (original behavior). The new components are additive and do not affect existing parameters or output ranges.

References

[tengri.components.agn.unified.unified_nlr_blr-1] (1,2)

Lovell C. C. et al. 2025, Open Journal of Astrophysics, 8, “Synthesizer: a Software Package for Synthetic Astronomical Observables”, https://doi.org/10.33232/001c.145766

[tengri.components.agn.unified.unified_nlr_blr-2] (1,2)

Roper W. J. et al. 2026, Journal of Open Source Software, 11, 9436, “Synthesizer: Synthetic Observables for Modern Astronomy”, https://doi.org/10.21105/joss.09436 (Both Synthesizer papers [tengri.components.agn.unified.unified_nlr_blr-1] [tengri.components.agn.unified.unified_nlr_blr-2] must be cited together.)

[tengri.components.agn.unified.unified_nlr_blr-3] (1,2,3)

G. Yang et al. 2020, MNRAS, 491, 740, “X-CIGALE: Fitting AGN/galaxy SEDs from X-ray to infrared” (skirtor2016 module), https://doi.org/10.1093/mnras/stz3001

[tengri.components.agn.unified.unified_nlr_blr-4]

C. Ricci et al. 2017, ApJS, 233, 17, “Swift/BAT and XMM-Newton observations of the hard X-ray selected active galactic nuclei sample” (X-ray AGN sample), https://doi.org/10.3847/1538-4365/aa96ad

[tengri.components.agn.unified.unified_nlr_blr-5]

Murphy E.~J. et al. 2011, ApJ, 737, 67, “The Radio Flux and Infrared Properties of the GOODS-North Radio Sources”, https://doi.org/10.1088/0004-637X/737/2/67

Examples

>>> import jax.numpy as jnp
>>> from tengri.components.agn.unified import unified_nlr_blr
>>> wave = jnp.linspace(1000.0, 30000.0, 512)
>>> sed = unified_nlr_blr(wave, agn_log_lbol=11.42, agn_cos_inc=0.8)
>>> sed.shape
(512,)
>>> bool(jnp.all(sed >= 0))
True

AGN informative priors

Optional composite log-prior penalty terms implementing the same physics as AGNfitter-rX’s PRIORS_AGNfitter.py (energy balance, AGN-fraction luminosity-function ties, mid-IR/UV/X-ray consistency). Reachable as tengri.agn.priors (mirroring the dust-priors pattern above); wired into a fit via Fitter(..., extra_log_prior=...), see tengri.inference.loss_functions.build_logprior_fn().

Informative AGN prior penalty terms, implementing the same physics as AGNfitter-rX.

These are the eight optional, composite log-prior penalty terms AGNfitter-rX adds on top of the per-parameter priors (Uniform/Gaussian/etc.) when the corresponding modelsettings flag is enabled (PRIORS_AGNfitter.py:1-75, the PRIORS() dispatcher). Unlike per-parameter priors, each of these links multiple predicted quantities (e.g. the galaxy-attenuated luminosity against the starburst-emitted luminosity), so they cannot be expressed as a bound on a single free parameter.

Each function here is a pure, JIT/grad-safe JAX implementation of one upstream branch’s physics, taking the physical scalar(s) (luminosities/fluxes in erg/s or erg/s/Hz, magnitudes, redshift) that upstream’s own local variables hold immediately before the prior arithmetic – the array slicing, band selection, and de-reddening bookkeeping that upstream performs to compute those scalars from its internal model-dictionary objects is a separate, model-specific concern (see “Adapters” below), not part of the prior formula itself.

The eight priors

Function

Upstream

Lines

prior_energy_balance()

prior_energy_balance

78-106

prior_agn_fraction()

prior_AGNfraction

109-199

prior_stellar_mass()

prior_stellar_mass

201-210

prior_ir_syn_fraction()

prior_IR_SYNfraction

212-254

prior_uv_xrays()

prior_UV_xrays

256-299

prior_ir_xrays()

prior_IR_XRays

302-324

prior_midir_uv()

prior_midIR_UV

327-357

prior_low_agn_fraction()

prior_low_AGNfraction

360-425

AGNFITTER_HARD_REJECT (below) is upstream’s literal sentinel for “outside the physically-allowed region”: a large finite negative number (-9999), not -inf. Upstream’s own comment marks the ambivalence (return -9999 #-np.inf, PRIORS_AGNfitter.py:98). tengri reproduces the finite sentinel exactly, since a finite value stays gradient-safe (-inf has an ill-defined gradient at that point) and is what upstream’s own posteriors were actually computed with.

Gaussian normalization

Every Gaussian branch below is evaluated through gaussian_log_prior(), which includes the log(1/(sqrt(2*pi)*sigma)) normalization constant that upstream’s own shared Gaussian_prior helper carries (PRIORS_AGNfitter.py:428-430). The constant is irrelevant to posterior shape at fixed sigma (cancels in MCMC acceptance ratios) but is not irrelevant to a nested-sampling evidence (Z) integral – upstream explicitly supports ultranest as a sampler, and any comparison of evidences between models with different sigma needs it.

Adapters

Turning a tengri Prediction / ForwardState into the physical scalars each function above expects (rest-1500 A disc/galaxy fluxes, nu*L_nu(6 micron) of the torus, L_IR of the cold dust, …) is model-specific glue. Two routes, for two different jobs:

  • agnfitter_priors() – the convenience adapter, built on the public, rich predict() / Prediction.sed.components surface. Computes every prior’s physical inputs from that dict plus (for the priors that compare against actual data, not just model self-consistency) explicit data keyword arguments, and returns (total_log_prior, breakdown_dict). Not JIT-compatible (Prediction is a Python-cached exploration object per its own docstring) – for post-fit inspection / reporting, one prediction at a time.

  • Fitter(..., extra_log_prior=...) (see tengri.inference.loss_functions.build_logprior_fn() and build_loss_fn()) – the JIT-safe fitting hook. A user’s closure receives (params, state) where state is the internal ForwardState (model.predict_state(params), JIT/grad safe) and calls the prior functions directly on state.derived keys; this is the route that actually reaches MAP/VI/MCMC/nested-sampling optimization.

Breaking change (this rewrite)

The previous three functions in this module (agn_prior_energy_balance, agn_prior_agn_fraction_floor, agn_prior_midir_uv_tie) did not reproduce their cited upstream branches (missing the Gaussian normalization; the energy-balance “flexible” mode applied a Gaussian penalty instead of upstream’s unconditional 0; the AGN-fraction floor compared a bolometric ratio, not upstream’s redshift-dependent rest-1500 A flux-ratio branch) and had no callers anywhere in tengri (grep -rn outside this file and its own test returned nothing). They are removed rather than aliased.

Implements the same AGN prior penalties as AGNfitter-rX (Martinez-Ramirez et al. 2024, A&A, 688, A46, arXiv:2405.12111, doi:10.1051/0004-6361/202449329); validated against independent reimplementations of functions/PRIORS_AGNfitter.py (the validation oracle) in tests/crossval/test_agn_priors_vs_agnfitter.py.

tengri.parameters.agn_priors.AGNFITTER_HARD_REJECT = -9999.0

Upstream’s finite reject sentinel for a physically-disallowed region (PRIORS_AGNfitter.py:98,192: return -9999 #-np.inf). A finite value keeps jax.grad well-defined at the boundary (-inf does not); this is also the literal value upstream’s own posteriors were computed with, so it is reproduced exactly rather than “corrected” to -jnp.inf.

tengri.parameters.agn_priors.AGNFITTER_PRIOR_DEFAULTS: dict = {'agn_fraction': True, 'energy_balance': True, 'energy_balance_mode': 'flexible', 'ir_syn_fraction': False, 'ir_xrays': False, 'low_agn_fraction': False, 'midir_uv': False, 'stellar_mass': False, 'uv_xrays': False}

Default enable/mode settings, matching SETTINGS_AGNfitter.py (upstream example config, example/SETTINGS_AGNfitter.py:225-247): PRIOR_energy_balance='Flexible' (on, flexible), PRIOR_AGNfraction=True (on), PRIOR_midIR_UV=False (off), PRIOR_galaxy_only=False (off, this is the flag that selects prior_low_AGNfraction). XRAYS in that same file is the boolean True, which matches NEITHER of the two literal strings ('Prior_UV', 'Prior_midIR') the PRIORS() dispatcher actually branches on (PRIORS_AGNfitter.py:63,68) – i.e. upstream’s own shipped example, read literally, leaves both X-ray-tied priors OFF; tengri mirrors that literal reading rather than guessing an intended default. prior_ir_syn_fraction has no dedicated PRIOR_* flag upstream at all (gated directly on RADIO, PRIORS_AGNfitter.py:57); off by default here since it always needs explicit radio+IR data kwargs regardless.

tengri.parameters.agn_priors.agnfitter_priors(pred, *, redshift, dlum, torus_key: str = 'sed_agn', disc_key: str = 'sed_agn', dust_ir_key: str = 'sed_dust_ir', galaxy_key: str = 'sed_attenuated', energy_balance_mode: str = 'flexible', enable_energy_balance: bool = True, enable_stellar_mass: bool = False, enable_agn_fraction: bool = True, enable_low_agn_fraction: bool = False, enable_midir_uv: bool = False, enable_uv_xrays: bool = False, enable_ir_xrays: bool = False, enable_ir_syn_fraction: bool = False, ga=None, data_flux_1500=None, log_l2kev_data=None, log_f2_10kev_data=None, data_flux_rad=None, data_nu_rad=None, data_flux_ir=None, data_nu_ir=None)[source]

Evaluate the AGNfitter-rX informative priors on a tengri prediction.

Computes each enabled prior’s physical inputs from the PUBLIC prediction surface – pred.sed.components (rest-frame wavelength [Angstrom] plus per-component \(L_\nu\) [erg/s/Hz]: sed_intrinsic, sed_attenuated, sed_dust_ir, sed_agn, sed_xray, sed_radio) – and returns the total log-prior plus a per-prior breakdown.

Parameters:
  • pred (Prediction) – A single-galaxy prediction, model.predict(params).

  • redshift (float) – Source redshift [dimensionless]. Used by prior_agn_fraction() / prior_low_agn_fraction().

  • dlum (float) – Luminosity distance [cm]. Used by the same two functions.

  • torus_key (str, optional) – Which pred.sed.components key to read the torus 6-micron nu*L_nu and the disc 1500/2500 A flux from. Both default to "sed_agn" (disc+torus combined) – known approximation: this reads the disc and torus continua at the SAME wavelengths from the SAME combined array, so the 6-micron value carries whatever residual disc contributes there (small; discs fall steeply into the IR) and the 1500/2500 A values carry whatever residual torus contributes there (small; tori peak in the IR, torus UV is typically a scattered fraction). A later task publishes per-sub-block AGN SEDs (sed_agn_disc, sed_agn_torus); switching to those once available is a one-line change: torus_key="sed_agn_torus", disc_key="sed_agn_disc".

  • disc_key (str, optional) – Which pred.sed.components key to read the torus 6-micron nu*L_nu and the disc 1500/2500 A flux from. Both default to "sed_agn" (disc+torus combined) – known approximation: this reads the disc and torus continua at the SAME wavelengths from the SAME combined array, so the 6-micron value carries whatever residual disc contributes there (small; discs fall steeply into the IR) and the 1500/2500 A values carry whatever residual torus contributes there (small; tori peak in the IR, torus UV is typically a scattered fraction). A later task publishes per-sub-block AGN SEDs (sed_agn_disc, sed_agn_torus); switching to those once available is a one-line change: torus_key="sed_agn_torus", disc_key="sed_agn_disc".

  • dust_ir_key (str, optional) – pred.sed.components key for the cold-dust/starburst IR emission (prior_energy_balance()’s l_sb_emit). Default "sed_dust_ir".

  • galaxy_key (str, optional) – pred.sed.components key for the dust-attenuated stellar SED (used both as prior_energy_balance()’s attenuated-luminosity reference and as prior_agn_fraction()’s galaxy flux). Default "sed_attenuated".

  • energy_balance_mode ({"flexible", "restrictive"}, optional) – Passed to prior_energy_balance(). Default "flexible" (SETTINGS_AGNfitter.py’s PRIOR_energy_balance default).

  • enable_energy_balance (bool, optional) – Which of the eight priors to evaluate. Defaults are AGNFITTER_PRIOR_DEFAULTS, matching example/SETTINGS_AGNfitter.py where a corresponding PRIOR_* flag exists (see that dict’s own docstring for the two flags that do not map cleanly, and why).

  • enable_stellar_mass (bool, optional) – Which of the eight priors to evaluate. Defaults are AGNFITTER_PRIOR_DEFAULTS, matching example/SETTINGS_AGNfitter.py where a corresponding PRIOR_* flag exists (see that dict’s own docstring for the two flags that do not map cleanly, and why).

  • enable_agn_fraction (bool, optional) – Which of the eight priors to evaluate. Defaults are AGNFITTER_PRIOR_DEFAULTS, matching example/SETTINGS_AGNfitter.py where a corresponding PRIOR_* flag exists (see that dict’s own docstring for the two flags that do not map cleanly, and why).

  • enable_low_agn_fraction (bool, optional) – Which of the eight priors to evaluate. Defaults are AGNFITTER_PRIOR_DEFAULTS, matching example/SETTINGS_AGNfitter.py where a corresponding PRIOR_* flag exists (see that dict’s own docstring for the two flags that do not map cleanly, and why).

  • enable_midir_uv (bool, optional) – Which of the eight priors to evaluate. Defaults are AGNFITTER_PRIOR_DEFAULTS, matching example/SETTINGS_AGNfitter.py where a corresponding PRIOR_* flag exists (see that dict’s own docstring for the two flags that do not map cleanly, and why).

  • enable_uv_xrays (bool, optional) – Which of the eight priors to evaluate. Defaults are AGNFITTER_PRIOR_DEFAULTS, matching example/SETTINGS_AGNfitter.py where a corresponding PRIOR_* flag exists (see that dict’s own docstring for the two flags that do not map cleanly, and why).

  • enable_ir_xrays (bool, optional) – Which of the eight priors to evaluate. Defaults are AGNFITTER_PRIOR_DEFAULTS, matching example/SETTINGS_AGNfitter.py where a corresponding PRIOR_* flag exists (see that dict’s own docstring for the two flags that do not map cleanly, and why).

  • enable_ir_syn_fraction (bool, optional) – Which of the eight priors to evaluate. Defaults are AGNFITTER_PRIOR_DEFAULTS, matching example/SETTINGS_AGNfitter.py where a corresponding PRIOR_* flag exists (see that dict’s own docstring for the two flags that do not map cleanly, and why).

  • ga (float, optional) – Upstream’s raw galaxy flux-normalization scalar (GA), required only if enable_stellar_mass=True. tengri has no automatically -derived equivalent (it is a template-normalization exponent specific to upstream’s model-dictionary bookkeeping, not a published prediction quantity) – callers wanting this term supply it explicitly, e.g. from their own fit parameters if they have constructed an analogous quantity.

  • data_flux_1500 (float, optional) – Observed flux density at rest-frame 1500 A [erg/s/cm^2/Hz], required if enable_agn_fraction or enable_low_agn_fraction is True (both need prior_agn_fraction() / prior_low_agn_fraction()’s data_flux_1500, a genuinely observed quantity, not a model prediction).

  • log_l2kev_data (float, optional) – log10 of the observed luminosity density at rest-frame 2 keV [log10(erg/s/Hz)], required if enable_uv_xrays=True.

  • log_f2_10kev_data (float, optional) – log10 of the observed monochromatic flux at the 2-10 keV band center [log10(erg/s/Hz)], required if enable_ir_xrays=True.

  • data_flux_rad (float, optional) – Observed radio flux/frequency and cold-dust-peak flux/frequency (data_nu_* in log10(Hz)), required if enable_ir_syn_fraction=True. sb_flux_ir/syn_flux_ir (the model-side inputs to prior_ir_syn_fraction()) are read from dust_ir_key / sed_radio at the wavelength corresponding to data_nu_ir.

  • data_nu_rad (float, optional) – Observed radio flux/frequency and cold-dust-peak flux/frequency (data_nu_* in log10(Hz)), required if enable_ir_syn_fraction=True. sb_flux_ir/syn_flux_ir (the model-side inputs to prior_ir_syn_fraction()) are read from dust_ir_key / sed_radio at the wavelength corresponding to data_nu_ir.

  • data_flux_ir (float, optional) – Observed radio flux/frequency and cold-dust-peak flux/frequency (data_nu_* in log10(Hz)), required if enable_ir_syn_fraction=True. sb_flux_ir/syn_flux_ir (the model-side inputs to prior_ir_syn_fraction()) are read from dust_ir_key / sed_radio at the wavelength corresponding to data_nu_ir.

  • data_nu_ir (float, optional) – Observed radio flux/frequency and cold-dust-peak flux/frequency (data_nu_* in log10(Hz)), required if enable_ir_syn_fraction=True. sb_flux_ir/syn_flux_ir (the model-side inputs to prior_ir_syn_fraction()) are read from dust_ir_key / sed_radio at the wavelength corresponding to data_nu_ir.

Returns:

  • total (float or jnp.ndarray) – Sum of every enabled prior’s log-prior contribution.

  • breakdown (dict of str to (float or jnp.ndarray)) – Per-prior log-prior contribution, keyed by the same names as the enable_* parameters (without the enable_ prefix), for every ENABLED prior only.

Raises:

ValueError – If a prior is enabled but a required data keyword argument is None.

Notes

JIT-compatible: no. pred ( Prediction) is a Python-cached exploration object by its own docstring (“Not JIT-compatible (uses Python caching)”); this adapter is for post-fit inspection and reporting, one prediction at a time – not the fitting hot path. For fitting, use Fitter(..., extra_log_prior=...) directly on state.derived (JIT/grad-safe); see the module docstring’s “Adapters” section.

Grad-compatible: the arithmetic inside is JAX-differentiable, but since the whole function is not JIT-traced there is limited practical reason to differentiate through it; differentiate the individual prior functions directly if needed.

References

[tengri.parameters.agn_priors.agnfitter_priors-1]

L. N. Martinez-Ramirez et al., “AGNFITTER-RX: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A, 688, A46 (2024). arXiv:2405.12111. doi:10.1051/0004-6361/202449329.

Examples

>>> pred = model.predict(params)
>>> total, breakdown = agnfitter_priors(
...     pred,
...     redshift=1.0,
...     dlum=6.6e27,
...     data_flux_1500=3e-28,
... )
>>> breakdown.keys()
dict_keys(['energy_balance', 'agn_fraction'])
tengri.parameters.agn_priors.gaussian_log_prior(mu, sigma, par)[source]

Gaussian log-prior density, including the normalization constant.

\[\ln P(par) = \ln\!\left(\frac{1}{\sqrt{2\pi}\,\sigma}\right) - \frac{1}{2}\left(\frac{par - \mu}{\sigma}\right)^2\]

where \(\mu\) is the mean, \(\sigma\) the standard deviation, and \(par\) the value at which the density is evaluated (same units for all three).

Parameters:
  • mu (float) – Mean [same units as par].

  • sigma (float) – Standard deviation [same units as par]. Must be > 0.

  • par (float or jnp.ndarray) – Value(s) at which to evaluate the log-density.

Returns:

Log-probability density. Can exceed 0 when sigma < 1/sqrt(2*pi) (a density, not a bounded penalty).

Return type:

float or jnp.ndarray

Notes

JIT-compatible: yes. Grad-compatible: yes (smooth everywhere for sigma > 0).

Implements the same density as upstream’s shared Gaussian_prior helper (PRIORS_AGNfitter.py:428-430), including the normalization term that every prior below needs for evidence (Z) comparisons across different sigma (see module docstring).

References

[tengri.parameters.agn_priors.gaussian_log_prior-1]

G. Calistro Rivera et al., “AGNfitter: A Bayesian MCMC Approach to Fitting Spectral Energy Distributions of AGNs,” ApJ, 833, 98 (2016). arXiv:1606.05648. doi:10.3847/1538-4357/833/1/98.

tengri.parameters.agn_priors.prior_agn_fraction(bbb_flux_1500, gal_flux_1500, data_flux_1500, dlum, redshift)[source]

Soft prior tying the rest-1500 A AGN/galaxy flux ratio to a UV luminosity function.

\[ \begin{align}\begin{aligned}\mathrm{AGNfrac}_{1500} = \log_{10}\!\left(\frac{F_{bbb,1500}} {F_{gal,1500}}\right)\\m_{\rm abs} = 51.6 - 2.5\log_{10}\!\left(4\pi d_L^2\,F_{data,1500} \right)\end{aligned}\end{align} \]

with the characteristic magnitude \(M^*(z)\) of _characteristic_uv_magnitude(). Branch structure:

\[\begin{split}P = \begin{cases} \mathcal{N}(-2,\ 2^2;\ \mathrm{AGNfrac}_{1500}) & m_{\rm abs} > M^*(z) - 1 \quad \text{(galaxy regime)} \\ \text{AGNFITTER\_HARD\_REJECT} & m_{\rm abs} \leq M^*(z) - 1,\ \mathrm{AGNfrac}_{1500} < 0 \\ \mathcal{N}(+2,\ 2^2;\ \mathrm{AGNfrac}_{1500}) & m_{\rm abs} \leq M^*(z) - 1,\ \mathrm{AGNfrac}_{1500} \geq 0 \end{cases}\end{split}\]
Parameters:
  • bbb_flux_1500 (float) – Model accretion-disc (BBB) brightness at rest-frame 1500 A. Only the ratio bbb_flux_1500 / gal_flux_1500 enters this prior (see AGNfrac_1500 above), so this need not be a flux density in the strict [erg/s/cm^2/Hz] sense – any common normalization is accepted (flux density, specific luminosity L_nu [erg/s/Hz], or another quantity proportional to those), provided ``gal_flux_1500`` shares the same one. The public agnfitter_priors() adapter passes specific luminosity (L_nu), not flux density.

  • gal_flux_1500 (float) – Model galaxy brightness at rest-frame 1500 A, in the same units and normalization as bbb_flux_1500 – see that parameter’s Notes.

  • data_flux_1500 (float) – Observed flux density at rest-frame 1500 A [erg/s/cm^2/Hz]. Unlike bbb_flux_1500/gal_flux_1500 this enters only through abs_mag_data (an absolute magnitude, not a ratio), so it MUST be a genuine physical flux density – see the equation above.

  • dlum (float) – Luminosity distance [cm].

  • redshift (float) – Source redshift [dimensionless].

Returns:

Log-prior contribution. AGNFITTER_HARD_REJECT in the bright/QSO regime when the AGN is fainter than the galaxy at 1500 A (AGNfrac1500 < 0); a Gaussian log-density otherwise.

Return type:

float or jnp.ndarray

Notes

JIT-compatible: yes. Grad-compatible: yes, via jnp.where.

Implements the same prior as upstream’s prior_AGNfraction (PRIORS_AGNfitter.py:109-199), validated against it, specifically its branch tail (:170-198`). This operates on a rest-1500 A flux ratio gated by a redshift-dependent UV luminosity-function threshold, not a bolometric AGN-fraction floor – see the module docstring’s “Breaking change” note for what the previous (removed) tengri implementation did instead. Upstream sums this with prior_stellar_mass() under one settings flag; see that function’s Notes.

Upstream’s caller (PRIORS_AGNfitter.py:177-178) applies if BB==0: bbb_flux_1500Angs /= 4*pi*dlum**2 before computing AGNfrac1500 – a model-bookkeeping detail of the R06/THB21 accretion-disc normalization convention (BB there is the disc’s log10 flux-normalization scalar, and BB==0 flags “already physical, not a fittable amplitude”), not a physics term of this prior. Because only the bbb_flux_1500 / gal_flux_1500 ratio enters AGNfrac1500 (see Parameters above), that branch is intentionally not reproduced here regardless of which disc model or normalization convention the caller uses; the caller supplying bbb_flux_1500/gal_flux_1500 is responsible for using one common normalization for the pair.

References

[tengri.parameters.agn_priors.prior_agn_fraction-1]

L. N. Martinez-Ramirez et al., “AGNFITTER-RX: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A, 688, A46 (2024). arXiv:2405.12111. doi:10.1051/0004-6361/202449329.

[tengri.parameters.agn_priors.prior_agn_fraction-2]

Parsa, S. & Dunlop, J. S. et al. – characteristic UV luminosity-function magnitude fit used by _characteristic_uv_magnitude(); see that function’s Notes for the citation-year caveat.

tengri.parameters.agn_priors.prior_energy_balance(l_gal_att, l_sb_emit, mode: Literal['flexible', 'restrictive'] = 'flexible')[source]

Soft penalty enforcing galaxy-attenuated <= starburst-emitted luminosity.

Encodes the physical requirement that energy absorbed by dust in the galaxy screen must be re-emitted in the infrared: the model cannot emit less IR luminosity than it absorbed.

\[\begin{split}P = \begin{cases} \text{AGNFITTER\_HARD\_REJECT} & L_{sb,emit} < L_{gal,att} \quad \text{(both modes)} \\ 0 & L_{sb,emit} \geq L_{gal,att},\ \text{mode = "flexible"} \\ \mathcal{N}\!\left(0,\ 0.1^2;\ \log_{10}\frac{L_{sb,emit}}{L_{gal,att}} \right) & L_{sb,emit} \geq L_{gal,att},\ \text{mode = "restrictive"} \end{cases}\end{split}\]
Parameters:
  • l_gal_att (float) – Galaxy-attenuated (dust-absorbed) luminosity [erg/s].

  • l_sb_emit (float) – Starburst/cold-dust re-emitted IR luminosity [erg/s].

  • mode ({"flexible", "restrictive"}, optional) – "flexible": only a hard floor – zero penalty for any excess IR emission. "restrictive": additionally penalizes deviation from exact equality with a narrow (sigma=0.1) Gaussian. Default "flexible".

Returns:

Log-prior contribution. AGNFITTER_HARD_REJECT (-9999) if l_sb_emit < l_gal_att in EITHER mode (upstream’s if at PRIORS_AGNfitter.py:97-98 is outside the mode branches); else 0.0 (flexible) or a Gaussian log-density (restrictive).

Return type:

float or jnp.ndarray

Raises:

ValueError – If mode is not "flexible" or "restrictive".

Notes

JIT-compatible: yes (mode is a Python-level static string, not traced). Grad-compatible: yes, via jnp.where (both branches are always evaluated so no branch is ever pruned from the trace).

Implements the same prior as upstream’s prior_energy_balance (PRIORS_AGNfitter.py:78-106), validated against it. A prior implementation of this function in tengri (removed by this rewrite) applied the restrictive-mode Gaussian in flexible mode too, and never hard-rejected – see the module docstring’s “Breaking change” note.

References

[tengri.parameters.agn_priors.prior_energy_balance-1]

L. N. Martinez-Ramirez et al., “AGNFITTER-RX: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A, 688, A46 (2024). arXiv:2405.12111. doi:10.1051/0004-6361/202449329.

tengri.parameters.agn_priors.prior_ir_syn_fraction(data_flux_rad, data_nu_rad, data_flux_ir, data_nu_ir, sb_flux_ir, syn_flux_ir)[source]

Soft prior on the synchrotron/starburst flux fraction at the cold-dust peak.

\[ \begin{align}\begin{aligned}F_{\rm syn,exp} = F_{\rm rad}\left(\frac{\nu_{IR}}{\nu_{\rm rad}} \right)^{-0.75}\\\mathrm{SYNfrac}_{IR} = \log_{10}\!\left(\frac{F_{\rm syn}(\nu_{IR})} {F_{\rm sb}(\nu_{IR})}\right)\\\begin{split}P = \begin{cases} \mathcal{N}(+2,\ 2^2;\ \mathrm{SYNfrac}_{IR}) & F_{IR}/F_{\rm syn,exp} < 2 \\ \mathcal{N}(-2,\ 2^2;\ \mathrm{SYNfrac}_{IR}) & \text{otherwise} \end{cases}\end{split}\end{aligned}\end{align} \]
Parameters:
  • data_flux_rad (float) – Observed radio flux density (highest-frequency detection in the 0.1-10 GHz rest-frame window) [erg/s/cm^2/Hz].

  • data_nu_rad (float) – log10(frequency) [log10(Hz)] of data_flux_rad.

  • data_flux_ir (float) – Observed flux density at the cold-dust spectral peak [erg/s/cm^2/Hz].

  • data_nu_ir (float) – log10(frequency) [log10(Hz)] of data_flux_ir.

  • sb_flux_ir (float) – Model starburst/cold-dust flux density at data_nu_ir [erg/s/cm^2/Hz].

  • syn_flux_ir (float) – Model synchrotron flux density at data_nu_ir [erg/s/cm^2/Hz].

Returns:

Log-prior contribution: a Gaussian log-density with mean +2 (radio power law can already explain the IR peak – favor synchrotron) or -2 (it cannot – favor starburst), sigma=2 either way.

Return type:

float or jnp.ndarray

Notes

JIT-compatible: yes. Grad-compatible: yes, via jnp.where.

Implements the same prior as upstream’s prior_IR_SYNfraction (PRIORS_AGNfitter.py:212-254), validated against it, specifically its arithmetic core (:237-254`); the caller-level early-return-0 when no radio/IR data is present (:225-226,:232-233) is a data-availability check that belongs to the adapter computing these inputs, not to this formula. Upstream’s branch is undefined exactly AT the == 2 boundary (neither if nor elif fires, an upstream gap); this implementation resolves the tie to the < 2 branch’s complement (>= 2) rather than reproducing an undefined return.

References

[tengri.parameters.agn_priors.prior_ir_syn_fraction-1]

L. N. Martinez-Ramirez et al., “AGNFITTER-RX: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A, 688, A46 (2024). arXiv:2405.12111. doi:10.1051/0004-6361/202449329.

tengri.parameters.agn_priors.prior_ir_xrays(log_f2_10kev_data, nulnu_6um)[source]

Soft prior tying the torus mid-IR flux to the observed 2-10 keV flux.

\[ \begin{align}\begin{aligned}x = \log_{10}\!\left(\frac{\nu L_\nu(6\,\mu{\rm m})}{10^{41}\, {\rm erg/s}}\right)\\\log_{10}f_{2-10\,\rm keV}^{\rm pred} = 22.9494264 + 1.024\,x - 0.047\,x^2\\P = \mathcal{N}\!\left(0,\ 0.5^2;\ \log_{10}f_{2-10\,\rm keV}^{\rm data} - \log_{10}f_{2-10\,\rm keV}^{\rm pred}\right)\end{aligned}\end{align} \]
Parameters:
  • log_f2_10kev_data (float) – log10 of the observed monochromatic flux (luminosity) at the 2-10 keV band center [log10(erg/s/Hz)].

  • nulnu_6um (float) – nu*L_nu of the torus at rest-frame 6 microns [erg/s].

Returns:

Log-prior contribution (Gaussian log-density).

Return type:

float or jnp.ndarray

Notes

JIT-compatible: yes. Grad-compatible: yes.

Implements the same prior as upstream’s prior_IR_XRays (PRIORS_AGNfitter.py:302-324), validated against it, specifically the Stern (2015) mid-IR– X-ray correlation and Gaussian penalty (:309-322`). x is computed by _x_from_nulnu_6um(), shared with prior_midir_uv() – see that helper’s Notes for why the two priors must agree on x for the same physical input.

References

[tengri.parameters.agn_priors.prior_ir_xrays-1]

D. Stern, “The X-Ray to Mid-Infrared Relation of AGNs at High Luminosity,” ApJ, 807, 129 (2015). doi:10.1088/0004-637X/807/2/129. arXiv:1506.00162. bibcode:2015ApJ…807..129S. Cited by upstream’s in-line comment at PRIORS_AGNfitter.py:310.

tengri.parameters.agn_priors.prior_low_agn_fraction(bbb_flux_1500, gal_flux_1500, data_flux_1500, dlum, redshift)[source]

Soft prior favoring a galaxy-dominated rest-1500 A flux ratio.

\[\begin{split}P = \begin{cases} \mathcal{N}(-2,\ 0.5^2;\ \mathrm{AGNfrac}_{1500}) & m_{\rm abs} > M^*(z) - 3 \\ \mathcal{N}(-2,\ 2^2;\ \mathrm{AGNfrac}_{1500}) & \text{otherwise} \end{cases}\end{split}\]

with \(\mathrm{AGNfrac}_{1500}\) and \(m_{\rm abs}\) as in prior_agn_fraction().

Parameters:
  • bbb_flux_1500 (float) – Model accretion-disc (BBB) brightness at rest-frame 1500 A. Only the ratio bbb_flux_1500 / gal_flux_1500 enters this prior (same AGNfrac_1500 as prior_agn_fraction()), so this need not be a flux density in the strict [erg/s/cm^2/Hz] sense – any common normalization is accepted (flux density, specific luminosity L_nu [erg/s/Hz], or another quantity proportional to those), provided ``gal_flux_1500`` shares the same one. See prior_agn_fraction()’s Parameters for the full discussion; the public agnfitter_priors() adapter passes specific luminosity (L_nu), not flux density.

  • gal_flux_1500 (float) – Model galaxy brightness at rest-frame 1500 A, in the same units and normalization as bbb_flux_1500 – see that parameter’s Notes.

  • data_flux_1500 (float) – Observed flux density at rest-frame 1500 A [erg/s/cm^2/Hz]. Unlike bbb_flux_1500/gal_flux_1500 this enters only through abs_mag_data (an absolute magnitude, not a ratio), so it MUST be a genuine physical flux density.

  • dlum (float) – Luminosity distance [cm].

  • redshift (float) – Source redshift [dimensionless].

Returns:

Log-prior contribution: a Gaussian log-density, mean -2 in both regimes, narrower (sigma=0.5) when the source is UV-faint relative to the (redshift-dependent, -3 mag offset) luminosity-function threshold, wider (sigma=2) otherwise. No hard-reject branch (unlike prior_agn_fraction()).

Return type:

float or jnp.ndarray

Notes

JIT-compatible: yes. Grad-compatible: yes, via jnp.where.

Implements the same prior as upstream’s prior_low_AGNfraction (PRIORS_AGNfitter.py:360-425), validated against it, specifically its branch tail (:412-423). Distinct from prior_agn_fraction(): same mean (-2) in both regimes here (vs. -2/+2 there), a -3 mag threshold offset (vs. -1), different sigma values (0.5/2 vs. 2/2), and no hard-reject branch at all. A prior tengri implementation of the AGN-fraction floor (removed by this rewrite) had accidentally borrowed this function’s mu=-2, sigma=0.5 constants while citing prior_AGNfraction – see the module docstring’s “Breaking change” note.

Unlike prior_agn_fraction(), upstream’s prior_low_AGNfraction (PRIORS_AGNfitter.py:360-425) has no if BB==0 caller-side normalization branch on bbb_flux_1500Angs at all (verified by reading the full function body: no such conditional appears there) – that branch is specific to prior_AGNfraction; see that function’s Notes.

References

[tengri.parameters.agn_priors.prior_low_agn_fraction-1]

L. N. Martinez-Ramirez et al., “AGNFITTER-RX: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A, 688, A46 (2024). arXiv:2405.12111. doi:10.1051/0004-6361/202449329.

[tengri.parameters.agn_priors.prior_low_agn_fraction-2]

Parsa, S. & Dunlop, J. S. et al. – see _characteristic_uv_magnitude() Notes for the citation-year caveat.

tengri.parameters.agn_priors.prior_midir_uv(log_l2500a_bbmodel, nulnu_6um)[source]

Soft prior tying the accretion-disc UV luminosity to the torus mid-IR flux.

Predicts an accretion-disc UV luminosity FROM the torus’s 6-micron emission by composing the Stern (2015) mid-IR–X-ray correlation with the Just+2007 alpha_ox X-ray–UV correlation – not a direct \(L_{\rm mir} = L_{\rm uv}\) comparison.

\[ \begin{align}\begin{aligned}x = \log_{10}\!\left(\frac{\nu L_\nu(6\,\mu{\rm m})\ [{\rm erg/s}]} {10^{41}\,{\rm erg/s}}\right)\\\log_{10}L_{2500\,\rm A}^{\rm pred} = \frac{16.2530786 + 1.024\,x - 0.047\,x^2}{0.643}\\P = \mathcal{N}\!\left(0,\ 0.6^2;\ \log_{10}L_{2500\,\rm A}^{\rm bb} - \log_{10}L_{2500\,\rm A}^{\rm pred}\right)\end{aligned}\end{align} \]
Parameters:
  • log_l2500a_bbmodel (float) – log10 of the model’s (unreddened) accretion-disc luminosity density at rest-frame 2500 A [log10(erg/s/Hz)].

  • nulnu_6um (float) – nu*L_nu of the torus at rest-frame 6 microns [erg/s]. Same physical quantity, and same units, as prior_ir_xrays()’s nulnu_6um.

Returns:

Log-prior contribution (Gaussian log-density).

Return type:

float or jnp.ndarray

Notes

JIT-compatible: yes. Grad-compatible: yes.

Implements the same prior as upstream’s prior_midIR_UV (PRIORS_AGNfitter.py:327-357), validated against it, specifically the composite correlation and Gaussian penalty (:333-355`). x is computed by _x_from_nulnu_6um(); upstream’s own formula for this x (log10(tor_flux_6microns*lumfactor) - 27.30103, a SPECIFIC luminosity L_nu, not nu*L_nu) is algebraically identical to that helper’s nu*L_nu form once the -13.69897 frequency offset is accounted for – see the helper’s Notes for the derivation and the bug it fixes (a previous version of this function took the nu*L_nu input but applied the L_nu-calibrated -27.30103 offset directly, off by log10(nu_6um) = 13.69897 in x).

The sigma=0.6 combines the mid-IR–X-ray scatter (~0.5, prior_ir_xrays()) with the alpha_ox scatter (~0.1, per upstream’s in-line comment at PRIORS_AGNfitter.py:354). A prior tengri implementation (removed well before this revision) compared \(L_{\rm mir}\) and \(L_{\rm uv}\) directly – see the module docstring’s “Breaking change” note; at equal nominal log-luminosities that comparison and this one disagree by hundreds of dex, because equal luminosities are nowhere near this correlation’s mean relation.

References

[tengri.parameters.agn_priors.prior_midir_uv-1]

D. Stern, “The X-Ray to Mid-Infrared Relation of AGNs at High Luminosity,” ApJ, 807, 129 (2015). doi:10.1088/0004-637X/807/2/129. arXiv:1506.00162. bibcode:2015ApJ…807..129S – mid-IR–X-ray correlation; see prior_ir_xrays() References for the full citation.

[tengri.parameters.agn_priors.prior_midir_uv-2]

D. W. Just et al., 2007, ApJ, 665, 1004 – alpha_ox correlation; see prior_uv_xrays() Notes for the citation-verification caveat.

tengri.parameters.agn_priors.prior_stellar_mass(ga)[source]

Soft Gaussian prior on the raw galaxy flux-normalization scalar.

\[P = \mathcal{N}(4.5,\ 1.5^2;\ GA)\]
Parameters:

ga (float) – Galaxy (host stellar) flux-normalization scalar, upstream’s GA – the log10 amplitude multiplying the galaxy template flux (Lgal = GALAXYFdict[...] * 10**GA). Dimensionless (a log10 normalization exponent, not a luminosity).

Returns:

Log-prior contribution (Gaussian log-density; can exceed 0).

Return type:

float or jnp.ndarray

Notes

JIT-compatible: yes. Grad-compatible: yes.

Implements the same prior as upstream’s prior_stellar_mass (PRIORS_AGNfitter.py:201-210), validated against it: GA < 3 upstream’s comment reads corresponds to \(M_* < 10^9\,M_\odot\). Upstream sums this with prior_agn_fraction() under a single PRIOR_AGNfraction settings flag (prior1 + prior2 at PRIORS_AGNfitter.py:46-48); tengri keeps them as two functions so a caller can enable either independently.

References

[tengri.parameters.agn_priors.prior_stellar_mass-1]

L. N. Martinez-Ramirez et al., “AGNFITTER-RX: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A, 688, A46 (2024). arXiv:2405.12111. doi:10.1051/0004-6361/202449329.

tengri.parameters.agn_priors.prior_uv_xrays(log_l2500a_data, log_l2kev_data)[source]

Soft prior tying the accretion-disc UV luminosity to the observed X-ray flux.

\[ \begin{align}\begin{aligned}\log_{10}L_{2500\,\rm A}^{\rm pred} = \frac{\log_{10}L_{2\,\rm keV} - \gamma}{\beta},\quad \beta = 0.643,\ \gamma = 6.8734\\P = \mathcal{N}\!\left(0,\ 0.4^2;\ \log_{10}L_{2500\,\rm A}^{\rm data} - \log_{10}L_{2500\,\rm A}^{\rm pred}\right)\end{aligned}\end{align} \]
Parameters:
  • log_l2500a_data (float) – log10 of the model’s dereddened accretion-disc luminosity density at rest-frame 2500 A [log10(erg/s/Hz)].

  • log_l2kev_data (float) – log10 of the observed luminosity density at rest-frame 2 keV [log10(erg/s/Hz)].

Returns:

Log-prior contribution (Gaussian log-density).

Return type:

float or jnp.ndarray

Notes

JIT-compatible: yes. Grad-compatible: yes.

Implements the same prior as upstream’s prior_UV_xrays (PRIORS_AGNfitter.py:256-299), validated against it, specifically the alpha_OX inverse relation and Gaussian penalty (:258-265,:291-297`). Upstream’s own in-line docstring for alpha_OX attributes the (beta, gamma) coefficients to “Lusso&Risaliti +16 gives beta=[0.6-0.65], gamma=[7-8]” (:260`), while the caller-site comment two functions up names “the alpha_ox correlation by Just et al. 2007” (:64`) for the same relation – upstream cites both for one formula; both are reproduced faithfully below rather than resolved.

References

[tengri.parameters.agn_priors.prior_uv_xrays-1]

E. Lusso & G. Risaliti, 2016, ApJ, 819, 154. (beta, gamma range cited by upstream’s alpha_OX docstring; exact DOI/arXiv not independently re-verified beyond tengri’s existing xray-component citation of this same journal reference, src/tengri/components/xray/xray.py.)

[tengri.parameters.agn_priors.prior_uv_xrays-2]

D. W. Just et al., 2007, ApJ, 665, 1004. (named by upstream’s caller-site comment for this same correlation, PRIORS_AGNfitter.py:64; title and DOI disagree between two existing citations of this same journal reference inside tengri’s own xray.py, so neither is repeated here – see prior_ir_xrays() Notes.)

AGN template-library grid reductions (AGNfitter-rX)

Additional AGNfitter-rX torus/disc grid reductions, vendored at native resolution and validated against the upstream library.

AGNfitter-rX’s Kubota & Done (2018) grid-tabulated accretion-disc library.

Two node-exact template grids, interpolated from HDF5 files built by scripts/build_kd18_grid.py from AGNfitter-rX’s KD18.pickle / KD18_warmInd.pickle:

  • kd18_agnfitter_sed() – 2-D grid over (log M_BH, log Mdot/Mdot_Edd).

  • kd18_agnfitter_warmindex_sed() – 3-D grid adding the warm Comptonization spectral index (AGNfitter-rX’s warmIndex).

A one-time measurement compared the two pickles at each candidate warmIndex value (matched node-by-node on (logBHmass, logEddra)): even the closest match disagreed by up to a factor of 1.27 at some wavelength, so the two are vendored and interpolated as independent grids rather than one grid at a fixed warmIndex (see scripts/build_kd18_grid.py module docstring for the measurement).

Both templates already carry AGNfitter-rX’s hot corona (the wavelength axis extends to \(\lambda \approx 0.06\) A, hard X-ray): the KD18 and KD18_warmIndex branches of AGNfitter-rX never call add_xrays. tengri’s own composable xray group must not be layered on top of either block for the same reason (see check_disc_xray_double_count).

Uses the same template library as AGNfitter-rX (Martinez-Ramirez et al. 2024 [tengri.components.agn.kd18_agnfitter-2]); validated against its output.

References

[tengri.components.agn.kd18_agnfitter-1]

A. Kubota and C. Done, “A physical model of the broad-band continuum of AGN and its implications for the UV/X relation and optical variability,” MNRAS, 480, 1247 (2018). doi:10.1093/mnras/sty1890. arXiv:1804.00171. bibcode:2018MNRAS.480.1247K.

[tengri.components.agn.kd18_agnfitter-2]

L. N. Martinez-Ramirez, et al., “AGNFITTER-RX: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A, 688, A46 (2024). doi:10.1051/0004-6361/202449329. arXiv:2405.12111.

class tengri.components.agn.kd18_agnfitter.KD18AGNfitterGrid(template: jnp.ndarray, wave_grid: jnp.ndarray, log_mbh: jnp.ndarray, log_edd: jnp.ndarray)[source]

Bases: NamedTuple

AGNfitter-rX KD18 disc template arrays, as a JAX pytree.

Variables:
  • template (ndarray, shape (n_mbh, n_edd, n_wave)) – Tabulated disc SEDs [shape only; renormalized on use].

  • wave_grid (ndarray, shape (n_wave,)) – Template rest-frame wavelength grid. [Angstrom]

  • log_mbh (ndarray, shape (n_mbh,)) – Grid axis, \(\log_{10}(M_{\rm BH}/M_\odot)\).

  • log_edd (ndarray, shape (n_edd,)) – Grid axis, \(\log_{10}(\dot M/\dot M_{\rm Edd})\).

log_edd: Array

Alias for field number 3

log_mbh: Array

Alias for field number 2

template: Array

Alias for field number 0

wave_grid: Array

Alias for field number 1

class tengri.components.agn.kd18_agnfitter.KD18AGNfitterWarmIndexGrid(template: jnp.ndarray, wave_grid: jnp.ndarray, log_mbh: jnp.ndarray, log_edd: jnp.ndarray, gamma_warm: jnp.ndarray)[source]

Bases: NamedTuple

AGNfitter-rX KD18-warmIndex disc template arrays, as a JAX pytree.

Variables:
  • template (ndarray, shape (n_mbh, n_edd, n_gamma_warm, n_wave)) – Tabulated disc SEDs [shape only; renormalized on use].

  • wave_grid (ndarray, shape (n_wave,)) – Template rest-frame wavelength grid. [Angstrom]

  • log_mbh (ndarray, shape (n_mbh,)) – Grid axis, \(\log_{10}(M_{\rm BH}/M_\odot)\).

  • log_edd (ndarray, shape (n_edd,)) – Grid axis, \(\log_{10}(\dot M/\dot M_{\rm Edd})\).

  • gamma_warm (ndarray, shape (n_gamma_warm,)) – Grid axis, warm Comptonization spectral index (AGNfitter-rX warmIndex; Kubota & Done 2018).

gamma_warm: Array

Alias for field number 4

log_edd: Array

Alias for field number 3

log_mbh: Array

Alias for field number 2

template: Array

Alias for field number 0

wave_grid: Array

Alias for field number 1

tengri.components.agn.kd18_agnfitter.create_kd18_agnfitter_from_grid(grid_path: str) → Callable[source]

Load the KD18-agnfitter grid and return a JAX-native interpolation closure.

Returns:

fn(wavelength, agn_log_lbol, agn_log_mbh, agn_log_ledd, **_) -> L_nu [erg/s/Hz].

Return type:

callable

Notes

JIT-compatible: yes, pure jnp and node-exact bilinear interpolation (same rationale as tengri.components.agn.slone_netzer.create_slone_netzer_from_grid(): the disc peak wavelength varies strongly with accretion rate, so bilinear – node-exact – is used rather than a smooth kernel).

tengri.components.agn.kd18_agnfitter.create_kd18_agnfitter_warmindex_from_grid(grid_path: str) → Callable[source]

Load the KD18-agnfitter-warmindex grid and return a JAX-native closure.

Returns:

fn(wavelength, agn_log_lbol, agn_log_mbh, agn_log_ledd, agn_gamma_warm, **_) -> L_nu [erg/s/Hz].

Return type:

callable

Notes

JIT-compatible: yes, pure jnp and node-exact trilinear interpolation (the 3-axis analog of create_kd18_agnfitter_from_grid()’s bilinear).

tengri.components.agn.kd18_agnfitter.kd18_agnfitter_grid_support() → dict[str, tuple[float, float]][source]

Parameter support of the shipped KD18-agnfitter grid, read from its own axes.

Mirrors tengri.components.agn.slone_netzer.slone_netzer_grid_support() (#1586): the closure built by create_kd18_agnfitter_from_grid() holds both parameters at these axes, so a value outside them collapses onto the edge node. agn_log_ledd overhangs its axis by 0.5 dex (a physical gap, not a numerical one), so it is not extrapolated; this registry entry is what reports it.

Returns:

support – {'agn_log_mbh': (lo, hi), 'agn_log_ledd': (lo, hi)}.

Return type:

dict[str, tuple[float, float]]

Raises:

FileNotFoundError – If the packaged grid is not installed.

Notes

JIT-compatible: not applicable; composition-time only. Cached.

tengri.components.agn.kd18_agnfitter.kd18_agnfitter_sed(*args, _template: KD18AGNfitterGrid | None = None, **kwargs) → Array[source]

AGNfitter-rX KD18 disc (auto-loaded from the packaged HDF5 grid).

Parameters:

_template (KD18AGNfitterGrid, optional) – Pre-loaded grid, threaded in as a JIT argument by the forward model. When None (default) the packaged grid is loaded from disk.

Returns:

Spectral luminosity density. [erg/s/Hz]

Return type:

ndarray, shape (n_wave,)

tengri.components.agn.kd18_agnfitter.kd18_agnfitter_sed_from_grid(grid: KD18AGNfitterGrid, wavelength: Array, agn_log_lbol: float = 10.0, agn_log_mbh: float = 7.0, agn_log_ledd: float = -1.0, **_kwargs) → Array[source]

AGNfitter-rX KD18 disc SED at a single (M_BH, Mdot/Mdot_Edd).

Parameters:
  • grid (KD18AGNfitterGrid) – Template arrays, passed as an argument so they thread through JIT.

  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength grid. [Angstrom]

  • agn_log_lbol (float, optional) – log10(L_bol / L_sun). Default 11.0.

  • agn_log_mbh (float, optional) – log10(M_BH / M_sun). Default 7.0 (on-grid: the KD18 grid’s log_mbh axis is [6, 10], identical to the shared declaration).

  • agn_log_ledd (float, optional) – log10(Mdot / Mdot_Edd). Default -1.0 (on-grid: the KD18 grid’s log_edd axis is [-1.5, 0]).

Returns:

Spectral luminosity density. [erg/s/Hz]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes.

tengri.components.agn.kd18_agnfitter.kd18_agnfitter_warmindex_grid_support() → dict[str, tuple[float, float]][source]

Parameter support of the shipped KD18-agnfitter-warmindex grid.

Mirrors kd18_agnfitter_grid_support() (#1586), with the added agn_gamma_warm axis.

Returns:

support – {'agn_log_mbh': (lo, hi), 'agn_log_ledd': (lo, hi), 'agn_gamma_warm': (lo, hi)}.

Return type:

dict[str, tuple[float, float]]

Raises:

FileNotFoundError – If the packaged grid is not installed.

Notes

JIT-compatible: not applicable; composition-time only. Cached.

tengri.components.agn.kd18_agnfitter.kd18_agnfitter_warmindex_sed(*args, _template: KD18AGNfitterWarmIndexGrid | None = None, **kwargs) → Array[source]

AGNfitter-rX KD18-warmIndex disc (auto-loaded from the packaged HDF5 grid).

Parameters:

_template (KD18AGNfitterWarmIndexGrid, optional) – Pre-loaded grid, threaded in as a JIT argument by the forward model. When None (default) the packaged grid is loaded from disk.

Returns:

Spectral luminosity density. [erg/s/Hz]

Return type:

ndarray, shape (n_wave,)

tengri.components.agn.kd18_agnfitter.kd18_agnfitter_warmindex_sed_from_grid(grid: KD18AGNfitterWarmIndexGrid, wavelength: Array, agn_log_lbol: float = 10.0, agn_log_mbh: float = 7.0, agn_log_ledd: float = -1.0, agn_gamma_warm: float = 2.5, **_kwargs) → Array[source]

AGNfitter-rX KD18-warmIndex disc SED at a single grid point.

Parameters:
  • grid (KD18AGNfitterWarmIndexGrid) – Template arrays, passed as an argument so they thread through JIT.

  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength grid. [Angstrom]

  • agn_log_lbol (float, optional) – log10(L_bol / L_sun). Default 11.0.

  • agn_log_mbh (float, optional) – log10(M_BH / M_sun). Default 7.0 (on-grid).

  • agn_log_ledd (float, optional) – log10(Mdot / Mdot_Edd). Default -1.0 (on-grid).

  • agn_gamma_warm (float, optional) – Warm Comptonization spectral index (AGNfitter-rX warmIndex). Default 2.5 (the shared agn_gamma_warm declared default; on-grid, the KD18-warmIndex axis is [1.5, 4.0]).

Returns:

Spectral luminosity density. [erg/s/Hz]

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes. Trilinear interpolation over the three grid axes: node-exact at any grid corner, same rationale as the 2-D bilinear case (a smooth kernel is not node-exact and would smear the disc peak).

tengri.components.agn.kd18_agnfitter.load_kd18_agnfitter_default_grid() → KD18AGNfitterGrid[source]

Load the packaged KD18-agnfitter grid pytree (discovery + cache).

This is the template_loader the kd18_agnfitter disc block registers.

Return type:

KD18AGNfitterGrid

Raises:

FileNotFoundError – If no KD18-agnfitter grid HDF5 is present on disk.

tengri.components.agn.kd18_agnfitter.load_kd18_agnfitter_grid(grid_path: str) → KD18AGNfitterGrid[source]

Load a KD18-agnfitter grid HDF5 into a KD18AGNfitterGrid pytree.

Notes

JIT-compatible: no, performs HDF5 I/O. Call outside the trace.

tengri.components.agn.kd18_agnfitter.load_kd18_agnfitter_warmindex_default_grid() → KD18AGNfitterWarmIndexGrid[source]

Load the packaged KD18-agnfitter-warmindex grid pytree (discovery + cache).

This is the template_loader the kd18_agnfitter_warmindex disc block registers.

Return type:

KD18AGNfitterWarmIndexGrid

Raises:

FileNotFoundError – If no KD18-agnfitter-warmindex grid HDF5 is present on disk.

tengri.components.agn.kd18_agnfitter.load_kd18_agnfitter_warmindex_grid(grid_path: str) → KD18AGNfitterWarmIndexGrid[source]

Load a KD18-agnfitter-warmindex grid HDF5 into a pytree.

Notes

JIT-compatible: no, performs HDF5 I/O. Call outside the trace.

Nenkova et al. (2008) CLUMPY AGN torus, two-parameter AGNfitter-rX reduction.

Two-parameter torus library keyed on inclination angle (agn_cos_inc) and half-opening angle (agn_oa_nenkova), interpolated node-exactly (monotone cubic / PCHIP) so gradients flow cleanly through both axes during HMC / geoVI / MAP inference. This is the NK0_mean_2p reduction from AGNfitter-rX – one axis wider than tengri.components.agn.nenkova_agnfitter (the NK0_mean_1p inclination-only reduction), which stays unchanged and uses a narrower, disjoint inclination extent (10-90 deg, not 0-90 deg).

Grid provenance

Template data published with AGNfitter-rX (Martínez-Ramírez et al. 2024): see scripts/build_agnfitter_torus_reductions.py. The AGNfitter-rX pickle (NK0_mean_2p.pickle, a pandas DataFrame) stores one shared log10(nu / Hz) axis and a per-(inclination, opening-angle) F_nu row; the build script converts to ascending wavelength [Å] at native resolution (the upstream axis is common to every row, so no resampling is performed) and reshapes into a rectangular (n_incl, n_oa, n_wave) grid. This runtime module only consumes the HDF5, not the pickle.

Axis semantics

agn_cos_inc

Cosine of inclination (1 = face-on, 0 = edge-on); shared with every other cos-inclination-parametrized torus in tengri.

agn_oa_nenkova

Half-opening angle of the CLUMPY torus [deg]. Range: 15-70 deg (NK0_mean_2p grid extent).

Runtime normalization

CLUMPY fluxes are normalized to the bolometric AGN flux F_AGN = L / 4 pi D^2 in every direction (Nenkova et al. 2008, ApJ 685, 160, Sect. 2 and 3.6), so the records share one scale across inclination; the AGNfitter-rX reductions are linear means on it (NK0_mean_3p averaged over its optical-depth axis is NK0_mean_2p to 5e-4). The template is therefore emitted as two factors (_torus_inclination.torus_lnu_anisotropic): the shape of the records normalized to unit power and interpolated as before, and the records’ own powers over their model’s mean, a scalar table interpolated with the same node-exact PCHIP. The angle-integrated torus power is L_bol * agn_torus_frac, each sightline keeps the library’s flux relative to the others, and the shape between nodes is the per-sightline one exactly.

References

[tengri.components.agn.nenkova_agnfitter_2p-1]

M. Nenkova, M. M. Sirocky, R. Nikutta, Z. Ivezic, and M. Elitzur, “AGN Dusty Tori. II. Observational Implications of Clumpiness,” ApJ 685, 160 (2008). doi:10.1086/590483. arXiv:0806.0512. bibcode:2008ApJ…685..160N.

[tengri.components.agn.nenkova_agnfitter_2p-2]

L. N. Martínez-Ramírez et al., “AGNfitter-rx: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A 688, A46 (2024). arXiv:2405.12111. DOI: 10.1051/0004-6361/202449329.

tengri.components.agn.nenkova_agnfitter_2p.TORUS_INCLINATION = (0, 'cos_inc', False)

the records share one radiative-transfer scale across inclination, so the template carries its anisotropy as a scalar factor (_torus_inclination.torus_lnu_anisotropic).

Type:

The library’s inclination axis

tengri.components.agn.nenkova_agnfitter_2p.create_nenkova_agnfitter_2p_from_grid(grid_path: str) → Callable[source]

Load a NK0_mean_2p grid and bind it to the SED evaluator.

Parameters:

grid_path (str) – Path to nenkova_agnfitter_2p_torus_grid.h5.

Return type:

callable

tengri.components.agn.nenkova_agnfitter_2p.nenkova_agnfitter_2p_sed(*args, _template: TorusTemplateGrid | None = None, **kwargs) → Array[source]

Nenkova+08 AGN torus, NK0_mean_2p reduction (auto-loaded from disk).

Wraps create_nenkova_agnfitter_2p_from_grid() with on-disk grid discovery.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength grid. [Å]

  • agn_log_lbol (float, optional) – log10(L_bol / L_sun). Default 10.0.

  • agn_cos_inc (float, optional) – Cosine of inclination (1 = face-on). Default matches CIGALE i=30.

  • agn_oa_nenkova (float, optional) – Half-opening angle [deg]. Default 40.0.

  • agn_torus_frac (float, optional) – Torus reprocessing fraction. Default 0.5.

  • **kwargs – Accepted and ignored for unified-dispatch compatibility.

Returns:

Spectral luminosity density. [erg/s/Hz]

Return type:

ndarray, shape (n_wave,)

Raises:

FileNotFoundError – If no NK0_mean_2p grid HDF5 is present on disk.

References

[tengri.components.agn.nenkova_agnfitter_2p.nenkova_agnfitter_2p_sed-1]

M. Nenkova, M. M. Sirocky, R. Nikutta, Z. Ivezic, and M. Elitzur, “AGN Dusty Tori. II. Observational Implications of Clumpiness,” ApJ 685, 160 (2008). doi:10.1086/590483. arXiv:0806.0512. bibcode:2008ApJ…685..160N.

[tengri.components.agn.nenkova_agnfitter_2p.nenkova_agnfitter_2p_sed-2]

L. N. Martínez-Ramírez et al., “AGNfitter-rx: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A 688, A46 (2024). arXiv:2405.12111.

Nenkova et al. (2008) CLUMPY AGN torus, three-parameter AGNfitter-rX reduction.

Three-parameter torus library keyed on inclination angle (agn_cos_inc), half-opening angle (agn_oa_nenkova), and equatorial optical depth (agn_tv_nenkova), interpolated node-exactly (monotone cubic / PCHIP) so gradients flow cleanly through every axis during HMC / geoVI / MAP inference. This is the NK0_mean_3p reduction from AGNfitter-rX – the full three-parameter sub-library, one axis wider than tengri.components.agn.nenkova_agnfitter_2p (NK0_mean_2p, which shares the same inclination and opening-angle extents).

Grid provenance

Template data published with AGNfitter-rX (Martínez-Ramírez et al. 2024): see scripts/build_agnfitter_torus_reductions.py. The AGNfitter-rX pickle (NK0_mean_3p.pickle, a pandas DataFrame) stores one shared log10(nu / Hz) axis and a per-(inclination, opening-angle, optical-depth) F_nu row; the build script converts to ascending wavelength [Å] at native resolution (the upstream axis is common to every row, so no resampling is performed) and reshapes into a rectangular (n_incl, n_oa, n_tv, n_wave) grid. This runtime module only consumes the HDF5, not the pickle.

Axis semantics

agn_cos_inc

Cosine of inclination (1 = face-on, 0 = edge-on); shared with every other cos-inclination-parametrized torus in tengri.

agn_oa_nenkova

Half-opening angle of the CLUMPY torus [deg]. Range: 15-70 deg.

agn_tv_nenkova

Equatorial optical depth. Range: 10-300 (NK0_mean_3p grid extent).

Runtime normalization

CLUMPY fluxes are normalized to the bolometric AGN flux F_AGN = L / 4 pi D^2 in every direction (Nenkova et al. 2008, ApJ 685, 160, Sect. 2 and 3.6), so the records share one scale across inclination; the AGNfitter-rX reductions are linear means on it (NK0_mean_3p averaged over its optical-depth axis is NK0_mean_2p to 5e-4). The template is therefore emitted as two factors (_torus_inclination.torus_lnu_anisotropic): the shape of the records normalized to unit power and interpolated as before, and the records’ own powers over their model’s mean, a scalar table interpolated with the same node-exact PCHIP. The angle-integrated torus power is L_bol * agn_torus_frac, each sightline keeps the library’s flux relative to the others, and the shape between nodes is the per-sightline one exactly.

References

[tengri.components.agn.nenkova_agnfitter_3p-1]

M. Nenkova, M. M. Sirocky, R. Nikutta, Z. Ivezic, and M. Elitzur, “AGN Dusty Tori. II. Observational Implications of Clumpiness,” ApJ 685, 160 (2008). doi:10.1086/590483. arXiv:0806.0512. bibcode:2008ApJ…685..160N.

[tengri.components.agn.nenkova_agnfitter_3p-2]

L. N. Martínez-Ramírez et al., “AGNfitter-rx: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A 688, A46 (2024). arXiv:2405.12111. DOI: 10.1051/0004-6361/202449329.

tengri.components.agn.nenkova_agnfitter_3p.TORUS_INCLINATION = (0, 'cos_inc', False)

the records share one radiative-transfer scale across inclination, so the template carries its anisotropy as a scalar factor (_torus_inclination.torus_lnu_anisotropic).

Type:

The library’s inclination axis

tengri.components.agn.nenkova_agnfitter_3p.create_nenkova_agnfitter_3p_from_grid(grid_path: str) → Callable[source]

Load a NK0_mean_3p grid and bind it to the SED evaluator.

Parameters:

grid_path (str) – Path to nenkova_agnfitter_3p_torus_grid.h5.

Return type:

callable

tengri.components.agn.nenkova_agnfitter_3p.nenkova_agnfitter_3p_sed(*args, _template: TorusTemplateGrid | None = None, **kwargs) → Array[source]

Nenkova+08 AGN torus, NK0_mean_3p reduction (auto-loaded from disk).

Wraps create_nenkova_agnfitter_3p_from_grid() with on-disk grid discovery.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength grid. [Å]

  • agn_log_lbol (float, optional) – log10(L_bol / L_sun). Default 10.0.

  • agn_cos_inc (float, optional) – Cosine of inclination (1 = face-on). Default matches CIGALE i=30.

  • agn_oa_nenkova (float, optional) – Half-opening angle [deg]. Default 40.0.

  • agn_tv_nenkova (float, optional) – Equatorial optical depth. Default 60.0.

  • agn_torus_frac (float, optional) – Torus reprocessing fraction. Default 0.5.

  • **kwargs – Accepted and ignored for unified-dispatch compatibility.

Returns:

Spectral luminosity density. [erg/s/Hz]

Return type:

ndarray, shape (n_wave,)

Raises:

FileNotFoundError – If no NK0_mean_3p grid HDF5 is present on disk.

References

[tengri.components.agn.nenkova_agnfitter_3p.nenkova_agnfitter_3p_sed-1]

M. Nenkova, M. M. Sirocky, R. Nikutta, Z. Ivezic, and M. Elitzur, “AGN Dusty Tori. II. Observational Implications of Clumpiness,” ApJ 685, 160 (2008). doi:10.1086/590483. arXiv:0806.0512. bibcode:2008ApJ…685..160N.

[tengri.components.agn.nenkova_agnfitter_3p.nenkova_agnfitter_3p_sed-2]

L. N. Martínez-Ramírez et al., “AGNfitter-rx: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A 688, A46 (2024). arXiv:2405.12111.

SKIRTOR-averaged (mean_1p) clumpy torus library (Stalevski et al. 2016).

One-parameter torus library interpolated differentiably in inclination over a precomputed HDF5 grid derived from AGNfitter-rX’s SKIRTOR_mean_1p.pickle. The sightline is the model’s one inclination, agn_cos_inc.

This is the coarsest of the three SKIRTOR-AGNfitter reductions tengri ships: tengri.components.agn.skirtor_agnfitter (SKIRTOR_mean_3p, three axes) is the AGNfitter-faithful default; tengri.components.agn.skirtor_agnfitter_2p (SKIRTOR_mean_2p) adds the opening-angle axis; this module averages over both opening angle and optical depth, retaining only inclination. All three share the same inclination axis convention and extent (0-90 deg).

Axis semantics

incl_axis

Inclination angle \(i\) measured from the polar axis [deg]. Range: 0-90 deg. 0 = face-on, 90 = edge-on. Keyed by agn_cos_inc (\(\cos i\)) through _skirtor_agnfitter_sightline.skirtor_incl_from_cos_inc, \(i = \arccos(\cos i)\).

Runtime normalization

SKIRTOR computes every model for one central source luminosity (Stalevski et al. 2016, Sect. 2.1), so its records share one scale across inclination. The stored inclination power ratios equal those of the SKIRTOR v3 records (multiplied back by their norm) averaged over tau, p, q, opening angle and radius ratio to 0.4 % at every node, so the reduction is on that scale (face-on/edge-on 2.12). The template is therefore emitted as two factors (_torus_inclination.torus_lnu_anisotropic): the shape of the records normalized to unit power and interpolated as before, and the records’ own powers over their model’s mean, a scalar table interpolated with the same node-exact PCHIP. The angle-integrated torus power is L_bol * agn_torus_frac, each sightline keeps the library’s flux relative to the others, and the shape between nodes is the per-sightline one exactly.

References

[tengri.components.agn.skirtor_agnfitter_1p-1]

M. Stalevski et al., “3D radiative transfer modeling of the dusty torus around AGN, the influence of clumping,” MNRAS, 420, 2756 (2012). arXiv:1109.1286. https://doi.org/10.1111/j.1365-2966.2011.19775.x

[tengri.components.agn.skirtor_agnfitter_1p-2]

M. Stalevski, C. Ricci, Y. Ueda, P. Lira, J. Fritz, and M. Baes, “The dust covering factor in active galactic nuclei,” MNRAS, 458, 2288 (2016). arXiv:1602.06954. bibcode:2016MNRAS.458.2288S. https://doi.org/10.1093/mnras/stw444

[tengri.components.agn.skirtor_agnfitter_1p-3]

L. N. Martinez-Ramirez, et al., “AGNFITTER-RX: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A 688, A46 (2024). arXiv:2405.12111.

tengri.components.agn.skirtor_agnfitter_1p.TORUS_INCLINATION = (0, 'incl_deg', False)

the records share one radiative-transfer scale across inclination, so the template carries its anisotropy as a scalar factor (_torus_inclination.torus_lnu_anisotropic).

Type:

The library’s inclination axis

tengri.components.agn.skirtor_agnfitter_1p.create_skirtor_agnfitter_1p_from_grid(grid_path: str) → Callable[source]

Load a SKIRTOR_mean_1p grid and bind it to the SED evaluator.

Parameters:

grid_path (str) – Path to skirtor_mean1p_torus_grid.h5.

Return type:

callable

tengri.components.agn.skirtor_agnfitter_1p.skirtor_agnfitter_1p_sed(*args, _template: TorusTemplateGrid | None = None, **kwargs) → Array[source]

SKIRTOR_mean_1p torus (auto-loaded from the packaged HDF5 grid).

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength. [Å]

  • agn_log_lbol (float, optional) – log10(L_bol / L_sun). Default 10.0.

  • agn_cos_inc (float, optional) – \(\cos i\), the model’s one inclination (1 = face-on) [dimensionless]. Default cos(30 deg).

  • agn_torus_frac (float, optional) – Torus reprocessing fraction. Default 0.5.

  • **kwargs – Accepted and ignored for unified-dispatch compatibility.

Returns:

Torus SED [erg/s/Hz].

Return type:

ndarray, shape (n_wave,)

Notes

This function auto-discovers the grid file from the package data directory or the current working directory. To use a non-standard grid location, call create_skirtor_agnfitter_1p_from_grid() directly.

SKIRTOR-averaged (mean_2p) clumpy torus library (Stalevski et al. 2016).

Two-parameter torus library interpolated differentiably in (agn_oa_skirtor, agn_cos_inc) over a precomputed HDF5 grid derived from AGNfitter-rX’s SKIRTOR_mean_2p.pickle.

Sits between tengri.components.agn.skirtor_agnfitter_1p (SKIRTOR_mean_1p, inclination only) and tengri.components.agn.skirtor_agnfitter (SKIRTOR_mean_3p, the AGNfitter-faithful default that adds the equatorial optical depth axis). All three share the same opening-angle (10-80 deg) and inclination (0-90 deg) extents.

Axis semantics

agn_oa_skirtor

Half-opening angle of the torus [deg]. Range: 10-80 deg.

incl_axis

Inclination angle \(i\) measured from the polar axis [deg]. Range: 0-90 deg. 0 = face-on, 90 = edge-on. Keyed by agn_cos_inc (\(\cos i\)) through _skirtor_agnfitter_sightline.skirtor_incl_from_cos_inc, \(i = \arccos(\cos i)\).

Runtime normalization

Template is shape-only. At runtime the module divides by the trapezoidal integral over frequency and multiplies by L_bol * agn_torus_frac, mirroring tengri.components.agn.skirtor_agnfitter.

References

[tengri.components.agn.skirtor_agnfitter_2p-1]

M. Stalevski et al., “3D radiative transfer modeling of the dusty torus around AGN, the influence of clumping,” MNRAS, 420, 2756 (2012). arXiv:1109.1286. https://doi.org/10.1111/j.1365-2966.2011.19775.x

[tengri.components.agn.skirtor_agnfitter_2p-2]

M. Stalevski, C. Ricci, Y. Ueda, P. Lira, J. Fritz, and M. Baes, “The dust covering factor in active galactic nuclei,” MNRAS, 458, 2288 (2016). arXiv:1602.06954. bibcode:2016MNRAS.458.2288S. https://doi.org/10.1093/mnras/stw444

[tengri.components.agn.skirtor_agnfitter_2p-3]

L. N. Martinez-Ramirez, et al., “AGNFITTER-RX: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A 688, A46 (2024). arXiv:2405.12111.

tengri.components.agn.skirtor_agnfitter_2p.create_skirtor_agnfitter_2p_from_grid(grid_path: str) → Callable[source]

Load a SKIRTOR_mean_2p grid and bind it to the SED evaluator.

Parameters:

grid_path (str) – Path to skirtor_mean2p_torus_grid.h5.

Return type:

callable

tengri.components.agn.skirtor_agnfitter_2p.skirtor_agnfitter_2p_sed(*args, _template: TorusTemplateGrid | None = None, **kwargs) → Array[source]

SKIRTOR_mean_2p torus (auto-loaded from the packaged HDF5 grid).

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength. [Å]

  • agn_log_lbol (float, optional) – log10(L_bol / L_sun). Default 11.0.

  • agn_oa_skirtor (float, optional) – Half-opening angle [deg]. Default 40.0.

  • agn_cos_inc (float, optional) – \(\cos i\), the model’s one inclination, \(i\) from the polar axis (1 = face-on) [dimensionless]. Default cos(30 deg), the declared agn_cos_inc default. The library is keyed at \(i = \arccos(\cos i)\) [deg]; the retired agn_incl_skirtor [deg] is translated with a DeprecationWarning.

  • agn_torus_frac (float, optional) – Torus reprocessing fraction. Default 0.5.

  • **kwargs – Accepted and ignored for unified-dispatch compatibility.

Returns:

Torus SED [erg/s/Hz].

Return type:

ndarray, shape (n_wave,)

Notes

This function auto-discovers the grid file from the package data directory or the current working directory. To use a non-standard grid location, call create_skirtor_agnfitter_2p_from_grid() directly.

CAT3D-Wind clumpy-disc-plus-polar-wind AGN torus, low-wind-fraction reduction (Hönig & Kishimoto 2017).

Three-parameter torus library interpolated differentiably in (agn_cos_inc, agn_a_cat3d_lowfwd, agn_fwd_cat3d_lowfwd) over a precomputed HDF5 grid derived from AGNfitter-rX’s CAT3D_mean_3p.pickle.

AGNfitter-rX’s CAT3D_mean_3p pickle concatenates two disjoint three-parameter sub-libraries at different rows: rows 0-209 (this module) cover a low polar-wind mass fraction range (fwd 0.15-0.75) at a wider radial power-law-index range (a -3 to -0.5); rows 210-377 (tengri.components.agn.cat3d_wind, the reduction AGNfitter-rX’s own fitter code selects by default) cover a high wind-fraction range (fwd 1.0-2.25) at a narrower radial-index range (a -3 to -1.5). The two sub-libraries do not overlap in (a, fwd) and are therefore vendored as two independent grids rather than one, each a full Cartesian rectangle in its own right (unlike the high-fwd sub-library, this low-fwd one is a complete Cartesian product – no nearest-neighbor cell filling is needed).

Axis semantics

agn_cos_inc

Cosine of inclination (1 = face-on, 0 = edge-on). The grid’s native incl_axis is stored in degrees; this module converts at load time, matching tengri.components.agn.cat3d_wind.

agn_a_cat3d_lowfwd

Radial power-law index of the clumpy-cloud distribution (Hönig & Kishimoto 2017 parameter a). Range: -3.0 to -0.5.

agn_fwd_cat3d_lowfwd

Polar-wind mass fraction (fwd). Range: 0.15 to 0.75.

Runtime normalization

Template is shape-only. At runtime the module divides by the trapezoidal integral over frequency and multiplies by L_bol * agn_torus_frac, mirroring tengri.components.agn.cat3d_wind.

Interpolation

Node-exact monotone cubic (PCHIP, tengri.utils.grid_interp.interp_nd_pchip()), matching tengri.components.agn.cat3d_wind.

References

[tengri.components.agn.cat3d_wind_lowfwd-1]

S. F. Hönig & M. Kishimoto, “Dusty winds in active galactic nuclei: reconciling observations with models,” ApJL 838, L20 (2017). arXiv:1703.07781.

[tengri.components.agn.cat3d_wind_lowfwd-2]

L. N. Martínez-Ramírez, G. Calistro Rivera, E. Lusso, et al., “AGNfitter-rx: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A 688, A46 (2024). arXiv:2405.12111. DOI: 10.1051/0004-6361/202449329.

tengri.components.agn.cat3d_wind_lowfwd.cat3d_wind_lowfwd_sed(*args, _template: TorusTemplateGrid | None = None, **kwargs) → Array[source]

CAT3D-Wind low-fwd torus (auto-loaded from tabulated templates).

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength grid. [Å]

  • agn_log_lbol (float, optional) – log10(L_bol / L_sun). Default 10.0.

  • agn_cos_inc (float, optional) – Cosine of inclination (1 = face-on). Default matches CIGALE i=30.

  • agn_a_cat3d_lowfwd (float, optional) – Radial power-law index. Default -2.0.

  • agn_fwd_cat3d_lowfwd (float, optional) – Polar-wind mass fraction. Default 0.45.

  • agn_torus_frac (float, optional) – Torus reprocessing fraction. Default 0.5.

  • **kwargs – Accepted and ignored for unified-dispatch compatibility.

Returns:

Spectral luminosity density. [erg/s/Hz]

Return type:

ndarray, shape (n_wave,)

Raises:

FileNotFoundError – If no CAT3D-Wind low-fwd grid HDF5 is present on disk.

References

[tengri.components.agn.cat3d_wind_lowfwd.cat3d_wind_lowfwd_sed-1]
    1. Hönig & M. Kishimoto, ApJL 838, L20 (2017). arXiv:1703.07781.

[tengri.components.agn.cat3d_wind_lowfwd.cat3d_wind_lowfwd_sed-2]
    1. Martínez-Ramírez et al., A&A 688, A46 (2024). arXiv:2405.12111.

tengri.components.agn.cat3d_wind_lowfwd.create_cat3d_wind_lowfwd_from_grid(grid_path: str) → Callable[source]

Load a CAT3D-Wind low-fwd grid and bind it to the SED evaluator.

Parameters:

grid_path (str) – Path to cat3d_wind_lowfwd_torus_grid.h5.

Return type:

callable

Legacy AGN template-library modules

Torus/disc template libraries and their SEDModelComponent adapters that predate the AGNfitter-rX parity branch (opt-in alternatives to the default AGNSEDComponent registry entries above). Each adapter class names its own loader module under “See Also” in its docstring.

SKIRTOR clumpy two-phase torus model (Stalevski et al. 2012, 2016).

Loads the full SKIRTOR SED library (create_skirtor_from_grid) and performs 5D node-exact PCHIP interpolation in JAX. Passes through every tabulated node and provides C¹-continuous gradients for inference (VI, MAP, NUTS). Requires a prior download of the template grid (~1 GB).

Supports two HDF5 layouts:

  • v2 (legacy): single spectra/torus_emission array (total only).

  • v3: separate spectra/disk_emission, spectra/dust_emission, and spectra/torus_emission. Matches the CIGALE skirtor2016 processing convention (disk = direct + scattered, both divided by wavelength, normalized so dust thermal integrates to 1 W).

All functions are pure JAX and JIT-compilable.

References

[tengri.components.agn.skirtor-1]

M. Stalevski et al., “3D radiative transfer modeling of the dusty torus around AGN, the influence of clumping,” MNRAS, 420, 2756 (2012). arXiv:1109.1286. https://doi.org/10.1111/j.1365-2966.2011.19775.x

[tengri.components.agn.skirtor-2]

M. Stalevski, C. Ricci, Y. Ueda, P. Lira, J. Fritz, and M. Baes, “The dust covering factor in active galactic nuclei,” MNRAS, 458, 2288 (2016). arXiv:1602.06954. bibcode:2016MNRAS.458.2288S. https://doi.org/10.1093/mnras/stw444

class tengri.components.agn.skirtor.SKIRTORBundle(torus: SKIRTORGrid, disc_dust: SkirtorDiscDustGrid | None)[source]

Bases: NamedTuple

Both SKIRTOR libraries the composable AGN path needs, as one pytree.

The torus block interpolates the dust cube, while the runner’s CIGALE-joint normalization separately needs the raw disk/dust pair to form the ratio \(R\). Both are template libraries and both must thread, so one loader returns both rather than leaving the second to load itself mid-trace and bake ~20 MB in.

Variables:
  • torus (SKIRTORGrid) – Dust-cube grid consumed by skirtor_sed().

  • disc_dust (SkirtorDiscDustGrid or None) – (disk, dust, wave_grid, axes, norm) for skirtor_disc_dust_ratio(); None when the on-disk grid predates the v3 split and carries no separate disk component.

disc_dust: SkirtorDiscDustGrid | None

Alias for field number 1

torus: SKIRTORGrid

Alias for field number 0

class tengri.components.agn.skirtor.SKIRTORComponents(disk: Array, dust: Array, total: Array)[source]

Bases: NamedTuple

Separate SKIRTOR spectral components.

Variables:
  • disk (jnp.ndarray, shape (n_wave,)) – Accretion disk emission (direct + scattered) [erg/s/Hz].

  • dust (jnp.ndarray, shape (n_wave,)) – Dust thermal emission from the torus [erg/s/Hz].

  • total (jnp.ndarray, shape (n_wave,)) – Total emission (disk + dust) [erg/s/Hz].

Notes

This is a lightweight container for decomposed SKIRTOR output. All arrays are rest-frame rest-frame spectral luminosity densities. The total field is the sum of disk and dust.

disk: Array

Alias for field number 0

dust: Array

Alias for field number 1

total: Array

Alias for field number 2

class tengri.components.agn.skirtor.SKIRTORDiscAttenGrid(disk: Array, wave_grid: Array, axes: tuple[Array, ...], edges: tuple[Array, ...], norm: Array | None = None)[source]

Bases: NamedTuple

SKIRTOR disc-column arrays for the inclination attenuation ratio.

Carried as a pytree so the forward model can thread the ~10 MB disc cube into jax.jit as an argument instead of closing over it, which would freeze it into the graph as Constant ops (#1383).

Variables:
  • disk (ndarray) – SKIRTOR disc template cube.

  • wave_grid (ndarray, shape (n_wave,)) – Template rest-frame wavelength grid [Angstrom].

  • axes (tuple of ndarray) – The SKIRTOR parameter axes.

  • edges (tuple of ndarray) – Triweight bin edges derived from axes.

  • norm (ndarray, shape (*axes_shape), or None) – The per-record scale divided out of disk (no wavelength axis), so that disk * norm is comparable between inclinations. None for a file that carries no norm dataset.

axes: tuple[Array, ...]

Alias for field number 2

disk: Array

Alias for field number 0

edges: tuple[Array, ...]

Alias for field number 3

norm: Array | None

Alias for field number 4

wave_grid: Array

Alias for field number 1

class tengri.components.agn.skirtor.SKIRTORGrid(grid: Array, wave_grid: Array, axes: tuple, edges: tuple)[source]

Bases: NamedTuple

Threadable SKIRTOR template arrays, a JAX pytree.

Holds the interpolation grid as pure array data so it threads through jax.jit as a runtime input (small compile), instead of baking into the trace as a constant or (worse) being threaded as a Python closure, which JAX cannot treat as a traced argument (issue #1198).

Variables:
  • grid (ndarray) – Template luminosity cube (dust-only for v3 grids, total for v2).

  • wave_grid (ndarray, shape (n_wave,)) – Template rest-frame wavelength grid. [Å]

  • axes (tuple of ndarray) – Parameter-axis node values (tau, p, q, oa, radius, inc).

  • edges (tuple of ndarray) – Per-axis triweight-kernel bin edges.

axes: tuple

Alias for field number 2

edges: tuple

Alias for field number 3

grid: Array

Alias for field number 0

wave_grid: Array

Alias for field number 1

class tengri.components.agn.skirtor.SkirtorDiscDustGrid(disk: Array, dust: Array, wave_grid: Array, axes: tuple, norm: Array | None)[source]

Bases: NamedTuple

The CIGALE-lineage SKIRTOR disk/dust library, as one threadable pytree.

Read from data/skirtor_templates_v3.h5 (the full 6-axis grid), which is the only SKIRTOR file tengri ships that carries separate disk and dust components and the per-cell norm beside them. The AGNfitter-rX reductions (skirtor_mean{1,2,3}p_torus_grid.h5, behind the skirtor_agnfitter* blocks) are inclination-averaged dust-only libraries with no such split and no norm; they are loaded by their own modules and never reach here.

The field order is positional-compatible with the plain (disk, dust, wave_grid, axes) tuple this replaced, so grid[3] is still the axes.

Variables:
  • disk (jnp.ndarray, shape (*axes_shape, n_native)) – Accretion-disc (direct + scattered) template \(L_\lambda\), divided by the cell’s norm. [normalized]

  • dust (jnp.ndarray, shape (*axes_shape, n_native)) – Torus thermal template \(L_\lambda\), divided by the same norm, hence of unit integral over the native grid (10 on the Angstrom axis). [normalized]

  • wave_grid (jnp.ndarray, shape (n_native,)) – The templates’ native wavelength grid [A].

  • axes (tuple of jnp.ndarray) – Strictly-ascending parameter axes (tau, p, q, oa, R, cos_inc) (a legacy 5-axis grid drops R).

  • norm (jnp.ndarray, shape (*axes_shape), or None) – The physical scale divided out of disk and dust, per parameter cell and with no wavelength axis: see _load_grid_arrays(). None for a grid that carries the component split without it, in which case skirtor_disc_dust_ratio() leaves the inclination normalization at 1.0 and says so.

axes: tuple

Alias for field number 3

disk: Array

Alias for field number 0

dust: Array

Alias for field number 1

norm: Array | None

Alias for field number 4

wave_grid: Array

Alias for field number 2

class tengri.components.agn.skirtor.SkirtorDiscTie(R: Array, incl_ratio: Array, R_faceon: Array, faceon_shape_native: Array, wave_native: Array, incl_native: Array | None = None)[source]

Bases: NamedTuple

What the CIGALE-joint disc normalization reads off the SKIRTOR pair.

Every field is measured on the SKIRTOR templates’ native wavelength grid, which is the grid CIGALE integrates on (skirtor2016.py uses x=AGN1.wl and x=self.SKIRTOR2016.wl throughout, never the model’s output grid) and the only grid on which the disk/dust integral ratio is undistorted – resampling those templates onto a caller grid moves the ratio by ~10%.

Variables:
  • R (jnp.ndarray, scalar) – Reddened, inclination-weighted disc/dust bolometric ratio \(\int \hat s\,\int{\rm disk}(0)\,{\rm disk}(i)/{\rm disk}(0)\,e^{-\tau}\,d\lambda / \int {\rm dust}(i)\,d\lambda\): what the disc output is normalized to via agn_power x R. The library ratio disk(i)/disk(0) carries the disc anisotropy \(\eta(i)\), so no explicit \(\eta\) enters.

  • incl_ratio (jnp.ndarray, shape (n_wave,)) – disk(i)/disk(0), resampled onto the CALLER’s grid (it multiplies the caller’s disc spectrum, so it is the one field that belongs there).

  • R_faceon (jnp.ndarray, scalar) – Face-on, UN-reddened ratio \({\rm norm}(0)/{\rm norm}(i) \int disk(i=0)/\int dust(i)\): the scale CIGALE’s polar l_ext proxy is referenced to. The norm(0)/norm(i) factor is the CIGALE-lineage grid’s own stored inclination normalization (see SkirtorDiscDustGrid), without which the face-on disc and the observer-inclination dust sit on different luminosity scales and this ratio comes out inclination-FLAT (R64).

  • faceon_shape_native (jnp.ndarray, shape (n_native,)) – The analytic disc shape resampled onto wave_native and normalized to unit integral there, i.e. CIGALE’s AGN1.disk / int_disk0. Multiplying it by agn_power * R_faceon reproduces CIGALE’s AGN1.disk on its own grid; unit-normalizing the same shape on a caller grid instead makes the polar share depend on that grid’s extent (measured: 11.0% for the skirtor disc block between 8-1e8 A and 500-1e8 A).

  • wave_native (jnp.ndarray, shape (n_native,)) – The SKIRTOR template wavelength grid faceon_shape_native is defined and unit-normalized on [A].

  • incl_native (jnp.ndarray, shape (n_native,)) – disk(i)/disk(0) on wave_native: what incl_ratio is resampled from, so the disc’s reweighted bolometric can be integrated on the library grid without touching the caller’s.

R: Array

Alias for field number 0

R_faceon: Array

Alias for field number 2

faceon_shape_native: Array

Alias for field number 3

incl_native: Array | None

Alias for field number 5

incl_ratio: Array

Alias for field number 1

wave_native: Array

Alias for field number 4

tengri.components.agn.skirtor.create_skirtor_components_from_grid(grid_path: str) → Callable[source]

Load SKIRTOR v3 templates and return a function giving separate components.

Requires a v3 HDF5 grid with spectra/disk_emission and spectra/dust_emission datasets (produced by scripts/download_skirtor_templates.py).

Parameters:

grid_path (str) – Path to a v3 SKIRTOR HDF5 file.

Returns:

Function with signature:

fn(wavelength, agn_log_lbol, ..., frac_agn, **kwargs)
    -> SKIRTORComponents(disk, dust, total)

Each component is in [erg s^-1 Hz^-1].

Return type:

callable

Raises:

KeyError – If the grid lacks spectra/disk_emission or spectra/dust_emission.

Notes

JIT-compatible: yes, the returned function is pure JAX. Grid loading is cached via @functools.cache.

Gradient-safe: yes, node-exact PCHIP interpolation is C1 in every coordinate.

Interpolation. Every parameter axis (tau, p, q, opening angle, radius ratio) and the inclination axis (\(\cos i\)) is interpolated with the monotone piecewise cubic of Fritsch & Carlson [tengri.components.agn.skirtor.create_skirtor_components_from_grid-3] (interp_nd_pchip()), applied one axis at a time. It passes exactly through the tabulated records, so the component along a library inclination IS the stored record times the common scale below; an axis of two nodes is linear (the PCHIP of two nodes). A coordinate outside a parameter axis is clamped to its end node; the inclination axis alone continues its end cubic, so the prior’s cos_inc = 0 (the stored axis starts at 6e-17) keeps a nonzero gradient. That extension is a numerical gap of a few 1e-17, not physics; the normalization below does not depend on the sightline, so it cannot change that gradient.

Normalization. The library stores every record divided by its own dust integral (spectra/norm holds the divisor), which erases the flux ratio between inclinations. The components here are the stored spectra multiplied back by that factor, interpolated, and scaled by ONE factor per parameter point, \(s = L_{\rm scale} / (\bar P_{\rm disc} + \bar P_{\rm dust})\), with \(L_{\rm scale} = 10^{\log L_{\rm bol}} L_\odot f\) (\(f\) = frac_agn) and

\[\bar P_X = \int_0^1 P_X(\mu)\,d\mu, \qquad \mu = \cos i,\]

the sphere mean of the power \(P_X(\mu) = \int L_\nu\,d\nu\) that the template carries along inclination \(\mu\), over the template’s own wavelength range (10 A to 1e8 A): the escaping disc (direct plus scattered) and the dust re-emission. SKIRTOR’s radiative transfer conserves energy, so these two add up to the intrinsic power of the central source, which is the accretion power \(10^{\log L_{\rm bol}} L_\odot\) (the parameter, #2678). The disc is counted over its whole native range, including the part below 8 nm where the analytic disc that the component emits is zero: the template disc carries a further 9 to 58 % (median 14 %, sphere mean per cell) of its in-support power outside the support of the emitted disc, power which the torus absorbs and re-emits as dust when it is obscured and which leaves with the escaping rays otherwise. Counting only the part above 8 nm drops that power from the budget and trends the absolute scale with the opening angle (-4 % to +9 %). By symmetry about the equator \(\tfrac12\int_0^\pi P(\theta)\sin\theta\,d\theta = \int_0^1 P(\mu)\,d\mu\). The sphere-mean disc plus dust is then \(L_{\rm scale}\), and every inclination keeps SKIRTOR’s own flux relative to the others: the same \(s\) multiplies the disc and the torus dust, so their power ratio at each inclination is the radiative-transfer one. The integral over \(\mu\) is Gauss-Legendre of order INCLINATION_GL_ORDER on each interval between the library’s inclination nodes (each panel is one cubic of the interpolant; the power is a smooth function of that cubic). disk is the template disc over its whole native range (the emitting component cuts it at 8 nm), and total is disk + dust.

Measured on the v3 library, the records conserve energy to 2.5 % rms over the 1920 parameter cells (the sphere-mean disc plus dust differs from cell to cell by -21 % to +11 %, with no trend in the opening angle or tau, correlations +0.11 and -0.10; counting the disc only above 8 nm gave 5.1 % rms and a correlation of +0.88 with the opening angle). Most of the remainder is the sampling of the disc’s step at the edge of the torus by the ten inclination nodes: resolving the polar cone leaves 1.6 % rms, the library’s own residual. The per-point scale absorbs that residual and nothing else.

A grid without spectra/norm is normalized the same way from the stored records, each on its own scale, so its power carries no inclination dependence.

The separate components enable:

  • Applying different extinction laws to disk vs. torus dust

  • Computing polar dust from the disk component alone

  • Anisotropy corrections on individual components

References

[tengri.components.agn.skirtor.create_skirtor_components_from_grid-1]
  1. Stalevski et al., MNRAS, 420, 2756 (2012). arXiv:1109.1286.

[tengri.components.agn.skirtor.create_skirtor_components_from_grid-2]

M. Boquien et al., “CIGALE,” A&A, 622, A103 (2019). arXiv:1811.03094. https://doi.org/10.1051/0004-6361/201834156

[tengri.components.agn.skirtor.create_skirtor_components_from_grid-3]

F. N. Fritsch & R. E. Carlson, “Monotone Piecewise Cubic Interpolation,” SIAM J. Numer. Anal. 17, 238 (1980). https://doi.org/10.1137/0717021

tengri.components.agn.skirtor.create_skirtor_disc_attenuation_from_grid(grid_path: str) → Callable[source]

Build the SKIRTOR inclination-dependent disc-attenuation factor.

Returns a callable that produces the wavelength-dependent ratio \(\rm SKIRTOR.disk(\lambda; i, \tau, p, q, oa) / SKIRTOR.disk(\lambda; i=0, \tau, p, q, oa)\) (face-on baseline). Multiplied with the analytic Schartmann-2005 disc shape, this reproduces CIGALE skirtor2016.py:336 (Boquien+2019):

SKIRTOR2016.disk = analytic × SKIRTOR.disk_at_i / AGN1.disk_at_face

For face-on type-1 (i ≲ 90°−oa, e.g. i=30° with oa=40°), the ratio is near unity at most wavelengths; for type-2 sightlines it captures the clumpy self-attenuation through the equatorial torus that CIGALE’s analytic-disc replacement is supposed to preserve.

Parameters:

grid_path (str) – Path to a v3 SKIRTOR HDF5 file with spectra/disk_emission.

Returns:

att_fn(wavelength, agn_tau_skirtor, agn_p_skirtor, agn_q_skirtor, agn_oa_skirtor, agn_cos_inc) -> ndarray of shape (n_wave,), dimensionless attenuation factor. Returns 1.0 everywhere when the disk grid is unavailable (v2 fallback).

Return type:

callable

Notes

JIT-compatible: yes, triweight interpolation in JAX.

Gradient-safe: yes.

tengri.components.agn.skirtor.create_skirtor_from_grid(grid_path: str) → Callable[source]

Load SKIRTOR templates and return an interpolation function.

The returned function has the same signature as skirtor_analytic and can be used as a drop-in replacement.

Grid dimensions: tau × p × q × oa × inc × wave. Interpolation: 5D node-exact PCHIP in JAX (JIT-compatible, C¹-continuous gradients).

Parameters:

grid_path (str) – Path to the SKIRTOR grid file (.npz or .h5).

Returns:

Function with signature:

fn(wavelength, agn_log_lbol, agn_tau_skirtor, agn_p_skirtor,
   agn_q_skirtor, agn_oa_skirtor, agn_cos_inc,
   agn_torus_frac, **kwargs) -> L_nu [erg s^-1 Hz^-1]

Return type:

callable

Raises:

Notes

JIT-compatible: yes, the returned function is pure JAX. Grid loading is cached via @functools.cache.

Gradient-safe: yes, PCHIP interpolation is fully differentiable.

Supports v2 (total-only) and v3 (separate disk/dust) HDF5 layouts. When v3 is available, use create_skirtor_components_from_grid to access individual disk and dust spectra.

References

[tengri.components.agn.skirtor.create_skirtor_from_grid-1]

M. Stalevski et al., “3D radiative transfer modeling of the dusty torus around AGN,” MNRAS, 420, 2756 (2012). arXiv:1109.1286. https://doi.org/10.1111/j.1365-2966.2011.19775.x

[tengri.components.agn.skirtor.create_skirtor_from_grid-2]

M. Stalevski, C. Ricci, Y. Ueda, P. Lira, J. Fritz, and M. Baes, “The dust covering factor in active galactic nuclei,” MNRAS, 458, 2288 (2016). arXiv:1602.06954. bibcode:2016MNRAS.458.2288S. https://doi.org/10.1093/mnras/stw444

tengri.components.agn.skirtor.create_skirtor_raw_total_from_grid(grid_path: str) → Callable[source]

Loader for the faithful v4 SKIRTOR grid: the published RT total SED.

The v4 grid (scripts/build_skirtor_raw_grid.py) carries the full (tau_97, p, q, opening_angle, radius_ratio, inclination) axes and stores the radiative-transfer total (.dat column 2), the disc + torus as Stalevski (2016) computed them, with no analytic-disc substitution. The returned function interpolates that total at any point (so a fixed parameter is just a slice) and scales it to the requested bolometric luminosity.

Parameters:

grid_path (str) – Path to a v4 SKIRTOR HDF5 grid.

Returns:

fn(wavelength, agn_log_lbol, agn_tau_skirtor, agn_p_skirtor, agn_q_skirtor, agn_oa_skirtor, agn_radius_ratio, agn_cos_inc, frac_agn) -> L_nu [erg/s/Hz].

Return type:

callable

Notes

JIT-compatible: yes, pure-JAX triweight interpolation; grid load cached.

tengri.components.agn.skirtor.load_skirtor_bundle() → SKIRTORBundle[source]

Load both packaged SKIRTOR libraries (discovery + cache).

This is the template_loader the SKIRTOR torus block registers.

Return type:

SKIRTORBundle

Raises:

FileNotFoundError – If no SKIRTOR grid is present on disk.

tengri.components.agn.skirtor.load_skirtor_disc_atten_grid() → SKIRTORDiscAttenGrid | None[source]

Load the packaged SKIRTOR disc-column arrays, keyed on the process float dtype.

This is the template_loader the SKIRTOR-attenuated disc block registers, so the forward model can hoist the ~10 MB disc cube out of the JIT trace.

Returns:

None for a v2 grid, which carries no separate disc column; the attenuation is then identity.

Return type:

SKIRTORDiscAttenGrid or None

Raises:
  • FileNotFoundError – If no SKIRTOR grid is present on disk.

  • Mechanism – caches are keyed on process float dtype so a float32 arm:

  • never hands its arrays to a float64 arm (#2275; same disease as #1392, #2024). –

tengri.components.agn.skirtor.load_skirtor_disc_atten_grid_for(float_dtype_name: str) → SKIRTORDiscAttenGrid | None[source]

Load the packaged SKIRTOR disc-column arrays (discovery + cache).

This is the template_loader the SKIRTOR-attenuated disc block registers, so the forward model can hoist the ~10 MB disc cube out of the JIT trace.

Returns:

None for a v2 grid, which carries no separate disc column; the attenuation is then identity.

Return type:

SKIRTORDiscAttenGrid or None

Raises:
  • FileNotFoundError – If no SKIRTOR grid is present on disk.

  • Mechanism – caches are keyed on process float dtype so a float32 arm:

  • never hands its arrays to a float64 arm (#2275; same disease as #1392, #2024). –

tengri.components.agn.skirtor.load_skirtor_grid(grid_path: str | None = None) → SKIRTORGrid[source]

Load a SKIRTOR grid file into a threadable SKIRTORGrid pytree.

Parameters:

grid_path (str, optional) – Path to a SKIRTOR grid file. If None, auto-discovers the best available.

Returns:

Threadable template arrays (grid, wave_grid, axes, edges).

Return type:

SKIRTORGrid

Notes

Public API for tests and research code. For production model loading, use load_skirtor_bundle() which loads both torus and disc_dust grids.

tengri.components.agn.skirtor.skirtor_analytic(*args, **kwargs)

Deprecated alias for skirtor_sed(). Will be removed in tengri v1.0.

tengri.components.agn.skirtor.skirtor_components(*args, **kwargs) → SKIRTORComponents[source]

SKIRTOR torus with separate disk/dust (auto-loaded).

Requires a v3 grid file. See create_skirtor_components_from_grid.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength grid [Angstrom].

  • agn_log_lbol (float, optional) – AGN bolometric luminosity [log10(L_sun)]. Default: 10.0.

  • agn_tau_skirtor (float, optional) – V-band optical depth of torus [dimensionless]. Default: 7.0.

  • agn_p_skirtor (float, optional) – Radial dust distribution power-law index [dimensionless]. Default: 1.0.

  • agn_q_skirtor (float, optional) – Temperature profile power-law index [dimensionless]. Default: 1.0.

  • agn_oa_skirtor (float, optional) – Half-opening angle of the torus [degrees]. Default: 40.0.

  • agn_cos_inc (float, optional) – Cosine of inclination angle [dimensionless, 0–1]. Default: 0.5 (60°).

  • frac_agn (float, optional) – AGN fraction (CIGALE-style). Preferred parameter. Default: 0.5.

  • agn_torus_frac (float, optional) – Deprecated: use frac_agn instead. Falls back to this if frac_agn is not provided.

  • _template (callable, optional) – Pre-loaded template function (for JIT threading). When provided, uses this instead of the module-level cached loader. Internal use.

  • **kwargs – Additional keyword arguments (ignored for compatibility).

Returns:

Named tuple with disk, dust, total arrays, each shape (n_wave,) with units [erg/s/Hz].

Return type:

SKIRTORComponents

Raises:

RuntimeError – If no v3 grid with separate components is available.

Notes

JIT-compatible: yes, delegates to cached grid function or pre-loaded template (when _template is threaded).

tengri.components.agn.skirtor.skirtor_disc_attenuation(*args, _template: SKIRTORDiscAttenGrid | None = None, **kwargs)[source]

SKIRTOR inclination-dependent disc attenuation factor (auto-loaded).

Identity-1.0 when the v3 disc grid is unavailable (v2 fallback). See skirtor_disc_attenuation_from_grid() for the signature and physics.

Parameters:

_template (SKIRTORDiscAttenGrid, optional) – Pre-loaded disc arrays, threaded in as a JIT argument by the forward model. When None (default) the grid is loaded from disk and: if this call happens under trace: baked into the graph as constants.

tengri.components.agn.skirtor.skirtor_disc_attenuation_from_grid(grid: SKIRTORDiscAttenGrid | None, wavelength: Array, agn_tau_skirtor: float = 7.0, agn_p_skirtor: float = 1.0, agn_q_skirtor: float = 1.0, agn_oa_skirtor: float = 40.0, agn_radius_ratio: float = 20.0, agn_cos_inc: float = 0.8660254037844386, **_kwargs) → Array[source]

Wavelength-dependent disc attenuation factor at a chosen inclination.

Returns SKIRTOR.disk(i) / SKIRTOR.disk(i=0) interpolated onto the requested wavelength grid.

Parameters:
  • grid (SKIRTORDiscAttenGrid or None) – Disc-column template arrays, passed as an argument so they thread through JIT. None (a v2 grid, which carries no separate disc column) yields identity attenuation.

  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength [Angstrom].

  • agn_tau_skirtor (float, optional) – SKIRTOR grid coordinates.

  • agn_p_skirtor (float, optional) – SKIRTOR grid coordinates.

  • agn_q_skirtor (float, optional) – SKIRTOR grid coordinates.

  • agn_oa_skirtor (float, optional) – SKIRTOR grid coordinates.

  • agn_radius_ratio (float, optional) – SKIRTOR grid coordinates.

  • agn_cos_inc (float, optional) – SKIRTOR grid coordinates.

Returns:

Attenuation factor, clipped to [0, 1.5] [dimensionless].

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes. Gradient-safe: yes, the triweight kernel is C2-continuous.

tengri.components.agn.skirtor.skirtor_disc_dust_ratio(wave: Array, disc_lambda_unreddened: Array, disc_ext_fac: Array, *, agn_tau_skirtor: float = 7.0, agn_p_skirtor: float = 1.0, agn_q_skirtor: float = 1.0, agn_oa_skirtor: float = 40.0, agn_radius_ratio: float = 20.0, agn_cos_inc: float = 0.8660254037844386, incl_wave: Array | None = None, _template=None) → SkirtorDiscTie[source]

CIGALE disc/dust bolometric ratio R = lumin_disk / lumin_dust.

Replicates CIGALE skirtor2016.py so the composable AGN can tie the disc to the single agn_power reference (energy-conserving). The analytic disc shape is renormalized to the face-on SKIRTOR disc integral \(\int{\rm disk}(0)\,d\lambda\), reweighted by the library inclination ratio \({\rm disk}(i)/{\rm disk}(0)\), reddened, and divided by the SKIRTOR dust integral:

\[R = \frac{\int \hat s(\lambda)\,I_0\, \frac{D_i(\lambda)}{D_0(\lambda)}\,e(\lambda)\,d\lambda} {\int U_i(\lambda)\,d\lambda}, \qquad I_0 = \int D_0(\lambda)\,d\lambda,\]

where \(\hat s\) is the unit-area analytic disc shape [1/Å], \(D_i\) and \(D_0\) are the library disc spectra at inclination \(i\) and face-on [erg/s/Å, each on its stored scale], \(U_i\) is the library dust spectrum [erg/s/Å] and \(e = 10^{-0.4 k E(B-V)}\) the line-of-sight reddening (1 without it). At the §9 fiducial this yields R = 4.42 at i = 0 and 3.61 at i = 30 deg, CIGALE’s lumin_disk/lumin_dust to 0.2 % on the coarser library axis.

The anisotropy of the accretion disc, \(L(\theta) \propto \cos\theta\,(1 + 2\cos\theta)\) (quoted in the CIGALE skirtor2016 source, Boquien et al. 2019), is in the library spectra: \(\int D_i/\int D_0 = \eta(i) = \cos i\,(1 + 2\cos i)/3\) to 0.6 % for i <= 40 deg. \(R\) therefore carries \(\eta\) once, through \(D_i/D_0\), and no explicit factor enters. For sightlines through the torus (\(i > 90^\circ - {\rm oa}\)) \(D_i/D_0\) also carries the torus extinction of the disc.

Parameters:
  • wave (ndarray, shape (n_wave,)) – Rest-frame wavelength grid [Å].

  • disc_lambda_unreddened (ndarray, shape (n_wave,)) – Analytic disc spectrum before reddening, any normalization (shape only is used). [erg/s/Å]

  • disc_ext_fac (ndarray, shape (n_wave,)) – Line-of-sight reddening factor 10^(-0.4·k·E(B-V)) (1.0 = no reddening). [dimensionless]

  • agn_tau_skirtor – SKIRTOR grid parameters (edge-on τ_9.7, radial/polar density indices, half-opening angle, cos inclination).

  • agn_p_skirtor – SKIRTOR grid parameters (edge-on τ_9.7, radial/polar density indices, half-opening angle, cos inclination).

  • agn_q_skirtor – SKIRTOR grid parameters (edge-on τ_9.7, radial/polar density indices, half-opening angle, cos inclination).

  • agn_oa_skirtor – SKIRTOR grid parameters (edge-on τ_9.7, radial/polar density indices, half-opening angle, cos inclination).

  • agn_cos_inc – SKIRTOR grid parameters (edge-on τ_9.7, radial/polar density indices, half-opening angle, cos inclination).

  • incl_wave (ndarray, shape (n_out,), optional) – Grid incl_ratio is returned on [Å]. Defaults to wave. A caller that evaluates the disc on the library’s own axis (so that R does not depend on its output grid) passes that axis as wave and its output grid here.

Returns:

tie – (R, incl_ratio, R_faceon, faceon_shape_native, wave_native) – see SkirtorDiscTie for each field. R and R_faceon are the disc/dust bolometric ratios (reddened+inclination-weighted, and face-on un-reddened, respectively), incl_ratio is disk(i)/disk(0) on the CALLER’s grid, and the last two fields carry the unit-integral face-on disc shape together with the native template grid it is normalized on. When the v3 grid (separate disk/dust components) is unavailable the ratios are 1.0, incl_ratio is ones, and the native pair degrades to the caller’s own grid and shape.

Return type:

SkirtorDiscTie

Raises:

TypeError – If _template is neither a SkirtorDiscDustGrid nor the 4-field tuple it replaced.

Notes

JIT-compatible: yes, grid interpolation is pure JAX.

R_faceon carries the CIGALE-lineage grid’s stored inclination normalization norm(0)/norm(i) (R64): the face-on disc integral and the observer-inclination dust integral are read from records stored on different luminosity scales, and this is the factor that puts them on one. The AGNfitter-rX SKIRTOR reductions behind skirtor_agnfitter* are dust-only, inclination-averaged libraries with no such normalization and do not reach this function.

The polar reference’s remaining 2.8% is the SMC extinction curve. Writing the polar share as x/(1 + x) with x = g(oa) . R_faceon . J, where J = int(disc.(1 - e^-tau)) / int(disc) is the disc-shape-weighted absorbed fraction, the CIGALE comparison factors into R_faceon’s own per-inclination quadrature times a constant 1.02809, identical at i = 0, 30, 60 and 80. The cone factor g(40 deg) = 0.261007 is common to both sides, so the constant is in J – and J differs only through the extinction curve the polar screen applies.

Measured at the fiducial (disc='schartmann2005', E(B-V) = 0.03, on the native grid): J = 0.216753119 with tengri’s SMC curve against 0.222831745 with CIGALE’s, a factor 1.028044 – so the SMC curve accounts for 2.80 of the 2.81 percentage points and leaves 0.004%. Decomposed by decade, 71.8% of the difference comes from 100 - 1000 A, 14.7% from 1 - 10 um and 7.5% from 1000 - 3000 A.

The two curves are two different published SMC parameterizations, not an error on either side. tengri’s is Pei (1992, ApJ 395, 130) Table 4 SMC Bar, the six-component generalized Drude sum, normalized to k(5500 A) = 1 and scaled by that table’s own R_V = 2.93; components.dust.attenuation.smc reproduces the paper’s xi(lambda) to a constant factor of 1.03445291 at every wavelength, the factor being exactly that normalization choice (Pei’s analytic sum by itself implies A(V)/E(B-V) = 2.5806). CIGALE’s skirtor2016.k_ext instead uses the SMC power law k = 1.39 (lambda/um)^-1.2 (Bongiorno et al. 2012, in the Prevot et al. 1984 family), which implies A(V)/E(B-V) = 2.848, and below 100 nm swaps in a tabulated curve rescaled to match at that boundary – which is why the EUV decade carries most of the difference. Per-wavelength k_CIGALE/k_tengri: 1.0759 (912 A), 0.9897 (1216), 1.0235 (2000), 0.9961 (3000), 0.9721 (5500), 1.2073 (1e4), 2.4317 (3e4), 0.1073 (1e5).

Reference: Implements CIGALE skirtor2016.py (Boquien+2019).

References

  • Stalevski et al. 2016, MNRAS, 458, 2288 (SKIRTOR)

  • Boquien et al. 2019, A&A, 622, A103 (CIGALE skirtor2016; arXiv:1811.03094)

  • Pei 1992, ApJ, 395, 130 (the SMC Bar extinction curve tengri applies)

  • Prevot et al. 1984, A&A, 132, 389 (the SMC power-law family)

  • Bongiorno et al. 2012, MNRAS, 427, 3103 (the 1.39 lambda^-1.2 form)

tengri.components.agn.skirtor.skirtor_disc_dust_wave(template=None)[source]

Wavelength axis of the SKIRTOR disk/dust library [Å], or None if unavailable.

The grid skirtor_disc_dust_ratio() integrates on. A caller that evaluates the disc here, rather than on its own output grid, gets a tie (R, the face-on reference) that does not move with that grid.

Parameters:

template (SkirtorDiscDustGrid or tuple, optional) – The threaded library; loaded from disk when omitted.

Return type:

ndarray, shape (n_native,) or None

tengri.components.agn.skirtor.skirtor_sed(*args, **kwargs)[source]

SKIRTOR torus SED (auto-loaded from tabulated templates).

This function uses the tabulated Stalevski+2016 template grid with 5D triweight interpolation.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength grid [Angstrom].

  • agn_log_lbol (float, optional) – AGN bolometric luminosity [log10(L_sun)]. Default: 10.0.

  • agn_tau_skirtor (float, optional) – V-band optical depth of torus [dimensionless]. Default: 7.0. Range: ~1–15 (grid-dependent).

  • agn_p_skirtor (float, optional) – Radial dust distribution power-law index [dimensionless]. Default: 1.0. Range: ~0–2 (grid-dependent).

  • agn_q_skirtor (float, optional) – Radial dust distribution power-law index (temperature profile) [dimensionless]. Default: 1.0. Range: ~0–2 (grid-dependent).

  • agn_oa_skirtor (float, optional) – Half-opening angle of the torus [degrees]. Default: 40.0. Range: ~10–80° (grid-dependent).

  • agn_cos_inc (float, optional) – Cosine of inclination angle [dimensionless, 0–1]. Default: 0.5 (60°).

  • agn_torus_frac (float, optional) – Fraction of bolometric luminosity from torus [dimensionless, 0–1]. Default: 0.5.

  • _template (callable, optional) – Pre-loaded template function (for JIT threading). When provided, uses this instead of the module-level cached loader. Internal use.

  • **kwargs – Additional keyword arguments (ignored for compatibility).

Returns:

Spectral luminosity density L_ν [erg/s/Hz].

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, delegates to cached grid function or pre-loaded template (when _template is threaded).

See create_skirtor_from_grid for full parameter documentation and grid-dependent ranges.

Nenkova et al. (2008) CLUMPY AGN torus from AGNfitter-rX.

One-parameter semi-empirical torus library keyed on inclination angle (agn_cos_inc). The grid (9 bins from 10° to 90° inclination, averaged over CLUMPY model parameters) is interpolated with node-exact monotone-cubic (PCHIP) interpolation so gradients flow cleanly through agn_cos_inc during HMC / geoVI / MAP inference.

Grid provenance

Template data published with AGNfitter-rX (Martínez-Ramírez et al. 2024) : see scripts/build_nk08_agnfitter_grid.py. The AGNfitter-rX pickle stores per-inclination log10(nu / Hz) and F_nu arrays; the build script converts to ascending-wavelength [Å] and common-grid, then emits nenkova_agnfitter_torus_grid.h5. This runtime module only consumes the HDF5, not the pickle.

Runtime normalization

CLUMPY fluxes are normalized to the bolometric AGN flux F_AGN = L / 4 pi D^2 in every direction (Nenkova et al. 2008, ApJ 685, 160, Sect. 2 and 3.6), so the records share one scale across inclination; the AGNfitter-rX reductions are linear means on it (NK0_mean_3p averaged over its optical-depth axis is NK0_mean_2p to 5e-4). The template is therefore emitted as two factors (_torus_inclination.torus_lnu_anisotropic): the shape of the records normalized to unit power and interpolated as before, and the records’ own powers over their model’s mean, a scalar table interpolated with the same node-exact PCHIP. The angle-integrated torus power is L_bol * agn_torus_frac, each sightline keeps the library’s flux relative to the others, and the shape between nodes is the per-sightline one exactly.

References

[tengri.components.agn.nenkova_agnfitter-1]

M. Nenkova, M. M. Sirocky, R. Nikutta, Z. Ivezic, and M. Elitzur, “AGN Dusty Tori. II. Observational Implications of Clumpiness,” ApJ 685, 160 (2008). doi:10.1086/590483. arXiv:0806.0512. bibcode:2008ApJ…685..160N.

[tengri.components.agn.nenkova_agnfitter-2]

L. N. Martínez-Ramírez et al., “AGNfitter-rx: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A 688, A46 (2024). arXiv:2405.12111. DOI: 10.1051/0004-6361/202449329.

tengri.components.agn.nenkova_agnfitter.TORUS_INCLINATION = (0, 'cos_inc', False)

the records share one radiative-transfer scale across inclination, so the template carries its anisotropy as a scalar factor (_torus_inclination.torus_lnu_anisotropic).

Type:

The library’s inclination axis

tengri.components.agn.nenkova_agnfitter.create_nenkova_agnfitter_from_grid(grid_path: str) → Callable[source]

Load a Nenkova AGNfitter grid and bind it to the SED evaluator.

Retained for callers holding the historical closure API; new code should prefer load_nenkova_agnfitter_grid() plus nenkova_agnfitter_sed_from_grid(), which keeps the grid threadable.

Parameters:

grid_path (str) – Path to nenkova_agnfitter_torus_grid.h5.

Return type:

callable

tengri.components.agn.nenkova_agnfitter.nenkova_agnfitter_sed(*args, _template: TorusTemplateGrid | None = None, **kwargs) → Array[source]

Nenkova+08 AGN torus (AGNfitter-rX, auto-loaded from tabulated templates).

Wraps create_nenkova_agnfitter_from_grid() with on-disk grid discovery.

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength grid. [Å]

  • agn_log_lbol (float, optional) – log10(L_bol / L_sun). Default 10.0.

  • agn_cos_inc (float, optional) – Cosine of inclination (1 = face-on). Default 0.5.

  • agn_torus_frac (float, optional) – Torus reprocessing fraction. Default 0.5.

  • **kwargs – Accepted and ignored for unified-dispatch compatibility.

Returns:

Spectral luminosity density. [erg/s/Hz]

Return type:

ndarray, shape (n_wave,)

Raises:

FileNotFoundError – If no Nenkova AGNfitter grid HDF5 is present on disk.

References

[tengri.components.agn.nenkova_agnfitter.nenkova_agnfitter_sed-1]

M. Nenkova, M. M. Sirocky, R. Nikutta, Z. Ivezic, and M. Elitzur, “AGN Dusty Tori. II. Observational Implications of Clumpiness,” ApJ 685, 160 (2008). doi:10.1086/590483. arXiv:0806.0512. bibcode:2008ApJ…685..160N.

[tengri.components.agn.nenkova_agnfitter.nenkova_agnfitter_sed-2]

L. N. Martínez-Ramírez et al., “AGNfitter-rx: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A 688, A46 (2024). arXiv:2405.12111. DOI: 10.1051/0004-6361/202449329.

SKIRTOR-averaged (mean_3p) clumpy torus library (Stalevski et al. 2016).

Three-parameter torus library interpolated differentiably in (agn_oa_skirtor, agn_cos_inc, agn_tv_skirtor) over a precomputed HDF5 grid derived from AGNfitter-rX’s SKIRTOR_mean_3p.pickle.

This module is distinct from tengri.components.agn.skirtor, which uses tengri’s full-grid SKIRTOR implementation. The SKIRTOR_mean_3p variant shipped in AGNfitter-rX averages over the clumpiness parameters (p, q) and radial index, retaining only the three-parameter sub-library with:

  • half-opening angle (agn_oa_skirtor) [deg]

  • inclination, the model’s one agn_cos_inc (\(\cos i\))

  • equatorial optical depth (agn_tv_skirtor)

This is the AGNfitter-faithful choice, where the default full-grid skirtor (X-CIGALE-faithful) differs in peak wavelength and other properties (see issue #614 and #592).

Axis semantics

agn_oa_skirtor

Half-opening angle of the torus [deg]. Range: 10–80 deg. This is the OpenAngle parameter of Stalevski et al. (2016).

incl_axis

Inclination angle \(i\) measured from the polar axis [deg]. Range: 0–90 deg. 0 = face-on, 90 = edge-on. Keyed by agn_cos_inc (\(\cos i\)) through _skirtor_agnfitter_sightline.skirtor_incl_from_cos_inc, \(i = \arccos(\cos i)\).

agn_tv_skirtor

Equatorial optical depth at 9.7 µm (τ_9.7). Range: 3–11. Controls the torus optical thickness.

Runtime normalization

Template is shape-only. At runtime the module divides by the trapezoidal integral over frequency and multiplies by L_bol * agn_torus_frac, mirroring tengri.components.agn.skirtor and tengri.components.agn.silva04.

References

[tengri.components.agn.skirtor_agnfitter-1]

M. Stalevski et al., “3D radiative transfer modeling of the dusty torus around AGN, the influence of clumping,” MNRAS, 420, 2756 (2012). arXiv:1109.1286. https://doi.org/10.1111/j.1365-2966.2011.19775.x

[tengri.components.agn.skirtor_agnfitter-2]

M. Stalevski, C. Ricci, Y. Ueda, P. Lira, J. Fritz, and M. Baes, “The dust covering factor in active galactic nuclei,” MNRAS, 458, 2288 (2016). arXiv:1602.06954. bibcode:2016MNRAS.458.2288S. https://doi.org/10.1093/mnras/stw444

[tengri.components.agn.skirtor_agnfitter-3]

L. N. Martinez-Ramirez, et al., “AGNFITTER-RX: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A 688, A46 (2024). arXiv:2405.12111.

tengri.components.agn.skirtor_agnfitter.create_skirtor_agnfitter_from_grid(grid_path: str) → Callable[source]

Load a SKIRTOR_mean_3p grid and bind it to the SED evaluator.

Retained for callers holding the historical closure API; new code should prefer load_skirtor_agnfitter_grid() plus skirtor_agnfitter_sed_from_grid(), which keeps the grid threadable.

Parameters:

grid_path (str) – Path to skirtor_mean3p_torus_grid.h5.

Return type:

callable

tengri.components.agn.skirtor_agnfitter.skirtor_agnfitter_sed(*args, _template: TorusTemplateGrid | None = None, **kwargs) → Array[source]

SKIRTOR_mean_3p torus (auto-loaded from the packaged HDF5 grid).

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength. [Å]

  • agn_log_lbol (float, optional) – log10(L_bol / L_sun). Default 11.0.

  • agn_oa_skirtor (float, optional) – Half-opening angle [deg]. Default 40.0.

  • agn_cos_inc (float, optional) – \(\cos i\), the model’s one inclination, \(i\) from the polar axis (1 = face-on) [dimensionless]. Default cos(30 deg), the declared agn_cos_inc default. The library is keyed at \(i = \arccos(\cos i)\) [deg]; the retired agn_incl_skirtor [deg] is translated with a DeprecationWarning.

  • agn_tv_skirtor (float, optional) – Equatorial optical depth τ_9.7. Default 7.0.

  • agn_torus_frac (float, optional) – Torus reprocessing fraction. Default 0.5.

  • **kwargs – Accepted and ignored for unified-dispatch compatibility.

Returns:

Torus SED [erg/s/Hz].

Return type:

ndarray, shape (n_wave,)

Notes

This function auto-discovers the grid file from the package data directory or the current working directory. To use a non-standard grid location, call create_skirtor_agnfitter_from_grid() directly.

CAT3D-Wind clumpy-disc-plus-polar-wind AGN torus (Hönig & Kishimoto 2017).

Three-parameter torus library interpolated differentiably in (agn_cos_inc, agn_a_cat3d, agn_fwd_cat3d) over a precomputed HDF5 grid derived from AGNfitter-rX’s CAT3D_mean_3p.pickle.

Axis semantics

agn_cos_inc

Cosine of inclination (1 = face-on, 0 = edge-on). The grid’s native incl_axis is stored in degrees; this module converts at load time so the runtime axis matches tengri’s naming convention and SKIRTOR’s agn_cos_inc usage.

agn_a_cat3d

Radial power-law index of the clumpy-cloud distribution (Hönig & Kishimoto 2017 parameter a). Typical range −2.5 to −0.5; exact bounds follow the populated grid.

agn_fwd_cat3d

Polar-wind mass fraction (fwd); the rest is in the mid-plane clumpy disc.

Runtime normalization

Template is shape-only. At runtime the module divides by the trapezoidal integral over frequency and multiplies by L_bol * agn_torus_frac, mirroring tengri.components.agn.skirtor and tengri.components.agn.silva04.

Grid completeness

AGNfitter-rX’s library is not a full Cartesian product of the three axes; scripts/build_cat3d_wind_grid.py fills the missing cells with their nearest-neighbor populated value at build time so the interpolant has support over the full grid box.

Interpolation

Node-exact monotone cubic (PCHIP, tengri.utils.grid_interp.interp_nd_pchip()): it reproduces every tabulated AGNfitter template at the grid nodes while keeping C¹-continuous gradients. The C²-smooth triweight smoother used elsewhere averages neighboring nodes, which smeared this torus’s mid-IR peak by tens of percent (median ~30%), the same peak-smear that moved tengri.components.agn.slone_netzer to node-exact interpolation. Monotone cubic is shape-preserving, so it does not overshoot on the nearest-neighbor-filled grid.

References

[tengri.components.agn.cat3d_wind-1]

S. F. Hönig & M. Kishimoto, “Dusty winds in active galactic nuclei: reconciling observations with models,” ApJL 838, L20 (2017). arXiv:1703.07781.

[tengri.components.agn.cat3d_wind-2]

L. N. Martínez-Ramírez, G. Calistro Rivera, E. Lusso, et al., “AGNfitter-rx: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A 688, A46 (2024). arXiv:2405.12111. DOI: 10.1051/0004-6361/202449329.

tengri.components.agn.cat3d_wind.cat3d_wind_analytic(*args, _template: TorusTemplateGrid | None = None, **kwargs) → Array

Deprecated alias for cat3d_wind_sed(). Will be removed in tengri v1.0.

tengri.components.agn.cat3d_wind.cat3d_wind_sed(*args, _template: TorusTemplateGrid | None = None, **kwargs) → Array[source]

CAT3D-Wind torus (auto-loaded from the packaged HDF5 grid).

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength. [Å]

  • agn_log_lbol (float, optional) – log10(L_bol / L_sun). Default 10.0.

  • agn_cos_inc (float, optional) – Cosine of inclination. Default 0.5.

  • agn_a_cat3d (float, optional) – Radial power-law index. Default −2.0.

  • agn_fwd_cat3d (float, optional) – Wind fraction. Default 1.0.

  • agn_torus_frac (float, optional) – Torus reprocessing fraction. Default 0.5.

  • **kwargs – Accepted and ignored for unified-dispatch compatibility.

Returns:

Spectral luminosity density. [erg/s/Hz]

Return type:

ndarray, shape (n_wave,)

Raises:

FileNotFoundError – If no CAT3D-Wind grid HDF5 is present on disk.

tengri.components.agn.cat3d_wind.cat3d_wind_sed_from_grid(grid: TorusTemplateGrid, wavelength: Array, agn_log_lbol: float = 10.0, agn_cos_inc: float = 0.8660254037844386, agn_a_cat3d: float = -2.0, agn_fwd_cat3d: float = 1.0, agn_torus_frac: float = 0.5, **_kwargs) → Array[source]

CAT3D-Wind torus SED at a single (cos_inc, a, f_wd).

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength grid. [Å]

  • agn_log_lbol (float, optional) – log10(L_bol / L_sun). Default 10.0.

  • agn_cos_inc (float, optional) – Cosine of inclination (1 = face-on). Default 0.5.

  • agn_a_cat3d (float, optional) – Radial power-law index of the clumpy-cloud distribution (Hönig & Kishimoto 2017 a). Default −2.0.

  • agn_fwd_cat3d (float, optional) – Polar-wind mass fraction. Default 1.0.

  • agn_torus_frac (float, optional) – Fraction of L_bol reprocessed by the torus. Default 0.5.

Returns:

Spectral luminosity density. [erg/s/Hz]

Return type:

ndarray, shape (n_wave,)

Notes

\[L_\nu(\lambda) = L_{\rm bol}\,f_{\rm torus}\, \frac{T(\lambda;\,\cos i,\,a,\,f_{\rm wd})} {\int T(\nu;\,\cos i,\,a,\,f_{\rm wd}) \,\mathrm{d}\nu}\]

JIT-compatible: yes.

Approximation: the grid is drawn from the CAT3D_mean_3p library (Hönig & Kishimoto 2017 [tengri.components.agn.cat3d_wind.cat3d_wind_sed_from_grid-1]) as packaged by AGNfitter-rX [tengri.components.agn.cat3d_wind.cat3d_wind_sed_from_grid-2], which averages out secondary parameters (N_0, τ_V, σ) of the full Hönig & Kishimoto 2017 parameter space. For torus studies where those parameters are scientifically important, use the full CAT3D-Wind library directly, not this three-parameter projection.

Grid completeness: cells absent from the upstream library are filled with the nearest populated cell at build time (see scripts/build_cat3d_wind_grid.py).

References

[tengri.components.agn.cat3d_wind.cat3d_wind_sed_from_grid-1]

S. F. Hönig & M. Kishimoto, “Dusty winds in active galactic nuclei: reconciling observations with models,” ApJL 838, L20 (2017). arXiv:1703.07781.

[tengri.components.agn.cat3d_wind.cat3d_wind_sed_from_grid-2]

L. N. Martínez-Ramírez, G. Calistro Rivera, E. Lusso, et al., “AGNfitter-rx: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A 688, A46 (2024). arXiv:2405.12111. DOI: 10.1051/0004-6361/202449329.

tengri.components.agn.cat3d_wind.create_cat3d_wind_from_grid(grid_path: str) → Callable[source]

Load a CAT3D-Wind grid and bind it to the SED evaluator.

Retained for callers holding the historical closure API; new code should prefer load_cat3d_wind_grid() plus cat3d_wind_sed_from_grid(), which keeps the grid threadable.

Parameters:

grid_path (str) – Path to cat3d_wind_torus_grid.h5.

Returns:

fn(wavelength, agn_log_lbol, agn_cos_inc, agn_a_cat3d, agn_fwd_cat3d, agn_torus_frac, **_) -> L_nu [erg/s/Hz].

Return type:

callable

tengri.components.agn.cat3d_wind.load_cat3d_wind_default_grid() → TorusTemplateGrid[source]

Load the packaged CAT3D-Wind grid pytree (discovery + cache).

This is the template_loader the torus block registers, so the forward model can hoist the library out of the JIT trace.

Return type:

TorusTemplateGrid

Raises:

FileNotFoundError – If no CAT3D-Wind grid HDF5 is present on disk.

tengri.components.agn.cat3d_wind.load_cat3d_wind_grid(grid_path: str) → TorusTemplateGrid[source]

Load a CAT3D-Wind grid HDF5 into a TorusTemplateGrid pytree.

Parameters:

grid_path (str) – Path to cat3d_wind_torus_grid.h5.

Returns:

Template arrays with axes (cos_inc, a, f_wd), as numpy arrays.

Return type:

TorusTemplateGrid

Raises:
  • FileNotFoundError – If grid_path does not exist.

  • KeyError – If the grid file is missing any expected dataset under /cat3d_wind.

Notes

JIT-compatible: no, performs HDF5 I/O. Call outside the trace and pass the result in as an argument; see tengri.components.agn._template_grid.

Silva, Maiolino & Granato (2004) smooth AGN torus.

One-parameter semi-empirical torus library keyed on hydrogen column density (log10(N_H / cm^-2)). The grid (60 nodes in the vendored silva04_torus_grid.h5) is interpolated with node-exact monotone-cubic (PCHIP) interpolation, so gradients flow cleanly through agn_log_nh_silva during HMC / geoVI / MAP inference while reproducing every tabulated node exactly (matching the interpolation kernel used by every other tabulated torus library: nenkova_agnfitter, skirtor_agnfitter, cat3d_wind; see torus_lnu_from_grid in components/agn/_template_grid.py).

Grid provenance

Template data published with AGNfitter (Calistro Rivera et al. 2016): see scripts/build_silva04_grid.py. The AGN-fitter pickle stores per-bin log10(nu) and F_nu arrays; the build script converts to ascending-wavelength [Å] and common-grid, then emits silva04_torus_grid.h5. This runtime module only consumes the HDF5, not the pickle.

Runtime normalization

The stored template is shape-only. At runtime, create_silva04_from_grid() divides by the trapezoidal integral over frequency and multiplies by L_bol * agn_torus_frac, matching tengri.components.agn.skirtor.

References

[tengri.components.agn.silva04-1]

L. Silva, R. Maiolino & G. L. Granato, “The nature of the Compton-thick AGN in NGC 1068 and implications for the cosmic X-ray background,” MNRAS 355, 973 (2004). arXiv:astro-ph/0403425. Citation details (volume, DOI) must be verified against the original paper before publication.

[tengri.components.agn.silva04-2]

G. Calistro Rivera et al., “AGNfitter: a Bayesian MCMC approach to fitting spectral energy distributions of AGNs,” ApJ 833, 98 (2016). arXiv:1606.05648.

class tengri.components.agn.silva04.Silva04Grid(template: jnp.ndarray, log_nh_axis: jnp.ndarray, wave_grid: jnp.ndarray)[source]

Bases: NamedTuple

Silva+04 template arrays, as a JAX pytree.

Carrying the grid as a pytree rather than closing over it is what makes threading possible: a closure’s captured arrays are concrete at trace time and freeze into the graph as Constant ops, whereas a pytree can be passed as a traced argument of the jitted forward model.

Variables:
  • template (ndarray, shape (n_nh, n_wave)) – Tabulated torus templates [arbitrary units; normalized on use].

  • log_nh_axis (ndarray, shape (n_nh,)) – Grid axis, \(\log_{10}(N_H / {\rm cm}^{-2})\).

  • wave_grid (ndarray, shape (n_wave,)) – Template rest-frame wavelength grid [Angstrom].

log_nh_axis: Array

Alias for field number 1

template: Array

Alias for field number 0

wave_grid: Array

Alias for field number 2

tengri.components.agn.silva04.create_silva04_from_grid(grid_path: str) → Callable[source]

Load Silva+04 grid and return a JAX-native interpolation closure.

Parameters:

grid_path (str) – Path to silva04_torus_grid.h5.

Returns:

Function fn(wavelength, agn_log_lbol, agn_log_nh_silva, agn_torus_frac, **_) -> L_nu [erg/s/Hz].

Return type:

callable

Raises:
  • FileNotFoundError – If grid_path does not exist.

  • KeyError – If the grid file is missing the expected /silva04 datasets.

Notes

JIT-compatible: yes, the returned closure uses only jnp and PCHIP interpolation.

Gradient-safe: yes, PCHIP (monotone-cubic) interpolation is C¹-continuous in agn_log_nh_silva and node-exact.

tengri.components.agn.silva04.load_silva04_grid(grid_path: str) → Silva04Grid[source]

Load a Silva+04 grid HDF5 into a Silva04Grid pytree.

Parameters:

grid_path (str) – Path to silva04_torus_grid.h5.

Returns:

Template arrays as numpy arrays.

Return type:

Silva04Grid

Notes

JIT-compatible: no, performs HDF5 I/O. Call it outside the trace and pass the result in as an argument.

Leaves stay np.ndarray rather than jnp.ndarray on purpose. If this loader were first invoked inside a JIT trace and converted here, any jnp op on those arrays would produce Tracers that the functools.cache then immortalizes, leaking them as UnexpectedTracerError on later out-of-trace calls. jnp.asarray at the point of use is safe in either context.

tengri.components.agn.silva04.silva04_analytic(*args, _template: Silva04Grid | None = None, **kwargs) → Array

Deprecated alias for silva04_sed(). Will be removed in tengri v1.0.

tengri.components.agn.silva04.silva04_sed(*args, _template: Silva04Grid | None = None, **kwargs) → Array[source]

Silva+04 smooth AGN torus (auto-loaded from tabulated templates).

Parameters:
  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength grid. [Å]

  • agn_log_lbol (float, optional) – log10(L_bol / L_sun). Default 10.0.

  • agn_log_nh_silva (float, optional) – log10(N_H / cm^-2). Default 23.0.

  • agn_torus_frac (float, optional) – Torus reprocessing fraction. Default 0.5.

  • _template (Silva04Grid, optional) – Pre-loaded grid, threaded in as a JIT argument by the forward model. When None (default) the packaged grid is loaded from disk and (if this call happens under trace) baked into the graph as constants.

  • **kwargs – Accepted and ignored for unified-dispatch compatibility.

Returns:

Spectral luminosity density. [erg/s/Hz]

Return type:

ndarray, shape (n_wave,)

Raises:

FileNotFoundError – If no Silva+04 grid HDF5 is present on disk.

tengri.components.agn.silva04.silva04_sed_from_grid(grid: Silva04Grid, wavelength: Array, agn_log_lbol: float = 10.0, agn_log_nh_silva: float = 23.0, agn_torus_frac: float = 0.5, **_kwargs) → Array[source]

Silva+04 torus SED at a single log10(N_H).

Parameters:
  • grid (Silva04Grid) – Template arrays. Passing these as an argument (rather than closing over them) is what lets the forward model thread the library through jax.jit as a Parameter instead of baking ~2 MB into the graph as Constant ops.

  • wavelength (array_like, shape (n_wave,)) – Rest-frame wavelength grid. [Å]

  • agn_log_lbol (float, optional) – Bolometric luminosity, log10(L_bol / L_sun). Default 10.0.

  • agn_log_nh_silva (float, optional) – Hydrogen column density, log10(N_H / cm^-2). Valid over the grid extent (Silva+04 bins typically 22–25). Default 23.0.

  • agn_torus_frac (float, optional) – Fraction of L_bol reprocessed by the torus. Default 0.5.

Returns:

Spectral luminosity density. [erg/s/Hz]

Return type:

ndarray, shape (n_wave,)

Notes

\[L_\nu(\lambda) = L_{\rm bol}\,f_{\rm torus}\, \frac{T(\lambda,\,\log N_H)} {\int T(\nu,\,\log N_H)\,\mathrm{d}\nu}\]

where \(T\) is the tabulated template and the integral is evaluated on the template’s own native frequency grid (before resampling), so the result does not depend on how wavelength is sampled or where it starts and stops.

JIT-compatible: yes. Differentiable in agn_log_nh_silva (PCHIP monotone-cubic interpolation is C¹-continuous and node-exact: it reproduces the tabulated template exactly at each log_nh_axis node, unlike the C²-smooth triweight kernel this replaced, which averaged neighboring nodes and smeared the template by ~9% at the boundary node).

Approximation: the template is semi-empirical (Silva, Maiolino & Granato 2004 [tengri.components.agn.silva04.silva04_sed_from_grid-1]); it assumes smooth-dust geometry and is not a full 3D radiative-transfer solution. For silicate-feature–level accuracy, use SKIRTOR ([tengri.components.agn.silva04.silva04_sed_from_grid-2]) instead.

References

[tengri.components.agn.silva04.silva04_sed_from_grid-1]

L. Silva, R. Maiolino & G. L. Granato, “The nature of the Compton-thick AGN in NGC 1068 and implications for the cosmic X-ray background,” MNRAS 355, 973 (2004). arXiv:astro-ph/0403425. Citation details (volume, DOI) must be verified against the original paper before publication.

[tengri.components.agn.silva04.silva04_sed_from_grid-2]

G. Calistro Rivera et al., “AGNfitter: a Bayesian MCMC approach to fitting spectral energy distributions of AGNs,” ApJ 833, 98 (2016). arXiv:1606.05648.

CAT3D-Wind clumpy-disc-plus-polar-wind torus (Hönig & Kishimoto 2017) SEDModelComponent.

Implements the CAT3D-Wind torus model on the SEDModelComponent contract, enabling use of three-parameter clumpy torus templates in the model-building API.

This is an opt-in adapter, the existing AGNSEDComponent continues to support CAT3D through the unified AGN registry.

References

[tengri.components.agn.cat3d_torus_model-1]

S. F. Hönig & M. Kishimoto, “Dusty winds in active galactic nuclei: reconciling observations with models,” ApJL 838, L20 (2017). arXiv:1703.07781.

[tengri.components.agn.cat3d_torus_model-2]

L. N. Martínez-Ramírez, G. Calistro Rivera, E. Lusso, et al., “AGNfitter-rx: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A 688, A46 (2024). arXiv:2405.12111.

class tengri.components.agn.cat3d_torus_model.CAT3DTorus(config: CAT3DTorusConfig = <factory>)[source]

Bases: SEDModelComponent

CAT3D-Wind clumpy-disc-plus-polar-wind AGN torus.

Three-parameter torus model with inclination, clump distribution, and polar-wind mass fraction. Provides C¹-continuous gradients via node-exact PCHIP interpolation over the 3D parameter space.

Variables:
  • name (str) – Component registry key: "cat3d_wind".

  • parameter_prefix (str) – Parameter namespace: "agn_".

  • config (CAT3DTorusConfig) – Frozen configuration (grid path).

  • auto-discovered) (Free parameters (class-level declarations,)

  • -----------------------------------------------------------

  • log_lbol (Uniform) – log₁₀(L_bol / L_sun). [dex, 8–14]

  • cos_inc (Uniform) – Cosine of inclination (1 = face-on, 0 = edge-on). [dimensionless, 0–1]

  • a_cat3d (Uniform) – Radial power-law index of clump distribution. [dimensionless, -3.0–-1.5]

  • fwd_cat3d (Uniform) – Polar-wind mass fraction. [dimensionless, 1.0–2.25]

  • torus_frac (Uniform) – Fraction of L_bol reprocessed by torus. [dimensionless, 0–1]

  • outputs (Cross-component)

  • -----------------------

  • log_L_agn_disc_unemitted (log_L_agn_torus, log_L_agn_torus_los,) – The torus-only energy ledger [dex re erg/s] (NAMING_CONTRACT section 4c, “Template tori”): the angle-integrated torus power f L_bol (f = torus_frac), the frequency integral of the torus SED emitted along the sightline, and the disc share (1 - f) L_bol this component does not emit, so the first and last add up to 10**log_lbol L_sun. Here the first two are equal: the AGNfitter-rX CAT3D_mean_3p records do not carry a documented common scale across inclination (neither Martinez-Ramirez et al. 2024, Sect. 3.3, nor the upstream pickle states one, and the stored powers are not monotonic in inclination), so each sightline is normalized on its own. Each has an L_agn_*_lsun [Lsun] sibling; -inf is an absent piece.

Notes

JIT-compatible: yes, predict() is pure JAX.

Gradient-safe: yes, PCHIP interpolation is C¹ and differentiable across the three parameter axes.

Requires template grid: The CAT3D-Wind template library must be downloaded separately and pointed to via grid_path in config. The predict method gracefully returns zero emission if templates are unavailable.

Inclination parameterization: Uses cosine of inclination (not degrees) to align with SKIRTOR and other components.

Examples

Minimal model with CAT3D-Wind torus:

from tengri import SEDModel, Fixed, DEFAULT, Uniform, builders
from tengri.components.agn.cat3d_torus_model import CAT3DTorus, CAT3DTorusConfig

model = SEDModel.build(
    ssp_data=ssp,
    observation=obs,
    sfh=builders.sfh.dpl(alpha=Fixed(1.5), beta=Fixed(1.0)),
    dust_attenuation={"type": "two_component", "all_params": Fixed(DEFAULT)},
    agn=CAT3DTorus(config=CAT3DTorusConfig(grid_path="path/to/grid.h5")),
)

See also

tengri.components.agn.cat3d_wind

template loader and interpolation.

a_cat3d = Uniform(-3.0, -1.5)
cos_inc = Uniform(0.0, 1.0)
fwd_cat3d = Uniform(1.0, 2.25)
load(wave: Array | None = None) → Any | None[source]

Load CAT3D-Wind template grid if available.

Parameters:

wave (ndarray, optional) – Rest-frame wavelength grid (not used by CAT3D; templates interpolate to any target grid).

Returns:

Interpolation function from create_cat3d_wind_from_grid, or None if template file is not available or grid_path is not set.

Return type:

callable or None

log_lbol = Uniform(8.0, 14.0)
name: str = 'cat3d_wind'
parameter_prefix: str = 'agn_'
predict(p: Mapping[str, Array], sed_in: Array, wave: Array, **inputs: Any) → tuple[Array, Mapping[str, Array]][source]

Pure JAX CAT3D-Wind torus prediction.

Interpolates the CAT3D-Wind template grid to the requested inclination, clump distribution, and wind fraction; normalizes to the user’s luminosity scale; and returns the torus SED contribution.

Parameters:
  • p (mapping[str, ndarray]) –

    Parameters with prefix already stripped:

    • log_lbol: log₁₀(L_bol / L_sun)

    • cos_inc: cosine of inclination

    • a_cat3d: radial power-law index

    • fwd_cat3d: polar-wind mass fraction

    • torus_frac: torus luminosity fraction

  • sed_in (ndarray, shape (n_wave,)) – Input SED in erg/s/Hz.

  • wave (ndarray, shape (n_wave,)) – Rest-frame wavelength grid in Angstrom.

  • **inputs (ndarray) – Unused (AGN torus is self-contained).

Returns:

(sed_out, published) where:

  • sed_out: Updated SED (sed_in + torus contribution).

  • published: log_L_agn_torus, log_L_agn_torus_los and log_L_agn_disc_unemitted [dex re erg/s] with their _lsun siblings (see Cross-component outputs).

Return type:

tuple[ndarray, dict]

torus_frac = Uniform(0.0, 1.0)

Three-zone accretion disc model (Kubota & Done 2018) SEDModelComponent.

Implements the Kubota & Done (2018) accretion disc model on the SEDModelComponent contract, enabling use in the model-building API.

This is an opt-in adapter, the existing AGNSEDComponent continues to support K&D18 through the unified AGN registry.

References

[tengri.components.agn.kd18_disc_model-1]

A. Kubota and C. Done, “A physical model of the broad-band continuum of AGN and its implications for the UV/X relation and optical variability,” MNRAS, 480, 1247 (2018). doi:10.1093/mnras/sty1890. arXiv:1804.00171. bibcode:2018MNRAS.480.1247K.

[tengri.components.agn.kd18_disc_model-2]

A. A. Beloborodov, “Energetic Radiation from Accretion Tori,” ApJ 510, L123 (1999). arXiv:astro-ph/9810145.

class tengri.components.agn.kd18_disc_model.KD18Disc(config: KD18DiscConfig = <factory>)[source]

Bases: SEDModelComponent

Kubota & Done (2018) three-zone accretion disc.

A physically stratified model with outer standard disc, warm Comptonization zone, and hot corona. Self-consistent zone radii and temperature profiles enable smooth inference gradients across the full parameter space.

Notes

Validity domain. The three-zone geometry applies for \(\lambda_{\rm Edd}\) above about \(f_{\rm hard}\) (~0.02). Below it the disc truncates: there are no disc or warm zones (as in RELQSO, Hagen & Done 2023, arXiv:2304.01253), and the hot flow is modeled as radiatively efficient Comptonization of all the dissipation inside \(R_{\rm out}\); Kubota & Done (2018) do not model radiative inefficiency. disc='adaf' is the radiatively inefficient alternative for that regime. No warning is issued.

Variables:
  • name (str) – Component registry key: "kd18_disc".

  • parameter_prefix (str) – Parameter namespace: "agn_".

  • config (KD18DiscConfig) – Frozen configuration (self-consistent gamma, radial grid).

  • auto-discovered) (Free parameters (class-level declarations,)

  • -----------------------------------------------------------

  • log_lbol (Uniform) – log₁₀(L_bol / L_sun). [dex, 8–14]

  • log_mbh (Uniform) – log₁₀(M_BH / M_sun). [dex, 6–10]

  • log_ledd (Uniform) – Eddington ratio log₁₀(L / L_Edd). [dex, -2–0.5]

  • a_spin (Uniform) – Dimensionless black hole spin (prograde). [dimensionless, 0–0.998]

  • cos_inc (Uniform) – Cosine of inclination (1 = face-on, 0 = edge-on). [dimensionless, 0–1]

  • f_hard (Uniform) – Fraction of Eddington luminosity in hot corona. [dimensionless, 0–0.1]

  • gamma_warm (Uniform) – Photon index of warm Comptonization zone. [dimensionless, 2–3]

  • kt_warm (Uniform) – Warm zone electron temperature. [keV, 0.1–1]

  • gamma_hard (Uniform) – Hard X-ray photon index (used if self_consistent_gamma=False). [dimensionless, 1.5–2.5]

  • kt_hot (Uniform) – Hot corona electron temperature. [keV, 50–300]

  • r_warm_ratio (Uniform) – Radius ratio R_warm / R_hot. [dimensionless, 1–5]

  • lum_ratio (Uniform) – Fraction of bolometric luminosity from disc. [dimensionless, 0–5]

  • outputs (Cross-component)

  • -----------------------

  • log_L_agn_disc_los (log_L_agn_disc,) – log10 of the angle-integrated power and of the line-of-sight isotropic-equivalent luminosity [dex re erg/s]: integrals over the full emission range of the emitted SED (all three zones), evaluated on the publication grid.

Notes

JIT-compatible: yes, predict() is pure JAX.

Gradient-safe: yes, self-consistent zone radii via bisection are smooth over the parameter space.

Cross-component note: AGN inclination (cos_inc) is shared with torus/corona models and is never auto-derived from geometry. Declare it as a free parameter independently.

Examples

Minimal model with K&D18 disc:

from tengri import SEDModel, Fixed, DEFAULT, Uniform, builders
from tengri.components.agn.kd18_disc_model import KD18Disc, KD18DiscConfig

model = SEDModel.build(
    ssp_data=ssp,
    observation=obs,
    sfh=builders.sfh.dpl(alpha=Fixed(1.5), beta=Fixed(1.0)),
    dust_attenuation={"type": "two_component", "all_params": Fixed(DEFAULT)},
    agn=KD18Disc(config=KD18DiscConfig(self_consistent_gamma=True)),
)

See also

tengri.components.agn.disc

Kubota & Done (2018) implementation.

a_spin = Uniform(0.0, 0.998)
cos_inc = Uniform(0.0, 1.0)
f_hard = Uniform(0.0, 0.1)
gamma_hard = Uniform(1.5, 2.5)
gamma_warm = Uniform(2.0, 3.0)
kt_hot = Uniform(50.0, 300.0)
kt_warm = Uniform(0.1, 1.0)
log_lbol = Uniform(8.0, 14.0)
log_ledd = Uniform(-2.0, 0.5)
log_mbh = Uniform(6.0, 10.0)
lum_ratio = Uniform(0.0, 5.0)
name: str = 'kd18_disc'
parameter_prefix: str = 'agn_'
predict(p: Mapping[str, Array], sed_in: Array, wave: Array, **inputs: Any) → tuple[Array, Mapping[str, Array]][source]

Pure JAX K&D18 three-zone disc prediction.

Parameters:
  • p (mapping[str, ndarray]) –

    Parameters with prefix already stripped:

    • log_lbol: log₁₀(L_bol / L_sun)

    • log_mbh: log₁₀(M_BH / M_sun)

    • log_ledd: Eddington ratio

    • a_spin: black hole spin

    • cos_inc: cosine of inclination

    • f_hard: hot corona fraction

    • gamma_warm: warm zone photon index

    • kt_warm: warm zone temperature (keV)

    • gamma_hard: hard X-ray index

    • kt_hot: hot corona temperature (keV)

    • r_warm_ratio: R_warm / R_hot

    • lum_ratio: disc luminosity fraction of L_bol [dimensionless]

  • sed_in (ndarray, shape (n_wave,)) – Input SED in erg/s/Hz.

  • wave (ndarray, shape (n_wave,)) – Rest-frame wavelength grid in Angstrom.

  • **inputs (ndarray) – Unused (AGN disc is self-contained).

Returns:

(sed_out, published) where:

  • sed_out: Updated SED (sed_in + disc contribution).

  • published: log_L_agn_disc and log_L_agn_disc_los [dex re erg/s], defined below.

Return type:

tuple[ndarray, dict]

Notes

The disc and warm Comptonization zones are optically thick, so their emission is proportional to \(\cos i\); the hot corona is optically thin and isotropic (Kubota & Done 2018 [tengri.components.agn.kd18_disc_model.KD18Disc.predict-1], Sects. 2.1 and 2.2). With \(D_\nu\) the angle-integrated (two-face) luminosity density of the disc and warm zones, whose power is \(\int D_\nu\,d\nu = 2\int\sigma T_{\rm NT}^4\,2\pi R\,dR\) (their Eq. 2 for the hot-flow range), and \(H_\nu\) the corona,

\[L_\nu(i) = 2\cos i\, D_\nu + H_\nu .\]

The factor 2 makes the mean of \(2\cos i\) over \(\cos i \in [0, 1]\) equal one; it is tengri’s isotropic-equivalent normalization, not an equation of the paper. Two luminosities are published:

\[L_{\rm agn\_disc} = \int (D_\nu + H_\nu)\,d\nu , \qquad L_{\rm agn\_disc\_los} = \int L_\nu(i)\,d\nu .\]

log_L_agn_disc [dex re erg/s] is the log of the angle-integrated emitted power: it is independent of cos_inc and equals lum_ratio times the accretion power implied by log_lbol, less the dissipation the disc does not emit beyond its outer radius (kubota_done_unemitted_fraction(), #3015). log_L_agn_disc_los is the log of the line-of-sight isotropic-equivalent luminosity of the emitted, inclination-projected SED, a derived output; at \(\cos i = 0.5\) the two coincide. Both are integrals on a fixed grid of 1e-3 A to 1e10 A, independent of the caller’s wavelength grid, and are formed in log space so they are finite and accurate in pure float32, where the erg/s value overflows (NAMING_CONTRACT section 4c). -inf is an absent disc (lum_ratio = 0).

JIT-compatible: yes.

References

[tengri.components.agn.kd18_disc_model.KD18Disc.predict-1]
  1. Kubota and C. Done, MNRAS, 480, 1247 (2018), arXiv:1804.00171.

r_warm_ratio = Uniform(1.0, 5.0)

Nebular emission

Nebular line and continuum emission from CLOUDY grids or the Cue neural network emulator, with optional shock and DIG mixing.

MAPPINGS III + V shock emission line model.

Loads Allen+2008 (ApJS 178 20) MAPPINGS III and Alarie & Morisset 2019 (3MdBs, RMxAA 55 279) MAPPINGS V grids from data/mappings_templates.h5 and interpolates line ratios across the full 4-D grid:

(v_shock, B/√n or B, log_density, abundance)

If the HDF5 file is missing, falls back to the Allen+2008 Table 5 hardcoded arrays (solar, n=1 cm⁻³, 8 velocity points, 10 lines) with a DeprecationWarning. Build the grid with:

python scripts/download_mappings_templates.py

Interpolation strategy

  • velocity, B-field, log_density : library_lookup, node-exact monotone cubic (PCHIP) over the populated cells of the MAPPINGS V grid (#2861). The population mask (#2575) restricts each read to populated nodes; the masked axes hold at their populated hull.

  • abundance, component, version : Python string → integer index (static)

References

  • Allen et al. 2008, ApJS, 178, 20 (MAPPINGS III)

  • Sutherland & Dopita 2017, ApJS, 229, 34 (MAPPINGS V)

  • Alarie & Morisset 2019, RMxAA, 55, 279 (3MdBs / Zenodo 14140949)

tengri.components.nebular.shock.SHOCK_LHA_LOG_REF: float = 30.0

Reference Hα luminosity the float32 shock path carries the shock shape at, as log10 of erg/s (#1206). The shock SED is exactly linear in L_Hα, so any split of the scale is exact; the split point decides whether float32 survives. A unit-Hα reference puts ~41 dex on one log10 offset, whose Jacobian is inf in float32 while the forward stays finite. At 1e30 the carried array and its derivative both sit well inside float32.

class tengri.components.nebular.shock.ShockTemplateGrid(shock_ratios: jnp.ndarray, precursor_ratios: jnp.ndarray, combined_ratios: jnp.ndarray, hbeta_log_lum_erg_s: jnp.ndarray)[source]

Bases: NamedTuple

The four MAPPINGS V ratio cubes, in a form that threads through jax.jit.

Read from the module-level cache inside a trace, the selected ratio cube freezes into the graph as an XLA Constant: 3.73 MB for the (5, 6, 37, 35, 24) float32 array, on every compile, against a 0.05 MB bare-stellar floor (#1694). Passed as an argument instead, it is a Parameter.

Only the cubes are carried here. The grid axes (velocity, B-field, density), their triweight edges, the line wavelengths, and the two name lists stay concrete, read from _load_mappings_grids() as before: together they are ~730 bytes, so baking them is free, and keeping them concrete is what lets _validate_shock_params() compare a user’s velocity against float(v_arr[0]) and lets the abundance string resolve to a static integer index. Threading those too would turn every one of those Python-level guards into a TracerArrayConversionError.

Being a NamedTuple of plain arrays, this is already a JAX pytree: no custom registration, and no exposure to the “arrays cannot be passed as metadata fields” failure that a hand-rolled aux_data split invites (see CueWeights, #464).

Variables:
  • combined_ratios (shock_ratios, precursor_ratios,) – Line ratios relative to Hbeta, shape (n_abund, n_n, n_v, n_b, n_lines) [dimensionless]. Sparse grid cells are NaN in the file and stored as 0.0 here.

  • hbeta_log_lum_erg_s (ndarray) – Hbeta luminosity normalization [log10(erg/s)].

Notes

JIT-compatible: yes, that is the point of the type. Pass an instance as an argument rather than closing over it.

combined_ratios: Array

Alias for field number 2

hbeta_log_lum_erg_s: Array

Alias for field number 3

precursor_ratios: Array

Alias for field number 1

shock_ratios: Array

Alias for field number 0

tengri.components.nebular.shock.compute_shock_sed(wavelength: Array, shock_velocity: float, l_shock_halpha: float, shock_log_density: float = 0.0, shock_b_over_sqrt_n: float = 1.0, shock_abundance: str = 'solar', shock_component: str = 'combined', line_sigma_aa: float = 0.0, line_sigma_kms: float = 0.0, templates: ShockTemplateGrid | None = None) → Array[source]

Compute shock emission line SED.

Places MAPPINGS V (3MdBs) shock emission lines on an arbitrary wavelength grid as Gaussians (line_sigma_aa > 0) or delta functions.

Parameters:
  • wavelength (array, shape (n_wave,)) – Wavelength grid in Å (rest-frame, increasing).

  • shock_velocity (float) – Shock velocity in km/s.

  • l_shock_halpha (float) – Total shock Hα luminosity in erg/s (normalization anchor).

  • shock_log_density (float) – Log10 pre-shock density in cm⁻³.

  • shock_b_over_sqrt_n (float) – Absolute B-field in μG (3MdBs MAPPINGS V). Snapped to nearest grid point.

  • shock_abundance (str) – Abundance set (see shock_line_ratios).

  • shock_component (str) – "shock", "precursor", or "combined".

  • line_sigma_aa (float) – Gaussian line width in Å. 0 → delta function into nearest pixel.

  • templates (ShockTemplateGrid, optional) – Pre-loaded ratio cubes threaded as a JIT argument instead of baked into the graph as 3.73 MB of constants (#1694). Forwarded to shock_line_ratios(); None reads the module-level cache.

Returns:

Shock emission SED in erg/s/Hz [erg/s/Hz].

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations use jnp primitives and calls to _shock_line_arrays and _place_line_profiles.

Line placement: Emission lines are placed as Gaussian profiles (if line_sigma_aa > 0) or delta functions (if line_sigma_aa = 0). Delta functions scatter energy into the nearest pixel, normalized by pixel width to preserve flux.

tengri.components.nebular.shock.factored_l_bol(sed, nu)[source]

Bolometric -trapz(sed, nu) as a power-of-two mantissa and exponent.

Returns (hat, exponent) with -trapz(sed, nu) == ldexp(hat, exponent). The integral is taken of sed divided by 2**exponent, where the exponent is the binary exponent of the peak of |sed|, so the quadrature runs on values of order one. A power of two is exact in binary floating point, so the restored value is the unfactored integral to the last bit in float64. The peak is a stop_gradient factorization constant; the derivative runs through sed alone.

Parameters:
  • sed (ndarray, shape (n_wave,)) – Rest-frame SED [erg/s/Hz].

  • nu (ndarray, shape (n_wave,)) – Frequency grid [Hz], ascending.

Returns:

  • hat (ndarray, scalar) – Mantissa integral, dimensionless. An all-zero SED gives exponent 0.

  • exponent (ndarray, scalar, int32) – Binary exponent of the peak [dimensionless].

Notes

JIT-compatible: yes. The integrated bolometric luminosity of a 1e10 Msun galaxy is ~1e46 erg/s, past the float32 ceiling of 3.4e38, so the linear integral cannot be formed in float32 at all.

tengri.components.nebular.shock.load_shock_template_grid() → ShockTemplateGrid | None[source]

Load the MAPPINGS V ratio cubes in threadable form.

Returns:

None when data/mappings_templates.h5 is absent or carries no mappings5 group: the caller then falls back to the hardcoded Allen+2008 subset, exactly as before threading existed.

Return type:

ShockTemplateGrid or None

Notes

JIT-compatible: no, call at build time. The returned value is what threads.

tengri.components.nebular.shock.population_envelope(shock_abundance: str, shock_component: str = 'combined') → tuple[float, float, float, float] | None[source]

Populated (density, B-field) envelope for one (abundance, component) grid.

A cheap, numpy-only, build-time summary of the sparse MAPPINGS V grid’s coverage (#2065): the outer bounding interval, on each axis independently, of grid nodes that have at least one populated companion on the other axis (mask.any(axis=...)). Backs SEDModel._validate_shock_coverage (private), the build-time guard that refuses a shock_log_density / shock_b_over_sqrt_n value with no grid support before it can silently predict an exactly-zero shock spectrum.

This is deliberately coarse, not the true 2-D-coupled population: a value inside the envelope on one axis can still land in a locally-unpopulated pocket paired with the other axis’s value (the solar grid has no fully-populated 3x3 neighborhood anywhere – see the case (c) diagnosis at docs/internal/specs/2026-09-05-shock-family-interp-diagnosis.md, #2066, which is what a family-aware interpolant would fix). What this envelope does guarantee: a value strictly outside it receives no contribution from any populated cell.

Parameters:
  • shock_abundance (str) – Abundance short name or full 3MdBs DB name (see _resolve_abundance()).

  • shock_component (str) – "shock", "precursor", or "combined". Default "combined".

Returns:

(dens_lo, dens_hi, b_lo, b_hi): populated envelope in the grid’s native units (log10(cm^-3), uG). nan for all four when the (abundance, component) combination has no populated cells at all. None when data/mappings_templates.h5 is absent: the fallback Allen+2008 Table 5 path has no sparsity to guard against.

Return type:

tuple[float, float, float, float] or None

Notes

JIT-compatible: no; build-time only, which is the point (#2065’s guard needs a concrete Python shock_abundance string, never legal inside a JAX trace).

tengri.components.nebular.shock.shock_line_ratios(shock_velocity: float, shock_log_density: float = 0.0, shock_b_over_sqrt_n: float = 1.0, shock_abundance: str = 'solar', shock_component: str = 'combined', templates: ShockTemplateGrid | None = None) → dict[str, float][source]

Return emission line luminosity ratios relative to Hβ.

Loads the MAPPINGS V (3MdBs) grid from data/mappings_templates.h5. If the file is missing, falls back to the Allen+2008 Table 5 hardcoded subset with a DeprecationWarning.

Parameters:
  • shock_velocity (float) – Shock velocity in km/s. Must be within the grid range (100–1000 km/s fallback; 200–1000 km/s HDF5). Raises ValueError if out of range. Continuously interpolated: safe under jax.jit.

  • shock_log_density (float) – Log10 pre-shock density in cm⁻³ (e.g. 0.0 = 1 cm⁻³). Must be within the HDF5 grid’s declared axis, [-2, 3] (this function’s own range check enforces exactly this; the range previously documented here, [0, 3], was narrower than what the code actually accepted – #2065). Not all of [-2, 3] is populated for every abundance: see population_envelope() for the per-abundance coverage. A model built via the shock={...} grammar group additionally gets a build-time guard (SEDModel._validate_shock_coverage, private) against silently landing in an unpopulated region; a direct call to this function does not go through that guard. Continuously interpolated via triweight kernel: safe under jax.jit. Raises ValueError if out of range.

  • shock_b_over_sqrt_n (float) – Absolute B-field strength in μG (3MdBs MAPPINGS V convention). Must be within the HDF5 grid’s declared axis, [0.0001, 1000] μG (this function’s own range check enforces exactly this; the range previously documented here, [0.0001, 10], was narrower than what the code actually accepted – #2065). Continuously interpolated via triweight kernel: safe under jax.jit. Raises ValueError if out of range.

  • shock_abundance (str) – Abundance pattern. Accepted short names: "solar", "2xsolar" / "twice_solar", "dopita2005", "lmc", "smc". Full 3MdBs DB names (e.g. "Allen2008_Solar") also accepted. Raises ValueError for unknown names.

  • shock_component (str) – Which emission component to return. One of "shock", "precursor", "combined" (default). Raises ValueError for unknown values.

  • templates (ShockTemplateGrid, optional) – Pre-loaded ratio cubes, threaded as a JIT argument so they are not baked into the compiled graph as constants (#1694). None (the default) reads them from the module-level cache, which is correct but costs 3.73 MB per compile. Supplied automatically by ShockNebular on the model path; callers using this function directly rarely need it.

Returns:

PyNeb-format line name → luminosity ratio relative to Hβ [dimensionless].

Return type:

dict[str, float]

Raises:

ValueError – If any parameter is outside the grid bounds or invalid.

References

[tengri.components.nebular.shock.shock_line_ratios-1]

D. A. Allen et al., “The Distance and Metallicity of the Galaxy M33,” ApJS, 178, 20 (2008). https://doi.org/10.1086/589652

[tengri.components.nebular.shock.shock_line_ratios-2]

R. J. R. Sutherland and M. A. Dopita, “Spectral Synthesis Modeling of AGN Heating in Starburst and Post-Starburst Galaxies,” ApJS, 229, 34 (2017). https://doi.org/10.3847/1538-4365/aa6541

[tengri.components.nebular.shock.shock_line_ratios-3]

D. Alarie and C. Morisset, “Synthetic Narrow-Line Emission from a Large Grid of CLOUDY Models,” Rev. Mex. Astron. Astrofis., 55, 279 (2019). https://doi.org/10.22201/ia.01851101p.2019.55.02.14

Notes

JIT-compatible: yes, continuous parameters (velocity, density, B-field) are interpolated via library_lookup (masked PCHIP), safe under jax.jit. Discrete parameters (abundance, component) are resolved at call time and not traced.

Fallback: If the MAPPINGS V HDF5 grid is missing, falls back to the Allen+2008 Table 5 hardcoded array (solar abundance, n=1 cm⁻³, 8 velocity points) with a DeprecationWarning. To avoid this, download the grid via scripts/download_mappings_templates.py.

Interpolation: masked PCHIP (node-exact, C¹) over the populated cells of velocity, density, and B-field (tengri.utils.masked_pchip); the read is jitted, so eager calls reuse one compiled kernel.

Examples

>>> ratios = shock_line_ratios(300.0)  # solar, combined, 300 km/s
>>> ratios = shock_line_ratios(500.0, shock_component="precursor")
>>> ratios = shock_line_ratios(400.0, shock_abundance="lmc", shock_log_density=1.0)
tengri.components.nebular.shock.shock_log10_halpha_anchor(hat, exponent, frac)[source]

log10 of the shock H-alpha anchor from a factored bolometric integral.

The anchor is \(f\,\max(10^{-3} L_\mathrm{bol}, 10^{-30})\) [erg/s], as the shock template is normalized to a fraction of the galaxy’s approximate H-alpha. It is returned in log10 so that a ~1e41 erg/s value is never formed in float32.

Parameters:
  • hat – Output of factored_l_bol().

  • exponent – Output of factored_l_bol().

  • frac (float or ndarray) – Fraction of H-alpha channeled into shocks [dimensionless].

Returns:

log10 of the anchor [dex, erg/s].

Return type:

ndarray

Diffuse Ionized Gas (DIG) nebular emission model.

Models the mixing of ionizing photon-powered emission from two gas components: dense HII regions and diffuse ionized gas (DIG). DIG is low-density ionized gas between HII regions, characterized by lower ionization parameter (log U ~ −4 vs −2.5 in HII regions). This produces a distinct emission-line signature: enhanced low-ionization diagnostics ([NII]/Hα, [SII]/Hα, [OI]/Hα).

Observationally, DIG contributes ~30–60% of Hα flux in local star-forming galaxies (Reynolds 1984; Haffner et al. 2009; Tacchella et al. 2022).

Mixing formula: Returns a weighted average of nebular emission at two ionization parameters (HII + DIG):

L_total = (1 − f_DIG) × L(log U_HII) + f_DIG × L(log U_DIG)

where log U_DIG = log U_HII + Δ log U, with Δ log U = −1 dex (default).

When f_DIG = 0 (default), collapses to pure HII region emission.

Three public channel entry points share one mixing core (_mix_dig_backend_evaluations()): mix_dig_emission() for the continuum SED (predict_nebular_sed) and mix_dig_line_luminosities() for the discrete line catalog (predict_nebular_line_luminosities), both against a live backend forward. Both build one frozen keyword dict and reuse it for the HII and DIG backend calls, so any extra backend-specific kwarg (e.g. an ionizing population resolved by the caller) reaches both evaluations identically (#2221).

mix_dig_grid_reconstruction() is the third: the same two-query-point mix against the tabulated per-Q_H nebular grid (nebular_grid_precompute) instead of a live backend forward, for the FeaturePrecomp fast path (#2222).

tengri.components.nebular.dig.mix_dig_emission(nebular_backend, ssp_wave: Array, ssp_weights: Array, ssp_log_ages_yr: Array, log_z: float, neb_logU: float = -3.0, neb_logZ_gas: float | None = None, neb_fesc: float = 0.0, neb_fesc_lya: float = 1.0, neb_dig_frac: float = 0.0, neb_dig_delta_logU: float = -1.0, line_sigma_aa: float = 0.0, *, dig_active: bool | None = None, **kwargs) → Array[source]

Predict nebular SED with HII region and diffuse ionized gas components.

Computes emission from two ionization regimes (HII + DIG) using any backend, then combines via mass-weighted mixing. This captures the enhanced low-ionization emission ([NII], [SII], [OI]) characteristic of warm, ionized ISM.

Parameters:
  • nebular_backend (NebularBackend (CloudyGridBackend or CueBackend)) – Backend with predict_nebular_sed() method. Called twice (HII, DIG).

  • ssp_wave (array, shape (n_wave,)) – SSP wavelength grid in Å. [Å]

  • ssp_weights (array, shape (n_age,)) – Stellar mass weights of composite stellar population per age bin. [Msun]

  • ssp_log_ages_yr (array, shape (n_age,)) – Age grid of SSP basis (in cosmic time). [log10(yr)]

  • log_z (float) – Stellar metallicity (SSP grid metallicity). [log10(Z)]

  • neb_logU (float, optional) – HII region ionization parameter. Default: −3.0. [log10(U)]

  • neb_logZ_gas (float, optional) – Gas-phase metallicity (relative to solar). If None, defaults to stellar metallicity. Default: None. [log10(Z/Zsun)]

  • neb_fesc (float, optional) – Ionizing photon escape fraction (applies to both HII and DIG). Default: 0.0. [dimensionless, ∈ [0, 1]]

  • neb_fesc_lya (float, optional) – Lyman-α-specific escape fraction. Default: 0.0. [dimensionless, ∈ [0, 1]]

  • neb_dig_frac (float, optional) – DIG mass fraction. Default: 0.0. [dimensionless, ∈ [0, 1]]

  • neb_dig_delta_logU (float, optional) – Offset in ionization parameter for DIG (negative). Default: −1.0 dex. [dex]

  • line_sigma_aa (float, optional) – Gaussian line width for emission-line placement. Default: 0.0 (delta). [Å]

  • dig_active (bool, optional) – Whether DIG mixing is active. When True, both HII and DIG are evaluated. When False, only HII is evaluated (skip DIG entirely). When None (default), uses Python-float check on neb_dig_frac. Call-time overrides of a spec-pinned neb_dig_frac are not honored when dig_active=False (#2296).

  • **kwargs – Additional backend-specific keyword arguments (passed to both calls).

Returns:

Combined nebular SED: (1 − f_DIG) × L_HII + f_DIG × L_DIG. [erg/s/Hz]

Return type:

array, shape (n_wave,)

Notes

JIT-compatible: yes, all operations use jnp primitives, but note that when neb_dig_frac is a traced JAX value, both HII and DIG forward passes execute (no short-circuit optimization).

Mixing model (Haffner et al. 2009, Tacchella et al. 2022):

The diffuse ionized gas (DIG) has a lower ionization parameter than HII regions, producing a distinct line-ratio signature. We approximate the total emission as a linear combination:

\[L_{\mathrm{total}}(\lambda) = (1 - f_{\mathrm{DIG}}) \, L_{\mathrm{HII}}(\lambda, \log U_{\mathrm{HII}}) + f_{\mathrm{DIG}} \, L_{\mathrm{DIG}}(\lambda, \log U_{\mathrm{DIG}})\]

where log U_DIG = log U_HII + Δ log U, and both components use the same metallicity, escape fraction, and stellar population weights.

Physical picture:

  • HII regions: dense, photoionized by young (< 1 Myr) OB stars. Log U ~ −2.5 to −3. Dominated by recombination lines ([OIII], [SIII], etc.).

  • DIG: diffuse, warm (~8000 K), ionized by stellar radiation and shocks. Log U ~ −3 to −4. Dominated by forbidden lines ([NII], [SII], [OI]).

Escape fraction:

Both HII and DIG share the same f_esc (stellar-population-level escape). This is a simplification; physically, dust might preferentially shield DIG, but we do not model this spatial variation.

Pitfall: When neb_dig_frac is a JAX-traced (differentiable) value, both forward passes (HII + DIG) execute and contribute to gradients, even if neb_dig_frac = 0 at runtime. Pre-compute DIG mixing only when needed.

References

[tengri.components.nebular.dig.mix_dig_emission-1]

L. M. Haffner et al., “The warm ionized medium in spiral galaxies,” Rev. Mod. Phys., 81, 969 (2009). https://doi.org/10.1103/RevModPhys.81.969

[tengri.components.nebular.dig.mix_dig_emission-2]

S. Tacchella et al., “H-alpha emission in local galaxies: star formation, time variability, and the diffuse ionized gas,” MNRAS, 513, 2904 (2022). arXiv:2112.00027. https://doi.org/10.1093/mnras/stac818

[tengri.components.nebular.dig.mix_dig_emission-3]

R. J. Reynolds, “A Measurement of the Hydrogen Recombination Rate in the Diffuse Interstellar Medium,” ApJ, 282, 191 (1984). https://doi.org/10.1086/162190

tengri.components.nebular.dig.mix_dig_grid_reconstruction(reconstruct, amplitude, point, table, neb_dig_frac, neb_dig_delta_logU, *, log_domain=False, dig_active=None)[source]

Mix two per-Q_H grid reconstructions (HII + DIG) at a shifted neb_logU (#2222).

The tabulated-grid analog of mix_dig_emission() / mix_dig_line_luminosities(): instead of two live backend forwards, this calls the same nebular_grid_precompute reconstruction function twice – once at point["neb_logU"] (HII) and, unless the zero-fraction short-circuit fires, again at point["neb_logU"] + neb_dig_delta_logU (DIG) – and mixes with the same core (_mix_dig_backend_evaluations()) the other two wrappers share. neb_logU is one of table.axis_names whenever DIG mixing could be active (nebular_grid_precompute._dig_may_be_active), with its range extended to cover both query points, so both are always resolvable against table without clipping.

\[R_{\mathrm{total}} = (1 - f_{\mathrm{DIG}}) \, \mathrm{reconstruct}(A, \log U) + f_{\mathrm{DIG}} \, \mathrm{reconstruct}(A, \log U + \Delta \log U)\]

where \(\mathrm{reconstruct}\) is reconstruct, \(A\) is amplitude, \(f_{\mathrm{DIG}}\) is neb_dig_frac [dimensionless, in 0 to 1], and \(\Delta \log U\) is neb_dig_delta_logU [dex].

Parameters:
  • reconstruct (callable) – reconstruct(amplitude, point, table) -> ndarray. One of reconstruct_nebular_phot(), reconstruct_nebular_restband() (both ndarray, shape (n_filter,), linear L_nu – pass with log_domain=False), or reconstruct_nebular_line_log_lums() (ndarray, shape (n_lines,), log10 erg/s – pass with log_domain=True). The plain linear reconstruct_nebular_line_lums() is float32-unsafe by construction (its own docstring) and should not be mixed here; use the log form instead.

  • amplitude (float or array_like, shape ()) – The Q_H-derived amplitude every reconstruct variant above expects: log_nion [dex re photons/s].

  • point (Mapping) – Interpolation point: point[name] for every name in table.axis_names, including neb_logU whenever that is one of them. A point with no "neb_logU" key is fine only when "neb_logU" is not a table axis (DIG necessarily inactive then); when it is an axis, a missing "neb_logU" raises.

  • table (NebularGridTable) – The grid to interpolate (precompute_nebular_grid()).

  • neb_dig_frac (float) – DIG mass fraction. [dimensionless, in [0, 1]]

  • neb_dig_delta_logU (float) – Offset in ionization parameter for DIG (negative). [dex]

  • log_domain (bool, optional) – False (default) mixes reconstruct’s return value linearly (_linear_mix()) – correct for the photometry / rest-band channels, whose linear L_nu never leaves float32 range. True mixes it as a log10 magnitude (_log10_weighted_mix()) – required for reconstruct_nebular_line_log_lums(), whose linear form (~1e40 erg/s) overflows float32 (#2269): mixing the log10 values directly, rather than exponentiating each to mix and re-logging, keeps every intermediate in range.

  • dig_active (bool, optional) – Whether DIG mixing is active. When True, both HII and DIG are evaluated. When False, only HII is evaluated (skip DIG entirely). When None (default), uses Python-float check on neb_dig_frac. This is the one call site where a call-time override of a spec-pinned neb_dig_frac actually reaches the mixing core: SEDModel.predict_line_fluxes merges {**self.spec.get_fixed_values(), **params} before reading full_params["neb_dig_frac"], so a caller can hand this function a nonzero fraction while dig_active (resolved once from self.spec via _dig_may_be_active, not from full_params) still reads False. When that happens the override is not honored: the second reconstruct call is skipped regardless of the overridden value (#2296).

Returns:

Whatever reconstruct returns: the HII-only reconstruction when neb_dig_frac short-circuits, else the mix (linear or log10 magnitude, per log_domain) of (1 - f) * hii + f * dig.

Return type:

ndarray, shape (n_filter,) or (n_lines,)

Raises:

KeyError – If "neb_logU" is one of table.axis_names but point does not carry it: every axis the table was built over must have a matching entry in the query point (#2222 review I1). A caller must merge the model’s Fixed values in first (mirrors predict_state’s full_params = {**fixed_values, **params}) rather than rely on a registry-default placeholder, which would substitute the wrong value for a model whose Fixed pin differs from the default.

Notes

JIT-compatible: yes – node-exact PCHIP interpolation (inside reconstruct) plus a linear or log10-domain mix (per log_domain), both pure jnp operations. Same short-circuit contract as mix_dig_emission(): a Python-literal neb_dig_frac == 0.0 skips the second interpolation entirely (one reconstruct call, the pre-DIG cost); a traced neb_dig_frac runs both.

References

[tengri.components.nebular.dig.mix_dig_grid_reconstruction-1]

L. M. Haffner et al., “The warm ionized medium in spiral galaxies,” Rev. Mod. Phys., 81, 969 (2009). https://doi.org/10.1103/RevModPhys.81.969

[tengri.components.nebular.dig.mix_dig_grid_reconstruction-2]

S. Tacchella et al., “H-alpha emission in local galaxies: star formation, time variability, and the diffuse ionized gas,” MNRAS, 513, 2904 (2022). arXiv:2112.00027. https://doi.org/10.1093/mnras/stac818

tengri.components.nebular.dig.mix_dig_line_luminosities(nebular_backend, ssp_wave: Array, ssp_weights: Array, ssp_log_ages_yr: Array, log_z: float, neb_logU: float = -3.0, neb_logZ_gas: float | None = None, neb_fesc: float = 0.0, neb_fesc_lya: float = 1.0, neb_dig_frac: float = 0.0, neb_dig_delta_logU: float = -1.0, line_sigma_aa: float = 0.0, *, dig_active: bool | None = None, **kwargs) → tuple[Array, Array][source]

Predict discrete line luminosities with HII and DIG components.

Same contract as mix_dig_emission(), but calls nebular_backend.predict_nebular_line_luminosities (a (line_waves, line_lums) pair) instead of predict_nebular_sed. Only the luminosities are mixed; the wavelengths are the HII call’s (the DIG call’s own line_waves are discarded), since both calls catalog the same species at the same rest wavelengths and only the HII evaluation’s copy is kept.

Parameters:
  • nebular_backend (NebularBackend (CloudyGridBackend, CueBackend, or CB19Backend)) – Backend with a predict_nebular_line_luminosities() method. Called twice (HII, DIG).

  • ssp_wave (array, shape (n_wave,)) – SSP wavelength grid in Å. [Å]

  • ssp_weights (array, shape (n_age,)) – Stellar mass weights of composite stellar population per age bin. [Msun]

  • ssp_log_ages_yr (array, shape (n_age,)) – Age grid of SSP basis (in cosmic time). [log10(yr)]

  • log_z (float) – Stellar metallicity (SSP grid metallicity). [log10(Z)]

  • neb_logU (float, optional) – HII region ionization parameter. Default: −3.0. [log10(U)]

  • neb_logZ_gas (float, optional) – Gas-phase metallicity (relative to solar). If None, defaults to stellar metallicity. Default: None. [log10(Z/Zsun)]

  • neb_fesc (float, optional) – Ionizing photon escape fraction (applies to both HII and DIG). Default: 0.0. [dimensionless, ∈ [0, 1]]

  • neb_fesc_lya (float, optional) – Lyman-α-specific escape fraction. Default: 0.0. [dimensionless, ∈ [0, 1]]

  • neb_dig_frac (float, optional) – DIG mass fraction. Default: 0.0. [dimensionless, ∈ [0, 1]]

  • neb_dig_delta_logU (float, optional) – Offset in ionization parameter for DIG (negative). Default: −1.0 dex. [dex]

  • line_sigma_aa (float, optional) – Unused by the line-luminosity channel (kept for a signature identical to mix_dig_emission(); forwarded via **kwargs to the backend, which ignores it). Default: 0.0. [Å]

  • dig_active (bool, optional) – Whether DIG mixing is active. When True, both HII and DIG are evaluated. When False, only HII is evaluated (skip DIG entirely). When None (default), uses Python-float check on neb_dig_frac. Call-time overrides of a spec-pinned neb_dig_frac are not honored when dig_active=False (#2296).

  • **kwargs – Additional backend-specific keyword arguments (passed to both calls).

Returns:

  • line_waves (array, shape (n_lines,)) – Rest-frame line wavelengths, from the HII evaluation. [Å]

  • line_lums (array, shape (n_lines,)) – Combined line luminosities: (1 − f_DIG) × L_HII + f_DIG × L_DIG. [Lsun]

Notes

JIT-compatible: yes, all operations use jnp primitives, but note that when neb_dig_frac is a traced JAX value, both HII and DIG forward passes execute (no short-circuit optimization).

Mixing model (Haffner et al. 2009, Tacchella et al. 2022): identical formula to mix_dig_emission(), applied to each cataloged line’s luminosity independently:

\[L_{\mathrm{total},i} = (1 - f_{\mathrm{DIG}}) \, L_{\mathrm{HII},i}(\log U_{\mathrm{HII}}) + f_{\mathrm{DIG}} \, L_{\mathrm{DIG},i}(\log U_{\mathrm{DIG}})\]

where log U_DIG = log U_HII + Δ log U and \(i\) indexes the cataloged lines.

Pitfall: When neb_dig_frac is a JAX-traced (differentiable) value, both forward passes (HII + DIG) execute and contribute to gradients, even if neb_dig_frac = 0 at runtime. Pre-compute DIG mixing only when needed.

References

[tengri.components.nebular.dig.mix_dig_line_luminosities-1]

L. M. Haffner et al., “The warm ionized medium in spiral galaxies,” Rev. Mod. Phys., 81, 969 (2009). https://doi.org/10.1103/RevModPhys.81.969

[tengri.components.nebular.dig.mix_dig_line_luminosities-2]

S. Tacchella et al., “H-alpha emission in local galaxies: star formation, time variability, and the diffuse ionized gas,” MNRAS, 513, 2904 (2022). arXiv:2112.00027. https://doi.org/10.1093/mnras/stac818

[tengri.components.nebular.dig.mix_dig_line_luminosities-3]

R. J. Reynolds, “A Measurement of the Hydrogen Recombination Rate in the Diffuse Interstellar Medium,” ApJ, 282, 191 (1984). https://doi.org/10.1086/162190

Observation models

Photometry, spectroscopy, calibration, and emission line marginalization.

Spectrophotometric calibration polynomials.

When fitting spectra, the observed spectrum has wavelength-dependent calibration errors from flux calibration, slit losses, and telluric residuals. A low-order Chebyshev polynomial corrects this multiplicatively:

spec_obs(lambda) = C(lambda) * spec_physical(lambda)

where C(lambda) = 1 + sum_{n=1}^{order} a_n * T_n(x) and x = 2*(lambda - lambda_min)/(lambda_max - lambda_min) - 1 maps wavelengths to [-1, 1]. The constant term is unity by convention (overall normalization is handled elsewhere); the fitted coefficients represent deviations from a flat calibration.

Coefficients a_n have a Gaussian(0, sigma) prior that regularizes the polynomial toward unity, preventing overfitting of broad spectral features.

Parameters integration example

To add calibration coefficients as free parameters:

from tengri.parameters.priors import Gaussian

spec = Parameters(
    ...,
    # 3rd-order calibration polynomial (3 free coefficients)
    cal_c1=Gaussian(0.0, 0.1),
    cal_c2=Gaussian(0.0, 0.1),
    cal_c3=Gaussian(0.0, 0.05),
)

# In the forward model, pack coefficients and apply:
coeffs = jnp.array([params["cal_c1"], params["cal_c2"], params["cal_c3"]])
model_spec = apply_calibration(physical_spec, wave_obs, coeffs, wave_min, wave_max)

References

Johnson et al. (2021), Prospector calibration model.

tengri.observation.calibration.apply_calibration(spectrum: Array, wavelength: Array, coeffs: Array, wave_min: float, wave_max: float) → Array[source]

Apply calibration polynomial to a spectrum.

Returns spectrum * C(lambda), where C(lambda) is the Chebyshev calibration polynomial evaluated at the given wavelengths.

Parameters:
  • spectrum (array, shape (n_wave,)) – Physical model spectrum (any flux units).

  • wavelength (array, shape (n_wave,)) – Wavelength grid [Angstrom].

  • coeffs (array, shape (order,)) – Chebyshev coefficients a_1, …, a_order.

  • wave_min (float) – Wavelength range for normalization to [-1, 1].

  • wave_max (float) – Wavelength range for normalization to [-1, 1].

Returns:

Calibrated spectrum (same units as input spectrum).

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes. Gradient-safe: yes, differentiable w.r.t. spectrum and coefficients.

tengri.observation.calibration.apply_double_calibration(spectrum: Array, wavelength: Array, coeffs_blue: Array, coeffs_red: Array, wave_split: float) → Array[source]

Apply piecewise calibration polynomial to a spectrum.

Parameters:
  • spectrum (array, shape (n_wave,)) – Physical model spectrum (any flux units).

  • wavelength (array, shape (n_wave,)) – Wavelength grid [Angstrom], must be sorted.

  • coeffs_blue (array, shape (order_blue,)) – Chebyshev coefficients for the blue arm (wavelength < wave_split).

  • coeffs_red (array, shape (order_red,)) – Chebyshev coefficients for the red arm (wavelength >= wave_split).

  • wave_split (float) – Wavelength boundary [Angstrom].

Returns:

Calibrated spectrum (same units as input spectrum).

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes. Gradient-safe: yes, differentiable w.r.t. spectrum and coefficients.

tengri.observation.calibration.calibration_basis(wave: Array, wave_min: float, wave_max: float, n_poly: int, segments: Array | None = None, n_segments: int = 0) → Array[source]

Chebyshev basis T_1 through T_{n_poly}, optionally prefixed by segment indicators.

Column \(k\) of the Chebyshev block is \(T_k(x)\) with \(x = (2\lambda - \lambda_\min - \lambda_\max)/(\lambda_\max - \lambda_\min)\), so that \(1 + B\,c\) equals calibration_polynomial() for coefficients \(c = (a_1, \ldots, a_{n})\).

With segments given, the result is \([\mathbb{1}_{s=1}, \ldots, \mathbb{1}_{s=n_\mathrm{seg}}, T_1(x), \ldots, T_{n_\mathrm{poly}}(x)]\): one indicator column per camera segment, so that the calibration multiplier \(\sum_s c_s \mathbb{1}_{s} + \sum_j a_j T_j\) carries its constant in the segment scales and no implicit unit term.

Parameters:
  • wave (array_like, shape (n,)) – Wavelength grid [Angstrom].

  • wave_min (float) – Lower bound of the normalization interval [Angstrom].

  • wave_max (float) – Upper bound of the normalization interval [Angstrom].

  • n_poly (int) – Highest Chebyshev order. Zero leaves only the segment indicators when segments is given. Static under JIT.

  • segments (array_like of int, shape (n,), optional) – Camera segment id of every pixel, in range(n_segments). Default: no segment columns.

  • n_segments (int, optional) – Number of segment columns. Static under JIT. Used only with segments. Default 0.

Returns:

Basis matrix (dimensionless). Without segments the columns are \([T_1(x), \ldots, T_{n_\mathrm{poly}}(x)]\); with segments the indicator columns come first.

Return type:

ndarray, shape (n, n_poly) or (n, n_segments + n_poly)

Notes

JIT-compatible: yes. n_poly and n_segments are static; the recurrence is a Python loop over n_poly, so no lax.scan is traced.

Gradient-safe: yes, differentiable with respect to wave, wave_min and wave_max. The indicator columns carry no gradient.

The recurrence is \(T_0 = 1\), \(T_1 = x\), \(T_{k+1} = 2x\,T_k - T_{k-1}\).

tengri.observation.calibration.calibration_polynomial(wavelength: Array, coeffs: Array, wave_min: float, wave_max: float) → Array[source]

Multiplicative calibration polynomial C(lambda).

C(lambda) = 1 + sum_{n=1}^{order} a_n * T_n(x)

The constant term is fixed to 1 (flat calibration); coeffs supplies a_1 through a_order representing deviations from unity.

Parameters:
  • wavelength (array, shape (n_wave,)) – Wavelength grid [Angstrom].

  • coeffs (array, shape (order,)) – Chebyshev coefficients a_1, …, a_order. Empty array gives C(lambda) = 1 everywhere.

  • wave_min (float) – Wavelength range for normalization to [-1, 1].

  • wave_max (float) – Wavelength range for normalization to [-1, 1].

Returns:

Multiplicative calibration factor (dimensionless).

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible and gradient-safe in both coeffs and wavelength.

Evaluated by Clenshaw’s backward recurrence on \(S = c_0 + \sum_{n \ge 1} c_n T_n(x)\) with implicit \(c_0 = 1\): \(b_k = c_k + 2x\,b_{k+1} - b_{k+2}\) scanned from \(k = N\) down to \(k = 1\), then \(S = 1 + x\,b_1 - b_2\).

tengri.observation.calibration.calibration_q_log_prior(log_q: Array, v: Array, *, prior_sigma: float = 1.0, cal_prior: str = 'gaussian') → Array[source]

Log prior on \(\ln q\) that the coefficient prior contributes.

With cal_prior="gaussian" the coefficient prior \(\mathcal{N}(0, \sigma_p^2 I)\) has the marginal \(q \sim \mathcal{N}(1, \sigma_p^2 v^\mathsf{T}v)\). Per unit \(\ln q\) its log density is

\[\ln\mathcal{N}(q;\,1,\,\sigma_p^2 v^\mathsf{T}v) + \ln q,\]

the second term being \(\ln(dq/d\ln q)\). With "scale_free" the flat coefficient prior contributes nothing along \(q\), and the result is zero. Add the log-normal prior on \(\ln q\) to this value.

Parameters:
  • log_q (array_like, shape ()) – \(\ln q\), the log of the mean multiplier (dimensionless).

  • v (array_like, shape (k,)) – Vector from mean_multiplier_vector() (dimensionless).

  • prior_sigma (float, optional) – Width \(\sigma_p\) of the coefficient prior. Default 1.0.

  • cal_prior ({"gaussian", "scale_free"}, optional) – Static. Default "gaussian".

Returns:

Log prior density per unit \(\ln q\) (dimensionless).

Return type:

ndarray, shape ()

Notes

JIT-compatible: yes. Gradient-safe: yes.

tengri.observation.calibration.chebyshev_basis(wavelength: Array, order: int, wave_min: float, wave_max: float) → Array[source]

Evaluate Chebyshev polynomial basis at given wavelengths.

Uses the three-term recurrence relation for numerical stability: T_0(x) = 1, T_1(x) = x, T_{n+1}(x) = 2x*T_n(x) - T_{n-1}(x).

Parameters:
  • wavelength (array, shape (n_wave,)) – Wavelength grid [Angstrom].

  • order (int) – Maximum polynomial order (returns order+1 basis functions, from T_0 through T_order).

  • wave_min (float) – Minimum wavelength for normalization to [-1, 1] [Angstrom].

  • wave_max (float) – Maximum wavelength for normalization to [-1, 1] [Angstrom].

Returns:

Chebyshev basis functions T_0(x), T_1(x), …, T_order(x) (dimensionless).

Return type:

ndarray, shape (order+1, n_wave)

Notes

JIT-compatible: yes, order is a static argument. Gradient-safe: yes, differentiable w.r.t. wavelength.

tengri.observation.calibration.double_calibration_polynomial(wavelength: Array, coeffs_blue: Array, coeffs_red: Array, wave_split: float) → Array[source]

Piecewise calibration: independent Chebyshev polynomials for blue and red halves.

For two-arm spectrographs (e.g. X-SHOOTER, DEIMOS) where a detector gap or dichroic split causes a calibration discontinuity, fitting a single polynomial across the full range can bias the result. This function applies separate polynomials to each half, matched to their local wavelength range.

Parameters:
  • wavelength (array, shape (n_wave,)) – Wavelength grid [Angstrom], must be sorted.

  • coeffs_blue (array, shape (order_blue,)) – Chebyshev coefficients for the blue arm (wavelength < wave_split).

  • coeffs_red (array, shape (order_red,)) – Chebyshev coefficients for the red arm (wavelength >= wave_split).

  • wave_split (float) – Wavelength boundary between blue and red arms [Angstrom].

Returns:

Multiplicative calibration factor (dimensionless).

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes. Gradient-safe: yes, differentiable w.r.t. coefficients and wavelengths.

tengri.observation.calibration.joint_calibration_line_marginal(data, model0, basis, line, prior_sigma, *, whitening, pix_mask=None, col_mask=None, dof=None)[source]

Return the linear-Gaussian marginal over the calibration polynomial and the lines.

The design is model0 * basis in front of line.design. The calibration block carries a zero-mean Gaussian prior of width prior_sigma, and the line block carries the prior of line. Normalization constants are left to the caller.

Parameters:
  • data (ndarray, shape (n_pix,)) – Observed values.

  • model0 (ndarray, shape (n_pix,)) – Unscaled model values that the calibration multiplies.

  • basis (ndarray, shape (n_pix, n_poly)) – Calibration basis evaluated on the pixels.

  • line (object) – Unit line prior with design, prior_mean, prior_precision and scale, as returned by unit_line_prior().

  • prior_sigma (float) – Standard deviation of the Gaussian prior on each calibration coefficient.

  • whitening (dict) – Noise keyword of marginalize_linear_nuisance(), either {"sigma": ...} or {"chol_lower": ...}.

  • pix_mask (ndarray, shape (n_pix,), optional) – Pixel weights; zero drops a pixel.

  • col_mask (ndarray, shape (n_poly + n_lines,), optional) – Column weights over the calibration and line columns together.

  • dof (float, optional) – Student-t degrees of freedom of the noise; given, the marginal is the Laplace approximation at the iteratively reweighted mode (see marginalize_linear_nuisance()).

Returns:

The marginal returned by marginalize_linear_nuisance.

Return type:

MarginalResult

tengri.observation.calibration.marginalize_calibration(model_flux: Array, obs_flux: Array, obs_err: Array, wavelength: Array, n_poly: int = 3, prior_sigma: float = 1.0, *, pix_mask: Array | None = None, wave_range: tuple[float, float] | None = None, chol_data: Array | None = None, chol_offsets: tuple[int, ...] | None = None, dof: Array | None = None, diagnostics: bool = False) → tuple[source]

Analytically marginalize over calibration polynomial coefficients.

Given a model SED m(lambda) and observed spectrum d(lambda) with noise sigma(lambda), the calibrated model is C(lambda)*m(lambda) where C is a Chebyshev polynomial. With a Gaussian prior on the polynomial coefficients c ~ N(0, prior_sigma^2 I), the optimal coefficients and marginalized log-likelihood are computed in closed form.

This follows the Prospector approach: the calibration polynomial is treated as a nuisance and integrated out analytically at each likelihood evaluation, reducing the dimensionality of the sampling problem.

Parameters:
  • model_flux (array, shape (n_wave,)) – Physical model spectrum (any flux units, matching obs_flux).

  • obs_flux (array, shape (n_wave,)) – Observed spectrum (same units as model_flux).

  • obs_err (array, shape (n_wave,)) – 1-sigma uncertainties on the observed spectrum (same units).

  • wavelength (array, shape (n_wave,)) – Wavelength grid [Angstrom].

  • n_poly (int, optional) – Number of Chebyshev polynomial coefficients (order 1 through n_poly). The constant term (T_0 = 1) is implicit and fixed. Default 3.

  • prior_sigma (float, optional) – Standard deviation of the Gaussian prior on each coefficient. Default 1.0.

  • pix_mask (array_like, shape (n_wave,), optional, keyword-only) – Pixel mask in {0, 1}. Masked pixels are absent from every term. Default: all pixels used.

  • wave_range (tuple of float, optional, keyword-only) – (wave_min, wave_max) [Angstrom] that normalize the Chebyshev coordinate. Default: (wavelength.min(), wavelength.max()).

  • chol_data (array_like, shape (p + 1, n_wave), optional, keyword-only) – Bands of the lower Cholesky factor of the pixel covariance, from banded_cholesky(). With a factor the pixels are whitened by it and obs_err is not read. Default: None (diagonal obs_err).

  • chol_offsets (tuple of int, optional, keyword-only) – Diagonal offsets (0, -1, ..., -p) of chol_data. Static. Required with chol_data.

  • dof (float, optional, keyword-only) – Student-t degrees of freedom of the noise. Given, the value is the Laplace approximation at the iteratively reweighted mode (see marginalize_linear_nuisance()). Default: None (Gaussian noise, exact).

  • diagnostics (bool, optional, keyword-only) – Append the MarginalResult of the primitive to the returned tuple; it carries the Student-t convergence diagnostics. Static. Default: False.

Returns:

  • log_likelihood_marginal (scalar) – Marginalized log-likelihood with calibration polynomial integrated out.

  • c_hat (ndarray, shape (n_poly,)) – MAP calibration coefficients (a_1 … a_n_poly).

  • c_hat_err (ndarray, shape (n_poly,)) – Posterior standard deviations of the coefficients.

Notes

JIT-compatible: yes, n_poly is a static argument. Gradient-safe: yes, inherited from marginalize_linear_nuisance().

The calibration polynomial is the nuisance design \(X = m(\lambda)\,T(x)\) with \(T\) from calibration_basis(), and the marginal is marginalize_linear_nuisance() with prior precision \(I/\sigma_{\rm prior}^2\) and prior mean zero. The sigma floor, \(\sigma \ge\) representable_floor(1e-300), is applied here, before whitening; the primitive itself applies no floor.

wave_range=None uses the grid extremes. On a monotonic grid these are the first and last wavelengths.

References

Johnson et al. 2021, ApJS, 254, 22 (Prospector).

tengri.observation.calibration.marginalize_calibration_segments(model_flux: Array, obs_flux: Array, obs_err: Array, wavelength: Array, segments: Array, *, n_segments: int, n_poly: int = 0, prior_sigma: float = 1.0, cal_prior: str = 'gaussian', pix_mask: Array | None = None, wave_range: tuple[float, float] | None = None, lines=None, line_col_mask: Array | None = None, log_q: Array | None = None, q_window: Array | None = None, q_prior: bool = False, chol_data: Array | None = None, chol_offsets: tuple[int, ...] | None = None, dof: Array | None = None, diagnostics: bool = False) → tuple[source]

Marginalize per-segment calibration scales and a Chebyshev tilt in closed form.

The calibrated model of a multi-camera spectrum is \(M(\lambda) = \sum_s c_s \mathbb{1}_{\mathrm{seg}(\lambda)=s} + \sum_j a_j T_j(x)\) times the model flux, with one free scale \(c_s\) per camera segment and a shared tilt of order n_poly. Every column is linear in the coefficients, so the data term is marginalize_linear_nuisance() with no fixed offset. Emission-line columns (lines) join the same marginal and keep their own prior; log_q pins the window-mean multiplier \(q\).

Parameters:
  • model_flux (array_like, shape (n,)) – Physical model spectrum [data flux units].

  • obs_flux (array_like, shape (n,)) – Observed spectrum [data flux units].

  • obs_err (array_like, shape (n,)) – One-sigma uncertainties [data flux units].

  • wavelength (array_like, shape (n,)) – Wavelength grid [Angstrom]; normalizes the Chebyshev tilt.

  • segments (array_like of int, shape (n,)) – Camera segment id of every pixel, in range(n_segments).

  • n_segments (int, keyword-only) – Number of segment scales. Static under JIT.

  • n_poly (int, keyword-only) – Order of the shared Chebyshev tilt. Zero keeps only the segment scales. Static under JIT. Default 0.

  • prior_sigma (float, keyword-only) – Width of the Gaussian prior on each coefficient when cal_prior="gaussian". Default 1.0.

  • cal_prior ({"gaussian", "scale_free"}, keyword-only) – "gaussian" puts \(\mathcal{N}(0, \sigma_p^2)\) on each segment deviation \(u_s = s_s - 1\) and on each tilt coefficient, so each segment scale \(s_s\) has the prior \(\mathcal{N}(1, \sigma_p^2)\). "scale_free" puts a flat prior on the coefficients in data-flux units: every calibration column is divided by \(a = \sum_i w_i m_i / N_\mathrm{eff}\), the masked mean model flux, and the flat-prior Jacobian \(k\ln a\) is added, where \(k\) counts only the calibration columns. Default "gaussian".

  • pix_mask (array_like, shape (n,), optional, keyword-only) – Pixel mask in {0, 1}. Masked pixels are absent from every term. Default: all pixels used.

  • wave_range (tuple of float, optional, keyword-only) – (wave_min, wave_max) [Angstrom] normalizing the tilt. Default: the grid extremes.

  • lines (UnitLinePrior, optional, keyword-only) – Emission-line block from unit_line_prior(), built on the same obs_flux units. Default: no lines.

  • line_col_mask (array_like, shape (n_lines,), optional, keyword-only) – 1 for a line with support on the grid, 0 to remove it. Default: all ones.

  • log_q (array_like, shape (), optional, keyword-only) – \(\ln q\), the log of the multiplier’s mean over q_window (dimensionless). Given, the coefficient block is conditioned on \(v^\mathsf{T}\beta = q - 1\) and the return value is the marginal given \(q\). Needs at least two calibration columns.

  • q_window (array_like, shape (n,), optional, keyword-only) – Window \(W_i \in \{0, 1\}\) over which \(q\) is the mean. Default: every unmasked pixel.

  • q_prior (bool, keyword-only) – Static. With log_q given, add calibration_q_log_prior(), so the value is the log density of \(\ln q\) under the coefficient prior times the data likelihood, up to the user’s own prior on \(\ln q\). Default False.

  • chol_data (array_like, shape (p + 1, n), optional, keyword-only) – Bands of the banded lower Cholesky factor of the pixel covariance, from banded_cholesky() with the same pix_mask [data flux units]. It replaces obs_err as the noise: the whitening is \(L^{-1}\) instead of \(\mathrm{diag}(\sigma)^{-1}\), and obs_err only sets the normalization. Default: diagonal noise.

  • chol_offsets (tuple of int, optional, keyword-only) – Diagonal offsets of chol_data, static under JIT. Given together with chol_data. Default: None.

  • dof (float, optional, keyword-only) – Student-t degrees of freedom of the noise. Given, the value is the Laplace approximation at the iteratively reweighted mode (see marginalize_linear_nuisance()). Default: None (Gaussian noise, exact).

  • diagnostics (bool, optional, keyword-only) – Append the MarginalResult of the primitive to the returned tuple; it carries the Student-t convergence diagnostics. Static. Default: False.

Returns:

  • log_likelihood_marginal (ndarray, shape ()) – Marginal log-likelihood with the calibration coefficients (and the lines) integrated out (dimensionless).

  • coef_hat (ndarray, shape (n_segments + n_poly,)) – Posterior mean of the calibration coefficients. For "gaussian" the first n_segments are the segment deviations \(u_s\), so the scales are 1 + coef_hat, and the rest are the tilt coefficients. For "scale_free" they are in data-flux units, and the multiplier coefficients are coef_hat / a.

  • coef_err (ndarray, shape (n_segments + n_poly,)) – Posterior standard deviations of the coefficients, in the units of coef_hat.

Raises:

ValueError – If cal_prior is neither "gaussian" nor "scale_free", or log_q is given with fewer than two calibration columns.

Notes

JIT-compatible: yes; n_segments, n_poly and cal_prior are static.

Gradient-safe: yes, with respect to model_flux, obs_flux, obs_err and log_q, inherited from marginalize_linear_nuisance(). The "scale_free" branch passes the normalization as the primitive’s coefficient scale, so the whitened design stays order unity when the flux is far below unity.

vmap: yes over any leading batch axis.

The data model is \(d = w\,\cdot\,M\,m + \epsilon\), with \(\epsilon\) drawn from \(\mathcal{N}(0, \sigma^2)\). The offset is \(m\) and the segment columns carry \(u_s = s_s - 1\), which is an exact reparametrization of the \(\mathcal{N}(1, \sigma_p^2)\) prior on \(s_s\). Keeping the offset at the model, rather than zero with the scale in the columns, keeps the residual small so float32 does not cancel two large sums of squares. The scale-free Jacobian is the change of variables from the multiplier coefficients \(c\) to data-flux coefficients \(\beta = a\,c\), which contributes \(+k\ln a\) to the log-density. Under rescaling of the model, data and errors by a common factor \(\lambda\), the marginal changes by \((k - N_\mathrm{eff})\ln\lambda\): the density of the data moves with its units and the flat coefficient prior with the calibration columns only.

With log_q the mean multiplier is \(q = 1 + v^\mathsf{T}\beta\) with \(v\) from mean_multiplier_vector(). The coefficients are written \(\beta = Q\gamma + u\,(q - 1)\) with \(u = v/v^\mathsf{T}v\) and \(Q\) an orthonormal basis of the null space of \(v^\mathsf{T}\) (\(v^\mathsf{T}Q = 0\), \(Q^\mathsf{T}Q = I\)), so the design is \(XQ\) (full rank), the offset is \(m + Xu\,(q - 1)\), and the Jacobian of \((\gamma, q) \to \beta\) is constant. For the isotropic Gaussian prior the conditional prior of \(\gamma\) given \(q\) is \(\mathcal{N}(0, \sigma_p^2 I)\) because \(Q^\mathsf{T}u = 0\); the marginal of \(q\) itself is calibration_q_log_prior(). With "scale_free" the flat branch counts the \(k - 1\) columns of \(\gamma\) only.

tengri.observation.calibration.mean_multiplier_vector(basis: Array, weight: Array, window: Array | None = None) → Array[source]

Return the vector \(v\) with \(q - 1 = v^\mathsf{T}\beta\) for the window mean.

The calibration multiplier is \(M = 1 + B\beta\) with \(B\) from calibration_basis() and the segment coefficients written as deviations \(u_s = s_s - 1\). Its mean over the window \(W\) is \(q = \sum_i w_i W_i M_i / \sum_i w_i W_i = 1 + v^\mathsf{T}\beta\).

Parameters:
  • basis (array_like, shape (n, k)) – Calibration basis from calibration_basis() (dimensionless).

  • weight (array_like, shape (n,)) – Pixel mask \(w_i \in \{0, 1\}\).

  • window (array_like, shape (n,), optional) – Window \(W_i \in \{0, 1\}\). Default: every pixel.

Returns:

\(v_k = \sum_i w_i W_i B_{ik} / \sum_i w_i W_i\) (dimensionless).

Return type:

ndarray, shape (k,)

Notes

JIT-compatible: yes. Gradient-safe: yes, a constant of the data.

Instrumental broadening — the intrinsic stellar velocity dispersion and the spectrograph’s own line-spread function — is applied to a model spectrum before it is compared with data.

tengri.velocity_broaden(flux: Array, wave: Array, sigma_km_s: float) → Array[source]

Broaden a spectrum by stellar velocity dispersion.

Convolves with a Gaussian in log-wavelength space (equivalent to velocity space: Δv/c = Δln(λ)). Uses FFT convolution for speed.

Parameters:
  • flux (array, shape (n_pix,)) – Input spectral flux.

  • wave (array, shape (n_pix,)) – Wavelength grid [Angstrom]. Must be uniformly spaced in log-wavelength, e.g. jnp.logspace(...), not jnp.linspace(...). A linearly-spaced grid is rejected; see Notes.

  • sigma_km_s (float) – Velocity dispersion [km/s]. Typical range: 50–300 km/s.

Returns:

Broadened spectrum (same units as input).

Return type:

ndarray, shape (n_pix,)

Raises:

ValueError – If wave is concrete and not uniform in ln(lambda). Resample onto a log grid first.

Notes

JIT-compatible: yes. Gradient-safe: yes.

The convolution is a constant Gaussian in ln(lambda), because Delta v / c = Delta ln(lambda). That is what makes one FFT correct for the whole array, and it is exact only when the grid is uniform in ln(lambda).

On a linear grid the result is wrong by a constant factor wave[0] / lambda_line (issue #1742). d(ln lambda) = d(lambda)/lambda varies as 1/lambda there, so a width read off the first pixel pair sets the kernel by the bluest pixel while the feature sits elsewhere. Measured on linspace(4500, 5500, 4096) with a line at 5000 A: 100 km/s recovered as 90.2, 500 as 450.1, a constant 0.900 = 4500/5000. The error scales with the wavelength range, not the pixel count, so refining the grid does not help: across 3000–10000 A a line at 9000 A would be broadened to 0.33 of the requested width, and a fitted velocity dispersion inherits that smoothly, with nothing looking broken.

This previously passed silently, and the Parameters section said “uniformly spaced”, instructing users to do the thing that breaks it. It now raises instead, on the reasoning recorded in tengri.forward.approx_policy: a silently-defaulting read is worse than a loud failure.

A traced wave cannot be inspected at trace time, so it takes the piecewise path of broaden_velocity_only() instead, which reads the pixel scale per pixel and so is correct on any increasing grid. On a log-uniform grid that path equals the single FFT (the piecewise bins share one sigma). Under jax.jit with a concrete (closed-over) grid, the usual case for a fixed instrument grid, the check still fires.

Examples

>>> import jax.numpy as jnp
>>> from tengri.observation.spectrum import velocity_broaden
>>> wave = jnp.logspace(jnp.log10(4500.0), jnp.log10(5500.0), 256)
>>> flux = jnp.ones_like(wave)
>>> out = velocity_broaden(flux, wave, 150.0)
>>> out.shape == wave.shape
True
tengri.apply_lsf(spectrum: Array, wave_obs: Array, resolution: Array | float, sigma_lib_kms: Array | float = 0.0, n_bins: int = 16, sigma_v_kms: Array | float = 0.0, *, pad_pixels: int | None = None) → Array[source]

Apply wavelength-dependent Line Spread Function with library resolution subtraction.

Convolves the input spectrum with a Gaussian kernel that combines instrument line-spread function (LSF) and stellar velocity dispersion, accounting for the pre-existing broadening in the SSP library. Uses FFT convolution for speed and differentiability.

The effective kernel width at each pixel is computed via quadrature subtraction:

\[\begin{split}\\sigma_\\mathrm{eff}(\\lambda) = \\sqrt{\\sigma_\\mathrm{inst}(\\lambda)^2 - \\sigma_\\mathrm{lib}^2}\end{split}\]

where \(\\sigma_\\mathrm{inst}(\\lambda) = c / (2.3548 \\times R(\\lambda))\) is the instrument’s velocity dispersion [km/s] from spectral resolution \(R(\\lambda) = \\lambda / \\Delta\\lambda\).

Special case: If \(\\sigma_\\mathrm{inst} < \\sigma_\\mathrm{lib}\) at some wavelengths, no broadening is applied (cannot sharpen an already-broadened spectrum). This happens when the SSP library resolution is better than the instrument’s LSF.

Implementation: For constant R (scalar input), uses a single FFT convolution in log-wavelength space (fast, O(N log N)). For variable R (array input), uses a piecewise-constant approximation with n_bins segments and smooth raised-cosine blending at boundaries (~10–20 FFTs, accurate to ~1%).

Parameters:
  • spectrum (array, shape (n_pix,)) – Input spectral flux at observed wavelengths [erg/s/cm²/Hz or arbitrary units].

  • wave_obs (array, shape (n_pix,)) – Observed-frame wavelength grid [Ångstrom]. Any strictly increasing grid is accepted. One not uniform in log-wavelength, a linearly-spaced grid, for instance, is routed through the piecewise path, which carries a per-bin pixel scale, so the requested width is delivered either way (#1791). A log-uniform grid with scalar R keeps the single-FFT path.

  • resolution (array, shape (n_pix,) or float) –

    Spectral resolution \(R(\\lambda) = \\lambda / \\Delta\\lambda\).

    • Scalar: constant resolution across wavelength (fast path)

    • Array: per-pixel wavelength-dependent resolution (e.g., JWST NIRSpec PRISM)

  • sigma_lib_kms (float or array, shape (n_pix,), optional) –

    SSP library velocity dispersion [km/s]. Subtracted in quadrature from instrument LSF. Default 0.0 (no subtraction).

    • Scalar (float): constant library resolution across spectrum. Common values: MILES-based (FSPS default) 70 km/s, C3K 15 km/s, IRTF 20 km/s. Use SSP_LIBRARY_RESOLUTIONS[library_name] for pre-defined values.

    • Array (n_pix,): per-wavelength library resolution derived from the loaded SSP template’s LSF. Example: MILES has FWHM ≈ 2.51 Å (constant in wavelength), giving σ_v(λ) ∝ 1/λ, from ~91 km/s at 3525 Å to ~43 km/s at 7500 Å. Retrieved from SSPData.ssp_resolution_kms after load.

  • n_bins (int, optional) – Number of piecewise-constant segments for variable-R approximation. Ignored for scalar R. Higher values are more accurate but slower. Typical: 10–20. Default 16.

  • sigma_v_kms (float or ndarray, optional) – Intrinsic galaxy velocity dispersion \(\\sigma_v\) [km/s] added in quadrature to \(\\sigma_{\\rm eff}\). This is the broadening from stellar dynamics, distinct from instrument LSF (resolution) and from the SSP-library template resolution (sigma_lib_kms). Default 0.0 (no extra broadening).

  • pad_pixels (int or None, optional) – Static padding [pixels] per side (keyword-only). None derives it from the bound of _lsf_sigma_bound_kms(): each component counts as the larger of _LSF_MAX_SIGMA_KMS (2000 km/s) and its concrete value, and a traced component counts as 2000 km/s. For components up to 2000 km/s the padding does not depend on tracing. A traced grid pads by n - 1. An explicit value is used as given, so it must cover 5 sigma of the kernel to be exact.

Returns:

spectrum_smoothed – Spectrum convolved with the effective LSF kernel [same units as input].

Return type:

array, shape (n_pix,)

Notes

JIT-compatible: no, the dispatch logic (constant vs. variable R) uses Python-side branching. Wrap the result in jax.jit() only if R is known at trace time.

Gradient-safe: yes, all operations inside the conditionally-selected path are differentiable.

Log-wavelength convolution: Convolution is performed in log-wavelength space, which correctly represents velocity-space broadening. A grid that is not uniform in ln(lambda) takes the piecewise path, where each bin uses its own local d ln lambda, n_bins FFTs instead of one, and nothing is resampled, so flux conservation and the zero-width identity stay exact to machine precision. Before #1791 such a grid was convolved with the pixel scale read from its blue end, under-broadening by wave[0]/lambda, 0.60 at 5000 A on a 3000-10000 A grid, and biasing any fitted sigma_v_kms high by the reciprocal. Measured recovery of a requested 200 km/s on linspace(3000, 10000): 0.991 at the default n_bins=16.

Boundary handling: the convolution runs on a reflecting (symmetric) margin of _lsf_pad_pixels() pixels per side (5 sigma of the kernel at the pixel scale the kernel uses, and at least 256 pixels for sub-pixel kernels), so the kernel does not wrap from one spectrum edge onto the other (#2712, #2832). The sigma is bounded per component, each at least 2000 km/s, and the bounds are combined in quadrature; the library dispersion is not subtracted. Every component at or below 2000 km/s gets the same padding whether or not it is traced, so the same call pads the same way under jax.jit.

See also

velocity_broaden

Convolve with velocity dispersion only (no library subtraction).

nirspec_prism_resolution

JWST NIRSpec PRISM variable-R function.

nirspec_g140m_resolution

JWST NIRSpec G140M constant-R function.

Examples

Constant spectral resolution (R = 100):

>>> spectrum_smoothed = apply_lsf(spectrum, wave_obs, resolution=100.0)

JWST NIRSpec PRISM (variable resolution, accounting for MILES library):

>>> wave_um = wave_obs / 1e4  # convert Angstrom to micron
>>> R_prism = nirspec_prism_resolution(wave_um)
>>> spectrum_smoothed = apply_lsf(
...     spectrum,
...     wave_obs,
...     resolution=R_prism,
...     sigma_lib_kms=70.0,  # MILES-based SSP library
... )

Custom wavelength-dependent resolution:

>>> R_custom = 100.0 + 50.0 * (wave_obs / 5000.0)  # increases with wavelength
>>> spectrum_smoothed = apply_lsf(spectrum, wave_obs, resolution=R_custom)

Radio

Star-formation synchrotron and AGN jets. Radio models activate via nested dictionaries separating star-forming and AGN components (e.g. SEDModel.build(..., radio={'sf': {'type': 'bell2003'}, 'agn': {'type': 'powerlaw'}})) or compact single-model activation (e.g. {'type': 'condon92'} combining both). Discover available models and radio-block options via:

tengri.list_radio_models(*, status: str | None = None) → _RegistryTable[source]

List all registered radio emission models.

The radio group adds the Condon+1992 FIR-radio correlation for the star-forming-galaxy contribution plus an optional AGN radio power-law via the radio-loudness parameter. 'none' disables the block.

Names come from the grammar validator itself (tengri.parameters.groups._valid_radio_types), which accepts the union of RADIO_MODELS and the SEDModelComponent radio variants in _REGISTRY, so radio_powerlaw and radio_dpl are listed here rather than being builder-only. The legacy radio={'type': ...} form is retired (PR6); use radio={'sf'/'agn': ...} instead. This menu lists the retired names for reference; the composable form is the only accepted surface.

See also: list_xray_models(), list_igm_models(), tengri.builders.radio.

tengri.list_radio_blocks(*, category: str | None = None, status: str | None = None) → _RegistryTable[source]

List the composable radio sub-block variants: sf and agn.

Radio is selected along two independent axes: the star-forming synchrotron model (radio={'sf': {'type': ...}}) and the AGN radio model (radio={'agn': {'type': ...}}). Either may be 'none' to run the other alone.

This is a different axis from list_radio_models(), which lists the retired radio={'type': ...} key. That key predates the SF/AGN split and is no longer accepted; use the composable radio={'sf': {...}, 'agn': {...}} form instead. The two forms cannot be combined.

Parameters:
  • category (str, optional) – Filter to "sf" or "agn". If None, list both.

  • status (str, optional) – Filter by "production", "experimental", "demo", or "deprecated".

Returns:

List of metadata dicts. Prints as a table in a notebook.

Return type:

_RegistryTable

Examples

>>> import tengri
>>> tengri.list_radio_blocks(category="sf")
>>> tengri.list_radio_blocks()

Radio SED models are configured via SEDComponent classes with configurable parameters for synchrotron spectral index, AGN loudness, and star-formation efficiency.

class tengri.components.radio.RadioDPL[source]

Bases: SEDModelComponent

Radio synchrotron + free-free + AGN double-power-law with aging cutoff.

AGNfitter-rx broken double power-law with smooth transition (Martinez-Ramirez+2024):

\[L_\nu = L_{5\,\mathrm{GHz}} \left(\frac{\nu}{\nu_t}\right)^{\alpha_1} \left[1 - \exp\left(-\left(\frac{\nu_t}{\nu}\right)^{\alpha_1 - \alpha_2} \right)\right] \exp\left(-\frac{\nu}{\nu_{\mathrm{cut}}}\right)\]

Pairs with the SF (Bell+2003 q_IR) and optional thermal free-free components: those flow through the standard radio primitive.

Cross-component contract

Reads (opportunistic, with documented fallbacks):

  • L_ir: total IR luminosity (erg/s) for SF synchrotron; falls back to 0.

  • L_agn_bol: AGN bolometric luminosity (erg/s); falls back to 0.

  • log_mstar: stellar mass for mass-slope correction; falls back to 10.

Reads:

  • redshift (from BARE_NAME_ALLOWLIST), for redshift evolution of q_IR.

Publishes:

  • sed_radio: full radio L_ν on the wave grid.

References

[tengri.components.radio.RadioDPL-1]

J. Martinez-Ramirez et al., “AGNfitter-rx: Modeling the radio-to-X-ray spectral energy distributions of AGNs,” A&A, 688, A46 (2024). https://doi.org/10.1051/0004-6361/202449329

INCLUDE_FREEFREE: bool = True
SFR_MODE: str = 'bell2003'
T_e = Fixed(10000.0)
alpha_ff = Fixed(-0.1)
alpha_sf = Fixed(0.8)
alpha_thick = Uniform(-0.5, 1.0)
alpha_thin = Uniform(-1.5, 0.0)
log_nu_cut = Uniform(11.0, 14.0)
log_nu_t = Uniform(8.0, 11.0)
loudness = Fixed(0.0)
name: str = 'radio_dpl'
parameter_prefix: str = 'radio_'
predict(p: dict[str, Any], sed_in: Array, wave: Array, **inputs: Any) → tuple[Array, dict[str, Array]][source]

Pure JAX prediction step. MUST be implemented by subclass.

Called by the default apply() with sliced parameters and unpacked inputs from state.derived.

Parameters:
  • p (mapping[str, ndarray]) – Parameters with prefix stripped. Access via p[“T”], p[“beta”], etc.

  • sed_in (ndarray) – Input rest-frame L_nu in erg/s/Hz.

  • wave (ndarray) – Rest-frame wavelength grid in Angstrom.

  • **inputs (ndarray) – Cross-component inputs, keyed by the names declared in the inputs dict. Example: L_absorbed=1e45.

Returns:

(sed_out, published) where:

  • sed_out: Updated rest-frame L_nu in erg/s/Hz.

  • published: Dict of keys declared in outputs, e.g., {"L_ir": 1e45}.

Return type:

tuple[ndarray, mapping[str, ndarray]]

Raises:

NotImplementedError – Default implementation raises. Subclasses MUST override.

q_ir = Fixed(2.64)
class tengri.components.radio.RadioPowerLawSEDComponent[source]

Bases: SEDModelComponent

SEDComponent for radio synchrotron (power-law) + thermal emission.

Computes radio continuum from star-formation rate (via FIR-radio correlation) and AGN luminosity. Single power-law model (double power-law with aging is a follow-up).

Free parameters (7):

  • radio_q_ir: FIR-radio correlation parameter

  • radio_alpha_sf: SFR-driven radio slope

  • radio_loudness: AGN radio loudness parameter

  • radio_alpha_agn: AGN radio spectral index

  • radio_T_e: electron temperature [K]

  • radio_alpha_ff: free-free spectral index

Notes

JIT-compatible: yes. Optional inputs: reads L_ir, L_agn_bol, log_mstar with fallbacks. Component is fully functional without dust/AGN/stellar upstream.

T_e = Fixed(8000.0)
alpha_agn = Uniform(-1.0, 0.5)
alpha_ff = Fixed(-0.1)
alpha_sf = Uniform(0.5, 1.2)
declared_parameters() → list[ParamDeclaration][source]

Declare the 6 free parameters owned by radio power-law.

load(wave: Array | None = None) → None[source]

No-op precomputation for power-law radio.

loudness = Fixed(0.0)
name: str = 'radio_powerlaw'
parameter_prefix: str = 'radio_'
predict(p: Mapping[str, Array], sed_in: Array, wave: Array, **inputs: Any) → tuple[Array, Mapping[str, Array]][source]

Predict radio SED via power-law model.

Parameters:
  • p (mapping[str, ndarray]) – Parameters with prefix stripped: q_ir, alpha_sf, loudness, alpha_agn, T_e, alpha_ff.

  • sed_in (ndarray) – Input SED (stellar + nebular + AGN continuum).

  • wave (ndarray) – Rest-frame wavelength grid in Angstrom.

  • **inputs (ndarray) – Opportunistic cross-component reads: L_ir, L_agn_bol, log_mstar (with defaults if not present).

Returns:

  • sed_out: sed_in + radio continuum.

  • published: Dict with “sed_radio”.

Return type:

tuple[ndarray, mapping]

q_ir = Uniform(1.0, 3.0)
requires_template_data: ClassVar[bool] = False

X-ray

X-ray emission from accretion-powered AGN coronae and stellar binary systems (both high-mass and low-mass). X-ray models activate via dictionary (e.g. SEDModel.build(..., xray={'type': 'simple'}) or xray={'type': 'lopez24'} for IR-selected AGN). Discover available models via:

tengri.list_xray_models(*, status: str | None = None) → _RegistryTable[source]

List all registered X-ray emission models.

The X-ray group composes the AGN corona (Yang+2020 alpha_ox(L_2500) relation), the Fragos+2013 high- and low-mass X-ray binary scalings, and optional thermal hot-gas emission. The 'none' entry disables the whole block.

Names come from the grammar validator itself (tengri.parameters.groups._valid_xray_types), which accepts the union of XRAY_MODELS and the SEDModelComponent X-ray variants in _REGISTRY. Reading only XRAY_MODELS (as this menu did) hid xray_aird and agn_xray_corona from every discovery surface from the moment #1323 made them builder-reachable, while the validator’s own docstring asserted the menu and builder “cannot drift”.

See also: list_radio_models(), list_igm_models(), tengri.builders.xray.

X-ray SED models include AGN corona normalizations tied to either UV-optical disc emission or mid-infrared dust luminosity, and XRB contributions scaled by galaxy stellar mass.

class tengri.components.xray.AGNXRayCoronaSEDComponent[source]

Bases: SEDModelComponent

SEDComponent for AGN X-ray corona emission.

Computes X-ray continuum from the AGN disc UV luminosity via the empirical alpha_ox(L_2500) relation (Just+2007 by default), following the X-CIGALE corona treatment.

Reads three parameters from the xray group rather than declaring its own (see parameter_prefix):

  • xray_gamma_agn: X-ray photon index (Gamma)

  • xray_delta_alpha_ox: offset [dex] on the Just+2007 alpha_ox(L_2500)

  • xray_E_cut: high-energy cutoff [keV]

Notes

JIT-compatible: yes. Optional inputs: anchors the α_ox corona to L_2500 via the chain L_2500_intrinsic (actual disc L_ν(2500 Å), any disc) → L_2500_30deg (SKIRTOR) → L_agn_bol with a Hopkins+2007 BC fallback. Returns zero X-ray if no AGN luminosity is published.

The corona is evaluated at the Yang+2020 30° reference inclination (anisotropy factor exactly 1): this component has no inclination input, so it stays at the anchor where the alpha_ox relation is defined; same policy as XRayAirdSEDComponent (#980).

declared_parameters() → list[ParamDeclaration][source]

Declare the 3 free parameters owned by AGN X-ray.

load(wave: Array | None = None) → None[source]

No-op precomputation for analytic X-ray model.

name: str = 'agn_xray_corona'
parameter_prefix: str = 'xray_'

The xray group’s prefix, not a private one.

This declared gamma / delta_alpha_ox / e_cut under agn_xray_, a prefix no group supplies, so its sliced parameter dict was empty and building it raised KeyError: 'gamma' inside predict(). That is why component_factory could not route this name and it silently delivered yang20’s physics instead (#1684, the unfinished half of #1120).

The three were duplicates rather than new knobs: the xray group already declares xray_gamma_agn, xray_E_cut and xray_delta_alpha_ox, which are the same three quantities. Reading those instead of declaring a parallel set keeps one name per physical knob and needs no addition to the public parameter surface.

predict(p: Mapping[str, Array], sed_in: Array, wave: Array, **inputs: Any) → tuple[Array, Mapping[str, Array]][source]

Predict AGN X-ray SED via corona model.

Parameters:
  • p (mapping[str, ndarray]) – Parameters with the xray_ prefix stripped: gamma_agn, delta_alpha_ox, E_cut.

  • sed_in (ndarray) – Input SED (stellar + nebular + radio).

  • wave (ndarray) – Rest-frame wavelength grid in Angstrom.

  • **inputs (ndarray) – Opportunistic cross-component reads: L_agn_bol (with fallback to 0.0 if not present from AGN component).

Returns:

  • sed_out: sed_in + X-ray continuum.

  • published: Dict with “sed_xray” (the X-ray continuum).

Return type:

tuple[ndarray, mapping]

publish_name: ClassVar[str] = 'xray'

Publish into the shared xray domain rather than under the registry key: DerivedState declares xray_* precompute fields, and keying them off name would spill agn_xray_corona_* into _extras and trip the ADR-0007 guard. Only one X-ray component is ever built.

requires_template_data: ClassVar[bool] = False
class tengri.components.xray.XRayAirdSEDComponent[source]

Bases: SEDModelComponent

SEDComponent for X-ray emission (Fragos+2013 / Yang+2020 canonical).

Computes total X-ray continuum from X-ray binaries (HMXB + LMXB), hot gas, and AGN corona. Implements Fragos et al. 2013 (metallicity- and age-dependent XRB scaling), Yang et al. 2020 (hot gas and AGN anisotropy), and Just et al. 2007 (α_OX–L_2500 relation).

Free parameters (6):

  • xray_gamma_hmxb: HMXB spectral index

  • xray_gamma_lmxb: LMXB spectral index

  • xray_gamma_agn: AGN X-ray spectral index

  • xray_log_nh: line-of-sight equivalent hydrogen column density, applied to the AGN corona only as T_phabs(E, N_H) × T_cabs(N_H) × intrinsic + 0.01 × intrinsic (Ricci+2017; Matsumoto+2026 Eq. B6). T_phabs uses Morrison & McCammon (1983) wabs cross-sections; T_cabs is Thomson down-scattering. Galactic absorption is not modeled (assume user provides intrinsic-frame fluxes).

  • xray_det_hmxb: HMXB luminosity offset (deviation from expected SFR relation in log-space; positive = brighter X-ray)

  • xray_det_lmxb: LMXB luminosity offset (deviation from expected mass relation in log-space; positive = brighter X-ray)

The α_OX parameter is not a free parameter here; it is a PRIOR that couples AGN UV (L_2500) and X-ray emission self-consistently (Just+2007, Yang+2020). Offsets from the empirical relation can be passed at the function level via delta_alpha_ox.

Notes

JIT-compatible: yes.

Optional inputs (#1846, #1755, #1706 fixed): declares six cross-component keys (sfr, log_mstar, L_2500_30deg, age_weights, ssp_ages_yr, log_metallicity_history). The base apply() injects 0.0 when absent; predict distinguishes these injected fallbacks via zero-sum checks (age_weights) and direct presence logic (sfr, log_mstar, L_2500_30deg). Reads X with sensible defaults: SFR from stellar (→ 1.0 Msun/yr), stellar mass from stellar (→ 10 Msun), AGN UV from AGN (→ 0.0, no corona), mass-weighted age from stellar (→ 1.0 Gyr), and metallicity from stellar (→ Z_sun). Matches yang20’s pattern (tengri.components.xray.component.XRaySEDComponent).

Models:

  • HMXB: Fragos+2013 metallicity quartic (Eq. 3), scaling with SFR

  • LMXB: Fragos+2013 age quartic (Eq. 4), scaling with M_star

  • Hot gas: Yang+2020, scaling with SFR

  • AGN corona: Just+2007 / Yang+2020 α_OX, scaling with L_2500

declared_parameters() → list[ParamDeclaration][source]

Declare the 3 free parameters owned by X-ray.

det_hmxb = Uniform(-2.0, 2.0)
det_lmxb = Uniform(-2.0, 2.0)
gamma_agn = Uniform(1.0, 3.0)
gamma_hmxb = Uniform(1.0, 3.0)
gamma_lmxb = Uniform(1.0, 3.0)
load(wave: Array | None = None) → None[source]

No-op precomputation for analytic X-ray model.

log_nh = Uniform(20.0, 26.0)
name: str = 'xray_aird'
parameter_prefix: str = 'xray_'
predict(p: Mapping[str, Array], sed_in: Array, wave: Array, **inputs: Any) → tuple[Array, Mapping[str, Array]][source]

Predict X-ray SED via Fragos+Yang canonical path.

Parameters:
  • p (mapping[str, ndarray]) – Parameters with prefix stripped: gamma_hmxb, gamma_lmxb, gamma_agn, log_nh, det_hmxb, det_lmxb.

  • sed_in (ndarray) – Input SED (stellar + nebular + AGN + radio).

  • wave (ndarray) – Rest-frame wavelength grid in Angstrom.

  • **inputs (ndarray) –

    Declared cross-component reads with documented fallback behavior:

    • sfr [Msun/yr], when stellar publishes, reads the value; when absent, the base apply() injects 0.0, yielding zero XRB luminosity (physically defensible: no SFH → no star-formation-driven X-rays).

    • log_mstar [dex], when stellar publishes, reads the value; when absent, injected 0.0 (10^0 = 1 Msun, a degenerate case but not used in practice since X-ray requires stellar component).

    • L_2500_30deg [erg/s/Hz], when AGN publishes L_2500, reads it; when absent, injected 0.0 (no AGN → no corona).

    • age_weights_surviving [Msun], surviving mass per SSP age bin; the weights of the LMXB age. age_weights [Msun], the formed-mass fallback. Zero-sum check: if a sum is 0 (absent or truly zero-weighted) the next source is used, then 1.0 Gyr.

    • ssp_ages_yr [yr]; SSP age grid; paired with age_weights.

    • log_metallicity_history [dex, absolute log10(Z)]: stellar’s SFH- indexed metallicity history. Present-day bin (index 0) drives the Fragos+2013 HMXB quartic; if absent, metallicity_from_history() returns Z_SUN (0.0142).

Returns:

  • sed_out: sed_in + X-ray continuum.

  • published: Dict with “sed_xray”.

Return type:

tuple[ndarray, mapping]

Notes

Implements the “declared-input” cross-component read pattern (ADR-0009): every key read here is declared in optional_inputs() so the validator can check units and the base apply() can wire them. Absent publishers are signaled by injected 0.0 from the base class; for most inputs (sfr, log_mstar, L_2500_30deg) this produces physically defensible zero- contribution SED. For the mass-weighted age, a zero-sum check (sum(age_weights) == 0) distinguishes “not published” from “truly zero- weighted” and enables the 1.0 Gyr fallback. Fixes #1846, #1755, #1706.

publish_name: ClassVar[str] = 'xray'

Publish into the shared xray domain rather than under the registry key. DerivedState declares xray_phot_lnu_precomp / xray_spec_lnu_precomp / xray_restband_lnu_precomp; keying them off name instead would emit xray_aird_*, which are not fields, so they spill into _extras and the ADR-0007 guard raises ComponentIOError on every WavePrecomp build. Only one X-ray component is ever built, so the two can share the domain without colliding.

requires_template_data: ClassVar[bool] = False

Intergalactic medium

Mean IGM attenuation blueward of Lyman-alpha.

Warning

Both functions take observed-frame wavelengths, not rest-frame ones. Passing a rest-frame grid silently returns the wrong transmission rather than raising.

tengri.igm_transmission(wave_obs: Array, z_source: float, add_cgm: bool = False, cgm_z_mid: float | None = None, cgm_dz: float | None = None, cgm_log_nhi: float | None = None) → Array[source]

Compute mean IGM transmission including Lyman-series and continuum absorption.

Implements the Inoue et al. (2014) prescription for the mean intergalactic medium (IGM) absorption from Lyman-series lines and continuum across all 39 Lyman transitions (Lyman-alpha through n=40), accounting for both the Lyman-alpha forest (LAF) and damped Lyman-alpha systems (DLA). Optionally includes circumgalactic medium (CGM) damping wing absorption at z > 5.

Parameters:
  • wave_obs (array_like, shape (n_wave,)) – Observed-frame wavelength. [Å]

  • z_source (float) – Redshift of the source galaxy. [dimensionless]

  • add_cgm (bool, optional) – If True, add CGM damping wing absorption (Asada et al. 2025) at z > 5. Default: False (experimental feature, not yet fully validated against observations).

  • cgm_z_mid (float, optional) – Redshift midpoint of the sigmoid column density evolution. [dimensionless] Default: 7.0.

  • cgm_dz (float, optional) – Redshift width of the sigmoid transition. [dimensionless] Default: 0.5.

  • cgm_log_nhi (float, optional) – log10(N_HI / cm^-2) at the plateau of the sigmoid evolution. Canonical Asada+2025 value (21.0) produces τ ≈ 0.10 at z=7 and rest 1230 Å (about 3500 km/s redward of Lyα) and τ ≈ 1.1 at 1220 Å; log_nhi ≤ 19 is invisible. [dimensionless] Default: 21.0.

Returns:

Transmission factor T(λ) ∈ [0, 1]. [dimensionless] Multiply the rest-frame SED (in erg/s/Hz) by T to obtain the observed flux absorbed by the IGM.

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives, fully vectorized over wavelength.

Gradient-safe: yes, differentiable everywhere via \(\exp(-\tau)\) (no discontinuities).

The total IGM optical depth is:

\[\tau_{\rm IGM}(\lambda_{\rm obs}, z_s) = \tau_{\rm LS}^{\rm LAF} + \tau_{\rm LS}^{\rm DLA} + \tau_{\rm LC}^{\rm LAF} + \tau_{\rm LC}^{\rm DLA}\]

where LS = Lyman-series line absorption, LC = Lyman-continuum absorption, LAF = Lyman-alpha forest, and DLA = damped Lyman-alpha systems. Each component is computed via piecewise power-law fits to photoionization simulations (Inoue et al. 2014, Tables 2–3).

The Lyman-series line absorption (LAF) is:

\[\begin{split}\tau_j^{\rm LAF}(\lambda_{\rm obs}) = \begin{cases} A_{j,1}^{\rm LAF} \, (\lambda_{\rm obs}/\lambda_j)^{1.2} & \lambda_{\rm obs} < 2.2\,\lambda_j \\ A_{j,2}^{\rm LAF} \, (\lambda_{\rm obs}/\lambda_j)^{3.7} & 2.2\,\lambda_j \leq \lambda_{\rm obs} < 5.7\,\lambda_j \\ A_{j,3}^{\rm LAF} \, (\lambda_{\rm obs}/\lambda_j)^{5.5} & \lambda_{\rm obs} \geq 5.7\,\lambda_j \end{cases}\end{split}\]

summed over all 39 Lyman lines (j = 2, Ly-alpha, to j = 40). The DLA line absorption follows a similar form with two regimes (Inoue et al. 2014, Eq. 22).

The transmission is:

\[T_{\rm IGM}(\lambda_{\rm obs}, z_s) = \exp[-\tau_{\rm IGM}(\lambda_{\rm obs}, z_s)]\]

High-redshift extension (z > 5): When add_cgm=True, CGM damping wing absorption (Asada et al. 2025) is added, modeling neutral hydrogen in the circumgalactic medium. This affects wavelengths redward of Lyman-alpha at the source redshift and is important for z > 5 galaxies.

Approximations:

  • Mean transmission: This is the mean IGM absorption averaged over cosmic variance.

    Individual sightlines have additional scatter from the Lyman-alpha forest (not included).

  • Piecewise power laws: The Inoue et al. (2014) model uses analytic fits to simulations

    rather than full radiative transfer. Accuracy is ~5–10% relative to simulations.

  • Validity: Calibrated for \(z \lesssim 6\) (Inoue et al. 2014). At \(z > 6\),

    reionization introduces significant variance; the patchy reionization model is available separately.

Upstream: Implements Inoue et al. (2014) [tengri.igm_transmission-1] mean IGM transmission model, with CGM damping wing extension from Asada et al. (2025) [tengri.igm_transmission-2]. Coefficients extracted from eazy-py (Brammer et al.).

References

[tengri.igm_transmission-1]

A. K. Inoue, I. Shimizu, I. Iwata, and M. Tanaka, “An updated analytic model for attenuation by the intergalactic medium,” MNRAS, 442, 1805 (2014). https://doi.org/10.1093/mnras/stu936

[tengri.igm_transmission-2]

Y. Asada et al., “Improving Photometric Redshifts of Epoch of Reionization Galaxies: A New Empirical Transmission Curve with Neutral Hydrogen Damping Wing Ly-alpha Absorption,” ApJL, 983, L2 (2025). arXiv:2410.21543. https://doi.org/10.3847/2041-8213/adc388

tengri.igm_transmission_madau(wave_obs: Array, z: float, igm_factor: float = 1.0) → Array[source]

Mean IGM transmission using the Madau (1995) model.

Computes line-of-sight Lyman-series absorption from three additive components: Lyman-series line absorption (eq. 14), Lyman-continuum absorption (eq. 16), and metal-line blanketing (eq. 15). This is the simpler of the two IGM models available in tengri; the default is igm_transmission() (Inoue+2014) which includes 39 lines and DLA contributions.

Parameters:
  • wave_obs (array_like, shape (n_wave,)) – Observed-frame wavelengths [Angstrom].

  • z (float) – Source redshift.

  • igm_factor (float, optional) – Multiplicative fudge factor for IGM strength. Default 1.0 (mean IGM).

Returns:

T_igm – Mean IGM transmission [dimensionless], in [0, 1]. Values outside the modeled wavelength range are set to 1.0 (no attenuation).

Return type:

jnp.ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, pure jnp operations with jax.lax.scan for the line summation.

Total opacity: The optical depth is the sum of three terms:

\[\tau_\mathrm{total} = (\tau_\mathrm{line} + \tau_\mathrm{cont} + \tau_\mathrm{metal}) \times \mathrm{igm\_factor}\]

Line opacity (eq. 14): The optical depth from each Lyman-series line is:

\[\tau_j(\lambda) = A_j \left(\frac{\lambda}{\lambda_j}\right)^{3.46}\]

where \(A_j\) are the line coefficients from Madau (1995) Table 1 [tengri.igm_transmission_madau-1], \(\lambda_j\) are the rest-frame Lyman-series wavelengths [Angstrom], and the formula applies for \(\lambda_j \leq \lambda_\mathrm{obs} \leq \lambda_j(1+z)\).

Metal-line blanketing (eq. 15): Accounts for absorption by metal resonance lines (Fe II, Mg II, Al II/III, Si II, etc.) in the Lyman-series forest:

\[\tau_\mathrm{metal}(\lambda_\mathrm{obs}) = 0.0017 \left(\frac{\lambda_\mathrm{obs}}{\lambda_\alpha}\right)^{1.68}\]

for \(\lambda_\mathrm{obs} \leq \lambda_\alpha(1+z)\), and zero otherwise, where \(\lambda_\alpha = 1215.67\,\mathrm{\AA}\) is the rest-frame Lyα wavelength.

wave_obs is observed-frame wavelength (consistent with tengri’s IGM convention). The Madau+1995 model takes observed-frame wavelengths directly.

Based on Prospector add_igm (Johnson+2021 [tengri.igm_transmission_madau-2]), but now includes the metal-line blanketing term (eq. 15) for the full Madau+1995 model. The Inoue+2014 model (igm_transmission()) supersedes this for science use; Madau+1995 is provided for comparison and backward compatibility.

References

[tengri.igm_transmission_madau-1]

P. Madau, “Radiative Transfer in a Clumpy Universe: The Colors of High-Redshift Galaxies,” ApJ, 441, 18 (1995). https://doi.org/10.1086/175332

[tengri.igm_transmission_madau-2]

B. D. Johnson et al., “Stellar Population Inference,” ApJS, 254, 22 (2021). arXiv:2012.01426. https://doi.org/10.3847/1538-4365/abef67

Examples

>>> import jax.numpy as jnp
>>> wave_obs = jnp.linspace(1000.0, 10000.0, 200)
>>> T = igm_transmission_madau(wave_obs, z=3.0)
>>> T.shape
(200,)
>>> float(T[0]) < 1.0  # attenuated at Ly-alpha
True
tengri.igm_transmission_meiksin06(wave_obs: Array, z: float) → Array[source]

Mean IGM transmission using the Meiksin (2006) prescription.

Parameters:
  • wave_obs (array_like, shape (n_wave,)) – Observed-frame wavelengths [Angstrom]. Must be sorted ascending for the LLS-continuum branch to apply correctly.

  • z (float) – Source redshift (must be > 0).

Returns:

T_igm – Mean IGM transmission in [0, 1]. Above 912 * (1 + z) Angstrom the value is exactly 1 (no Lyman absorption).

Return type:

jnp.ndarray, shape (n_wave,)

Notes

JIT-compatible: yes – pure jnp operations, no Python control flow except the z <= 4 vs z > 4 branch on the Lyman-alpha normalization (kept as a jnp.where so the function is also vmap/grad safe).

Convention: wave_obs is observed-frame wavelength, matching the rest of tengri’s IGM API (Inoue+2014, Madau+1995). The CIGALE implementation takes the same observed-frame wavelength but in nm; we convert internally.

Physics summary:

  1. Lyman series (lines n = 2 .. 30): each line’s opacity is evaluated at its absorber redshift z_n = λ_obs / λ_n - 1 per Meiksin (2006) Table 1. The mean optical depths τ_α and line-strength ratios τ_n / τ_α both depend on the absorber redshift. Series strengths from Meiksin Table 1; high-n tail (n >= 10) follows 720 / (n * (n^2 - 1)).

  2. Lyman-alpha-forest continuum (tau_l_igm): smooth ramp blueward of the Lyman limit, peaking at z_l = 0.

  3. Lyman-Limit Systems (tau_l_lls): higher-order suppression from optically-thick absorbers, using O’Meara+2013’s lambda^2.75 cross-section damping.

Differences from CIGALE 2025.1 (pcigale.sed_modules.redshifting .igm_transmission [tengri.igm_transmission_meiksin06-2]). The forest (Eq. 5) and Lyman-limit-system (Eq. 7) terms are the same closed forms and agree with it to 1.3e-5 in T. The Lyman series differs in two ways, both blueward of Lyβ (redward of it the two agree to 1e-10). The paper does not say which redshift sets Eqs. 2-3; the absorber-redshift reading here follows Table 1, whose ratios are functions of z_n, and reproduces Table 2 (0.003283 against 0.003277 at 1730 A, z = 5, where the source-redshift reading gives 0.000909):

  • CIGALE evaluates tau_alpha for n >= 3 at the source redshift; here it is evaluated at z_n, since Table 1 gives tau_n / tau_alpha as a function of z_n and Eqs. 2-3 are mean optical depths of the gas at the absorbing redshift.

  • CIGALE selects Eq. 2 (z < 4) or Eq. 3 (z > 4) for Lyα from the source redshift; here the selection is on z_n.

The first dominates: the maximum |ΔT| over a 600-point grid on 900-9000 Å is 0.044, 0.047 and 0.020 at z = 3, 5 and 7, and T(1730 Å, z = 5) is 0.003283 here and 0.000909 for CIGALE; Meiksin’s Table 2 gives 0.003277. The second changes T by at most 8.4e-3 (z = 5).

For wavelengths short of the Lyman limit at z=0 (z_l < 0), the LLS+forest opacity is damped by (z_l + 1)^2.75 per O’Meara+2013.

See also

igm_transmission

Inoue+2014 (grid-based, default in tengri).

igm_transmission_madau

Madau+1995 (simpler, fewer lines).

References

[tengri.igm_transmission_meiksin06-1]

A. Meiksin, “Color corrections for high-redshift objects due to intergalactic attenuation,” MNRAS, 365, 807 (2006). https://doi.org/10.1111/j.1365-2966.2005.09756.x

[tengri.igm_transmission_meiksin06-2]

Boquien, M., et al. 2019, A&A, 622, A103 (CIGALE). https://doi.org/10.1051/0004-6361/201834156

Intergalactic medium (IGM) attenuation models.

class tengri.components.igm.IGMRegistryEntry(callable: Callable | None, citation: str = '', status: str = 'production', short_doc: str = '')[source]

Bases: object

Registry entry for an IGM transmission model.

callable: Callable | None
citation: str = ''
short_doc: str = ''
status: str = 'production'
tengri.components.igm.dla_transmission(wave_rest: Array, log_n_hi: float, temp: float = 10000.0, b_turb_kms: float = 0.0) → Array[source]

Transmission through a DLA absorber at rest-frame wavelengths.

Parameters:
  • wave_rest (array, shape (n_wave,)) – Rest-frame wavelength [Å] in the absorber frame (i.e., already de-redshifted to the absorber’s rest frame).

  • log_n_hi (float) – log10(N_HI / cm⁻²). Typical DLA: 20.3–22.

  • temp (float) – Gas temperature [K]. Default 10⁴ K (warm neutral medium).

  • b_turb_kms (float) – Turbulent broadening [km/s]. Default 0.

Returns:

Transmission T = exp(−τ) [dimensionless, 0–1].

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, pure JAX function with @jax.jit decorator.

Examples

>>> import jax.numpy as jnp
>>> from tengri import dla_transmission
>>> wave = jnp.linspace(1100.0, 1300.0, 200)
>>> T = dla_transmission(wave, log_n_hi=21.0)
>>> T.shape
(200,)
tengri.components.igm.dla_transmission_obs(wave_obs: Array, z_dla: float, log_n_hi: float, temp: float = 10000.0, b_turb_kms: float = 0.0) → Array[source]

Transmission through a DLA absorber at observed wavelengths.

Convenience wrapper that de-redshifts wave_obs to the absorber rest frame before computing the Voigt absorption.

Parameters:
  • wave_obs (array, shape (n_wave,)) – Observed-frame wavelength [Å].

  • z_dla (float) – Redshift of the DLA absorber.

  • log_n_hi (float) – log10(N_HI / cm⁻²).

  • temp (float) – Gas temperature [K]. Default 10⁴ K.

  • b_turb_kms (float) – Turbulent broadening [km/s]. Default 0.

Returns:

Transmission T = exp(−τ) [dimensionless, 0–1].

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, pure JAX function with @jax.jit decorator.

Examples

>>> import jax.numpy as jnp
>>> from tengri import dla_transmission_obs
>>> wave_obs = jnp.linspace(1100.0 * 1.5, 1300.0 * 1.5, 200)
>>> T = dla_transmission_obs(wave_obs, z_dla=0.5, log_n_hi=21.0)
>>> T.shape
(200,)
tengri.components.igm.igm_absorption(wave_obs: Array, z: float, *, igm_x_HI: float = 0.0, igm_bubble_mpc: float = 10.0, igm_patchy: bool = False, igm_model: str = 'inoue', use_dla: bool = False, dla_z: float = 0.0, dla_log_n_hi: float = 20.3, dla_temp: float = 10000.0, dla_b_turb: float = 0.0) → Array[source]

Total observed-frame absorption: the single flat dispatch.

Composes the observed-frame transmission from a mean-IGM model and optional modifiers, and is the ONE call every observed-frame consumer uses (the exact predict_obs_sed path and the IGMSEDComponent photometry/spectroscopy projection), so all paths stay consistent (#932):

  • mean IGM: resolved once from the registry (resolve_igm_model(): inoue/inoue14, madau, meiksin06, asada25 = Inoue + Asada+2025 CGM damping wing), or replaced by the patchy-reionization model when igm_patchy is set.

  • DLA: an optional multiplicative damped-Lyman-α absorber layered on top of the mean IGM (use_dla), so photometry and spectroscopy both see it rather than only predict_obs_sed.

New CGM prescriptions are added as new registry models (like asada25), not flags: keeping the per-model dispatch flat.

Parameters:
  • wave_obs (ndarray, shape (n_wave,)) – Observed-frame wavelength [Angstrom].

  • z (float) – Source redshift [dimensionless].

  • igm_x_HI (float, optional) – Patchy-reionization neutral fraction (0-1) and bubble radius [proper Mpc]; only used when igm_patchy=True.

  • igm_bubble_mpc (float, optional) – Patchy-reionization neutral fraction (0-1) and bubble radius [proper Mpc]; only used when igm_patchy=True.

  • igm_patchy (bool, optional) – Use the patchy reionization damping-wing model instead of the mean IGM. Default False.

  • igm_model (str, optional) – Registry key or alias of the mean-IGM model. Default "inoue".

  • use_dla (bool, optional) – Multiply by a damped-Lyman-α absorber. Default False.

  • dla_z (float, optional) – DLA absorber redshift (0 → source z), log10 H I column density [cm^-2], temperature [K], and turbulent Doppler velocity [km/s].

  • dla_log_n_hi (float, optional) – DLA absorber redshift (0 → source z), log10 H I column density [cm^-2], temperature [K], and turbulent Doppler velocity [km/s].

  • dla_temp (float, optional) – DLA absorber redshift (0 → source z), log10 H I column density [cm^-2], temperature [K], and turbulent Doppler velocity [km/s].

  • dla_b_turb (float, optional) – DLA absorber redshift (0 → source z), log10 H I column density [cm^-2], temperature [K], and turbulent Doppler velocity [km/s].

Returns:

Transmission fraction [dimensionless, 0-1].

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes. igm_patchy / use_dla are static structural flags, so their branches resolve at trace time. The absorber knobs (igm_x_HI, igm_bubble_mpc, dla_*) are runtime values that may be traced free parameters: they must never gate a Python branch. At igm_x_HI = 0 the patchy path reduces bit-for-bit to the mean-IGM model.

tengri.components.igm.igm_transmission(wave_obs: Array, z_source: float, add_cgm: bool = False, cgm_z_mid: float | None = None, cgm_dz: float | None = None, cgm_log_nhi: float | None = None) → Array[source]

Compute mean IGM transmission including Lyman-series and continuum absorption.

Implements the Inoue et al. (2014) prescription for the mean intergalactic medium (IGM) absorption from Lyman-series lines and continuum across all 39 Lyman transitions (Lyman-alpha through n=40), accounting for both the Lyman-alpha forest (LAF) and damped Lyman-alpha systems (DLA). Optionally includes circumgalactic medium (CGM) damping wing absorption at z > 5.

Parameters:
  • wave_obs (array_like, shape (n_wave,)) – Observed-frame wavelength. [Å]

  • z_source (float) – Redshift of the source galaxy. [dimensionless]

  • add_cgm (bool, optional) – If True, add CGM damping wing absorption (Asada et al. 2025) at z > 5. Default: False (experimental feature, not yet fully validated against observations).

  • cgm_z_mid (float, optional) – Redshift midpoint of the sigmoid column density evolution. [dimensionless] Default: 7.0.

  • cgm_dz (float, optional) – Redshift width of the sigmoid transition. [dimensionless] Default: 0.5.

  • cgm_log_nhi (float, optional) – log10(N_HI / cm^-2) at the plateau of the sigmoid evolution. Canonical Asada+2025 value (21.0) produces τ ≈ 0.10 at z=7 and rest 1230 Å (about 3500 km/s redward of Lyα) and τ ≈ 1.1 at 1220 Å; log_nhi ≤ 19 is invisible. [dimensionless] Default: 21.0.

Returns:

Transmission factor T(λ) ∈ [0, 1]. [dimensionless] Multiply the rest-frame SED (in erg/s/Hz) by T to obtain the observed flux absorbed by the IGM.

Return type:

ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, all operations are jnp primitives, fully vectorized over wavelength.

Gradient-safe: yes, differentiable everywhere via \(\exp(-\tau)\) (no discontinuities).

The total IGM optical depth is:

\[\tau_{\rm IGM}(\lambda_{\rm obs}, z_s) = \tau_{\rm LS}^{\rm LAF} + \tau_{\rm LS}^{\rm DLA} + \tau_{\rm LC}^{\rm LAF} + \tau_{\rm LC}^{\rm DLA}\]

where LS = Lyman-series line absorption, LC = Lyman-continuum absorption, LAF = Lyman-alpha forest, and DLA = damped Lyman-alpha systems. Each component is computed via piecewise power-law fits to photoionization simulations (Inoue et al. 2014, Tables 2–3).

The Lyman-series line absorption (LAF) is:

\[\begin{split}\tau_j^{\rm LAF}(\lambda_{\rm obs}) = \begin{cases} A_{j,1}^{\rm LAF} \, (\lambda_{\rm obs}/\lambda_j)^{1.2} & \lambda_{\rm obs} < 2.2\,\lambda_j \\ A_{j,2}^{\rm LAF} \, (\lambda_{\rm obs}/\lambda_j)^{3.7} & 2.2\,\lambda_j \leq \lambda_{\rm obs} < 5.7\,\lambda_j \\ A_{j,3}^{\rm LAF} \, (\lambda_{\rm obs}/\lambda_j)^{5.5} & \lambda_{\rm obs} \geq 5.7\,\lambda_j \end{cases}\end{split}\]

summed over all 39 Lyman lines (j = 2, Ly-alpha, to j = 40). The DLA line absorption follows a similar form with two regimes (Inoue et al. 2014, Eq. 22).

The transmission is:

\[T_{\rm IGM}(\lambda_{\rm obs}, z_s) = \exp[-\tau_{\rm IGM}(\lambda_{\rm obs}, z_s)]\]

High-redshift extension (z > 5): When add_cgm=True, CGM damping wing absorption (Asada et al. 2025) is added, modeling neutral hydrogen in the circumgalactic medium. This affects wavelengths redward of Lyman-alpha at the source redshift and is important for z > 5 galaxies.

Approximations:

  • Mean transmission: This is the mean IGM absorption averaged over cosmic variance.

    Individual sightlines have additional scatter from the Lyman-alpha forest (not included).

  • Piecewise power laws: The Inoue et al. (2014) model uses analytic fits to simulations

    rather than full radiative transfer. Accuracy is ~5–10% relative to simulations.

  • Validity: Calibrated for \(z \lesssim 6\) (Inoue et al. 2014). At \(z > 6\),

    reionization introduces significant variance; the patchy reionization model is available separately.

Upstream: Implements Inoue et al. (2014) [tengri.components.igm.igm_transmission-1] mean IGM transmission model, with CGM damping wing extension from Asada et al. (2025) [tengri.components.igm.igm_transmission-2]. Coefficients extracted from eazy-py (Brammer et al.).

References

[tengri.components.igm.igm_transmission-1]

A. K. Inoue, I. Shimizu, I. Iwata, and M. Tanaka, “An updated analytic model for attenuation by the intergalactic medium,” MNRAS, 442, 1805 (2014). https://doi.org/10.1093/mnras/stu936

[tengri.components.igm.igm_transmission-2]

Y. Asada et al., “Improving Photometric Redshifts of Epoch of Reionization Galaxies: A New Empirical Transmission Curve with Neutral Hydrogen Damping Wing Ly-alpha Absorption,” ApJL, 983, L2 (2025). arXiv:2410.21543. https://doi.org/10.3847/2041-8213/adc388

tengri.components.igm.igm_transmission_asada25(wave_obs: Array, z: float, **kwargs: object) → Array[source]

Inoue+2014 mean IGM plus the Asada+2025 proximate-CGM damping wing.

A registry model (not a flag) so future CGM prescriptions slot in as additional registry entries. Uses the published Asada+2025 (ApJL 983, L2) H I column-density sigmoid (cgm_* left at their paper defaults). Fixes the z > 7 photometric-redshift bias from assuming a sharp Lyman break.

Notes

JIT-compatible: yes, delegates to igm_transmission().

tengri.components.igm.igm_transmission_madau(wave_obs: Array, z: float, igm_factor: float = 1.0) → Array[source]

Mean IGM transmission using the Madau (1995) model.

Computes line-of-sight Lyman-series absorption from three additive components: Lyman-series line absorption (eq. 14), Lyman-continuum absorption (eq. 16), and metal-line blanketing (eq. 15). This is the simpler of the two IGM models available in tengri; the default is igm_transmission() (Inoue+2014) which includes 39 lines and DLA contributions.

Parameters:
  • wave_obs (array_like, shape (n_wave,)) – Observed-frame wavelengths [Angstrom].

  • z (float) – Source redshift.

  • igm_factor (float, optional) – Multiplicative fudge factor for IGM strength. Default 1.0 (mean IGM).

Returns:

T_igm – Mean IGM transmission [dimensionless], in [0, 1]. Values outside the modeled wavelength range are set to 1.0 (no attenuation).

Return type:

jnp.ndarray, shape (n_wave,)

Notes

JIT-compatible: yes, pure jnp operations with jax.lax.scan for the line summation.

Total opacity: The optical depth is the sum of three terms:

\[\tau_\mathrm{total} = (\tau_\mathrm{line} + \tau_\mathrm{cont} + \tau_\mathrm{metal}) \times \mathrm{igm\_factor}\]

Line opacity (eq. 14): The optical depth from each Lyman-series line is:

\[\tau_j(\lambda) = A_j \left(\frac{\lambda}{\lambda_j}\right)^{3.46}\]

where \(A_j\) are the line coefficients from Madau (1995) Table 1 [tengri.components.igm.igm_transmission_madau-1], \(\lambda_j\) are the rest-frame Lyman-series wavelengths [Angstrom], and the formula applies for \(\lambda_j \leq \lambda_\mathrm{obs} \leq \lambda_j(1+z)\).

Metal-line blanketing (eq. 15): Accounts for absorption by metal resonance lines (Fe II, Mg II, Al II/III, Si II, etc.) in the Lyman-series forest:

\[\tau_\mathrm{metal}(\lambda_\mathrm{obs}) = 0.0017 \left(\frac{\lambda_\mathrm{obs}}{\lambda_\alpha}\right)^{1.68}\]

for \(\lambda_\mathrm{obs} \leq \lambda_\alpha(1+z)\), and zero otherwise, where \(\lambda_\alpha = 1215.67\,\mathrm{\AA}\) is the rest-frame Lyα wavelength.

wave_obs is observed-frame wavelength (consistent with tengri’s IGM convention). The Madau+1995 model takes observed-frame wavelengths directly.

Based on Prospector add_igm (Johnson+2021 [tengri.components.igm.igm_transmission_madau-2]), but now includes the metal-line blanketing term (eq. 15) for the full Madau+1995 model. The Inoue+2014 model (igm_transmission()) supersedes this for science use; Madau+1995 is provided for comparison and backward compatibility.

References

[tengri.components.igm.igm_transmission_madau-1]

P. Madau, “Radiative Transfer in a Clumpy Universe: The Colors of High-Redshift Galaxies,” ApJ, 441, 18 (1995). https://doi.org/10.1086/175332

[tengri.components.igm.igm_transmission_madau-2]

B. D. Johnson et al., “Stellar Population Inference,” ApJS, 254, 22 (2021). arXiv:2012.01426. https://doi.org/10.3847/1538-4365/abef67

Examples

>>> import jax.numpy as jnp
>>> wave_obs = jnp.linspace(1000.0, 10000.0, 200)
>>> T = igm_transmission_madau(wave_obs, z=3.0)
>>> T.shape
(200,)
>>> float(T[0]) < 1.0  # attenuated at Ly-alpha
True
tengri.components.igm.igm_transmission_meiksin06(wave_obs: Array, z: float) → Array[source]

Mean IGM transmission using the Meiksin (2006) prescription.

Parameters:
  • wave_obs (array_like, shape (n_wave,)) – Observed-frame wavelengths [Angstrom]. Must be sorted ascending for the LLS-continuum branch to apply correctly.

  • z (float) – Source redshift (must be > 0).

Returns:

T_igm – Mean IGM transmission in [0, 1]. Above 912 * (1 + z) Angstrom the value is exactly 1 (no Lyman absorption).

Return type:

jnp.ndarray, shape (n_wave,)

Notes

JIT-compatible: yes – pure jnp operations, no Python control flow except the z <= 4 vs z > 4 branch on the Lyman-alpha normalization (kept as a jnp.where so the function is also vmap/grad safe).

Convention: wave_obs is observed-frame wavelength, matching the rest of tengri’s IGM API (Inoue+2014, Madau+1995). The CIGALE implementation takes the same observed-frame wavelength but in nm; we convert internally.

Physics summary:

  1. Lyman series (lines n = 2 .. 30): each line’s opacity is evaluated at its absorber redshift z_n = λ_obs / λ_n - 1 per Meiksin (2006) Table 1. The mean optical depths τ_α and line-strength ratios τ_n / τ_α both depend on the absorber redshift. Series strengths from Meiksin Table 1; high-n tail (n >= 10) follows 720 / (n * (n^2 - 1)).

  2. Lyman-alpha-forest continuum (tau_l_igm): smooth ramp blueward of the Lyman limit, peaking at z_l = 0.

  3. Lyman-Limit Systems (tau_l_lls): higher-order suppression from optically-thick absorbers, using O’Meara+2013’s lambda^2.75 cross-section damping.

Differences from CIGALE 2025.1 (pcigale.sed_modules.redshifting .igm_transmission [tengri.components.igm.igm_transmission_meiksin06-2]). The forest (Eq. 5) and Lyman-limit-system (Eq. 7) terms are the same closed forms and agree with it to 1.3e-5 in T. The Lyman series differs in two ways, both blueward of Lyβ (redward of it the two agree to 1e-10). The paper does not say which redshift sets Eqs. 2-3; the absorber-redshift reading here follows Table 1, whose ratios are functions of z_n, and reproduces Table 2 (0.003283 against 0.003277 at 1730 A, z = 5, where the source-redshift reading gives 0.000909):

  • CIGALE evaluates tau_alpha for n >= 3 at the source redshift; here it is evaluated at z_n, since Table 1 gives tau_n / tau_alpha as a function of z_n and Eqs. 2-3 are mean optical depths of the gas at the absorbing redshift.

  • CIGALE selects Eq. 2 (z < 4) or Eq. 3 (z > 4) for Lyα from the source redshift; here the selection is on z_n.

The first dominates: the maximum |ΔT| over a 600-point grid on 900-9000 Å is 0.044, 0.047 and 0.020 at z = 3, 5 and 7, and T(1730 Å, z = 5) is 0.003283 here and 0.000909 for CIGALE; Meiksin’s Table 2 gives 0.003277. The second changes T by at most 8.4e-3 (z = 5).

For wavelengths short of the Lyman limit at z=0 (z_l < 0), the LLS+forest opacity is damped by (z_l + 1)^2.75 per O’Meara+2013.

See also

igm_transmission

Inoue+2014 (grid-based, default in tengri).

igm_transmission_madau

Madau+1995 (simpler, fewer lines).

References

[tengri.components.igm.igm_transmission_meiksin06-1]

A. Meiksin, “Color corrections for high-redshift objects due to intergalactic attenuation,” MNRAS, 365, 807 (2006). https://doi.org/10.1111/j.1365-2966.2005.09756.x

tengri.components.igm.igm_transmission_patchy(wave_obs: Array, z: float, x_HI: float = 0.0, R_bubble: float = 1.0, **kwargs) → Array[source]

IGM transmission with patchy reionization damping wing.

Extends Inoue+2014 with a neutral IGM damping wing component for z > 5.5 where reionization is incomplete. When x_HI = 0, this reduces exactly to standard igm_transmission.

The damping wing optical depth follows Miralda-Escude (1998):

tau_DW(lambda) = tau_GP * x_HI * (gamma / 4pi)

/ (delta_nu^2 + (gamma/4pi)^2)

where delta_nu is the frequency offset from Ly-alpha at the source redshift, and the Gunn-Peterson optical depth is:

tau_GP = 6.45e5 * ((1+z)/7)^1.5

An ionized bubble of radius R_bubble around the source creates a proximity zone that suppresses the damping wing close to Ly-alpha.

Parameters:
  • wave_obs (array, shape (n_wave,)) – Observed-frame wavelength [Angstrom].

  • z (float) – Source redshift.

  • x_HI (float) – Volume-averaged neutral hydrogen fraction. 0 = fully ionized (standard Inoue+2014), 1 = fully neutral. At z~6: x_HI ~ 0.1-0.5. At z~8: x_HI ~ 0.5-0.9. Default 0.0.

  • R_bubble (float) – Radius of ionized bubble around the source [proper Mpc]. Typical: 0.5-5 pMpc at z~7. Larger bubbles reduce the damping wing absorption. Default 1.0.

  • **kwargs – Additional keyword arguments passed to igm_transmission (e.g., add_cgm, cgm_z_mid, etc.).

Returns:

Transmission factor T in [0, 1]. Multiply rest-frame SED by T to get absorbed spectrum.

Return type:

array, shape (n_wave,)

Notes

At z < 5.5, the neutral fraction is effectively zero and this function returns the same result as igm_transmission.

The damping wing extends redward of Ly-alpha, affecting the UV continuum longward of Ly-alpha, which the standard Inoue+2014 model does not capture. Blueward of Ly-alpha the neutral gas outside the bubble adds the Gunn-Peterson trough, tau_GP * x_HI (#3429), so the transmission there falls with x_HI as well.

References

  • Miralda-Escude 1998, ApJ, 501, 15

  • Mason et al. 2018, ApJ, 856, 2

  • Keating et al. 2025

tengri.components.igm.register_igm_model(name: str, *, citation: str = '', status: str = 'production', short_doc: str = '') → Callable[[Callable | None], Callable | None][source]

Register an IGM transmission model in IGM_MODELS.

tengri.components.igm.resolve_igm_model(name: str) → object[source]

Return the IGM transmission function for name, resolving aliases.

Parameters:

name (str) – Registry key (e.g. "inoue14", "madau") or a recognized alias (e.g. "inoue").

Returns:

Pure-JAX transmission function (wave_obs, z, **kwargs) -> T_igm.

Return type:

Callable

Raises:

ValueError – If name is neither a registry key nor a known alias.

Stellar population synthesis

DSPS-based stellar population synthesis: loading SSP grids and computing effective metallicities.

class tengri.SSPData(ssp_wave: Array, ssp_flux: Array, ssp_lg_age_gyr: Array, ssp_lgmet: Array, ssp_mass_remaining: Array | None = None, ssp_resolution_kms: Array | None = None, ssp_alpha_fe: Array | None = None, imf: str = 'unknown', source: str = '', nebular: str = 'unknown', mass_remaining_source: str = 'unspecified', top_z: tuple | None = None, grid_notes: tuple[str, ...] = (), repaired_cells: tuple = (), ssp_mass_remaining_alpha: Array | None = None)[source]

Bases: NamedTuple

Immutable container for SSP template library.

Holds wavelength grid, flux templates, and metadata (age/metallicity grids) needed by the CSP integration engine. Typically loaded once from disk and reused across many forward-model evaluations.

Parameters:
  • ssp_wave (array, shape (n_wave,)) – Rest-frame wavelength grid [Angstrom].

  • ssp_flux (array, shape (n_met, n_age, n_wave)) – Spectral luminosity density of simple stellar populations (SSPs) per unit stellar mass [erg/s/Hz/Msun]. Origin: BC03, BPASS, FSPS, ProGeny, or other DSPS-compatible library.

  • ssp_lg_age_gyr (array, shape (n_age,)) – Age grid in log10 space [log10(Gyr)].

  • ssp_lgmet (array, shape (n_met,)) – Metallicity grid (absolute, NOT solar-relative) [log10(Z)]. Offset: log10(Z_sun) ≈ −1.848 (Asplund+2009). Do NOT confuse with user-facing log10(Z/Z_sun).

  • ssp_mass_remaining (array, shape (n_met, n_age), optional) – Fraction of initial stellar mass still present (living stars + remnants) at each (age, metallicity) [dimensionless, ∈ [0, 1]]. Used for stellar mass normalization in CSP integral. Depends on IMF and isochrone library; None if unavailable.

  • ssp_mass_remaining_alpha (array, shape (n_met, n_alpha, n_age), optional) – Surviving-mass fraction on a 4D grid’s [alpha/Fe] axis (#2250); its alpha = 0 plane is ssp_mass_remaining. None on 3D grids and on 4D grids without the table.

  • mass_remaining_source (str, optional) – Provenance of ssp_mass_remaining: "embedded", "companion:<file>", "dsps_fit" or "unspecified" (hand-built).

  • ssp_alpha_fe (array, shape (n_alpha,), optional) – [alpha/Fe] grid values, relative to solar. Present only for a 4D alpha-enhanced library; None for every library shipped here. When present, ssp_flux is (n_met, n_alpha, n_age, n_wave) and the alpha axis is collapsed by interpolate_alpha_only() before the DSPS kernel sees a 3D grid.

  • nebular (str, optional) – Nebular provenance: "included" (wNE: nebular continuum and lines baked in), "bare", or "unknown" (default). Resolved by load_ssp_data() from the nebular_included HDF5 attribute, else the wNE filename convention (#1014).

Notes

Metallicity convention: ssp_lgmet is absolute log10(Z), the total metallicity, on every grid. To convert user-supplied log10(Z/Z_sun) to grid coordinates, add LOG10_ZSUN ≈ −1.848. The loader refuses a file whose metallicity_axis attribute is on a fixed-[Fe/H] axis (#3411).

Alpha enhancement: a 4D library carrying an [alpha/Fe] axis is supported. has_alpha_grid() detects one and interpolate_alpha_only() collapses the axis at met_alpha_fe. A 3D grid has no [alpha/Fe] axis: met_logzsol is the total metallicity there, and met_alpha_fe has no effect, so the model builder refuses a non-zero value rather than folding it in.

Survival mass: ssp_mass_remaining encodes stellar mass loss due to stellar evolution (main-sequence turnoff, white dwarf cooling, etc.). It is essential for mass-based inferences but may not be present in older SSP libraries.

Examples

>>> from tengri import SSPData, load_ssp_data
>>> ssp = load_ssp_data("data/ssp_miles.h5")
>>> ssp.ssp_flux.shape  # (n_met, n_age, n_wave)
(22, 107, 4563)
cache_key() → tuple[source]

Return a hashable cache key for this SSPData instance.

Returns:

Cache key derived from every field of the NamedTuple.

Return type:

tuple

Notes

All fields are keyed by content since they define the SSP library identity (see _SSP_CACHE_KEY_POLICY).

grid_notes: tuple[str, ...]

Alias for field number 12

imf: str

Alias for field number 7

mass_remaining_source: str

Alias for field number 10

nebular: str

Alias for field number 9

repaired_cells: tuple

Alias for field number 13

source: str

Alias for field number 8

ssp_alpha_fe: Array | None

Alias for field number 6

ssp_flux: Array

Alias for field number 1

ssp_lg_age_gyr: Array

Alias for field number 2

ssp_lgmet: Array

Alias for field number 3

ssp_mass_remaining: Array | None

Alias for field number 4

ssp_mass_remaining_alpha: Array | None

Alias for field number 14

ssp_resolution_kms: Array | None

Alias for field number 5

ssp_wave: Array

Alias for field number 0

top_z: tuple | None

Alias for field number 11

tengri.load_ssp_data(filepath: str, *, dtype=None, download: bool = False, mass_remaining: str = 'table', top_z: str = 'clip', imf: str | None = None) → SSPData[source]

Load SSP templates from a DSPS-format HDF5 file.

Reads stellar population synthesis templates stored in HDF5 format (compatible with DSPS library and distributed SSP libraries: BC03, BPASS, FSPS, ProGeny). Handles optional fields (ssp_mass_remaining, ssp_alpha_fe) gracefully.

Parameters:
  • filepath (str) – Path to HDF5 file. Expected fields: ssp_wave, ssp_flux, ssp_lg_age_gyr, ssp_lgmet. Optional: ssp_mass_remaining, ssp_alpha_fe.

  • dtype (DTypeLike, optional) – Dtype for every loaded float array. None (default) follows tengri’s working precision (float64 under jax_enable_x64, its default). Pass jnp.float32 for a fully 32-bit pipeline: it halves the host-side grid (the ssp_flux cube is the model’s largest single array) and is applied regardless of the jax_enable_x64 flag. Safe now that the ~1e42 stellar_mass_scale and ~1e56 nion seams are carried in log space (#1206); before that, a float32 grid overflowed them silently, which is why the default still upcasts.

  • download (bool, optional) – Fetch the grid from the hosted catalog when filepath does not exist and its basename is one the catalog ships. Default False, which raises instead. See Notes for why the default is off.

  • mass_remaining ({"table", "dsps_fit"}, optional) – Source of ssp_mass_remaining. "table" (default) takes the grid’s own table or the companion table registered for its isochrones and IMF, and refuses a registered grid that has neither (a ValueError naming the missing table). An unregistered grid with no table warns and uses the fit when its IMF has one; when its IMF is not stated or has no fit, it is refused (see imf). "dsps_fit" is the explicit opt-in to DSPS’s metallicity-independent sigmoid fit to FSPS, for any grid.

  • top_z ({"clip", "mist", "raw"}, optional) – What to do with a top-metallicity node known to lack young massive stars (the Z = 0.06 node of every PARSEC grid has no stars above 12 Msun for log age <= 7.15, because the PARSEC massive-star tracks stop at Z = 0.04). Grids with no limit on record are unaffected. "clip" (default) refuses the node where it is incomplete: the metallicity is held at the highest complete node (Z = 0.04) for log age <= 7.15, and the node’s weight rises linearly with log age from 0 to 1 over the next 0.05 dex (one grid step), so the population is continuous in age and the node is used unchanged from log age 7.20. The Z = 0.06 node is ~800-2700x low in Q_H and ~16x low at 1500 A at log age 5.5-6.5 without this. "mist" is the opt-in that makes the clip target a MIST [Z/H] = +0.5 SSP (MILES, same IMF and ages) inserted as an extra metallicity node at FSPS’s zlegend value Z = Z_sun 10^[Z/H] = 0.0449 (Z_sun = 0.0142; Choi et al. 2016); between Z = 0.040 (PARSEC) and 0.0449 (MIST) the young population then switches isochrone physics, not only metallicity (see tengri.components.stellar.sps.top_z_validity for the measured ratios). It is shipped for the MILES grids. "raw" keeps the file’s node as shipped, for cross-code parity with FSPS only.

  • imf (str or None, optional) – The initial mass function the grid was computed under, for example "chabrier", "kroupa" or "salpeter". Normalized with strip().lower(). Takes precedence over the HDF5 imf attribute and the file-name token. None (default) reads those two in turn, and a grid that states neither is labeled "unknown". The label sets SSPData.imf and, for a user grid with no surviving-mass table, selects the DSPS fit (see Raises).

Returns:

Loaded SSP container with all template data and metadata; mass_remaining_source records where the surviving mass came from.

Return type:

SSPData

Raises:
  • ImportError – If h5py is not installed.

  • FileNotFoundError – If filepath does not exist and was not fetched. The message distinguishes a grid the catalog hosts (recoverable with download=True) from one it does not (must already be on disk).

  • KeyError – If required HDF5 fields are missing.

  • OSError – If filepath exists but is not readable.

  • ValueError – If mass_remaining is not a known mode, if imf is an empty string, or the surviving-mass table cannot be resolved honestly (see resolve_mass_remaining()): a registered grid with no table, a metallicity-node mismatch with the companion table, or ages that do not match the companion table’s nodes. A user’s own grid with no ssp_mass_remaining table and an IMF that is not stated or has no DSPS fit is refused too: the message names imf= (state the IMF) and mass_remaining="dsps_fit" (accept the Chabrier-parameter fit).

Notes

JIT-compatible: yes; only file I/O occurs; returned SSPData is immutable and suitable for use in JAX operations.

The fetch is opt-in, and the default changed in v0.9. This function used to fetch whenever the path was absent and the basename matched the catalog. Because it matched on the basename alone, a mistyped directory was not reported: load_ssp_data("/wrong/dir/fsps_prsc_miles_chabrier.h5") wrote ~67 MB into /wrong/dir/ and returned a grid, so the caller never learned the path was wrong. It also put a third-party host on the critical path of anything that merely named a grid, which reddened CI twice (#1486, #1528). download=False reports the path instead. This matches load_ssp(), which has defaulted to False since #1536.

Prefer :func:`load_ssp` when you want resolution rather than a literal path: it walks every ancestor for a data/ directory, honors $TENGRI_DATA_DIR, and so does not depend on the working directory.

Surviving-mass fraction (ssp_mass_remaining): living stars plus stellar remnants per unit formed mass [dimensionless], from the grid’s own isochrones, IMF and metallicity (Conroy, Gunn & White 2009; FSPS remnants after Renzini & Ciotti 1993; BC03 after Bruzual & Charlot 2003). It is resolved by resolve_mass_remaining(): for a registered grid, the companion table shipped as package data (authoritative; any table in the file is ignored); otherwise the file’s own table; otherwise, only with mass_remaining="dsps_fit", DSPS’s metallicity-independent fit. The fit discards the isochrones and the metallicity dependence (0.03 in the surviving mass at 10 Gyr on MIST), so it is never used silently.

File format: Standard DSPS HDF5 layout. See DSPS documentation and distributed templates on halos.as.arizona.edu for format details.

Precision: this knob sets the dtype of the host grid. Under the default x64 config a float32 grid gives correct results: intermediates promote to float64; so it halves grid memory (66.9 MB -> 33.5 MB for a typical SSP) with no change to the answer.

It does not, on its own, buy a correct pure-float32 forward pass. Overflow tracks the compute precision, not the storage dtype: pairing this with jax.enable_x64(False) sends two published linear keys out of range, and they return inf rather than raising. Measured on ssp_prsc_miles at 1e10 Msun, where only the x64 setting differs:

configuration                     grid dtype   stellar_mass_scale   nion
dtype=None,    x64 on (default)   float64      3.828e43             2.55e49
dtype=float32, x64 on             float32      3.828e43             2.55e49
dtype=None,    x64 off            float32      inf                  inf
dtype=float32, x64 off            float32      inf                  inf

Both exceed the float32 maximum of 3.4e38 by construction, so no grid dtype can rescue them: stellar_mass_scale is total_mass * L_sun and nion is an ionizing-photon rate. Their log-domain counterparts (log_stellar_mass_scale, log_nion) stay finite and are the float32-safe reads; note that log_nion is finite in every row above, so a test that asserts on it will not notice the linear key going inf. The remaining linear keys are issue #1206 item 3 (a breaking unit change, deliberately deferred); see docs/dev/float32-tier-b-boundary.md.

Examples

>>> from tengri.components.stellar.sps import load_ssp_data
>>> ssp = load_ssp_data("data/ssp_bc03.h5")
>>> print(ssp.ssp_wave.shape, ssp.ssp_flux.shape)
(6000,) (50, 300, 6000)
>>> import jax.numpy as jnp
>>> ssp32 = load_ssp_data("data/ssp_bc03.h5", dtype=jnp.float32)
>>> ssp32.ssp_flux.dtype
dtype('float32')
tengri.compute_mass_remaining_fraction(age_gyr: Array, imf: str = 'chabrier', m_low: float = 0.08, m_high: float = 120.0, n_mass: int = 500) → Array[source]

Compute surviving mass fraction at each age for a given IMF.

The surviving mass includes living stars (m < m_turnoff) plus remnants (WD, NS, BH) from stars that have died (m > m_turnoff).

Parameters:
  • age_gyr (array, shape (n_age,)) – Population ages [Gyr], sorted ascending.

  • imf (str) – IMF name: "chabrier", "salpeter", or "kroupa".

  • m_low (float) – Lower mass limit of the IMF [Msun]. Default 0.08.

  • m_high (float) – Upper mass limit of the IMF [Msun]. Default 120.

  • n_mass (int) – Number of mass grid points for logarithmic integration. Default 500.

Returns:

Fraction of formed mass in living stars + remnants (dimensionless, in (0, 1]). Value is 1.0 at age=0 (no stars have died).

Return type:

array, shape (n_age,)

Notes

JIT-compatible: yes, uses jax.vmap for vectorized age integration. Gradient-safe: yes.

This function numerically integrates the IMF in logarithmic mass space and uses Newton’s method to compute the MS turnoff mass at each age. See module docstring for limitations vs. FSPS mass-remaining tables.

Acquiring an SSP grid

tengri does not bundle SSP grids; they are downloaded on first use. The usual sequence is to see what exists, fetch one, then load it.

tengri.list_known_ssps()[source]

Return the known SSP names and their filenames.

Returns:

One row per SSP: {"name": ..., "kind": "ssp", "filename": ...}. Renders as a table in a notebook.

This used to return dict[str, str], one of only two list_* that did (#1285). Use .to_dict("filename") for the old mapping, or .names() for just the identifiers. Membership tests ("name" in ...) still work, because a row’s name is what .names() reports: but in on the table itself checks rows, so prefer in ....names().

Return type:

_RegistryTable

Examples

>>> import tengri
>>> "fsps_prsc_miles_chabrier" in tengri.list_known_ssps().names()
True
tengri.list_available_ssps() → list[dict][source]

Structured view of the SSP catalog grouped by family and IMF (#307).

Returns:

One row per registered SSP. Keys per row:

{
    "name": "fsps_prsc_miles_chabrier",
    "family": "fsps_prsc_miles",
    "imf": "chabrier",
    "filename": "fsps_prsc_miles_chabrier.h5",
    "downloaded": True or False,
}

family is the SSP name with the IMF suffix stripped (e.g. "fsps_prsc_miles" from "fsps_prsc_miles_chabrier"). downloaded is True iff the file is present under any data/ directory walked upward from Path.cwd(), the same discovery rule tengri.load_ssp() uses.

Return type:

list of dict

Examples

Find every IMF available for the FSPS+MIST+MILES family:

>>> import tengri
>>> rows = tengri.list_available_ssps()
>>> sorted({r["imf"] for r in rows if r["family"] == "fsps_mist_c3k_a"})
['chabrier', 'kroupa', 'salpeter']

See also

list_known_ssps

The flat name → filename mapping that this view groups and enriches.

tengri.download_ssp(name: str = 'mist_c3k_hr_chabrier_wNE', dest: str | PathLike | None = None, force: bool = False, progress: bool = True) → Path[source]

Download a pre-formatted SSP HDF5 file used by tengri’s stellar component.

Parameters:
  • name (str, optional) – Short SSP identifier (see list_known_ssps()) or a bare catalog filename ending in .h5. Defaults to DEFAULT_SSP, "mist_c3k_hr_chabrier_wNE" (FSPS MIST tracks + C3K HR library, Chabrier IMF, nebular emission baked in at logU = -3).

  • dest (path-like, optional) – Target directory. Defaults to download_dir(), $TENGRI_DATA_DIR if set, else data/ relative to the working directory. Either way it is a directory data_dirs() searches, so the loaders find the file afterwards.

  • force (bool, optional) – Re-download even if the file already exists. Default False.

  • progress (bool, optional) – Print download progress. Default True; pass False for clean log output.

Returns:

Path to the downloaded file.

Return type:

pathlib.Path

Raises:
  • KeyError – If name is neither in list_known_ssps() nor a .h5 filename.

  • RuntimeError – If the HTTP download fails (network error or non-200 status).

Examples

>>> import tengri
>>> tengri.download_ssp()  # default nebular-baked MIST+C3K HR grid → data/
>>> tengri.download_ssp("bc03_pdva_stelib_chabrier", dest="/scratch/ssp")
tengri.load_ssp(name: str | None = None, *, download: bool = False, mass_remaining: str | None = None, top_z: str = 'clip', imf: str | None = None) → SSPData[source]

Load an SSP grid by short name, walking parent dirs for data/.

Convenience wrapper around load_ssp_data() for tutorial and gallery scripts. Resolves a short alias ("prsc_miles_chabrier_wNE") or a bare filename to a full path by walking Path.cwd() upward until it finds a data/ directory containing the file.

Parameters:
  • name (str or None, optional) – Short alias from _LOAD_SSP_PRESETS, a key from tengri.list_known_ssps(), or a literal filename (with or without .h5). None (default) loads tengri._data_setup.DEFAULT_SSP, the nebular-baked MIST/C3K HR Chabrier grid, the same one tengri.download_ssp() fetches. A model built on it with a nebular backend other than baked-in is paired with the bare twin (#3465).

  • download (bool, optional) – Fetch the grid from the hosted catalog if it is not found locally. Default False, which raises instead; a default-on fetch would turn any mistyped grid name into a silent multi-tens-of-megabyte download (#1486). Pass True in tutorials and gallery scripts, where a fresh checkout is expected not to have the grid yet.

  • mass_remaining ({"table", "dsps_fit"} or None, optional) – Surviving-mass source, forwarded to load_ssp_data() (see there). None (default) takes "table", except for a grid that has no shipped table and is listed in DEFAULT_MASS_REMAINING: BPASS (bpss_stars_c3k_a_chabrier) then loads with "dsps_fit" and warns (#3428). Pass "table" to refuse instead.

  • top_z ({"clip", "mist", "raw"}, optional) – Treatment of a top-metallicity node that lacks young massive stars, forwarded to load_ssp_data() (see there). "mist" is the opt-in that replaces the clip target with a MIST [Z/H] = +0.5 node.

  • imf (str or None, optional) – The IMF the grid was computed under, forwarded to load_ssp_data() (see there). None (default) reads the grid’s own IMF statement.

Returns:

Loaded SSP container, same as load_ssp_data().

Return type:

SSPData

Raises:
  • FileNotFoundError – If the grid exists in none of tengri._data_setup.data_dirs and either download is False or the grid is not one the catalog hosts. The message names the directories searched.

  • ValueError – As load_ssp_data(): an empty imf, or a user grid whose IMF is not stated and has no surviving-mass table.

Notes

download=True makes this the single call a script needs, replacing the resolve-test-fetch-load sequence each one used to carry. That sequence began with a working-directory-relative path, so it looked in the wrong place (and therefore re-downloaded) whenever the script ran from anywhere but its own directory (#1486). The resolver here is cwd-independent: it honors $TENGRI_DATA_DIR, walks every ancestor for data/, and falls back to the package’s own source tree.

Examples

>>> from tengri import load_ssp
>>> ssp = load_ssp()  # default nebular-baked grid (== download_ssp())
>>> ssp = load_ssp("mist_c3k_hr_chabrier_noNE")  # bare-stellar twin
>>> ssp = load_ssp(download=True)  # fetch it if this checkout lacks it

Filters

Loading and managing photometric filter transmission curves.

tengri.load_filter_set(names: list[str], cache_dir: str | Path | None = None) → tuple[list[Array], list[Array], list[FilterCurve]][source]

Load multiple filters by short name.

Parameters:
  • names (list of str) – Short names from FILTER_REGISTRY.

  • cache_dir (str or pathlib.Path or None, optional) – Directory for cached filter files. None (default) resolves through default_filter_cache_dir().

Returns:

  • filter_waves (list of jnp.ndarray) – Wavelength arrays per filter, each shape (n_wave,) [Angstrom].

  • filter_trans (list of jnp.ndarray) – Transmission arrays per filter, each shape (n_wave,) (dimensionless [0, 1]).

  • filter_curves (list of FilterCurve) – Full FilterCurve objects with wavelength, transmission, and name.

Raises:

KeyError – If any name is not in FILTER_REGISTRY.

Notes

Filters are downloaded from SVO on first use and cached locally. See load_filter() for single-filter loading.

Examples

>>> from tengri import load_filter_set
>>> waves, trans, curves = load_filter_set(["sdss_r", "sdss_i", "sdss_z"])
>>> len(curves)
3
>>> curves[0].name
'sdss_r'

Spatial profiles

Surface-brightness profiles and the sub-models that compose them. A SpatialModel runs a list of profile components; SpatialSEDModel joins a SED chain to a spatial chain so both are fitted together.

class tengri.SpatialModel(components: Sequence[SpatialComponent], grid_kpc: tuple[Array, Array] | None = None)[source]

Bases: object

Composer over a list of SpatialComponent objects.

Satisfies tengri.protocols.SubModel, has name, declared_parameters(), and run().

Parameters:
  • components (sequence of SpatialComponent) – Spatial physics blocks to thread state through, in order.

  • grid_kpc (tuple of (ndarray, ndarray), optional) – (x_grid_kpc, y_grid_kpc), the 2D spatial coordinate grids, each of shape (ny, nx). If omitted, a sensible default 64×64 grid spanning ±10 kpc is constructed via default_grid_kpc(). Pass an explicit grid when the production fit needs different resolution or extent.

Notes

JIT/grad/vmap-compatible: run() is pure JAX. The grid is held as a static attribute, not closed over.

components: tuple[SpatialComponent, ...]
declared_parameters() → list[ParamDeclaration][source]

Aggregated parameter declarations across all spatial components.

grid_kpc: tuple[Array, Array]
name: str = 'spatial'

The SubModel identifier. init=False because the protocol calls it a stable identifier: this constructor never accepted it, and an ordinary field declaration advertised otherwise to dataclasses.fields() and to the docs.

run(state: ForwardState, params: Mapping[str, Array]) → ForwardState[source]

Thread state through each components in order.

Inserts grid_kpc into state.derived["spatial_grid_xy_kpc"] if not already present (callers can override by setting it on the incoming state). Each component then consumes the grid and updates state.derived["spatial_profile_2d"].

Parameters:
  • state (ForwardState) – Incoming state. Wave grid is preserved; spatial grid is inserted (or kept if caller already set it).

  • params (Mapping) – Free parameter values.

Returns:

New state with spatial_profile_2d populated.

Return type:

ForwardState

class tengri.SpatialSEDModel(sed: Any, spatial: SpatialModel)[source]

Bases: object

The joint spatial+SED sub-model.

Composes one tengri.SEDModel and one SpatialModel into a single tengri.protocols.SubModel. SED runs first (head of the chain); spatial runs second so spatial components can optionally read SED-derived keys from state.derived (architecture spec §4.3, SED → Spatial ordering).

Parameters:

Notes

Composer-only, no physics of its own. Aggregates declared parameters from both halves; runs SED, then spatial, on the same threaded ForwardState.

JIT/grad/vmap-compatible.

declared_parameters() → list[ParamDeclaration][source]

Union of SED and spatial declared parameters.

name: str = 'spatial_sed'

The SubModel identifier. init=False for the same reason as on SpatialModel, and here it also closes a hole: the generated constructor accepted name= and let a caller overwrite the identifier the protocol promises is stable.

run(state: ForwardState, params: Mapping[str, Array]) → ForwardState[source]

Run SED first, then spatial. Pure JAX.

sed: Any
spatial: SpatialModel
class tengri.Sersic[source]

Bases: SpatialModelComponent

Sérsic surface-brightness profile.

Free parameters

re_kpcUniform(0.1, 20.0) [kpc]

Effective (half-light) radius.

nUniform(0.5, 8.0)

Sérsic index. n=1 recovers an exponential disk, n=4 a de Vaucouleurs spheroid.

axis_ratioUniform(0.1, 1.0)

Minor-to-major axis ratio (b/a). 1.0 ↔ circular.

pa_degUniform(-90.0, 90.0) [deg]

Position angle of the major axis, measured east of north.

Notes

JIT/grad/vmap-compatible.

axis_ratio = Uniform(0.1, 1.0)
n = Uniform(0.5, 8.0)
name: str = 'sersic'
pa_deg = Uniform(-90.0, 90.0)
parameter_prefix: str = 'spatial_'
predict(p, profile_in, grid_kpc)[source]

Pure JAX prediction step. MUST be implemented by subclasses.

Parameters:
  • p (mapping[str, ndarray]) – Parameters with prefix stripped (p["re_kpc"], not p["spatial_re_kpc"]).

  • profile_in (ndarray, shape (ny, nx)) – Running 2D surface-brightness profile from upstream components, or zeros if this component is first.

  • grid_kpc (tuple of (ndarray, ndarray), each shape (ny, nx)) – (x_grid_kpc, y_grid_kpc): the 2D spatial coordinate grids.

  • **inputs (ndarray) – Cross-component reads keyed by names in reads.

Returns:

(profile_out, published). profile_out has shape (ny, nx) and replaces (or extends) profile_in. published is a dict matching publishes keys other than spatial_profile_2d, which the base class handles automatically.

Return type:

tuple[ndarray, mapping[str, ndarray]]

publishes: ClassVar[dict[str, str]] = {'spatial_profile_2d': ''}
re_kpc = Uniform(0.1, 20.0)
reads: ClassVar[dict[str, str]] = {}
class tengri.Exponential[source]

Bases: SpatialModelComponent

Exponential disk profile.

Free parameters

rd_kpcUniform(0.1, 20.0) [kpc]

Disk scale length.

axis_ratioUniform(0.1, 1.0)

Minor-to-major axis ratio.

pa_degUniform(-90.0, 90.0) [deg]

Position angle of the major axis.

Notes

JIT/grad/vmap-compatible.

axis_ratio = Uniform(0.1, 1.0)
name: str = 'exponential'
pa_deg = Uniform(-90.0, 90.0)
parameter_prefix: str = 'spatial_'
predict(p, profile_in, grid_kpc)[source]

Pure JAX prediction step. MUST be implemented by subclasses.

Parameters:
  • p (mapping[str, ndarray]) – Parameters with prefix stripped (p["re_kpc"], not p["spatial_re_kpc"]).

  • profile_in (ndarray, shape (ny, nx)) – Running 2D surface-brightness profile from upstream components, or zeros if this component is first.

  • grid_kpc (tuple of (ndarray, ndarray), each shape (ny, nx)) – (x_grid_kpc, y_grid_kpc): the 2D spatial coordinate grids.

  • **inputs (ndarray) – Cross-component reads keyed by names in reads.

Returns:

(profile_out, published). profile_out has shape (ny, nx) and replaces (or extends) profile_in. published is a dict matching publishes keys other than spatial_profile_2d, which the base class handles automatically.

Return type:

tuple[ndarray, mapping[str, ndarray]]

publishes: ClassVar[dict[str, str]] = {'spatial_profile_2d': ''}
rd_kpc = Uniform(0.1, 20.0)
reads: ClassVar[dict[str, str]] = {}
class tengri.FlatSlab[source]

Bases: SpatialModelComponent

Uniform-disk (flat-slab) profile.

Free parameters

radius_kpcUniform(0.1, 50.0) [kpc]

Disk radius. Intensity = 1 inside, 0 outside, with a small sigmoidal smoothing at the edge for differentiability.

Notes

JIT/grad/vmap-compatible. The edge softening is a numerical convenience for gradient-based inference; it is not a physical claim.

name: str = 'flat_slab'
parameter_prefix: str = 'spatial_'
predict(p, profile_in, grid_kpc)[source]

Pure JAX prediction step. MUST be implemented by subclasses.

Parameters:
  • p (mapping[str, ndarray]) – Parameters with prefix stripped (p["re_kpc"], not p["spatial_re_kpc"]).

  • profile_in (ndarray, shape (ny, nx)) – Running 2D surface-brightness profile from upstream components, or zeros if this component is first.

  • grid_kpc (tuple of (ndarray, ndarray), each shape (ny, nx)) – (x_grid_kpc, y_grid_kpc): the 2D spatial coordinate grids.

  • **inputs (ndarray) – Cross-component reads keyed by names in reads.

Returns:

(profile_out, published). profile_out has shape (ny, nx) and replaces (or extends) profile_in. published is a dict matching publishes keys other than spatial_profile_2d, which the base class handles automatically.

Return type:

tuple[ndarray, mapping[str, ndarray]]

publishes: ClassVar[dict[str, str]] = {'spatial_profile_2d': ''}
radius_kpc = Uniform(0.1, 50.0)
reads: ClassVar[dict[str, str]] = {}