Diagnostics

Tools enabled by end-to-end differentiability of the forward model. These provide Fisher information analysis, gradient SEDs (saliency maps), chain convergence diagnostics, and Green’s function time-sensitivity analysis.

Fisher information

tengri.analysis.diagnostics.fisher.compute_jacobian(predict_fn, params, param_keys)[source]

Compute the Jacobian ∂m/∂θ of model predictions w.r.t. parameters.

Parameters:
  • predict_fn (callable) – Function mapping a flat parameter array to model predictions.

  • params (array, shape (n_params,)) – Parameter values.

  • param_keys (tuple of str) – Parameter names (for static hashing).

Returns:

Jacobian matrix.

Return type:

array, shape (n_data, n_params)

Notes

Forward mode, deliberately. jax.jacobian is jacrev, and in float32 the reverse-mode Jacobian of a raw flux is exactly all zeros (#1388/#1415, measured in #1542); a silent, plausible-looking answer rather than a loud one. jacfwd is alive on the same model and, for n_params << n_data, is also the cheaper mode. Identical in float64 up to accumulation order.

tengri.analysis.diagnostics.fisher.compute_fisher_matrix(forward_model, params, noise, data_type='photometry', param_names=None)[source]

Compute the Fisher Information Matrix.

F_ij = sum_k (1/sigma_k^2) * (dm_k/dtheta_i) * (dm_k/dtheta_j)

Parameters:
  • forward_model (ForwardModel) – Configured forward model.

  • params (dict) – Parameter values at which to evaluate the FIM.

  • noise (array) – 1-sigma uncertainties on the data.

  • data_type (str) – “photometry” or “spectroscopy”.

  • param_names (list of str, optional) – Which parameters to include. Defaults to all physical params (excludes xi; the GP latent is high-dimensional).

Returns:

  • fim (array, shape (n_params, n_params)) – Fisher Information Matrix.

  • names (list of str) – Parameter names corresponding to FIM rows/columns.

tengri.analysis.diagnostics.fisher.fisher_parameter_errors(fim)[source]

Compute 1-sigma parameter uncertainties from the FIM.

sigma_i = sqrt((F^{-1})_ii)

Parameters:

fim (array, shape (n_params, n_params)) – Fisher Information Matrix.

Returns:

1-sigma marginal uncertainties.

Return type:

array, shape (n_params,)

tengri.analysis.diagnostics.fisher.fisher_correlation_matrix(fim)[source]

Compute parameter correlation matrix from the FIM.

Parameters:

fim (array, shape (n_params, n_params)) – Fisher Information Matrix.

Returns:

Correlation matrix (values in [-1, 1]).

Return type:

array, shape (n_params, n_params)

Chain convergence diagnostics

tengri.analysis.diagnostics.autocorrelation_time(x: ndarray, absolute: bool = False) → float[source]

Estimate integrated autocorrelation time using Sokal’s method.

Follows Behroozi’s autocorrelation_time_estimate() from acor_estimate.c:

τ = 1 + 2 Σ ρ(k)

with adaptive truncation at k > 5τ and skip-size doubling for efficiency on long chains.

Parameters:
  • x (array, shape (N,)) – 1D chain (single parameter).

  • absolute (bool) – If True, use absolute-deviation autocorrelation.

Returns:

Estimated integrated autocorrelation time (in samples). τ = 1 means uncorrelated; τ = 10 means ~10 samples per independent draw.

Return type:

float

tengri.analysis.diagnostics.autocorrelation_time_combined(x: ndarray) → dict[source]

Compute both standard and absolute autocorrelation times.

Returns the max of the two (following Behroozi’s diagnostic output), which is the most conservative estimate.

Parameters:

x (array, shape (N,)) – 1D chain.

Returns:

Keys: ‘tau_standard’, ‘tau_absolute’, ‘tau_max’, ‘ess’, ‘chain_converged’.

Return type:

dict

tengri.analysis.diagnostics.effective_sample_size(chains: dict[str, ndarray], exclude_prefixes: tuple[str, ...] = ('psd_xi',)) → dict[source]

Compute ESS for all scalar parameters using Sokal’s method.

Parameters:
  • chains (dict) – Parameter name → array of shape (N,) or (N, …).

  • exclude_prefixes (tuple of str) – Parameter name prefixes to skip (e.g., GP latent vector).

Returns:

Parameter name → dict with ‘tau_standard’, ‘tau_absolute’, ‘tau_max’, ‘ess’, ‘chain_converged’.

Return type:

dict

tengri.analysis.diagnostics.check_chain_length(chains: dict[str, ndarray], exclude_prefixes: tuple[str, ...] = ('psd_xi',), verbose: bool = True) → dict[source]

Check chain convergence using autocorrelation time estimates.

Follows Behroozi’s criterion: chain is converged when N > 5τ for all parameters. Reports both standard and absolute ACT.

Parameters:
  • chains (dict) – Parameter name → array of shape (N,).

  • exclude_prefixes (tuple of str) – Prefixes to skip.

  • verbose (bool) – Print diagnostics.

Returns:

Keys: ‘all_converged’ (bool), ‘params’ (per-parameter info), ‘warnings’ (list of str).

Return type:

dict

Saliency (gradient SEDs)

tengri.analysis.diagnostics.saliency.compute_gradient_sed(forward_model, params, param_name)[source]

Compute ∂SED(λ)/∂θ: the gradient of the SED w.r.t. one parameter.

Parameters:
  • forward_model (ForwardModel) – Configured forward model.

  • params (dict) – Parameter values.

  • param_name (str) – Which parameter to differentiate with respect to.

Returns:

  • gradient_sed (array, shape (n_wave,)) – ∂SED/∂θ at each wavelength.

  • wavelength (array, shape (n_wave,)) – Rest-frame wavelengths (Angstrom).

tengri.analysis.diagnostics.saliency.compute_all_gradient_seds(forward_model, params, param_names=None)[source]

Compute gradient SEDs for all physical parameters.

Parameters:
  • forward_model (ForwardModel) – Configured forward model.

  • params (dict) – Parameter values.

  • param_names (list of str, optional) – Parameters to compute gradients for.

Returns:

  • gradients (dict of {param_name: array (n_wave,)}) – Gradient SED per parameter.

  • wavelength (array, shape (n_wave,)) – Rest-frame wavelengths.

tengri.analysis.diagnostics.saliency.compute_photometry_sensitivity(forward_model, params, param_names=None)[source]

Compute ∂flux_band/∂θ for each filter and parameter.

Returns a matrix showing how sensitive each photometric band is to each parameter: useful for understanding degeneracies and planning filter sets.

Parameters:
  • forward_model (ForwardModel) – Configured forward model (must have filters set).

  • params (dict) – Parameter values.

  • param_names (list of str, optional) – Parameters to include.

Returns:

  • sensitivity (array, shape (n_filters, n_params)) – ∂flux_band/∂θ_param matrix.

  • param_names (list of str) – Parameter names (columns).

Emission-line measures

tengri.analysis.diagnostics.compute_equivalent_widths(line_fluxes: Array, continuum_at_lines: Array, redshift: float) → Array[source]

Rest-frame equivalent widths from line fluxes and continuum levels.

Follows the convention of Steidel et al. (1996) [tengri.analysis.diagnostics.compute_equivalent_widths-2] and FastSpecFit [tengri.analysis.diagnostics.compute_equivalent_widths-1]: EW is positive for emission.

Parameters:
  • line_fluxes (array_like, shape (n_lines,)) – Integrated emission line fluxes [erg/s/cm²].

  • continuum_at_lines (array_like, shape (n_lines,)) – Continuum spectral flux density evaluated at each line center [erg/s/cm²/Angstrom].

  • redshift (float) – Galaxy redshift [dimensionless].

Returns:

Rest-frame equivalent widths [Angstrom]. Zero where continuum_at_lines <= 0.

Return type:

ndarray, shape (n_lines,)

Notes

JIT-compatible: yes; differentiable through line_fluxes and continuum_at_lines.

The rest-frame EW is

\[\mathrm{EW}_i = \frac{F_i}{f_{\lambda,i}\,(1 + z)}\]

where \(f_{\lambda,i}\) is the observed-frame continuum at line \(i\) and the \((1+z)\) factor converts from observed to rest-frame wavelength interval.

Pixels with non-positive continuum return EW = 0 (guarded with jnp.where).

Implements the same calculation as FastSpecFit populate_emtable() [tengri.analysis.diagnostics.compute_equivalent_widths-1]; validated against its output.

References

[tengri.analysis.diagnostics.compute_equivalent_widths-1] (1,2)

Moustakas, J., Scholte, D., Dey, B., Khederlarian, A., 2023, “FastSpecFit: Fast spectral synthesis and emission-line fitting of DESI spectra”, Astrophysics Source Code Library, record ascl:2308.005. https://ui.adsabs.harvard.edu/abs/2023ascl.soft08005M

[tengri.analysis.diagnostics.compute_equivalent_widths-2]

Steidel, C. C., et al., 1996, ApJ, 462, L17.

tengri.analysis.diagnostics.compute_line_fluxes(amplitudes: Array, line_rest_waves: Array, redshift: float, sigma_kms: float, spectral_resolution: float) → Array[source]

Integrated Gaussian emission line fluxes from amplitude parameters.

Converts per-line Gaussian amplitudes into integrated fluxes by multiplying by the Gaussian normalization \(\sqrt{2\pi}\,\sigma_{\rm ang}\), where \(\sigma_{\rm ang}\) combines intrinsic velocity broadening and the instrumental line-spread function (LSF) in quadrature.

Parameters:
  • amplitudes (array_like, shape (n_lines,)) – Gaussian amplitude of each line [erg/s/cm²/Angstrom].

  • line_rest_waves (array_like, shape (n_lines,)) – Rest-frame vacuum wavelengths [Angstrom].

  • redshift (float) – Galaxy redshift [dimensionless].

  • sigma_kms (float) – Intrinsic line velocity dispersion [km/s].

  • spectral_resolution (float) – Spectral resolution \(R = \lambda/\Delta\lambda\) [dimensionless].

Returns:

Integrated line fluxes [erg/s/cm²].

Return type:

ndarray, shape (n_lines,)

Notes

JIT-compatible: yes, differentiable through amplitudes, sigma_kms, and spectral_resolution.

The observed-frame line center is \(\lambda_z = \lambda_{\rm rest}(1+z)\). The combined angular sigma in Angstrom is

\[\sigma_{\rm ang} = \lambda_z \sqrt{ \left(\frac{\sigma_{\rm kms}}{c}\right)^2 + \left(\frac{1}{2\sqrt{2\ln 2}\,R}\right)^2 }\]

where the second term is the LSF contribution (Gaussian FWHM = \(\lambda/R\)). The integrated flux is then

\[F_i = A_i \sqrt{2\pi}\,\sigma_{{\rm ang},i}\]

Implements the same calculation as FastSpecFit populate_emtable() [tengri.analysis.diagnostics.compute_line_fluxes-1]; validated against its output.

References

[tengri.analysis.diagnostics.compute_line_fluxes-1]

Moustakas, J., Scholte, D., Dey, B., Khederlarian, A., 2023, “FastSpecFit: Fast spectral synthesis and emission-line fitting of DESI spectra”, Astrophysics Source Code Library, record ascl:2308.005. https://ui.adsabs.harvard.edu/abs/2023ascl.soft08005M

tengri.analysis.diagnostics.compute_line_moments(wave_obs: Array, flux_residual: Array, ivar: Array, line_obs_wave: float, sigma_kms: float) → tuple[Array, Array][source]

Flux-weighted velocity centroid and dispersion from residual spectrum.

Computes the first and second velocity moments of a continuum-subtracted emission line using a soft Gaussian weight kernel. Unlike FastSpecFit’s hard \(\pm n_\sigma\) pixel window, the soft kernel is differentiable through sigma_kms and fully JIT-compatible. Can be jax.vmap-ed over lines for batch measurement.

Parameters:
  • wave_obs (array_like, shape (n_pix,)) – Observed-frame wavelength array [Angstrom].

  • flux_residual (array_like, shape (n_pix,)) – Continuum-subtracted flux [erg/s/cm²/Angstrom].

  • ivar (array_like, shape (n_pix,)) – Inverse variance [(erg/s/cm²/Angstrom)^-2].

  • line_obs_wave (float) – Observed-frame line center wavelength [Angstrom].

  • sigma_kms (float) – Gaussian sigma for the soft integration window [km/s].

Returns:

  • v_centroid (ndarray, shape ()) – Flux-weighted velocity centroid relative to line_obs_wave [km/s].

  • sigma_int (ndarray, shape ()) – Flux-weighted velocity dispersion [km/s].

Notes

JIT-compatible: yes; differentiable through sigma_kms.

Velocity of pixel \(k\) relative to the line center:

\[v_k = c \frac{\lambda_k - \lambda_0}{\lambda_0}\]

Soft Gaussian integration weight:

\[w_k = \exp\!\left(-\frac{v_k^2}{2\,\sigma_{\rm kms}^2}\right)\]

Combined weight incorporating inverse variance:

\[W_k = w_k \cdot \max(f_k,\, 0) \cdot \mathrm{ivar}_k\]

First moment (centroid):

\[v_{\rm cent} = \frac{\sum_k W_k\,v_k}{\sum_k W_k + \epsilon}\]

Second moment (dispersion):

\[\sigma_{\rm int} = \sqrt{ \frac{\sum_k W_k\,(v_k - v_{\rm cent})^2}{\sum_k W_k + \epsilon} }\]

where \(\epsilon = 10^{-30}\) prevents division by zero in empty windows.

Improvement over FastSpecFit [tengri.analysis.diagnostics.compute_line_moments-1]: the hard \(\pm n_\sigma\) window in FastSpecFit requires dynamic boolean indexing (flux[mask]), which is incompatible with JAX JIT due to its variable-length output. The soft kernel retains the full pixel array at fixed shape, enabling gradient-based inference through line widths.

References

[tengri.analysis.diagnostics.compute_line_moments-1]

Moustakas, J., Scholte, D., Dey, B., Khederlarian, A., 2023, “FastSpecFit: Fast spectral synthesis and emission-line fitting of DESI spectra”, Astrophysics Source Code Library, record ascl:2308.005. https://ui.adsabs.harvard.edu/abs/2023ascl.soft08005M

Green’s functions

tengri.analysis.diagnostics.green_functions.compute_green_function(ssp_flux_at_z, ssp_wave, filter_wave=None, filter_trans=None, wave_target=None, *, convention)[source]

Compute Green’s function G(t_age) for a filter or wavelength.

G(t_age) = flux contribution per unit stellar mass at age t_age.

For photometry:

G = int L_SSP(lambda|t_age) * T(lambda) * w(lambda) dlambda
    / int T(lambda) * w(lambda) dlambda

with w = 1/lambda (BESSELL default, matches DSPS/FSPS) or w = 1/lambda**2 (ENERGY, CIGALE).

For a single wavelength, G = L_SSP(wave_target | t_age).

Parameters:
  • ssp_flux_at_z (array, shape (n_age, n_wave)) – SSP spectra at fixed metallicity.

  • ssp_wave (array, shape (n_wave,)) – Wavelength grid (Angstrom).

  • filter_wave (array, optional) – Filter wavelength grid.

  • filter_trans (array, optional) – Filter transmission.

  • wave_target (float, optional) – Single wavelength (Angstrom). Used if no filter provided.

Returns:

Green’s function G(t_age).

Return type:

array, shape (n_age,)

tengri.analysis.diagnostics.green_functions.compute_window_function(green_fn, mean_sfr_on_ages)[source]

Compute window function W(t_age) = G(t_age) * <SFR(t_age)>.

The window function tells you which lookback times actually contribute to the observed flux, given the galaxy’s mean SFH.

Parameters:
  • green_fn (array, shape (n_age,)) – Green’s function G(t_age).

  • mean_sfr_on_ages (array, shape (n_age,)) – Mean SFR evaluated at the SSP age grid (Msun/yr).

Returns:

Window function W(t_age) (unnormalized).

Return type:

array, shape (n_age,)

tengri.analysis.diagnostics.green_functions.compute_time_sensitivity_matrix(ssp_flux_at_z, ssp_wave, wavelengths_target, *, convention: FilterConvention)[source]

Compute sensitivity of multiple wavelengths to different ages.

Returns a matrix G(wavelength, age) showing which wavelengths are sensitive to which stellar population ages.

Parameters:
  • ssp_flux_at_z (array, shape (n_age, n_wave)) – SSP spectra at fixed metallicity.

  • ssp_wave (array, shape (n_wave,)) – Wavelength grid (Angstrom).

  • wavelengths_target (array, shape (n_target,)) – Target wavelengths to evaluate (Angstrom). E.g., [1500, 2500, 4000, 5500, 6563, 8000, 16000] for FUV, NUV, Balmer break, V-band, H-alpha, I-band, H-band.

Returns:

sensitivity – G(wavelength, age) matrix. Each row is the Green’s function at that wavelength.

Return type:

array, shape (n_target, n_age)

Spectral indices and diagnostics

tengri.analysis.diagnostics.dn4000(wavelength_aa: Array, l_nu: Array) → float[source]

Dn4000 narrow-band break index (Balogh et al. 1999).

Computes the ratio of the wavelength-averaged flux density in a red band (4000–4100 Å) to a blue band (3850–3950 Å), both published in air and applied here in vacuum (tengri.utils.break_windows): ⟨F⟩ = ∫F dλ / ∫dλ, a trapezoid integral over exactly the band, with F interpolated linearly at the band edges, so the value does not depend on the wavelength sampling.

Parameters:
  • wavelength_aa (array_like, shape (n_wave,)) – Rest-frame wavelength grid in Ångstrom. [Å]

  • l_nu (array_like, shape (n_wave,)) – Luminosity density L_ν. [erg s⁻¹ Hz⁻¹] or [Lsun Hz⁻¹]

Returns:

Dn4000 index: ratio of red to blue band flux. [dimensionless]

Return type:

float

Notes

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

Dn4000 is a diagnostic of age: young star-forming galaxies with hot OB stars have Dn4000 ≈ 0.4–1.0 (weak 4000-Å break), while old quiescent galaxies have Dn4000 > 1.5 (strong break).

References

[tengri.analysis.diagnostics.dn4000-1]

Balogh, M. L., Morris, S. L., Yee, H. K. C., Carlberg, R. G., Ellingson, E., 1999, ApJ, 527, 54. https://doi.org/10.1086/308056

tengri.analysis.diagnostics.irx(l_dust: float, l_fuv: float) → float[source]

Infrared excess IRX as a function of dust and FUV luminosity.

IRX quantifies the ratio of dust emission (IR) to non-attenuated UV emission (FUV).

Parameters:
  • l_dust (float) – Total dust emission luminosity. [Lsun] or [erg s⁻¹]

  • l_fuv (float) – Far-UV (rest-frame 1500 Å) luminosity. [Lsun] or [erg s⁻¹]

Returns:

log₁₀(L_dust / L_FUV). [dimensionless]

Return type:

float

Notes

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

The infrared excess is:

\[\text{IRX} = \log_{10}(L_{\rm dust} / L_{\rm FUV})\]

High IRX (> 0.5) indicates significant dust attenuation. IRX ≈ 0 corresponds to unobscured star formation. IRX < 0 is rare and indicates highly ionized ISM with little dust.

Typical IRX–UV slope (β) relations (Meurer+1999):

  • Starbursts: IRX ≈ β_UV + 2.0 − 2.5

  • Quiescent: IRX ≈ β_UV + 0.7

See also uv_slope_beta.

tengri.analysis.diagnostics.uv_slope_beta(wavelength_aa: Array, l_nu: Array) → float[source]

UV spectral slope β from Calzetti et al. (1994) 10-window method.

Computes the UV slope by fitting log(F_lambda) vs log(lambda) over the union of 10 clean spectral windows that avoid the 2175-Å dust bump and strong spectral features. Implements Calzetti+1994 Eq. 3: ONE pooled least-squares fit across all window pixels, not per-window slopes averaged.

Parameters:
  • wavelength_aa (array_like, shape (n_wave,)) – Rest-frame wavelength grid in Ångstrom. [Å]

  • l_nu (array_like, shape (n_wave,)) – Luminosity density L_ν. [erg s⁻¹ Hz⁻¹] or [Lsun Hz⁻¹]

Returns:

Spectral slope β where F_λ ∝ λ^β. [dimensionless]

Return type:

float

Notes

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

The method uses 10 wavelength windows (Calzetti+1994 Table 2) that avoid the 2175-Å absorption feature and Ly-alpha:

No.

Range (Ångstrom)

1

1268–1284

2

1309–1316

3

1342–1371

4

1407–1515

5

1562–1583

6

1677–1740

7

1760–1833

8

1866–1890

9

1930–1950

10

2400–2580

The slope is one ordinary least-squares fit of log F_λ against log λ over the pixels with lo <= λ <= hi in any window. The window bounds are hard, as in Eq. 3: they are constants, so the hard masks carry no derivative with respect to the model, and the fit is linear in log F. The abscissa and ordinate are centered on their window means before the sums of squares are formed, so the fit is stable in float32 (log λ ≈ 7.4 with a spread of 0.5).

References

[tengri.analysis.diagnostics.uv_slope_beta-1]

Calzetti, D., Kinney, A. L., Storchi-Bergmann, T., 1994, ApJ, 429, 582. Equation 3 and Table 2. https://doi.org/10.1086/174330

tengri.analysis.diagnostics.rest_frame_color(wavelength_aa: Array, l_nu: Array, filter1_wave_aa: Array, filter1_trans: Array, filter2_wave_aa: Array, filter2_trans: Array, *, convention: FilterConvention) → float[source]

Rest-frame color from two filters (magnitude difference).

Computes rest-frame photometric color as m1 - m2.

Parameters:
  • wavelength_aa (array_like, shape (n_wave,)) – Rest-frame wavelength grid in Ångstrom. [Å]

  • l_nu (array_like, shape (n_wave,)) – Luminosity density L_ν. [erg s⁻¹ Hz⁻¹] or [Lsun Hz⁻¹]

  • filter1_wave_aa (array_like, shape (n_f1,)) – First filter wavelength grid in Ångstrom. [Å]

  • filter1_trans (array_like, shape (n_f1,)) – First filter transmission. [dimensionless]

  • filter2_wave_aa (array_like, shape (n_f2,)) – Second filter wavelength grid in Ångstrom. [Å]

  • filter2_trans (array_like, shape (n_f2,)) – Second filter transmission. [dimensionless]

Returns:

Color m1 - m2 (in AB magnitudes). [mag]

Return type:

float

Notes

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

The color is computed from the flux ratio:

\[c = m_1 - m_2 = -2.5 \log_{10}(f_1 / f_2)\]

where f1, f2 are synthetic fluxes through the two filters.

If either flux is zero or negative (due to interpolation artifacts), the color is set to 0.

tengri.analysis.diagnostics.rest_frame_luminosity(wavelength_aa: Array, l_nu: Array, filter_wave_aa: Array, filter_trans: Array, convention: FilterConvention) → float[source]

Synthetic rest-frame luminosity through a filter.

Computes rest-frame photometry by convolving L_ν with a filter response, using the same bandpass weight as the observed-frame kernel so rest- and observed-frame photometry are consistent (matching DSPS calc_rest_flux).

Parameters:
  • wavelength_aa (array_like, shape (n_wave,)) – Rest-frame wavelength grid in Ångstrom. [Å]

  • l_nu (array_like, shape (n_wave,)) – Luminosity density L_ν. [erg s⁻¹ Hz⁻¹] or [Lsun Hz⁻¹]

  • filter_wave_aa (array_like, shape (n_filter,)) – Filter wavelength grid in Ångstrom. [Å]

  • filter_trans (array_like, shape (n_filter,)) – Filter transmission (normalized to peak = 1). [dimensionless]

  • convention (FilterConvention, optional) – Bandpass weight. BESSELL (default) is photon-counting (\(w=1/\lambda\), matches DSPS calc_rest_flux); ENERGY is \(w=1/\lambda^2\) (CIGALE).

Returns:

Synthetic luminosity. [Lsun] or [erg s⁻¹]

Return type:

float

Notes

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

The photometric luminosity is:

\[L = \frac{\int T(\lambda) L_\nu(\lambda) w(\lambda) d\lambda} {\int T(\lambda) w(\lambda) d\lambda}\]

where T(λ) is the filter transmission and \(w(\lambda)\) the bandpass weight (\(1/\lambda\) for BESSELL, \(1/\lambda^2\) for ENERGY).

The filter is interpolated to the wavelength grid of the SED using linear interpolation with zero-padding outside the filter range.

tengri.analysis.diagnostics.dust_energy_balance(wavelength_aa: Array, l_nu_unattenuated: Array, l_nu_attenuated: Array, l_nu_dust_emission: Array, tol: float = 0.05, uv_nir_band_aa: tuple[float, float] = (911.76, 30000.0), ir_band_aa: tuple[float, float] = (30000.0, 30000000.0)) → dict[source]

Check whether absorbed and re-emitted dust energy balance.

Integrates \((L_\nu^{\rm unatten} - L_\nu^{\rm atten})\) over the UV-NIR band and \(L_\nu^{\rm dust\,emission}\) over the IR band, and reports the ratio.

Parameters:
  • wavelength_aa (array_like, shape (n_wave,)) – Rest-frame wavelength grid (ascending). [Å]

  • l_nu_unattenuated (array_like, shape (n_wave,)) – Stellar (+ AGN) \(L_\nu\) before dust attenuation. [erg/s/Hz]

  • l_nu_attenuated (array_like, shape (n_wave,)) – Stellar (+ AGN) \(L_\nu\) after dust attenuation. [erg/s/Hz]

  • l_nu_dust_emission (array_like, shape (n_wave,)) – Dust thermal \(L_\nu\) re-emission. [erg/s/Hz]

  • tol (float, optional) – Fractional tolerance on the absorbed/emitted ratio for the balanced flag. Default 0.05 (5%).

  • uv_nir_band_aa (tuple of (float, float), optional) – Band over which absorption is integrated. Default (LYMAN_LIMIT_AA, 3e4) Å.

  • ir_band_aa (tuple of (float, float), optional) – Band over which re-emission is integrated. Default (3e4, 3e7) Å.

Returns:

Keys:

  • absorbed : float: \(\int (L_\nu^{\rm unatten} - L_\nu^{\rm atten}) d\nu\) over the UV-NIR band. [erg/s]

  • emitted : float; \(\int L_\nu^{\rm dust} d\nu\) over the IR band. [erg/s]

  • ratio : float. emitted / absorbed (inf if absorbed is zero, nan if both are zero).

  • balanced : bool; abs(ratio - 1) <= tol and absorbed > 0.

Return type:

dict

Notes

JIT-compatible: yes for the underlying integrals; the dict return is constructed at trace time.

The default UV-NIR/IR band split at 3 μm is the conventional boundary used by MAGPHYS and CIGALE. For galaxies with significant PAH or torus emission the user should widen the IR band.

Examples

>>> result = dust_energy_balance(wave, l_unatten, l_atten, l_dust)
>>> if not result["balanced"]:
...     print(f"WARN: dust ratio {result['ratio']:.2f}, expected ~1")
tengri.analysis.diagnostics.integrate_lnu_over_band(wavelength_aa: Array, l_nu: Array, lambda_lo_aa: float, lambda_hi_aa: float) → Array[source]

Integrate \(L_\nu\) over a wavelength band.

Equivalent to \(\int F_\lambda \, d\lambda\) over the same band (since \(L_\nu \, d\nu = F_\lambda \, d\lambda\) up to sign).

Parameters:
  • wavelength_aa (array_like, shape (n_wave,)) – Wavelength grid in ascending order. [Å]

  • l_nu (array_like, shape (n_wave,)) – Spectral luminosity density. [erg/s/Hz] or [Lsun/Hz]

  • lambda_lo_aa (float) – Lower band edge. [Å]

  • lambda_hi_aa (float) – Upper band edge. [Å]

Returns:

Integrated luminosity over the band, in the same units as \(L_\nu \cdot \nu\) (so [erg/s] or [Lsun]).

Return type:

float

Notes

JIT-compatible: yes.

Bands that fall entirely outside the supplied grid return 0; bands that partially overlap return only the overlapping portion. The integration is performed in \(\lambda\) space using \(\int F_\lambda \, d\lambda = \int (c/\lambda^2)\, L_\nu \, d\lambda\), which avoids the irregular spacing introduced by switching to \(\nu = c/\lambda\).