Source code for tengri.components.stellar.sps.dsps_wrapper

# SPDX-License-Identifier: BSD-3-Clause
"""DSPS integration: differentiable CSP synthesis and SSP template management.

This module wraps the Differentiable Stellar Population Synthesis (DSPS) library
(Hearin et al. 2023), which provides the core forward model operation: integrating
a star formation history (SFH) with SSP templates to produce a composite stellar
population (CSP) spectrum. All operations are JAX-native and fully differentiable
via automatic differentiation.

The CSP integral is:

    L_CSP(λ) = ∫ SFR(t) × L_SSP(λ|age,Z) dt

See 3-forward-model.tex, Eq. 3.1–3.5 for the mathematical formulation and
Appendix A.1 for metallicity marginalization and precomputation schemes.
"""

import hashlib
import warnings
import weakref
from functools import cache
from typing import NamedTuple

import jax
import jax.numpy as jnp
import numpy as np
from jax import dtypes as jax_dtypes

from tengri._cache_keys import KeyPolicy, baked, content
from tengri._x64_hold import hold_x64_preference
from tengri.components.stellar.sps.grid_defects import repair_known_grid_defects
from tengri.components.stellar.sps.met_pchip import (
    met_weights,
    read_met,
    read_met_per_age,
)


def canonical_dsps_kwargs(**kwargs):
    """Cast every float operand of a DSPS kernel call to one working dtype.

    Parameters
    ----------
    **kwargs
        Array/scalar operands to forward to a DSPS kernel. Integer and boolean
        operands (indices, counts, masks) pass through untouched.

    Returns
    -------
    dict
        The same keys. Floating operands are cast to
        ``canonicalize_dtype(result_type(*floating_values))``; every other
        operand is returned as-is.

    Notes
    -----
    **JIT/grad/vmap-safe**: yes.

    Only *floating* operands are canonicalized, and only they contribute to the
    promotion. Folding an integer into ``result_type`` would promote it to float
    and hand a DSPS kernel a float where it expects an index: the cast this
    function exists to prevent, in the opposite direction.

    The SSP grids (``ssp_lgmet``, ``ssp_lg_age_gyr``, ``ssp_flux``) are cached
    host arrays built once at load time, so they stay float64 even inside
    ``jax.enable_x64(False)`` while fitted parameters arrive as float32
    tracers. DSPS then sizes its internal buffers from the float64 grids and
    scatters float32-derived values into them::

        FutureWarning: scatter inputs have incompatible types: cannot safely
        cast value from dtype=float32 to dtype=float64 ...
        In future JAX releases this will result in an error.

    Measured: a field-SFH forward pass emitted six of these in pure float32 and
    none in float64; canonicalizing first takes it to zero.

    Under ``x64=True`` the canonical float *is* float64, so this is a no-op
    there and float64 results are bit-unchanged: the property that makes the
    pattern safe to apply at every DSPS boundary. Same treatment as
    :func:`tengri.utils.interpolation.compute_grid_weights` (#1206, #1448).

    This lives beside the DSPS bindings so every call site in the tree can
    reach it without importing back into ``components/stellar/component.py``.
    """
    arrays = {key: jnp.asarray(value) for key, value in kwargs.items()}
    floating = {
        key: value for key, value in arrays.items() if jnp.issubdtype(value.dtype, jnp.floating)
    }
    if not floating:
        return arrays
    dt = jax_dtypes.canonicalize_dtype(jnp.result_type(*floating.values()))
    return {key: (value.astype(dt) if key in floating else value) for key, value in arrays.items()}


# Imported at module scope, not inside ``load_ssp``, so the fetch is a visible
# dependency of this module rather than a hidden one. ``_data_setup`` imports
# only the standard library, so there is no cycle to avoid.
from tengri._data_setup import download_ssp
from tengri.components.stellar.sps.mass_remaining_tables import (
    DEFAULT_MASS_REMAINING,
    GRID_CAVEATS,
    canonical_grid_name,
    fit_imf_params,
    resolve_mass_remaining,
)
from tengri.config.exceptions import MetallicityAxisAssumedWarning, TengriIOError
from tengri.utils.interpolation import concrete_canonical_numpy
from tengri.utils.ssp_anchor import ZERO_AGE_ANCHOR_FLOOR_LG_AGE_YR


[docs] class SSPData(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 :func:`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 :func:`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. :func:`has_alpha_grid` detects one and :func:`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") # doctest: +SKIP >>> ssp.ssp_flux.shape # (n_met, n_age, n_wave) # doctest: +SKIP (22, 107, 4563) """ ssp_wave: jnp.ndarray ssp_flux: jnp.ndarray # (n_met, n_age, n_wave) or future (n_met, n_alpha, n_age, n_wave) ssp_lg_age_gyr: jnp.ndarray ssp_lgmet: jnp.ndarray ssp_mass_remaining: jnp.ndarray | None = None # Per-wavelength SSP library resolution [km/s] (#2518): velocity dispersion # σ_lib(λ) derived from the loaded library's documented LSF. Used to # subtract library broadening in apply_lsf (and project_spectrum) when # convolving spectra. Example: MILES has FWHM ≈ 2.51 Å (constant in # wavelength), giving σ_v(λ) ∝ 1/λ, from 91 km/s at 3525 Å to 43 km/s # at 7500 Å. None if not populated (e.g., loaded from older file format). ssp_resolution_kms: jnp.ndarray | None = None # Future: ssp_alpha_fe grid for alpha-enhanced templates (Vazdekis+2015, MIST) # When available, ssp_flux becomes (n_met, n_alpha, n_age, n_wave) and # interpolation adds a third dimension. A 3D grid has no such axis. ssp_alpha_fe: jnp.ndarray | None = None # Initial mass function the SSP was computed under, e.g. ``"chabrier"``, # ``"kroupa"``, ``"salpeter"``. Surfaced by :func:`load_ssp_data` from # the file's HDF5 metadata if present, else parsed from the filename # tail (last underscore-delimited token before ``.h5``). ``"unknown"`` # when neither path yields a match. See issue #307 for the discovery # gap this closes; the IMF is invisible in the model spec otherwise. imf: str = "unknown" # Provenance name the grid was loaded from (filename stem, e.g. # ``ssp_prsc_miles_chabrier_wNE_logGasU-3.0_logGasZ0.0``). Surfaced by # :func:`load_ssp_data` so the citation machinery can infer the SPS code, # isochrone set, and spectral library from the # ``<code>_<isochrone>_<library>_<imf>`` token convention. Empty when # unknown. Metadata only: never a JIT leaf. source: str = "" # Nebular provenance of the grid (#1014): ``"included"`` (wNE # post-processed: nebular continuum and lines baked into the templates # at fixed logU/logZ_gas), ``"bare"`` (pure stellar), or ``"unknown"`` # (no metadata). Resolved by :func:`load_ssp_data` from the # ``nebular_included`` HDF5 attribute when present (stamp existing files # with ``tools/stamp_ssp_nebular_attrs.py``), else from the ``wNE`` # filename convention. The Cue / CloudyGrid backends refuse # ``"included"`` grids; a retained-LyC wNE grid is indistinguishable # from bare by any Q_H heuristic, so the flag is the only reliable # signal. Metadata only: never a JIT leaf. nebular: str = "unknown" # Where ``ssp_mass_remaining`` came from (#2751): ``"embedded"`` (the grid # file's own table), ``"companion:<file>"`` (a table shipped in # ``tengri.data.ssp_mass_remaining`` for the grid's isochrones and IMF), # ``"dsps_fit"`` (DSPS's metallicity-independent sigmoid, explicit opt-in) or # ``"unspecified"`` for a hand-built SSPData. Metadata only: never a JIT leaf. mass_remaining_source: str = "unspecified" # Validity limit of the grid's top-metallicity node and the ``top_z=`` policy # applied to it (:class:`~tengri.components.stellar.sps.top_z_validity.TopZValidity`), # or ``None`` when the grid has no limit on record. Metadata only: never a JIT leaf. top_z: tuple | None = None # Caveats on the flux of this grid, one string each (#3428), warned once at load # (see ``GRID_CAVEATS``). Metadata only: never a JIT leaf. grid_notes: tuple[str, ...] = () # Cells ``(lgmet, lg_age_gyr)`` whose flux was replaced at load by # :func:`~tengri.components.stellar.sps.grid_defects.repair_known_grid_defects` (#3406). # Empty for every grid without a recorded defect. Metadata only. repaired_cells: tuple = () # [alpha/Fe]-dependent surviving-mass table (#2250), shape (n_met, n_alpha, n_age), with # ``ssp_mass_remaining`` as its alpha = 0 plane; None on 3-D grids and on 4-D grids without it. ssp_mass_remaining_alpha: jnp.ndarray | None = None
[docs] def cache_key(self) -> tuple: """Return a hashable cache key for this SSPData instance. Returns ------- tuple Cache key derived from every field of the NamedTuple. Notes ----- All fields are keyed by content since they define the SSP library identity (see _SSP_CACHE_KEY_POLICY). """ return ("SSPData", tuple((name, baked(getattr(self, name))) for name in self._fields))
def _sspdata_flatten(s): # ``imf``/``source``/``nebular``/``mass_remaining_source`` are metadata, not JIT leaves: keep # strings out of the trace. children = ( s.ssp_wave, s.ssp_flux, s.ssp_lg_age_gyr, s.ssp_lgmet, s.ssp_mass_remaining, s.ssp_alpha_fe, s.ssp_resolution_kms, s.ssp_mass_remaining_alpha, ) aux = ( s.imf, s.source, s.nebular, s.mass_remaining_source, s.top_z, s.grid_notes, s.repaired_cells, ) return children, aux def _sspdata_unflatten(aux, children): # All-keyword reconstruction: the flattened ``children`` order # (..., ssp_alpha_fe, ssp_resolution_kms) does not match the field # declaration order (..., ssp_resolution_kms, ssp_alpha_fe). Keywords # make the mapping explicit and immune to reordering either tuple. return SSPData( ssp_wave=children[0], ssp_flux=children[1], ssp_lg_age_gyr=children[2], ssp_lgmet=children[3], ssp_mass_remaining=children[4], ssp_alpha_fe=children[5], ssp_resolution_kms=children[6], ssp_mass_remaining_alpha=children[7], imf=aux[0], source=aux[1], nebular=aux[2], mass_remaining_source=aux[3], top_z=aux[4], grid_notes=aux[5], repaired_cells=aux[6], ) jax.tree_util.register_pytree_node(SSPData, _sspdata_flatten, _sspdata_unflatten) _SSP_CACHE_KEY_POLICY: KeyPolicy = { "ssp_wave": content("wavelength grid defines the flux resolution"), "ssp_flux": content("flux templates define the stellar populations"), "ssp_lg_age_gyr": content("age grid defines the SFH discretization"), "ssp_lgmet": content("metallicity grid defines the Z discretization"), "ssp_mass_remaining": content("stellar mass fractions define mass normalization"), "ssp_alpha_fe": content("alpha enhancement grid defines the stellar templates"), "ssp_resolution_kms": content("per-wavelength library resolution affects LSF subtraction"), "ssp_mass_remaining_alpha": content("alpha-dependent surviving-mass table defines the mass"), "imf": content("initial mass function affects stellar population synthesis"), "source": content("source/library identity affects stellar templates"), "nebular": content("nebular inclusion status (wNE vs bare) affects the grid"), "mass_remaining_source": content("where the surviving-mass table came from"), "top_z": content("top-metallicity validity limit and policy change the node arrays"), "grid_notes": content("caveats on the grid's flux identify the library"), "repaired_cells": content("cells repaired at load change the flux templates"), } #: Content digests keyed by ``id(ssp_flux)``, each entry validated by a #: weakref to the array it was computed from. SSPData is a NamedTuple, so #: nothing can be cached on the instance (tuples reject ``__setattr__`` and #: weakrefs); jax/numpy arrays support weakrefs, so the flux array itself is #: the anchor. A recycled ``id`` after garbage collection fails the identity #: check and recomputes, so it can never return another grid's digest. _SSP_CONTENT_HASH_CACHE: dict[int, tuple[object, int]] = {} def get_ssp_content_hash(ssp_data: SSPData) -> int: """Return a content digest of ``ssp_flux`` for cache keying (#1973). Two SSPData instances with identical shape and ``ssp_lgmet`` but different flux must produce different values, so the compile signature can distinguish SSP libraries; the collision this closes silently ran one grid's physics for another (+0.9962 dex on ``log_total_mass`` by fit order). Returns ------- int blake2b digest (8 bytes, as int) of the flux buffer. Deterministic across processes, unlike ``hash(bytes)``, which PYTHONHASHSEED salts per process (the #1032 nondeterminism class). Notes ----- **Cost**: one digest per distinct flux array object, about 30 ms for the default 66.9 MB grid, then O(1) via the module cache above. Two SSPData objects sharing one flux array share the cache entry; two objects loaded separately with identical content recompute but return EQUAL digests (content-based), so catalog fits that reload an SSP file never over-key. """ arr = ssp_data.ssp_flux key = id(arr) hit = _SSP_CONTENT_HASH_CACHE.get(key) if hit is not None: ref, digest = hit if ref() is arr: return digest # Drop entries whose arrays were garbage-collected so the cache stays # bounded by the number of LIVE grids (typically one or two). dead = [k for k, (ref, _) in _SSP_CONTENT_HASH_CACHE.items() if ref() is None] for k in dead: del _SSP_CONTENT_HASH_CACHE[k] buf = np.asarray(arr) # one device transfer, once per grid digest = int.from_bytes(hashlib.blake2b(buf.tobytes(), digest_size=8).digest(), "big") _SSP_CONTENT_HASH_CACHE[key] = (weakref.ref(arr), digest) return digest _LOAD_SSP_PRESETS: dict[str, str] = { # Short alias → full filename. Bare-stellar entries come from # ``_KNOWN_SSPS`` (the auto-fetch catalog); wNE entries are produced # locally and recorded here so demo scripts can ``load_ssp("…wNE")`` # without spelling out the gas-grid suffix. "prsc_miles_chabrier_wNE": "ssp_prsc_miles_chabrier_wNE_logGasU-3.0_logGasZ0.0.h5", "mist_c3k_a_chabrier_wNE": "ssp_mist_c3k_a_chabrier_wNE_logGasU-3.0_logGasZ0.0.h5", } def _default_mass_remaining(name: str | None) -> str: """The ``mass_remaining`` mode a grid loads with when the caller passes none (#3428). A grid listed in ``DEFAULT_MASS_REMAINING`` takes that mode and warns, naming the opt-in that accepts it. Every other grid, and the default grid when ``name`` is ``None``, takes ``"table"``. """ from pathlib import Path if name is None: return "table" grid = canonical_grid_name(Path(name).stem) mode = DEFAULT_MASS_REMAINING.get(grid, "table") if mode != "table": warnings.warn( f"'{grid}' has no shipped surviving-mass table, so load_ssp loads it with " f"mass_remaining={mode!r} (DSPS's Chabrier fit). Pass mass_remaining='table' " "to refuse instead.", UserWarning, stacklevel=3, ) return mode
[docs] def load_ssp( name: str | None = None, *, download: bool = False, mass_remaining: str | None = None, top_z: str = "clip", imf: str | None = None, ) -> "SSPData": """Load an SSP grid by short name, walking parent dirs for ``data/``. Convenience wrapper around :func:`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 :func:`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 :func:`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 :func:`load_ssp_data` (see there). ``None`` (default) reads the grid's own IMF statement. Returns ------- SSPData Loaded SSP container, same as :func:`load_ssp_data`. 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 :func:`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 """ from pathlib import Path from tengri._data_setup import _KNOWN_SSPS, DEFAULT_SSP, catalog_short_name if mass_remaining is None: mass_remaining = _default_mass_remaining(name) if name is None: # The default is the named grid DEFAULT_SSP (#3465). return load_ssp( DEFAULT_SSP, download=download, mass_remaining=mass_remaining, top_z=top_z, imf=imf, ) if name in _LOAD_SSP_PRESETS: # Produced locally, not hosted; so there is nothing to fall back to. catalog_key = None filename = _LOAD_SSP_PRESETS[name] elif name in _KNOWN_SSPS: catalog_key = name filename = _KNOWN_SSPS[name].filename else: # Accept an explicit absolute/relative path to an .h5 file directly # (closes #496: reproduction notebooks ship SSPs under # ``reproduction/<code>/_drivers/data/`` rather than ``<root>/data/``). as_path = Path(name) if as_path.suffix == ".h5" and as_path.exists(): return load_ssp_data(str(as_path), mass_remaining=mass_remaining, top_z=top_z, imf=imf) filename = name if name.endswith(".h5") else name + ".h5" catalog_key = catalog_short_name(filename) from tengri._data_setup import TENGRI_DATA_ENV, data_dirs for directory in data_dirs(): candidate = directory / filename if candidate.exists(): return load_ssp_data( str(candidate), mass_remaining=mass_remaining, top_z=top_z, imf=imf ) if download and catalog_key is not None: return load_ssp_data( str(download_ssp(catalog_key)), mass_remaining=mass_remaining, top_z=top_z, imf=imf ) catalog_note = ( f"{filename!r} is not in the download catalog, so download=True cannot " f"fetch it: the wNE (with-nebular-emission) grids are produced locally. " if download else "Call tengri.download_ssp('<short_name>') to fetch a bundled SSP " "(tengri.list_known_ssps() lists them), " ) raise FileNotFoundError( f"SSP file {filename!r} not found. Looked in: " f"{', '.join(str(d) for d in data_dirs()[:4])} (and further ancestors). " f"{catalog_note}" f"place the file under <project_root>/data/, or set ${TENGRI_DATA_ENV} " f"to the directory holding it." )
def _load_float(dataset, dtype=None) -> jnp.ndarray: """Read an HDF5 float dataset at tengri's working precision (#1099). Several repackaged grids store float32 (``bc03_*``, ``pgny_*``). Left as float32, ``stellar_mass_scale = total_mass x L_sun`` ~ 1e42 overflows the float32 ceiling of 3.4e38 to ``inf`` (silently) and poisons the ionizing SED the nebular backends consume. The default upcast is lossless: every float32 is exactly a float64, so no stored value changes. Parameters ---------- dataset : h5py.Dataset The HDF5 dataset to read. dtype : DTypeLike, optional Target dtype. ``None`` (default) follows tengri's working precision (``jnp.result_type(float)``); an explicit dtype (e.g. ``jnp.float32``) forces it regardless of the ``jax_enable_x64`` flag: the opt-in for a fully 32-bit pipeline (#1206), safe now that the ~1e42/1e56 scale seams are carried in log space. """ return jnp.asarray(dataset[:], dtype=dtype if dtype is not None else jnp.result_type(float)) def _read_metallicity_axis(attrs) -> str | None: """Return the file's ``metallicity_axis`` attribute as a stripped string. ``None`` when the attribute is absent. h5py returns ``str`` for string attributes; a ``bytes`` value from an older writer is decoded, and a one-element array (some writers store strings that way) is unwrapped. """ raw = attrs.get("metallicity_axis") if raw is None: return None if isinstance(raw, np.ndarray) and raw.size == 1: raw = raw.reshape(-1)[0] text = raw.decode(errors="replace") if isinstance(raw, bytes) else str(raw) return text.strip() def _check_metallicity_axis(f, filename: str, stem: str, *, has_alpha_axis: bool) -> None: """Refuse a fixed-[Fe/H] SSP file; accept a fixed total-Z one (#3411). tengri holds every metallicity node at fixed total Z. A file whose ``metallicity_axis`` attribute begins with "feh" sits on a fixed-[Fe/H] axis, where the same ``met_logzsol`` means a different total metallicity, so it is refused with a pointer to the ``<stem>_totalz.h5`` variant rather than converted here. A 4-D file with no attribute is loaded as total Z and says so once. """ axis = _read_metallicity_axis(f.attrs) if axis is None: if has_alpha_axis: warnings.warn( f"'{filename}' is an [alpha/Fe] grid with no 'metallicity_axis' " "attribute: its metallicity nodes are assumed to be fixed total Z, " "the convention of every grid tengri builds. Set the attribute to " "'total Z' to silence this.", MetallicityAxisAssumedWarning, stacklevel=3, ) return lowered = axis.lower() if lowered.startswith(("feh", "[fe/h]", "fe/h")): raise TengriIOError( f"SSP file '{filename}' is on a fixed-[Fe/H] metallicity axis " f"(metallicity_axis={axis!r}). tengri uses fixed total metallicity " "for every grid, so this file cannot be loaded as it is. Use the " f"hosted total-Z variant '{stem}_totalz.h5' instead, available from " "tengri.download_ssp() and the ssp-spectra page." ) if lowered.startswith("total z"): return raise TengriIOError( f"SSP file '{filename}' has an unrecognized metallicity_axis={axis!r}. " "tengri accepts 'total Z' (fixed total metallicity) and refuses " "fixed-[Fe/H] axes ('feh...'); no other value is loaded." ) def _check_alpha_grid_layout(f, filename: str) -> None: """Refuse an SSP file whose [alpha/Fe] axis disagrees with its flux shape. A 4-D ``ssp_flux`` must come with ``ssp_alpha_fe`` and a 3-D one must not carry it. The four axes must match the flux shape, and ``ssp_alpha_fe`` (1-D) and ``ssp_lgmet`` must be strictly ascending, because the interpolation bins on them. Only dataset shapes and small 1-D axes are read here, so the flux array is not loaded. """ flux_ds = f["ssp_flux"] has_alpha = "ssp_alpha_fe" in f if (flux_ds.ndim == 4) != has_alpha: raise TengriIOError( f"SSP file '{filename}': ssp_flux has {flux_ds.ndim} dimension(s) " f"{tuple(flux_ds.shape)} but ssp_alpha_fe is " f"{'present' if has_alpha else 'absent'}. A 4-D flux " "(n_met, n_alpha, n_age, n_wave) requires ssp_alpha_fe, and a 3-D " "flux (n_met, n_age, n_wave) must not carry it." ) if not has_alpha: return alpha_fe = np.asarray(f["ssp_alpha_fe"][:]) lgmet = np.asarray(f["ssp_lgmet"][:]) if alpha_fe.ndim != 1: raise TengriIOError( f"SSP file '{filename}': ssp_alpha_fe must be 1-D, got shape {alpha_fe.shape}." ) for name, axis in (("ssp_alpha_fe", alpha_fe), ("ssp_lgmet", lgmet)): if not np.all(np.diff(axis) > 0): raise TengriIOError( f"SSP file '{filename}': {name} must be strictly ascending, got " f"{np.asarray(axis).tolist()}." ) n_met, n_alpha, n_age, _ = flux_ds.shape expected = (lgmet.shape[0], alpha_fe.shape[0], f["ssp_lg_age_gyr"].shape[0]) if (n_met, n_alpha, n_age) != expected or flux_ds.shape[3] != f["ssp_wave"].shape[0]: raise TengriIOError( f"SSP file '{filename}': ssp_flux shape {tuple(flux_ds.shape)} does not " f"match its axes (n_met={expected[0]} from ssp_lgmet, " f"n_alpha={expected[1]} from ssp_alpha_fe, n_age={expected[2]} from " f"ssp_lg_age_gyr, n_wave={f['ssp_wave'].shape[0]} from ssp_wave); " "expected (n_met, n_alpha, n_age, n_wave)." )
[docs] def load_ssp_data( filepath: str, *, dtype=None, download: bool = False, mass_remaining: str = "table", top_z: str = "clip", imf: str | None = None, ) -> SSPData: """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 :mod:`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 ------- SSPData Loaded SSP container with all template data and metadata; ``mass_remaining_source`` records where the surviving mass came from. 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 :func:`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 :func:`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 :func:`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: .. code-block:: text 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") # doctest: +SKIP >>> print(ssp.ssp_wave.shape, ssp.ssp_flux.shape) # doctest: +SKIP (6000,) (50, 300, 6000) >>> import jax.numpy as jnp >>> ssp32 = load_ssp_data("data/ssp_bc03.h5", dtype=jnp.float32) # doctest: +SKIP >>> ssp32.ssp_flux.dtype # doctest: +SKIP dtype('float32') """ try: import h5py except ImportError: raise ImportError("h5py required for SSP loading: pip install h5py") from None import os import warnings from pathlib import Path from tengri._data_setup import TENGRI_DATA_ENV, catalog_short_name fp = Path(filepath) short = catalog_short_name(fp.name) in_catalog = short is not None if not fp.exists() and download and in_catalog: # Must run BEFORE the existence check below: #1015 placed the raise # first, which silently made this branch unreachable. Gated on # ``download`` since v0.9: the match is on the basename only, so an # unconditional fetch answers a wrong *directory* by writing the grid # into it (#1548). from tengri._data_setup import download_ssp print(f"[tengri] {fp} not found: fetching '{short}' from public catalog...") download_ssp(short, dest=fp.parent if fp.parent != Path("") else "data") if not os.path.isfile(filepath): if in_catalog: remedy = ( f"The catalog ships {fp.name!r}, so this is recoverable: " f"tengri.load_ssp() finds it in any ancestor data/ directory with no " f"network call, and load_ssp_data(..., download=True) fetches it into " f"{fp.parent if fp.parent != Path('') else Path('data')}/. " ) else: remedy = ( f"{fp.name!r} is not in the download catalog, so fetching this path " "cannot help. tengri.list_known_ssps() shows the grids " "tengri.download_ssp() can retrieve; locally generated grids (ssp_*, " "including the wNE variants) must already be on disk. " ) raise FileNotFoundError( f"SSP file not found: '{filepath}'. {remedy}" f"Already have grids elsewhere? Point ${TENGRI_DATA_ENV} at that directory." ) explicit_imf = _normalize_imf_argument(imf) with h5py.File(filepath, "r") as f: ssp_lg_age_gyr = _load_float(f["ssp_lg_age_gyr"], dtype=dtype) ssp_lgmet = _load_float(f["ssp_lgmet"], dtype=dtype) _check_alpha_grid_layout(f, fp.name) _check_metallicity_axis(f, fp.name, fp.stem, has_alpha_axis="ssp_alpha_fe" in f) # IMF discovery (#307, #3285): the ``imf=`` argument wins, then the HDF5 # attribute, then the filename tail. Surfaced as ``ssp.imf`` so model # spec / summary / gallery plots can introspect the assumed IMF without # grepping the filename. Resolved before ``ssp_mass_remaining`` so the # surviving-mass synthesizer can pick the right DSPS calibration. imf = explicit_imf if explicit_imf is not None else _detect_imf(f, fp.name) # Nebular provenance (#1014): the ``nebular_included`` HDF5 # attribute wins, else the ``wNE`` filename convention. A wNE grid # that retains its ionizing continuum passes every Q_H sanity check # downstream while silently double-counting nebular emission under # the Cue / CloudyGrid backends, so classify it here and surface it # as ``ssp.nebular`` for the backends to act on. nebular = _detect_nebular(f, fp.name) if nebular == "included": warnings.warn( f"'{fp.name}' is a wNE (with-Nebular-Emission) SSP: nebular " "continuum and lines are already baked into the templates " "at fixed logU/logZ_gas. Pair it with the default baked-in " "nebular backend only: adding neb={'type': 'cue'} or a " "CLOUDY grid on top double-counts nebular emission.", UserWarning, stacklevel=2, ) # Solar-luminosity unit contract (#969): ``ssp_flux`` is stored in # "Lsun/Hz per Msun", but WHICH Lsun depends on the code that wrote # the file: the repackaged ``fsps_*`` catalog grids carry FSPS's # native numbers (Lsun = 3.839e33 erg/s, ``sps_vars.f90``), while # tengri converts to erg/s with the IAU 2015 value (3.828e33), a # flat 0.29 % absolute-flux offset. Rescale on load so the # in-memory arrays are IAU-Lsun-normalized and every downstream # conversion is exact. # Known single-cell grid defects (#3406) are repaired in float64 from the age # neighbors before the working-precision cast: a float32 cast underflows the wNE # grid's ~1e-70 neighbor flux to zero. The repair commutes with the unit rescale. flux_raw, repaired_cells = repair_known_grid_defects( fp.stem, f["ssp_flux"][:], ssp_lgmet, ssp_lg_age_gyr ) ssp_flux = jnp.asarray( flux_raw, dtype=dtype if dtype is not None else jnp.result_type(float) ) native_lsun = _detect_native_lsun(f, fp.name) if native_lsun is not None: from tengri.utils.physics_constants import L_SUN if abs(native_lsun / L_SUN - 1.0) > 1e-12: # Python-float scalar keeps ssp_flux's dtype under JAX weak typing. ssp_flux = ssp_flux * (native_lsun / L_SUN) embedded = np.asarray(f["ssp_mass_remaining"][:]) if "ssp_mass_remaining" in f else None resolution = resolve_mass_remaining( stem=fp.stem, detected_imf=imf, lg_age_gyr=np.asarray(ssp_lg_age_gyr, dtype=np.float64), lgmet=np.asarray(ssp_lgmet, dtype=np.float64), embedded=embedded, has_alpha_axis="ssp_alpha_fe" in f, synthetic=bool(f.attrs.get("synthetic", False)), mode=mass_remaining, ) target = dtype if dtype is not None else jnp.result_type(float) if resolution.table is not None: mass_table = jnp.asarray(resolution.table, dtype=target) else: mass_table = jnp.asarray( _synthesize_mass_remaining( filepath, ssp_lg_age_gyr, ssp_lgmet, imf_tag=resolution.fit_imf ), dtype=target, ) alpha_fe = None if "ssp_alpha_fe" in f: alpha_fe = _load_float(f["ssp_alpha_fe"], dtype=dtype) # The alpha-dependent surviving-mass table (#2250) is read only when the grid's own # (n_met, n_age) table was used: a synthesized ``dsps_fit`` table has no alpha dependence. mass_remaining_alpha = None if ( alpha_fe is not None and "ssp_mass_remaining_alpha" in f and resolution.table is not None ): mass_remaining_alpha = _load_float(f["ssp_mass_remaining_alpha"], dtype=dtype) _check_alpha_mass_remaining( mass_remaining_alpha, fp.name, alpha_nodes=np.asarray(alpha_fe), lgmet=np.asarray(ssp_lgmet), n_age=ssp_lg_age_gyr.shape[0], table_2d=np.asarray(mass_table, dtype=np.float64), ) ssp_wave = _load_float(f["ssp_wave"], dtype=dtype) top_z_validity = None if alpha_fe is None: ssp_flux, mass_table, ssp_lgmet, top_z_validity = _apply_top_z( stem=fp.stem, policy=top_z, synthetic=bool(f.attrs.get("synthetic", False)), ssp_wave=ssp_wave, ssp_flux=ssp_flux, mass_table=mass_table, ssp_lg_age_gyr=ssp_lg_age_gyr, ssp_lgmet=ssp_lgmet, native_lsun=native_lsun, ) # Per-wavelength library resolution (#2518): match the library token # in the filename to the FSPS-derived reference table and read off # the library's own per-node velocity dispersion, but ONLY when # ``ssp_wave`` actually is that library's reference grid: the # filename token alone is not sufficient (a grid built from a # different library on a wavelength axis that happens to echo # another library's name -- e.g. a BPASS grid whose filename # contains the C3K token -- must not receive that library's # curve). No warning here when the library has no reference table # or its wavelength grid does not match: a missing curve is simply # "no correction", and every grid passes through this function # regardless of whether it will ever be used spectroscopically. # The correctly-scoped warning is at ``SEDModel`` build time # (``_init_instrument``), which fires only when the model actually # configures spectroscopy and falls back to the flat # ``sigma_lib_kms`` scalar, naming the grid. library_stem = fp.stem library_key = _detect_library_resolution_key(library_stem) if library_key is not None and _wave_matches_reference( np.asarray(ssp_wave, dtype=float), _load_library_resolution_reference(library_key)[0] ): ssp_resolution_kms, _ = _resolve_ssp_resolution(ssp_wave, library_key) else: ssp_resolution_kms = None caveat = GRID_CAVEATS.get(canonical_grid_name(fp.stem)) if caveat is not None: warnings.warn(caveat, UserWarning, stacklevel=2) return SSPData( ssp_wave=ssp_wave, ssp_flux=ssp_flux, ssp_lg_age_gyr=ssp_lg_age_gyr, ssp_lgmet=ssp_lgmet, ssp_mass_remaining=mass_table, ssp_alpha_fe=alpha_fe, ssp_resolution_kms=ssp_resolution_kms, imf=imf, source=fp.stem, nebular=nebular, mass_remaining_source=resolution.source, top_z=top_z_validity, grid_notes=(caveat,) if caveat is not None else (), repaired_cells=repaired_cells, ssp_mass_remaining_alpha=mass_remaining_alpha, )
def _check_alpha_mass_remaining( table, filename: str, *, alpha_nodes: np.ndarray, lgmet: np.ndarray, n_age: int, table_2d: np.ndarray, atol: float = 1e-6, ) -> None: """Refuse an embedded [alpha/Fe] surviving-mass table that does not fit its grid (#2250). The table must be (n_met, n_alpha, n_age). When the alpha = 0 node is on the grid, its plane must equal the file's (n_met, n_age) table to ``atol``, since two tables that disagree would make the surviving mass depend on which one is read. """ expected = (lgmet.shape[0], alpha_nodes.shape[0], n_age) if tuple(table.shape) != expected: raise TengriIOError( f"SSP file {filename}: 'ssp_mass_remaining_alpha' has shape {tuple(table.shape)}, " f"expected (n_met, n_alpha, n_age) = {expected}." ) zero_nodes = np.flatnonzero(np.isclose(alpha_nodes, 0.0, rtol=0.0, atol=1e-12)) if zero_nodes.size == 0: return plane = np.asarray(table[:, int(zero_nodes[0]), :], dtype=np.float64) if not np.allclose(plane, table_2d, rtol=0.0, atol=atol): raise TengriIOError( f"SSP file {filename}: the alpha = 0 plane of 'ssp_mass_remaining_alpha' and the " f"(n_met, n_age) 'ssp_mass_remaining' table disagree by more than {atol:g}. The two " "tables must describe the same grid." ) def _apply_top_z( *, stem, policy, synthetic, ssp_wave, ssp_flux, mass_table, ssp_lg_age_gyr, ssp_lgmet, native_lsun, ): """Run :func:`apply_top_z_policy` on loaded JAX arrays and cast back to their dtypes.""" from tengri.components.stellar.sps.mass_remaining_tables import ( MASS_REMAINING_REGISTRY, canonical_grid_name, ) from tengri.components.stellar.sps.top_z_validity import TOP_Z_MODES, apply_top_z_policy from tengri.utils.physics_constants import L_SUN if policy not in TOP_Z_MODES: raise ValueError(f"top_z must be one of {TOP_Z_MODES}, got {policy!r}") entry = None if synthetic else MASS_REMAINING_REGISTRY.get(canonical_grid_name(stem)) flux_scale = 1.0 if native_lsun is None else native_lsun / L_SUN flux, mass, lgmet, validity = apply_top_z_policy( stem=stem, isoc=None if entry is None else entry.isoc, policy=policy, wave=np.asarray(ssp_wave, dtype=np.float64), lg_age_yr=np.asarray(ssp_lg_age_gyr, dtype=np.float64) + 9.0, lgmet=np.asarray(ssp_lgmet, dtype=np.float64), flux=np.asarray(ssp_flux, dtype=np.float64), mass=np.asarray(mass_table, dtype=np.float64), flux_scale=flux_scale, ) if validity is None or (policy == "raw"): return ssp_flux, mass_table, ssp_lgmet, validity return ( jnp.asarray(flux, dtype=ssp_flux.dtype), jnp.asarray(mass, dtype=mass_table.dtype), jnp.asarray(lgmet, dtype=ssp_lgmet.dtype), validity, ) #: FSPS's internal solar luminosity (``sps_vars.f90``, ``lsun = 3.839d33``) #: [erg/s]. The repackaged ``fsps_*`` catalog grids store flux in units of #: this Lsun: verified by the reproduction notebook's §1 bit-match of the #: raw HDF5 values against live ``python-fsps`` output (#969). _FSPS_LSUN_ERG_PER_S: float = 3.839e33 def _detect_native_lsun(h5_file, filename: str) -> float | None: """Solar-luminosity constant the SSP file's flux units are based on (#969). Resolution order (mirrors :func:`_detect_imf`): 1. ``h5_file.attrs["lsun_erg_per_s"]``: the explicit unit contract; components should write this going forward. 2. Filename prefix ``fsps_`` → FSPS's native 3.839e33 erg/s (the published catalog grids store FSPS's raw numbers; §1 of the Prospector reproduction pins this bit-exactly). 3. ``None``: unknown provenance; the loader assumes the file is already IAU-normalized and applies no rescale. Guessing a wrong constant is worse than a documented 0.3 %-scale uncertainty. Parameters ---------- h5_file : h5py.File Open HDF5 handle (for the attribute lookup). filename : str Basename of the file (for the catalog-prefix fallback). Returns ------- float or None The file's native Lsun [erg/s], or ``None`` when unknown. """ attr = h5_file.attrs.get("lsun_erg_per_s") if hasattr(h5_file, "attrs") else None if attr is not None: return float(attr) if filename.startswith("fsps_"): return _FSPS_LSUN_ERG_PER_S return None #: IMFs that ship in the public SSP catalog. Parsed out of HDF5 metadata #: or filename tails. Extend when a new IMF lands in ``_data_setup._KNOWN_SSPS``. _KNOWN_IMFS: tuple[str, ...] = ("chabrier", "kroupa", "salpeter") def _normalize_imf_argument(imf: str | None) -> str | None: """Normalize the ``imf=`` argument of :func:`load_ssp_data` (#3285). Parameters ---------- imf : str or None The caller's IMF label; ``None`` means not given. Returns ------- str or None The label stripped and lower-cased, or ``None`` when not given. Raises ------ ValueError The label is an empty string (after stripping). """ if imf is None: return None label = imf.strip().lower() if not label: raise ValueError("imf must name the IMF, got an empty string") return label def _detect_imf(h5_file, filename: str) -> str: """Detect the IMF an SSP grid was computed under (#307). Resolution order: 1. ``h5_file.attrs["imf"]`` (when SSP files start shipping the metadata). 2. Filename tail matched against :data:`_KNOWN_IMFS`, e.g. ``"fsps_prsc_miles_chabrier.h5"`` → ``"chabrier"``. 3. Fallback: ``"unknown"``. Falsely returning a wrong IMF is worse than returning ``"unknown"``, so the filename match requires an exact ``_<imf>`` token, not a substring (avoids ``"_kroupa_burst"`` → ``"kroupa"`` if someone appends qualifiers). """ attr_imf = h5_file.attrs.get("imf") if hasattr(h5_file, "attrs") else None if attr_imf: # h5py returns ``bytes`` on Python 3 for string attrs from older files. if isinstance(attr_imf, bytes): attr_imf = attr_imf.decode("utf-8", errors="replace") return str(attr_imf).strip().lower() stem = filename.rsplit(".h5", 1)[0] tokens = stem.split("_") for tok in reversed(tokens): low = tok.lower() if low in _KNOWN_IMFS: return low return "unknown" def _detect_nebular(h5_file, filename: str) -> str: """Classify a grid's nebular provenance: ``"included"``/``"bare"``/``"unknown"`` (#1014). Resolution order: 1. ``h5_file.attrs["nebular_included"]``: written at generation time or stamped onto existing files with ``tools/stamp_ssp_nebular_attrs.py``. An explicit ``False`` classifies the grid as ``"bare"`` even when the filename says wNE (the attribute is authoritative). 2. ``wNE`` filename convention → ``"included"``. 3. Fallback: ``"unknown"``; absence of the marker cannot prove the grid is bare, and no Q_H heuristic can either: a retained-LyC wNE grid measures young-bin log Q_H identical to its bare parent. """ attrs = h5_file.attrs if hasattr(h5_file, "attrs") else {} if "nebular_included" in attrs: return "included" if bool(attrs["nebular_included"]) else "bare" if "wne" in filename.lower(): return "included" return "unknown" #: Spectral-library resolution reference tables (#2518): maps the library #: token in a filename to the package-data file holding FSPS's own per-node #: velocity dispersion for that library (see #: ``src/tengri/data/ssp_library_resolution/PROVENANCE.md`` for source and #: format). ``load_ssp_data`` looks this token up against #: ``<code>_<isochrone>_<library>_<imf>`` (the download catalog's #: ``fsps_<isochrone>_<library>_<imf>.h5``, ``_data_setup._KNOWN_SSPS``, and #: the locally generated ``..._wNE_logGasU<...>_logGasZ<...>`` variants both #: carry this token). A library absent here has no reference resolution #: (``ssp_resolution_kms`` stays ``None``; the flat ``sigma_lib_kms`` scalar #: is the fallback). _LIBRARY_RESOLUTION_DATA_FILES: dict[str, str] = { "miles": "miles.dat", "c3k_a": "c3k_afe0.0.dat", "c3k_hr": "c3k_hr.dat", "c3k_lr": "c3k_lr.dat", } def _detect_library_resolution_key(filename_stem: str) -> str | None: """Match a filename's spectral-library token to a resolution table key. Splits ``filename_stem`` on ``_`` and checks every contiguous token window (two-token windows first, so ``"c3k_a"`` is preferred over the single-token ``"c3k"`` it contains) against :data:`_LIBRARY_RESOLUTION_DATA_FILES`. Parameters ---------- filename_stem : str SSP HDF5 filename without the ``.h5`` extension. Returns ------- str or None Key into :data:`_LIBRARY_RESOLUTION_DATA_FILES`, or ``None`` if no token matches. """ tokens = filename_stem.split("_") for width in (2, 1): for i in range(len(tokens) - width + 1): candidate = "_".join(tokens[i : i + width]) if candidate in _LIBRARY_RESOLUTION_DATA_FILES: return candidate return None @cache def _load_library_resolution_reference(library_key: str) -> tuple[np.ndarray, np.ndarray]: """Load a library's reference resolution table from package data. Parameters ---------- library_key : str Key into :data:`_LIBRARY_RESOLUTION_DATA_FILES`. Returns ------- wave_aa : ndarray, shape (n_ref,) Reference rest-frame wavelength grid [Angstrom]. sigma_kms_signed : ndarray, shape (n_ref,) Velocity dispersion [km/s], FSPS's own sign convention: positive where the library's own template measurement sets the value, negative where it is FSPS's approximate extrapolation. """ from importlib.resources import files path = ( files("tengri.data.ssp_library_resolution") / _LIBRARY_RESOLUTION_DATA_FILES[library_key] ) with path.open("r") as fh: arr = np.loadtxt(fh) return arr[:, 0], arr[:, 1] def _wave_matches_reference(query_wave: np.ndarray, ref_wave: np.ndarray) -> bool: """Whether ``query_wave`` is a library's own reference wavelength grid. Requires the same node count and every node equal to ``rtol=1e-6``: a grid built by evolving the same library's templates on a different (e.g. resampled or truncated) wavelength axis has the library's own filename token but is not the grid the resolution table was measured on, and must not be treated as if it were. Parameters ---------- query_wave, ref_wave : ndarray Wavelength grids to compare [Angstrom]. Returns ------- bool """ return query_wave.shape == ref_wave.shape and bool( np.allclose(query_wave, ref_wave, rtol=1e-6, atol=0.0) ) def _resolve_ssp_resolution( ssp_wave: jnp.ndarray, library_key: str ) -> tuple[jnp.ndarray, np.ndarray]: """Per-wavelength library resolution [km/s] and its approximate mask (#2518). Reads FSPS's own per-node velocity dispersion for ``library_key`` directly when ``ssp_wave`` matches the reference grid node for node (every shipped ``fsps_*.h5`` catalog grid), otherwise interpolates log-linearly in (wavelength, sigma) onto ``ssp_wave``. Interpolation never blends across a sign change in the reference table -- FSPS's own boundary between a library's measured window and an extrapolated wing -- a query bracketed by nodes of opposite sign is snapped to the nearer one instead of interpolated between them. A resolution-regime boundary that FSPS does not sign-flag (e.g. C3K's R=3000-to-R=500 step, both positive) is not detected this way; a query landing within one reference node-spacing of such a boundary is smoothly blended across it rather than snapped, a narrow interpolation artifact that does not arise for an ``ssp_wave`` matching the reference grid exactly. Parameters ---------- ssp_wave : array, shape (n_wave,) Rest-frame wavelength grid [Angstrom] to evaluate the curve on. library_key : str Key into :data:`_LIBRARY_RESOLUTION_DATA_FILES`. Returns ------- sigma_kms : ndarray, shape (n_wave,) Velocity dispersion [km/s], always positive. approximate : ndarray of bool, shape (n_wave,) ``True`` where the value is FSPS's approximate extrapolation rather than a direct library measurement. """ ref_wave, ref_sigma_signed = _load_library_resolution_reference(library_key) query_wave = np.asarray(ssp_wave, dtype=float) if _wave_matches_reference(query_wave, ref_wave): sigma = np.abs(ref_sigma_signed) approximate = ref_sigma_signed < 0.0 return jnp.asarray(sigma, dtype=jnp.result_type(float)), approximate ref_sign = np.sign(ref_sigma_signed) ref_log_wave = np.log(ref_wave) ref_log_sigma = np.log(np.abs(ref_sigma_signed)) n = ref_wave.size clipped_query = np.clip(query_wave, ref_wave[0], ref_wave[-1]) idx1 = np.clip(np.searchsorted(ref_wave, clipped_query), 1, n - 1) idx0 = idx1 - 1 same_regime = ref_sign[idx0] == ref_sign[idx1] w0, w1 = ref_log_wave[idx0], ref_log_wave[idx1] s0, s1 = ref_log_sigma[idx0], ref_log_sigma[idx1] query_log_wave = np.log(clipped_query) span = np.where(w1 > w0, w1 - w0, 1.0) t = (query_log_wave - w0) / span interp_log_sigma = s0 + t * (s1 - s0) nearer = np.where( np.abs(clipped_query - ref_wave[idx0]) <= np.abs(ref_wave[idx1] - clipped_query), idx0, idx1, ) out_log_sigma = np.where(same_regime, interp_log_sigma, ref_log_sigma[nearer]) out_sign = np.where(same_regime, ref_sign[idx0], ref_sign[nearer]) sigma = np.exp(out_log_sigma) approximate = out_sign < 0.0 return jnp.asarray(sigma, dtype=jnp.result_type(float)), approximate def _synthesize_mass_remaining( filepath, ssp_lg_age_gyr: jnp.ndarray, ssp_lgmet: jnp.ndarray, imf_tag=None ) -> jnp.ndarray: """Evaluate the DSPS surviving-mass fit; reached only through the explicit opt-in. The fit has no [alpha/Fe] dependence, so an alpha grid gets no ``ssp_mass_remaining_alpha``. Uses :func:`dsps.imf.surviving_mstar.surviving_mstar`, a 9-parameter sigmoid fit to FSPS with shipped per-IMF calibrations (Chabrier, Salpeter, Kroupa, van Dokkum). This is the same fallback diffsky and other DSPS-stack codes use, so tengri's reported surviving masses stay bit-aligned with that ecosystem. Resolves the IMF via :func:`_detect_imf` (HDF5 attribute → filename tail → ``"unknown"``). When the IMF is ``"unknown"`` or absent, falls back to Chabrier with a one-shot ``UserWarning`` naming the file and convention. The DSPS sigmoid agrees with FSPS to 1–2 % including at young ages, where the IMF-turnoff integrator in :mod:`tengri.components.stellar.sps.mass_remaining` undercounts mass return by missing MS/post-MS stellar-wind losses (e.g. 0% vs 2-3% at 1 Myr). Returns ------- array, shape (n_met, n_age) Surviving mass fraction broadcast over the metallicity axis (metallicity dependence is dropped here by design; a grid table (embedded or companion, :func:`resolve_mass_remaining`) is what carries it). """ import warnings _IMF_PARAMS = fit_imf_params() with hold_x64_preference(): from dsps.imf.surviving_mstar import surviving_mstar if isinstance(imf_tag, bytes): imf_tag = imf_tag.decode("utf-8", errors="replace") imf = (imf_tag or "unknown").strip().lower() params = _IMF_PARAMS.get(imf, _IMF_PARAMS["chabrier"]) if imf not in _IMF_PARAMS: warnings.warn( f"SSP file {filepath!s} has no 'ssp_mass_remaining' table and " f"IMF could not be resolved (got {imf!r}); synthesizing " "surviving-mass fractions from dsps.imf.surviving_mstar with " "the Chabrier-fit-to-FSPS parameters. Set the 'imf' HDF5 " "attribute or use a filename suffix matching _detect_imf's " "_KNOWN_IMFS to silence, or integrate the upstream table for a " "bit-exact match.", UserWarning, stacklevel=3, ) # surviving_mstar takes log10(age/yr): ssp_lg_age_gyr is log10(age/Gyr). # Age-0 anchor templates (#1016): lg_age = -inf (bc03 stelib) makes the # DSPS sigmoid chain emit NaN, and one NaN entry poisons every # surviving-mass sum downstream (log_mstar = NaN) regardless of the # anchor's weight. No star has died at age 0, so floor the age at # 0.1 Myr where f_surv = 1 to DSPS's own fit accuracy; a no-op for # grids whose youngest template is already >= 0.1 Myr. The floor is the # one constant the nebular Q_H axes also read (#2418). lg_age_yr = jnp.maximum(ssp_lg_age_gyr + 9.0, ZERO_AGE_ANCHOR_FLOOR_LG_AGE_YR) f_surv_age = surviving_mstar(lg_age_yr, **params) return jnp.broadcast_to(f_surv_age, (ssp_lgmet.shape[0], lg_age_yr.shape[0])) def _csp_age_dt_trapz_numpy(a: np.ndarray) -> np.ndarray: """Numpy twin of the linear-age trapz bin widths (IEEE-exact ops only).""" half = a.dtype.type(0.5) return np.concatenate( [ np.array([half * (a[1] - a[0])], dtype=a.dtype), half * (a[2:] - a[:-2]), np.array([half * (a[-1] - a[-2])], dtype=a.dtype), ] ) def csp_age_dt(ssp_ages_yr: jnp.ndarray, method: str = "trapz") -> jnp.ndarray: """Compute CSP quadrature bin widths for a given integration method. Both methods implement trapezoidal integration of the CSP integral ∫ SFR(t) dt, but differ in the quadrature variable: ``"trapz"`` is the standard trapezoidal rule in **linear age**: dt_i = 0.5 * (t_{i+1} - t_{i-1}) [interior] dt_0 = 0.5 * (t_1 - t_0) [left endpoint] dt_N = 0.5 * (t_N - t_{N-1}) [right endpoint] ``"log_trapz"`` is the trapezoidal rule in **log₁₀-age** with Jacobian: dt_i = t_i * ln(10) * d(log₁₀ t)_i where d(log₁₀ t)_i are the half-widths in log₁₀-age space. This is equivalent to the substitution x = log₁₀(t), dt = t·ln(10)·dx (Johnson et al. 2021, Appendix B). For log-spaced SSP grids (equal Δ(log₁₀ t) per bin), this achieves uniform quadrature accuracy across all ages, while linear trapz over-resolves old stars and under-resolves young stars. Parameters ---------- ssp_ages_yr : array, shape (n_age,) SSP ages in years [yr], sorted ascending. method : {"trapz", "log_trapz"} Integration scheme. Default ``"trapz"`` matches DSPS. Returns ------- array, shape (n_age,) Effective linear-age bin widths [yr]. Multiply by SFR [Msun/yr] to get mass formed per bin [Msun]. Notes ----- **JIT-compatible**: yes, all operations use ``jnp`` primitives. **Gradient-safe**: yes. References ---------- .. [1] C. Johnson et al., "Prospector: Bayesian Stellar Population Inference with Separable Star Formation Histories," ApJ, 927, 74 (2021). https://doi.org/10.3847/1538-4357/ac4867 """ if method == "trapz": ages_np = concrete_canonical_numpy(ssp_ages_yr) if ages_np is not None: # Build-time path: IEEE-exact host arithmetic, no eager micro-compiles. return jnp.asarray(_csp_age_dt_trapz_numpy(ages_np)) return jnp.concatenate( [ jnp.array([0.5 * (ssp_ages_yr[1] - ssp_ages_yr[0])]), 0.5 * (ssp_ages_yr[2:] - ssp_ages_yr[:-2]), jnp.array([0.5 * (ssp_ages_yr[-1] - ssp_ages_yr[-2])]), ] ) elif method == "log_trapz": log10_ages = jnp.log10(ssp_ages_yr) d_log10 = jnp.concatenate( [ jnp.array([0.5 * (log10_ages[1] - log10_ages[0])]), 0.5 * (log10_ages[2:] - log10_ages[:-2]), jnp.array([0.5 * (log10_ages[-1] - log10_ages[-2])]), ] ) return ssp_ages_yr * jnp.log(10.0) * d_log10 else: raise ValueError( f"Unknown CSP integration method: {method!r}. " "Valid options: 'trapz', 'log_trapz', 'log_interp'." ) def csp_log_interp_matrix(ssp_ages_yr, n_gl: int = 5): """Johnson+2021 log-linear SSP interpolation weight matrix. Returns an N×N matrix A such that ``m = A @ sfr`` gives the CSP mass weights when SSP spectra are interpolated **linearly in log(t)** between grid points and the SFR is assumed **piecewise-linear in t** between SSP ages (Johnson et al. 2021, ApJS 254, 22, Appendix B, Eq. B3). The CSP integral is approximated as: F_λ = ∫ SFR(t) · S_λ(t) dt ≈ Σ_j m_j · S_λ(t_j) where S_λ(t) between grid points is the log-linear interpolant: S_λ(t) = a_j(t)·S_λ(t_j) + b_{j+1}(t)·S_λ(t_{j+1}), t ∈ [t_j, t_{j+1}] a_j(t) = (log t_{j+1} − log t) / (log t_{j+1} − log t_j) [falls 1→0] b_{j+1}(t) = (log t − log t_j) / (log t_{j+1} − log t_j) [rises 0→1] Substituting a piecewise-linear SFR and integrating each interval gives: m_j = Σ_{intervals touching j} ∫ SFR(t) · φ_j(t) dt where φ_j is the hat basis function (a_j on the right interval, b_j on the left). This is computed via 5-point Gauss-Legendre quadrature per interval, exact for polynomials up to degree 9. The returned matrix is symmetric tridiagonal: - A[j, j-1] = contribution from left interval via b_j - A[j, j] = sum of right-interval a_j and left-interval b_j contributions - A[j, j+1] = contribution from right interval via a_j (symmetric) Parameters ---------- ssp_ages_yr : array-like, shape (n_age,) SSP ages in years [yr], sorted ascending. n_gl : int, optional Number of Gauss-Legendre quadrature points per interval. Default 5 (exact for degree-9 polynomials; more than sufficient). Returns ------- ndarray, shape (n_age, n_age) Weight matrix A (dimensionless, evaluated in years). Use as ``weights = A @ sfr_on_ssp`` to integrate the CSP. Notes ----- **JIT-compatible**: no, uses numpy and does not support traced evaluation. Precompute the matrix at startup or outside JAX functions. **Gradient-safe**: not applicable (CPU-only computation). """ import numpy as np ages = np.asarray(ssp_ages_yr, dtype=float) N = len(ages) A = np.zeros((N, N)) # 5-point Gauss-Legendre nodes on [-1,1], mapped to [0,1] xi, wi = np.polynomial.legendre.leggauss(n_gl) p_nodes = (xi + 1.0) / 2.0 # in [0, 1] p_weights = wi / 2.0 # sum = 1 for j in range(N - 1): t_lo, t_hi = ages[j], ages[j + 1] delta_t = t_hi - t_lo delta_u = np.log10(t_hi) - np.log10(t_lo) # always > 0 # Quadrature points in linear t t_q = t_lo + p_nodes * delta_t # Log-linear basis functions at quadrature points a_j = (np.log10(t_hi) - np.log10(t_q)) / delta_u # falls 1→0 b_j1 = 1.0 - a_j # rises 0→1 # SFR(t_q) = SFR_j*(1-p) + SFR_{j+1}*p (piecewise-linear in t) # Contribution to m_j (integrate SFR · a_j dt over [t_j, t_{j+1}]): A[j, j] += delta_t * np.dot(p_weights, (1.0 - p_nodes) * a_j) A[j, j + 1] += delta_t * np.dot(p_weights, p_nodes * a_j) # Contribution to m_{j+1} (integrate SFR · b_{j+1} dt): A[j + 1, j] += delta_t * np.dot(p_weights, (1.0 - p_nodes) * b_j1) A[j + 1, j + 1] += delta_t * np.dot(p_weights, p_nodes * b_j1) return A def enforce_increasing_cosmic_time(t_cosmic_asc: jnp.ndarray) -> jnp.ndarray: r"""Project an ascending cosmic-time table to *strictly* increasing. DSPS' SFH-table kernels interpolate on ``gal_t_table`` and return NaN when the knots are non-monotone or duplicated. At high observation redshift the youngest valid cosmic-time bins can fall below ``T_TABLE_MIN`` and clamp to the same floor as the cosmically-invalid ramp, so the table dips below the ramp and DSPS NaNs the whole weight tensor (the invalid-bin ramp alone does not cover boundary-valid bins). Uses a subtract-ramp / cumulative-maximum / add-ramp projection: it removes any inversion or tie while staying an *exact* no-op for tables that already increase by more than ``eps`` per step (the normal low-z case); then ``t - ramp`` is still increasing, ``cummax`` is the identity, and adding ``ramp`` back recovers the input bit-for-bit. Parameters ---------- t_cosmic_asc : array_like, shape (n_age,) Cosmic-time knots [Gyr], ascending. Returns ------- ndarray, shape (n_age,) Strictly-increasing cosmic-time knots [Gyr]. Notes ----- **JIT-compatible**: yes. **Differentiable**: yes. The ``eps`` step (1e-6 Gyr = 1000 yr) is far below the smallest SSP age-grid spacing, so the perturbation to genuinely-clamped bins is negligible. References ---------- .. [1] suchethac/tengri#683; SFH age weights NaN at high redshift. """ eps = 0.01 * 1e-4 # 1e-6 Gyr (1000 yr); far below any SSP age step ramp = jnp.arange(t_cosmic_asc.shape[0]) * eps return jnp.maximum.accumulate(t_cosmic_asc - ramp) + ramp def _dsps_kernel_scatter(lgmet_scatter): """Scatter passed to the DSPS kernel: the declared value, else a finite nominal. An undeclared scatter (``None`` or zero) is replaced so DSPS never sees a zero bandwidth. Its kernel output is then discarded in favor of the node-exact read. """ scatter = _scatter_value(lgmet_scatter) return jnp.where(scatter > 0.0, scatter, _NOMINAL_LGMET_SCATTER) def _native_joint(dsps_joint, lgmet, lgmet_scatter, ssp_lgmet): """Joint (n_met, n_age) weights of the DSPS-native kernel, normalized to 1. Declared: DSPS's joint as is. Undeclared: the PCHIP metallicity surrogate for ``lgmet`` times DSPS's age marginal (#3434; :func:`met_weights`). """ declared = _scatter_value(lgmet_scatter) > 0.0 age_marginal = dsps_joint.sum(axis=0) # Normalization that can only vanish if DSPS returned a degenerate joint: NaN # propagates to the output instead of a plausible finite zero (zero-hiding clamp # kind 3). The denominator is held at 1 on the dead branch so its gradient stays finite. total = age_marginal.sum() live = total > 1e-20 age_marginal = jnp.where(live, age_marginal / jnp.where(live, total, 1.0), jnp.nan) met_row = met_weights(jnp.asarray(lgmet), ssp_lgmet) node_exact = met_row[:, None] * age_marginal[None, :] return jnp.where(declared, dsps_joint, node_exact) def _met_table_weights(dsps_met_w, lgmet_on_ssp_ages, lgmet_scatter, ssp_lgmet): """Per-age metallicity weights (n_met, n_age), each column summing to 1. Declared: DSPS's per-age lognormal columns. Undeclared: the PCHIP metallicity surrogate at each age's own metallicity (#3434; :func:`met_weights`). """ declared = _scatter_value(lgmet_scatter) > 0.0 kernel_w = dsps_met_w / dsps_met_w.sum(axis=0, keepdims=True) node_exact = met_weights(lgmet_on_ssp_ages, ssp_lgmet) return jnp.where(declared, kernel_w, node_exact) def compute_dsps_native_weights( sfr_on_ssp_ages: jnp.ndarray, ssp_ages_yr: jnp.ndarray, ssp_lgmet: jnp.ndarray, ssp_lg_age_gyr: jnp.ndarray, ssp_flux: jnp.ndarray, t_obs_gyr: float, lgmet: float, lgmet_scatter: float | None = None, ) -> tuple: """Compute CSP age weights and metallicity-marginalized SSP flux via DSPS. **This is tengri's primary (recommended) CSP integration mode**, selected via ``SEDModel(..., csp_integration="dsps_native")``. Uses DSPS's triweight metallicity kernel (Hearin et al. 2023, Eq. 10) to convolve the stellar metallicity distribution with SSP templates, then integrates the SFH via DSPS's trapezoidal scheme on cosmic time. Age and metallicity integration are performed in a single DSPS call, eliminating the need for a separate :func:`compute_csp_weights` + ``interp_metallicity`` step. Unlike the trapezoidal quadrature modes (``trapz``, ``log_trapz``), this method computes the CSP on **cosmic** (not lookback) time, which avoids endpoint-weighting errors at young ages. The metallicity distribution is a lognormal (Gaussian in log10 Z) with scatter ``lgmet_scatter``, matching the Prospector/DSPS convention (Johnson et al. 2021). The resulting ``ssp_flux_at_z`` is already marginalized over the full metallicity PDF and flows into tengri's existing dust and AGN pipeline unchanged. Parameters ---------- sfr_on_ssp_ages : array, shape (n_age,) Star formation rate (Msun/yr) evaluated at each SSP lookback age, sorted **ascending by age** (youngest = index 0). ssp_ages_yr : array, shape (n_age,) SSP lookback ages in years (ascending). ssp_lgmet : array, shape (n_met,) log10(Z) metallicity grid of the SSP library (absolute, not Z/Zsun). ssp_lg_age_gyr : array, shape (n_age,) log10(age/Gyr) of SSP templates. ssp_flux : array, shape (n_met, n_age, n_wave) SSP spectra in Lsun/Hz/Msun. t_obs_gyr : float Age of the universe in Gyr at the observation redshift. Computed from tengri's cosmology (not DSPS's DEFAULT_COSMOLOGY). lgmet : float log10(Z) metallicity of the galaxy (absolute, same units as ssp_lgmet). lgmet_scatter : float, optional Gaussian scatter in log10(Z) (dex). ``None`` or zero is undeclared: the metallicity reads the SSP grid node-exactly (#3434). Default None. Returns ------- age_weights_msun : array, shape (n_age,) Mass formed per SSP age bin (Msun), sorted ascending by age. Sum = total stellar mass formed. Directly replaces the output of :func:`compute_csp_weights`. ssp_flux_at_z : array, shape (n_age, n_wave) SSP flux marginalized over the metallicity distribution (Lsun/Hz/Msun). Notes ----- SSP ages in tengri are **lookback times** (youngest = smallest). DSPS needs **cosmic times** sorted ascending. The conversion is:: t_cosmic_gyr = clip(t_obs_gyr - ssp_ages_yr / 1e9, min=1e-3) Reversal (youngest→oldest in tengri ↔ oldest→youngest in cosmic time) is handled internally; the returned ``age_weights_msun`` is sorted back to tengri's ascending-age convention. Requires ``dsps`` to be installed (``pip install dsps``). References ---------- Hearin et al. 2023, arXiv:2112.08423, Eq. 10 (triweight kernel). """ try: with hold_x64_preference(): from dsps.sed.stellar_sed import calc_rest_sed_sfh_table_lognormal_mdf except ImportError: raise ImportError( "dsps is required for csp_integration='dsps_native'. Install with: pip install dsps" ) from None # SSP ages are lookback times (young→old, ascending). # DSPS needs cosmic times (old→young = ascending cosmic time). # Reverse so that gal_t_table is sorted ascending for DSPS. ssp_age_gyr = ssp_ages_yr / 1e9 t_cosmic_raw = t_obs_gyr - ssp_age_gyr # may go ≤ 0 for SSP ages > t_obs # Mask out invalid bins (stars formed before the Big Bang). For # those bins, set SFR to zero so they contribute no mass to the # CSP integral. The cosmic-time array must be **strictly** # monotonic (no duplicates) AND every entry must satisfy # ``t >= T_TABLE_MIN = 0.01 Gyr`` for DSPS's internal # ``cumulative_mstar_formed`` and ``log10(M*)`` calls to behave # sanely. We give each bin a small linear ramp starting at # T_TABLE_MIN; valid bins keep their actual cosmic time but # also get a floor at T_TABLE_MIN so very-high-z observations # don't underflow. T_TABLE_MIN = 0.01 # Gyr; matches dsps.constants.T_TABLE_MIN n_ssp = ssp_ages_yr.shape[0] # Floor every cosmic time to T_TABLE_MIN. t_cosmic_floor = jnp.maximum(t_cosmic_raw, T_TABLE_MIN) # Identify invalid bins (originally ≤0). valid = t_cosmic_raw > 0.0 # ``valid`` is in lookback (young→old) order; reverse to align # with ascending cosmic time. valid_asc = valid[::-1] t_cosmic_asc_raw = t_cosmic_floor[::-1] sfr_asc_raw = sfr_on_ssp_ages[::-1] # In ascending-cosmic-time order, invalid bins occupy the first # ``k = n_invalid`` indices. Give them a strict-monotonic ramp # in ``[T_TABLE_MIN, T_TABLE_MIN + ε]`` so they stay below the # youngest valid bin (which has t_cosmic > 0 by definition, # though potentially small). n_invalid = jnp.sum(~valid_asc) idx = jnp.arange(n_ssp) is_invalid_pos = idx < n_invalid # Ramp from T_TABLE_MIN to T_TABLE_MIN * 1.5, strictly increasing. ramp = T_TABLE_MIN + (T_TABLE_MIN * 0.5) * (idx + 1) / jnp.maximum(n_invalid, 1) t_cosmic_asc = jnp.where(is_invalid_pos, ramp, t_cosmic_asc_raw) # Guarantee strictly-increasing knots: at high z boundary-valid bins can # clamp to T_TABLE_MIN below the invalid-bin ramp, which DSPS NaNs on. #683 t_cosmic_asc = enforce_increasing_cosmic_time(t_cosmic_asc) sfr_asc = jnp.where(is_invalid_pos, 0.0, sfr_asc_raw) result = calc_rest_sed_sfh_table_lognormal_mdf( **canonical_dsps_kwargs( gal_t_table=t_cosmic_asc, gal_sfr_table=sfr_asc, gal_lgmet=lgmet, gal_lgmet_scatter=_dsps_kernel_scatter(lgmet_scatter), ssp_lgmet=ssp_lgmet, ssp_lg_age_gyr=ssp_lg_age_gyr, ssp_flux=ssp_flux, t_obs=t_obs_gyr, ) ) # ``result.weights`` is the joint (n_met, n_age) probability # distribution (sums to 1) used by DSPS internally to build # ``rest_sed``. The joint is **non-separable**: the outer product # of the marginals (lgmet_weights ⊗ age_weights) gives the right # marginals but the wrong per-bin product when convolved with # ``ssp_flux``, over-scaling the CSP SED by orders of magnitude. # Use the joint directly. total_mass = jnp.trapezoid(sfr_asc, t_cosmic_asc * 1e9) joint = _native_joint(result.weights, lgmet, lgmet_scatter, ssp_lgmet) # (n_met, n_age) age_weights_norm = joint.sum(axis=0) # (n_age,) sum=1 age_weights_msun = age_weights_norm * jnp.maximum(total_mass, 0.0) # Per-age conditional metallicity-weighted SSP flux (Lsun/Hz/Msun). # weighted_ssp[a] = sum_m(joint[m, a] × ssp_flux[m, a, :]) # ssp_flux_at_z[a] = weighted_ssp[a] / age_weights_norm[a] # so that ``age_weights_msun[a] × ssp_flux_at_z[a, :]`` reproduces # ``total_mass × weighted_ssp[a]``. Sum over a → rest_sed. weighted_ssp = jnp.einsum("ma,maw->aw", joint, ssp_flux) # (n_age, n_wave) age_weights_safe = jnp.maximum(age_weights_norm, 1e-30) ssp_flux_at_z = weighted_ssp / age_weights_safe[:, None] return age_weights_msun, ssp_flux_at_z def compute_dsps_age_weights( sfr_on_ssp_ages: jnp.ndarray, ssp_ages_yr: jnp.ndarray, ssp_lg_age_gyr: jnp.ndarray, t_obs_gyr: float, ) -> jnp.ndarray: r"""DSPS-canonical age weights only (no metallicity dispatch). Produces the SFH→age weight tensor (Hearin+ 2021 Eq. 9) on the SSP age grid in absolute mass units (Msun per age bin), without doing the metallicity marginalization. Useful when the caller runs an independent metallicity dispatch (bilinear on a 4D α-grid, ramp, chem-evol, etc.) and only needs DSPS-canonical SFH integration. Implements the same negative-cosmic-time safety as :func:`compute_dsps_native_weights` (invalid SSP bins masked via ``T_TABLE_MIN`` ramp + zero SFR). Parameters ---------- sfr_on_ssp_ages : array, shape (n_age,) Star formation rate (Msun/yr) at each SSP lookback age, sorted **ascending by age** (youngest = index 0). ssp_ages_yr : array, shape (n_age,) SSP lookback ages in years (ascending). ssp_lg_age_gyr : array, shape (n_age,) log10(age/Gyr) of SSP templates (DSPS convention). t_obs_gyr : float Age of the universe in Gyr at the observation redshift. Returns ------- age_weights_msun : ndarray, shape (n_age,) Mass formed per SSP age bin (Msun), sorted ascending by age. Sum = total stellar mass formed. Notes ----- **JIT-compatible**: yes. **Differentiable**: yes, pure JAX, no shape changes from inputs. References ---------- .. [1] Hearin et al. 2021, "DSPS: Differentiable Stellar Population Synthesis", arXiv:2112.06830, Eq. 9. """ try: with hold_x64_preference(): from dsps.sed.ssp_weights import calc_age_weights_from_sfh_table except ImportError: raise ImportError( "dsps is required for DSPS-canonical age weights. Install with: pip install dsps" ) from None ssp_age_gyr = ssp_ages_yr / 1e9 t_cosmic_raw = t_obs_gyr - ssp_age_gyr # NaN-safety: floor + invalid-bin ramp (see compute_dsps_native_weights). T_TABLE_MIN = 0.01 # Gyr; matches dsps.constants.T_TABLE_MIN n_ssp = ssp_ages_yr.shape[0] t_cosmic_floor = jnp.maximum(t_cosmic_raw, T_TABLE_MIN) valid = t_cosmic_raw > 0.0 valid_asc = valid[::-1] t_cosmic_asc_raw = t_cosmic_floor[::-1] sfr_asc_raw = sfr_on_ssp_ages[::-1] n_invalid = jnp.sum(~valid_asc) idx = jnp.arange(n_ssp) is_invalid_pos = idx < n_invalid ramp = T_TABLE_MIN + (T_TABLE_MIN * 0.5) * (idx + 1) / jnp.maximum(n_invalid, 1) t_cosmic_asc = jnp.where(is_invalid_pos, ramp, t_cosmic_asc_raw) # Guarantee strictly-increasing knots: at high z boundary-valid bins can # clamp to T_TABLE_MIN below the invalid-bin ramp, which DSPS NaNs on. #683 t_cosmic_asc = enforce_increasing_cosmic_time(t_cosmic_asc) sfr_asc = jnp.where(is_invalid_pos, 0.0, sfr_asc_raw) # DSPS canonical trapezoidal-in-cosmic-time SFH integration. age_weights_norm = calc_age_weights_from_sfh_table( gal_t_table=t_cosmic_asc, gal_sfr_table=sfr_asc, ssp_lg_age_gyr=ssp_lg_age_gyr, t_obs=t_obs_gyr, ) total_mass = jnp.trapezoid(sfr_asc, t_cosmic_asc * 1e9) return age_weights_norm * jnp.maximum(total_mass, 0.0) def compute_dsps_met_table_weights( sfr_on_ssp_ages: jnp.ndarray, lgmet_on_ssp_ages: jnp.ndarray, ssp_ages_yr: jnp.ndarray, ssp_lgmet: jnp.ndarray, ssp_lg_age_gyr: jnp.ndarray, ssp_flux: jnp.ndarray, t_obs_gyr: float, lgmet_scatter: float | None = None, ) -> tuple: """Compute CSP age weights and metallicity-marginalized SSP flux via DSPS. Uses a per-age metallicity table (time-evolving Z(t)). Selected via ``SEDModel(..., csp_integration="dsps_met_table")``. Unlike :func:`compute_dsps_native_weights` which uses a single scalar ``lgmet`` with a lognormal MDF, this function accepts a per-SSP-age metallicity array so each age bin can have its own metallicity and lognormal scatter (Hearin et al. 2023, Eq. 11). This is the natural mode for models with an evolving chemical history (``_met_mode="ramp"``). For a constant-metallicity model, pass a uniform array ``jnp.full_like(ssp_ages_yr, log_z_abs)``; the result is numerically equivalent to :func:`compute_dsps_native_weights` but computed via the met-table DSPS path. Parameters ---------- sfr_on_ssp_ages : array, shape (n_age,) Star formation rate (Msun/yr) at each SSP lookback age, sorted **ascending by age** (youngest = index 0). lgmet_on_ssp_ages : array, shape (n_age,) log10(Z) metallicity at each SSP lookback age (absolute, not Z/Zsun), sorted ascending by age (youngest = index 0). ssp_ages_yr : array, shape (n_age,) SSP lookback ages in years (ascending). ssp_lgmet : array, shape (n_met,) log10(Z) metallicity grid of the SSP library (absolute). ssp_lg_age_gyr : array, shape (n_age,) log10(age/Gyr) of SSP templates. ssp_flux : array, shape (n_met, n_age, n_wave) SSP spectra in Lsun/Hz/Msun. t_obs_gyr : float Age of the universe in Gyr at the observation redshift. lgmet_scatter : float, optional Gaussian scatter in log10(Z) per age bin (dex). ``None`` or zero is undeclared: each age reads the SSP grid node-exactly (#3434). Default None. Returns ------- age_weights_msun : array, shape (n_age,) Mass formed per SSP age bin (Msun), ascending by age (youngest first). ssp_flux_at_z : array, shape (n_age, n_wave) SSP flux marginalized over the per-age metallicity distribution (Lsun/Hz/Msun), ascending by age. Notes ----- DSPS returns ``lgmet_weights`` with shape ``(n_met, n_age)`` in ascending **cosmic** time order (oldest first). We flip the age axis back with ``lgmet_weights[:, ::-1]`` before the ``"ma,maw->aw"`` einsum so the metallicity weights are correctly paired with tengri's youngest-first SSP convention. References ---------- Hearin et al. 2023, arXiv:2112.08423, Eq. 11 (met-table kernel). """ try: with hold_x64_preference(): from dsps.sed.stellar_sed import calc_rest_sed_sfh_table_met_table except ImportError: raise ImportError( "dsps is required for csp_integration='dsps_met_table'. Install with: pip install dsps" ) from None # SSP ages are lookback times (young→old, ascending). # DSPS needs cosmic times sorted ascending (oldest first). ssp_age_gyr = ssp_ages_yr / 1e9 t_cosmic_gyr = jnp.clip(t_obs_gyr - ssp_age_gyr, min=1e-3) t_cosmic_asc = t_cosmic_gyr[::-1] # oldest first sfr_asc = sfr_on_ssp_ages[::-1] lgmet_asc = lgmet_on_ssp_ages[::-1] # metallicity aligned with cosmic time result = calc_rest_sed_sfh_table_met_table( gal_t_table=t_cosmic_asc, gal_sfr_table=sfr_asc, gal_lgmet_table=lgmet_asc, gal_lgmet_scatter=_dsps_kernel_scatter(lgmet_scatter), ssp_lgmet=ssp_lgmet, ssp_lg_age_gyr=ssp_lg_age_gyr, ssp_flux=ssp_flux, t_obs=t_obs_gyr, ) # The joint weights factor exactly as (age marginal) x (per-age metallicity # distribution), so each factor is taken from DSPS on its own. DSPS aligns # both age axes with the SSP grid (lookback-time ascending); no flips. # # Mass per age bin is the SFH's age marginal ``result.age_weights``, which # does not depend on the metallicity table: lgmet chooses templates, it does # not move mass, so d(mass)/d(lgmet) is exactly zero. Summing the joint # weights over metallicity instead returns the same marginal only to # round-off (DSPS normalizes each per-age MDF and then the whole matrix), and # that round-off has a non-zero lgmet gradient. total_mass = jnp.trapezoid(sfr_asc, t_cosmic_asc * 1e9) age_weights_norm = result.age_weights # (n_age,), DSPS normalizes it to sum 1 age_weights_msun = age_weights_norm * jnp.maximum(total_mass, 0.0) # Per-age metallicity distribution, each column normalized to one: the # flux of one solar mass formed at that age. DSPS places a column whose # lognormal falls wholly off the grid on the nearest node, so no column sum # is zero. met_w = _met_table_weights(result.lgmet_weights, lgmet_on_ssp_ages, lgmet_scatter, ssp_lgmet) ssp_flux_at_z = jnp.einsum("ma,maw->aw", met_w, ssp_flux) # (n_age, n_wave) per Msun return age_weights_msun, ssp_flux_at_z def compute_csp_weights( sfr_on_ssp_ages: jnp.ndarray, ssp_ages_yr: jnp.ndarray, method: str = "trapz", _log_interp_matrix=None, ) -> jnp.ndarray: """Compute SFH weights (mass formed per SSP age bin). Returns the stellar mass formed in each age bin (Msun), NOT normalized to sum=1. This way the CSP SED = sum(w_i * SSP_i) is in Lsun/Hz (same as DSPS), not Lsun/Hz/Msun. The total stellar mass formed is sum(weights). Parameters ---------- sfr_on_ssp_ages : array, shape (n_age,) Star formation rate at each SSP age [Msun/yr]. ssp_ages_yr : array, shape (n_age,) SSP ages [yr], sorted ascending. method : {"trapz", "log_trapz", "log_interp"} Integration method. See :func:`csp_age_dt` for details. Default ``"trapz"`` is the DSPS-compatible linear-age trapezoid rule. ``"log_trapz"`` applies the log-age Jacobian. ``"log_interp"`` uses Johnson+2021 log-linear interpolation (matrix multiply); requires ``_log_interp_matrix`` to be supplied. _log_interp_matrix : array, shape (n_age, n_age), optional Precomputed weight matrix from :func:`csp_log_interp_matrix`. Required when ``method="log_interp"``. Returns ------- array, shape (n_age,) Mass formed per age bin [Msun]. Sum = total mass formed. Notes ----- **JIT-compatible**: yes, all operations use ``jnp`` primitives. **Gradient-safe**: yes. """ if method == "log_interp": if _log_interp_matrix is None: _log_interp_matrix = jnp.array( csp_log_interp_matrix(ssp_ages_yr), dtype=sfr_on_ssp_ages.dtype ) return _log_interp_matrix @ sfr_on_ssp_ages dt = csp_age_dt(ssp_ages_yr, method) return sfr_on_ssp_ages * dt # ── Alpha-element enhancement ───────────────────────────────────── # Salaris relation coefficients (Salaris, Chieffi & Straniero 1993; # Knowles et al. 2023 Eq. 2). This is a semi-empirical fit to detailed # stellar interior models with different abundance mixtures. _SALARIS_LINEAR = 0.66154 _SALARIS_QUADRATIC = 0.20465 def salaris_mh_from_feh(feh: float, alpha_fe: float) -> float: """Convert [Fe/H] + [α/Fe] to total metallicity [M/H]. Uses the Salaris, Chieffi & Straniero (1993) relation as parameterized by Knowles et al. (2023) Eq. 2:: [M/H] = [Fe/H] + 0.66154 × [α/Fe] + 0.20465 × [α/Fe]² At solar [α/Fe] = 0.0, [M/H] = [Fe/H] exactly. Parameters ---------- feh : float Iron abundance [Fe/H] (relative to solar, dimensionless). alpha_fe : float Alpha-element enhancement [α/Fe] (relative to solar, dimensionless). Returns ------- float Total metallicity [M/H] (relative to solar, dimensionless). Notes ----- **JIT-compatible**: yes, pure arithmetic operations. **Gradient-safe**: yes. References ---------- Salaris, Chieffi & Straniero 1993, ApJ, 414, 580. Knowles et al. 2023, Eq. 2. Examples -------- >>> from tengri import salaris_mh_from_feh >>> round(float(salaris_mh_from_feh(feh=-0.5, alpha_fe=0.2)), 4) -0.3595 """ return feh + _SALARIS_LINEAR * alpha_fe + _SALARIS_QUADRATIC * alpha_fe**2 def salaris_feh_from_mh(mh: float, alpha_fe: float) -> float: """Convert total metallicity [M/H] + [α/Fe] to iron abundance [Fe/H]. Inverse of the Salaris relation:: [Fe/H] = [M/H] − 0.66154 × [α/Fe] − 0.20465 × [α/Fe]² At solar [α/Fe] = 0.0, [Fe/H] = [M/H] exactly. Parameters ---------- mh : float Total metallicity [M/H] (relative to solar, dimensionless). alpha_fe : float Alpha-element enhancement [α/Fe] (relative to solar, dimensionless). Returns ------- float Iron abundance [Fe/H] (relative to solar, dimensionless). Notes ----- **JIT-compatible**: yes, pure arithmetic operations. **Gradient-safe**: yes. References ---------- Salaris, Chieffi & Straniero 1993, ApJ, 414, 580 (inverse formula). Examples -------- >>> from tengri import salaris_feh_from_mh >>> round(float(salaris_feh_from_mh(mh=-0.5, alpha_fe=0.2)), 4) -0.6405 """ return mh - _SALARIS_LINEAR * alpha_fe - _SALARIS_QUADRATIC * alpha_fe**2 def has_alpha_grid(ssp_data: SSPData) -> bool: """Check if SSP data includes an [alpha/Fe] grid dimension. When True, ssp_flux has shape (n_met, n_alpha, n_age, n_wave) and proper bilinear (Z, [α/Fe]) interpolation is used. Parameters ---------- ssp_data : SSPData Loaded SSP template data. Returns ------- bool True if ssp_alpha_fe is present and ssp_flux is 4D. Notes ----- **JIT-compatible**: yes, pure shape checking and conditionals. **Gradient-safe**: yes. Examples -------- >>> from tengri import has_alpha_grid, load_ssp_data >>> # ssp = load_ssp_data("data/ssp_BC03_Chabrier.h5") >>> # has_alpha_grid(ssp) # True if file contains [alpha/Fe] axis >>> # False for standard BC03 grids (no alpha grid) """ return ssp_data.ssp_alpha_fe is not None and ssp_data.ssp_flux.ndim == 4 @jax.jit def interpolate_alpha_only( ssp_flux: jnp.ndarray, ssp_alpha_fe: jnp.ndarray, alpha_fe: float, ) -> jnp.ndarray: """Linear interpolation along the [α/Fe] axis only: 4D → 3D. Collapses the [α/Fe] dimension of a 4D SSP grid at a single target value, leaving the metallicity axis intact. The result feeds the standard 3D DSPS lognormal-MDF kernel, so the Z marginalization behaves identically to a no-α-grid run with the same met scatter. Parameters ---------- ssp_flux : array, shape (n_met, n_alpha, n_age, n_wave) SSP flux on the full 4D (Z, [α/Fe]) grid. [Lsun/Hz/Msun] ssp_alpha_fe : array, shape (n_alpha,) [α/Fe] grid values, relative to solar. alpha_fe : float Target [α/Fe] (dimensionless, relative to solar). Clipped to the grid bounds before interpolation. Returns ------- array, shape (n_met, n_age, n_wave) α-collapsed SSP flux, ready for the 3D MDF kernel. Notes ----- **JIT-compatible**: yes, all operations use ``jnp`` primitives. **Gradient-safe**: yes, linear interpolation is differentiable. Complements :func:`interpolate_met_alpha`, which collapses both axes to a single (Z, [α/Fe]) point. Samplers that want lognormal MDF marginalization over metallicity should use this α-only path so the 4D and 3D code paths share the same Z kernel. """ afe = jnp.clip(alpha_fe, ssp_alpha_fe[0], ssp_alpha_fe[-1]) ia = jnp.clip(jnp.searchsorted(ssp_alpha_fe, afe) - 1, 0, ssp_alpha_fe.shape[0] - 2) fa = (afe - ssp_alpha_fe[ia]) / (ssp_alpha_fe[ia + 1] - ssp_alpha_fe[ia]) return (1.0 - fa) * ssp_flux[:, ia] + fa * ssp_flux[:, ia + 1] def alpha_bracket(ssp_alpha_fe: jnp.ndarray, alpha_fe: float) -> tuple[jnp.ndarray, jnp.ndarray]: """Bracketing node index ``ia`` and fraction ``fa`` of ``alpha_fe`` on the [alpha/Fe] axis. The index and fraction are clipped to the grid. They are the linear weights :func:`interpolate_alpha_only` uses, exposed so a consumer can contract a 4D cube over metallicity and age first and interpolate the small per-node result (no per-sample copy of the cube).""" afe = jnp.clip(alpha_fe, ssp_alpha_fe[0], ssp_alpha_fe[-1]) last = ssp_alpha_fe.shape[0] - 2 idx = jnp.searchsorted(ssp_alpha_fe, afe) - 1 ia = jnp.where(idx < 0, 0, jnp.where(idx > last, last, idx)) fa = (afe - ssp_alpha_fe[ia]) / (ssp_alpha_fe[ia + 1] - ssp_alpha_fe[ia]) return ia, fa def collapse_alpha_axis(x: jnp.ndarray, ia, fa, axis: int = 0) -> jnp.ndarray: """Linear interpolation of ``x`` along its [alpha/Fe] node ``axis``. Uses the :func:`alpha_bracket` weights. A scalar bracket collapses the whole array to one [alpha/Fe]. A bracket of shape ``(n_age,)`` (an age-dependent [alpha/Fe], see :func:`~tengri.components.stellar.sps.dsps_wrapper.compute_alpha_fe_evolving`) collapses each age ``a`` at its own node pair; the age axis must follow the alpha axis, so ``x.shape[axis + 1] == n_age``, and the result has the alpha axis removed. Parameters ---------- x : array Array with an [alpha/Fe] node axis at ``axis``. ia : int array, scalar or shape (n_age,) Lower node index of each bracket. fa : float array, scalar or shape (n_age,) Fraction of the way from node ``ia`` to node ``ia + 1``. axis : int, default 0 Position of the [alpha/Fe] node axis in ``x``. Returns ------- array ``x`` with the [alpha/Fe] axis removed. Raises ------ ValueError If the bracket is a vector whose length is not ``x.shape[axis + 1]``. Notes ----- **JIT-compatible**: yes; the scalar/vector branch is taken on the static ``jnp.ndim(ia)``. **Gradient-safe**: yes, linear in ``fa``. """ if jnp.ndim(ia) == 0: return (1.0 - fa) * jnp.take(x, ia, axis=axis) + fa * jnp.take(x, ia + 1, axis=axis) n_age = jnp.shape(ia)[0] if x.shape[axis + 1] != n_age: raise ValueError( f"collapse_alpha_axis: a per-age bracket of length {n_age} needs the age axis " f"(axis {axis + 1}) of length {n_age}, got x.shape={tuple(x.shape)} with " f"alpha axis {axis}." ) target = list(x.shape) target[axis] = 1 age_shape = [1] * x.ndim age_shape[axis + 1] = n_age idx = jnp.broadcast_to(jnp.reshape(ia, age_shape), target) wgt = jnp.broadcast_to(jnp.reshape(fa, age_shape), target) lo = jnp.take_along_axis(x, idx, axis=axis) hi = jnp.take_along_axis(x, idx + 1, axis=axis) return jnp.squeeze((1.0 - wgt) * lo + wgt * hi, axis=axis) @jax.jit def interpolate_met_alpha( ssp_flux: jnp.ndarray, ssp_lgmet: jnp.ndarray, ssp_alpha_fe: jnp.ndarray, log_z: float, alpha_fe: float, ) -> jnp.ndarray: """Bilinear interpolation in (metallicity, [α/Fe]) for 4D SSP grids. This is the correct approach when alpha-enhanced SSP templates are available (e.g., sMILES, BPASS v2.3, α-MC). A 3D grid has no [α/Fe] axis to interpolate on, so the bilinear path does not apply to it. Parameters ---------- ssp_flux : array, shape (n_met, n_alpha, n_age, n_wave) SSP flux [Lsun/Hz/Msun] on the full (Z, [α/Fe]) grid. ssp_lgmet : array, shape (n_met,) [Fe/H] iron abundance grid (log10 relative to solar, dimensionless). All source libraries must be converted to [Fe/H] at load time. ssp_alpha_fe : array, shape (n_alpha,) [α/Fe] grid values (relative to solar, dimensionless; e.g., [-0.2, 0.0, +0.2, +0.4, +0.6]). log_z : float Target [Fe/H] (iron abundance, log10 relative to solar). alpha_fe : float Target [α/Fe] (relative to solar, dimensionless). Returns ------- array, shape (n_age, n_wave) Interpolated SSP flux [Lsun/Hz/Msun] at the target (Z, [α/Fe]). Notes ----- **JIT-compatible**: yes, all operations use ``jnp`` primitives. **Gradient-safe**: yes, bilinear interpolation is differentiable. """ # Metallicity index and fraction lz = jnp.clip(log_z, ssp_lgmet[0], ssp_lgmet[-1]) iz = jnp.clip(jnp.searchsorted(ssp_lgmet, lz) - 1, 0, len(ssp_lgmet) - 2) fz = (lz - ssp_lgmet[iz]) / (ssp_lgmet[iz + 1] - ssp_lgmet[iz]) # Alpha index and fraction afe = jnp.clip(alpha_fe, ssp_alpha_fe[0], ssp_alpha_fe[-1]) ia = jnp.clip(jnp.searchsorted(ssp_alpha_fe, afe) - 1, 0, len(ssp_alpha_fe) - 2) fa = (afe - ssp_alpha_fe[ia]) / (ssp_alpha_fe[ia + 1] - ssp_alpha_fe[ia]) # Bilinear: four corners → (n_age, n_wave) return ( (1.0 - fz) * (1.0 - fa) * ssp_flux[iz, ia] + fz * (1.0 - fa) * ssp_flux[iz + 1, ia] + (1.0 - fz) * fa * ssp_flux[iz, ia + 1] + fz * fa * ssp_flux[iz + 1, ia + 1] ) @jax.jit def interpolate_met_alpha_evolving( ssp_flux: jnp.ndarray, ssp_lgmet: jnp.ndarray, ssp_alpha_fe: jnp.ndarray, log_z_per_age: jnp.ndarray, alpha_fe_per_age: jnp.ndarray, ) -> jnp.ndarray: """Per-age bilinear interpolation in (Z, [α/Fe]) for time-evolving abundances. Each SSP age bin can have a different metallicity AND a different [α/Fe], enabling physically motivated chemical evolution where old stars are α-enhanced and young stars are solar-scaled. Parameters ---------- ssp_flux : array, shape (n_met, n_alpha, n_age, n_wave) SSP flux [Lsun/Hz/Msun] on the full (Z, [α/Fe]) grid. ssp_lgmet : array, shape (n_met,) [Fe/H] iron abundance grid (log10 relative to solar, dimensionless). ssp_alpha_fe : array, shape (n_alpha,) [α/Fe] grid values (relative to solar, dimensionless). log_z_per_age : array, shape (n_age,) Target [Fe/H] at each SSP age bin (dimensionless). alpha_fe_per_age : array, shape (n_age,) Target [α/Fe] at each SSP age bin (relative to solar, dimensionless). Returns ------- array, shape (n_age, n_wave) Interpolated SSP flux [Lsun/Hz/Msun] with per-age (Z, [α/Fe]). Notes ----- **JIT-compatible**: yes, uses ``jax.vmap`` for vectorized interpolation. **Gradient-safe**: yes. """ def _interp_one_age(lz_i, afe_i, flux_at_age_i): """Bilinear interpolation over metallicity and alpha-element abundance.""" # flux_at_age_i: (n_met, n_alpha, n_wave) lz = jnp.clip(lz_i, ssp_lgmet[0], ssp_lgmet[-1]) iz = jnp.clip(jnp.searchsorted(ssp_lgmet, lz) - 1, 0, len(ssp_lgmet) - 2) fz = (lz - ssp_lgmet[iz]) / (ssp_lgmet[iz + 1] - ssp_lgmet[iz]) afe = jnp.clip(afe_i, ssp_alpha_fe[0], ssp_alpha_fe[-1]) ia = jnp.clip(jnp.searchsorted(ssp_alpha_fe, afe) - 1, 0, len(ssp_alpha_fe) - 2) fa = (afe - ssp_alpha_fe[ia]) / (ssp_alpha_fe[ia + 1] - ssp_alpha_fe[ia]) return ( (1.0 - fz) * (1.0 - fa) * flux_at_age_i[iz, ia] + fz * (1.0 - fa) * flux_at_age_i[iz + 1, ia] + (1.0 - fz) * fa * flux_at_age_i[iz, ia + 1] + fz * fa * flux_at_age_i[iz + 1, ia + 1] ) # Transpose: (n_met, n_alpha, n_age, n_wave) → (n_age, n_met, n_alpha, n_wave) flux_by_age = jnp.transpose(ssp_flux, (2, 0, 1, 3)) return jax.vmap(_interp_one_age)(log_z_per_age, alpha_fe_per_age, flux_by_age) @jax.jit def compute_alpha_fe_evolving( ssp_lg_age_gyr: jnp.ndarray, alpha_fe_old: float, alpha_fe_young: float, t_universe_gyr: float, ) -> jnp.ndarray: """Compute per-age [α/Fe] from a linear ramp in lookback time. Old stars (large lookback time) have high [α/Fe] (formed before Type Ia SNe enriched Fe). Young stars have lower [α/Fe] (solar or sub-solar). This is the standard chemical evolution prediction. The ramp is linear in lookback time:: [α/Fe](t_lookback) = α_young + (α_old - α_young) * t_lookback / t_universe Parameters ---------- ssp_lg_age_gyr : array, shape (n_age,) Log10(age [Gyr]) of SSP templates (= lookback time for SSP bins). alpha_fe_old : float [α/Fe] of the oldest stars (at t_lookback = t_universe, dimensionless). Typically +0.3 to +0.5 for massive ellipticals. alpha_fe_young : float [α/Fe] at present day (t_lookback ≈ 0, dimensionless). Typically ~0.0 (solar) for disk galaxies. t_universe_gyr : float Age of the universe at the observed redshift [Gyr]. Returns ------- array, shape (n_age,) [α/Fe] at each SSP age bin (dimensionless). Notes ----- **JIT-compatible**: yes, all operations use ``jnp`` primitives. **Gradient-safe**: yes. """ age_gyr = 10.0**ssp_lg_age_gyr t_frac = jnp.clip(age_gyr / t_universe_gyr, 0.0, 1.0) return alpha_fe_young + (alpha_fe_old - alpha_fe_young) * t_frac from tengri.utils.physics_constants import L_SUN as LSUN_ERG_PER_S @jax.jit def compute_csp_sed( weights: jnp.ndarray, ssp_flux_at_met: jnp.ndarray, dust_attenuation: jnp.ndarray ) -> jnp.ndarray: """Compute composite stellar population SED. SED = Lsun * sum_i (weight_i * dust_i * ssp_flux_i) where weights are in Msun (mass formed per bin) and SSP flux is in Lsun/Hz/Msun. The result is in erg/s/Hz. Parameters ---------- weights : array, shape (n_age,) Mass formed per age bin [Msun] from :func:`compute_csp_weights`. ssp_flux_at_met : array, shape (n_age, n_wave) SSP spectra at fixed metallicity [Lsun/Hz/Msun]. dust_attenuation : array, shape (n_age, n_wave) Multiplicative dust transmission per age and wavelength (dimensionless, in [0, 1]). Returns ------- array, shape (n_wave,) Composite SED [erg/s/Hz] (rest-frame luminosity density). Notes ----- **JIT-compatible**: yes, uses ``jnp.einsum`` for vectorized multiplication. **Gradient-safe**: yes. """ # weights [Msun] * ssp [Lsun/Hz/Msun] * dust [dimensionless] -> Lsun/Hz sed_lsun = jnp.einsum("i,iw,iw->w", weights, dust_attenuation, ssp_flux_at_met) return sed_lsun * LSUN_ERG_PER_S # -> erg/s/Hz @jax.jit def interpolate_metallicity( ssp_flux: jnp.ndarray, ssp_lgmet: jnp.ndarray, log_z: float ) -> jnp.ndarray: r"""Interpolate SSP flux to a target metallicity. Linear interpolation in log(Z/Zsun) space between the two nearest metallicity grid points. Parameters ---------- ssp_flux : array_like, shape (n_met, n_age, n_wave) Full SSP flux grid. [Lsun/Hz/Msun] ssp_lgmet : array_like, shape (n_met,) log10(Z/Zsun) grid points. [dimensionless] log_z : float Target metallicity log10(Z/Zsun). Values outside the grid bounds are clamped to ``[ssp_lgmet[0], ssp_lgmet[-1]]``. [dimensionless] Returns ------- ndarray, shape (n_age, n_wave) SSP flux interpolated to the target metallicity. [Lsun/Hz/Msun] Notes ----- **JIT-compatible**: yes, all operations use ``jnp`` primitives. **Gradient-safe**: yes, linear interpolation is differentiable. **Approximation**: piecewise-linear interpolation in :math:`\log_{10}(Z/Z_\odot)`. Strictly valid only for grids whose flux varies smoothly with metallicity; for sharply varying lines or edges, prefer the smooth triweight kernel in :func:`compute_lgmet_weights`. Given bracketing grid indices :math:`i, i+1` with :math:`\log Z_i \le \log Z \le \log Z_{i+1}`, .. math:: f = \frac{\log Z - \log Z_i}{\log Z_{i+1} - \log Z_i}, \qquad F(\log Z) = (1 - f)\, F_i + f\, F_{i+1} where :math:`F_i \equiv` ``ssp_flux[i]`` [Lsun/Hz/Msun]. """ # Clamp to grid bounds log_z_clamped = jnp.clip(log_z, ssp_lgmet[0], ssp_lgmet[-1]) # Find bracketing indices idx = jnp.searchsorted(ssp_lgmet, log_z_clamped) - 1 idx = jnp.clip(idx, 0, len(ssp_lgmet) - 2) # Linear interpolation weight frac = (log_z_clamped - ssp_lgmet[idx]) / (ssp_lgmet[idx + 1] - ssp_lgmet[idx]) return (1.0 - frac) * ssp_flux[idx] + frac * ssp_flux[idx + 1] # ── Smooth metallicity interpolation (triweight kernel, DSPS-compatible) @jax.jit def _tw_cuml_kern(x, m, h): """Triweight kernel CDF: bit-exact mirror of DSPS ``_tw_cuml_kern``. Cumulative distribution of the triweight kernel with support |z| < 3. Returns 0 for z < -3, 1 for z > 3, smooth polynomial between. Notes ----- **JIT-compatible**: yes. **Do not consolidate this with** :func:`tengri.utils.interpolation.tw_cuml_kern`. The two evaluate the same polynomial but in different forms, deliberately: - ``utils.interpolation`` (and ``utils.diffndhist``) use Horner's method, chosen for fewer FLOPs and better conditioning. - **this copy uses the direct-power form**, because it reproduces upstream DSPS term-for-term so that ``compute_lgmet_weights`` stays bit-comparable with ``dsps.utils._tw_cuml_kern``. Measured difference between the two forms over ``z`` in [-4, 4]: ``3.3e-16`` in float64 and ``2.4e-7`` in float32: about 1 ulp, so either form is numerically fine in isolation. Rewriting this one to Horner would silently drop the upstream-parity property, which is the only reason the duplicate exists (#1401). """ z = (x - m) / h val = -5.0 * z**7 / 69984.0 + 7.0 * z**5 / 2592.0 - 35.0 * z**3 / 864.0 + 35.0 * z / 96.0 + 0.5 val = jnp.where(z < -3.0, 0.0, val) val = jnp.where(z > 3.0, 1.0, val) return val # Scatter used only to read the age marginal of the DSPS-native kernel, which # does not depend on the metallicity kernel. Never a physics default. _NOMINAL_LGMET_SCATTER = 0.1 def _scatter_value(lgmet_scatter): """Declared scatter as an array. ``None`` (undeclared) is zero (#3434).""" return jnp.asarray(0.0 if lgmet_scatter is None else lgmet_scatter) def _dsps_lgmet_bin_edges(grid): """Metallicity bin edges of the DSPS kernel: ``dsps.utils._get_bin_edges``. Uses DSPS's own ``LGMET_LO`` / ``LGMET_HI`` outer edges (the same ones ``_lgmet_weights_parcels`` in ``tengri.components.stellar.component`` reads), so the wrapper and the component cannot disagree on the bin edges. A local copy with a narrower lower edge gave negative weights for nodes below it (#3434). """ with hold_x64_preference(): from dsps.constants import LGMET_HI, LGMET_LO from dsps.utils import _get_bin_edges return _get_bin_edges(grid, LGMET_LO, LGMET_HI) @jax.jit def compute_lgmet_weights(log_z, ssp_lgmet, lgmet_scatter=None): """Metallicity weights of one parcel, on the fixed-Z rule (#3434). A declared scatter (``lgmet_scatter > 0``) gives the triweight-kernel weights: the kernel CDF integrated over DSPS's bin edges, matching DSPS ``triweighted_histogram``. Non-negative, summing to 1. A zero scatter is undeclared and reads the SSP grid by monotone PCHIP in log Z (:func:`read_met`; its linear surrogate :func:`met_weights` gives the weights): one-hot at every node. Parameters ---------- log_z : float Target log10(Z/Zsun) (dimensionless), a scalar. ssp_lgmet : array, shape (n_met,) SSP metallicity grid [log10(Z/Zsun)], sorted ascending. lgmet_scatter : float or None Declared metallicity scatter [dex]. ``None`` or zero means undeclared, the node-exact read. Default None: a function default is not a declaration. Returns ------- array, shape (n_met,) Weights summing to 1 (dimensionless). Notes ----- **JIT-compatible**: yes; the rule is a ``jnp.where`` on the traced scatter. **Gradient-safe**: yes. The kernel bandwidth is replaced by 1 where the scatter is zero, so the unselected kernel branch stays finite. """ scatter = _scatter_value(lgmet_scatter) declared = scatter > 0.0 bandwidth = jnp.where(declared, scatter, 1.0) edges = _dsps_lgmet_bin_edges(ssp_lgmet) # Evaluated once per edge, not once per (bin, side): bin k's upper edge is # bin k+1's lower edge, so the CDF is differenced on adjacent entries. cdf = _tw_cuml_kern(log_z, edges, bandwidth) raw = cdf[:-1] - cdf[1:] total = jnp.sum(raw) nearest = jnp.argmin(jnp.abs(ssp_lgmet - log_z)) fallback = jnp.zeros_like(raw).at[nearest].set(1.0) kernel = jnp.where(total > 0, raw / total, fallback) return jnp.where(declared, kernel, met_weights(log_z, ssp_lgmet)) @jax.jit def interpolate_metallicity_smooth(ssp_flux, ssp_lgmet, log_z, lgmet_scatter=None): """Interpolate SSP flux using triweight kernel over metallicity. C²-continuous gradients. Matches DSPS approach (Hearin+2023). Parameters ---------- ssp_flux : array, shape (n_met, n_age, n_wave) Full SSP flux grid [Lsun/Hz/Msun]. ssp_lgmet : array, shape (n_met,) SSP metallicity grid [log10(Z/Zsun)], sorted ascending. log_z : float Target log10(Z/Zsun). lgmet_scatter : float or None Declared kernel bandwidth [dex]. ``None`` or zero is undeclared (node-exact read). Default None. Returns ------- array, shape (n_age, n_wave) Interpolated SSP flux [Lsun/Hz/Msun]. Notes ----- **JIT-compatible**: yes, uses triweight kernel via :func:`compute_lgmet_weights`. **Gradient-safe**: yes; C²-continuous gradients. """ w = compute_lgmet_weights(log_z, ssp_lgmet, lgmet_scatter) kernel_out = jnp.einsum("m,maw->aw", w, ssp_flux) exact = read_met(ssp_flux, ssp_lgmet, log_z) # PCHIP each SSP column, then (no age sum here) return jnp.where(_scatter_value(lgmet_scatter) > 0.0, kernel_out, exact) @jax.jit def interpolate_metallicity_smooth_evolving( ssp_flux, ssp_lgmet, log_z_per_age, lgmet_scatter=None ): """Triweight metallicity interpolation with per-age Z. Parameters ---------- ssp_flux : array, shape (n_met, n_age, n_wave) Full SSP flux grid [Lsun/Hz/Msun]. ssp_lgmet : array, shape (n_met,) SSP metallicity grid [log10(Z/Zsun)], sorted ascending. log_z_per_age : array, shape (n_age,) Target log10(Z/Zsun) at each SSP age bin (dimensionless). lgmet_scatter : float or None Declared kernel bandwidth [dex]. ``None`` or zero is undeclared (node-exact read). Default None. Returns ------- array, shape (n_age, n_wave) Interpolated SSP flux [Lsun/Hz/Msun]. Notes ----- **JIT-compatible**: yes, uses ``jax.vmap`` for per-age interpolation. **Gradient-safe**: yes; C²-continuous gradients. """ def _one_age(log_z_i, flux_at_age_i): """Marginalize SSP flux over metallicity using triweight kernel.""" w = compute_lgmet_weights(log_z_i, ssp_lgmet, lgmet_scatter) return jnp.einsum("m,mw->w", w, flux_at_age_i) flux_by_age = jnp.transpose(ssp_flux, (1, 0, 2)) kernel_out = jax.vmap(_one_age)(log_z_per_age, flux_by_age) exact = read_met_per_age(ssp_flux, ssp_lgmet, log_z_per_age) # (n_age, n_wave) return jnp.where(_scatter_value(lgmet_scatter) > 0.0, kernel_out, exact) @jax.jit def interpolate_mass_remaining_smooth(ssp_mass_remaining, ssp_lgmet, log_z, lgmet_scatter=None): """Smooth mass-remaining interpolation using triweight kernel. Interpolates the surviving mass fraction to a target metallicity using the same triweight kernel as :func:`interpolate_metallicity_smooth`. Parameters ---------- ssp_mass_remaining : array, shape (n_met, n_age) Surviving mass fraction per metallicity and age (dimensionless, in [0, 1]). ssp_lgmet : array, shape (n_met,) SSP metallicity grid, absolute log10(Z) [dex] on tengri grids, sorted ascending. log_z : float Target metallicity [dex], in the units of ``ssp_lgmet``. lgmet_scatter : float or None Declared kernel bandwidth [dex]. ``None`` or zero is undeclared (node-exact read). Default None. Returns ------- array, shape (n_age,) Interpolated mass-remaining fraction per age (dimensionless). Notes ----- **JIT-compatible**: yes, uses triweight kernel via :func:`compute_lgmet_weights`. **Gradient-safe**: yes; C²-continuous gradients. """ w = compute_lgmet_weights(log_z, ssp_lgmet, lgmet_scatter) kernel_out = jnp.einsum("m,ma->a", w, ssp_mass_remaining) exact = read_met(ssp_mass_remaining, ssp_lgmet, log_z) return jnp.where(_scatter_value(lgmet_scatter) > 0.0, kernel_out, exact) @jax.jit def interpolate_metallicity_evolving( ssp_flux: jnp.ndarray, ssp_lgmet: jnp.ndarray, log_z_per_age: jnp.ndarray, ) -> jnp.ndarray: """Interpolate SSP flux with a different metallicity per age bin. Each SSP age bin is interpolated at its own metallicity, enabling time-evolving metallicity models (e.g., chemical enrichment). Parameters ---------- ssp_flux : array, shape (n_met, n_age, n_wave) Full SSP flux grid [Lsun/Hz/Msun]. ssp_lgmet : array, shape (n_met,) Metallicity grid, absolute log10(Z) [dex] on tengri grids, sorted ascending. log_z_per_age : array, shape (n_age,) Target metallicity at each age bin [dex], in the units of ``ssp_lgmet``. Returns ------- array, shape (n_age, n_wave) Interpolated SSP flux [Lsun/Hz/Msun] with per-age metallicity. Notes ----- **JIT-compatible**: yes, uses ``jax.vmap`` for vectorized interpolation. **Gradient-safe**: yes, linear interpolation is differentiable. """ def _interp_one_age(log_z_i, ssp_flux_at_age_i): """Interpolate a single age bin at its metallicity. Parameters ---------- log_z_i : scalar Target log10(Z/Zsun) for this age bin. ssp_flux_at_age_i : array, shape (n_met, n_wave) SSP flux at all metallicities for this age bin. Returns ------- array, shape (n_wave,) Interpolated flux [Lsun/Hz/Msun]. """ log_z_c = jnp.clip(log_z_i, ssp_lgmet[0], ssp_lgmet[-1]) idx = jnp.clip( jnp.searchsorted(ssp_lgmet, log_z_c) - 1, 0, len(ssp_lgmet) - 2, ) frac = (log_z_c - ssp_lgmet[idx]) / (ssp_lgmet[idx + 1] - ssp_lgmet[idx]) return (1.0 - frac) * ssp_flux_at_age_i[idx] + frac * ssp_flux_at_age_i[idx + 1] # ssp_flux is (n_met, n_age, n_wave); transpose to (n_age, n_met, n_wave) # so vmap over the leading (age) axis pairs each age with its metallicity ssp_flux_by_age = jnp.transpose(ssp_flux, (1, 0, 2)) # (n_age, n_met, n_wave) return jax.vmap(_interp_one_age)(log_z_per_age, ssp_flux_by_age) @jax.jit def interpolate_mass_remaining_evolving( ssp_mass_remaining: jnp.ndarray, ssp_lgmet: jnp.ndarray, log_z_per_age: jnp.ndarray, ) -> jnp.ndarray: """Interpolate mass-remaining with a different metallicity per age bin. Parameters ---------- ssp_mass_remaining : array, shape (n_met, n_age) Surviving mass fraction per metallicity and age (dimensionless, in [0, 1]). ssp_lgmet : array, shape (n_met,) Metallicity grid, absolute log10(Z) [dex] on tengri grids, sorted ascending. log_z_per_age : array, shape (n_age,) Target metallicity at each age bin [dex], in the units of ``ssp_lgmet``. Returns ------- array, shape (n_age,) Interpolated mass-remaining fraction per age bin (dimensionless). Notes ----- **JIT-compatible**: yes, uses ``jax.vmap`` for vectorized interpolation. **Gradient-safe**: yes, linear interpolation is differentiable. """ def _interp_one_age(log_z_i, mr_at_age_i): """Linear interpolation of mass-remaining at a single age bin.""" log_z_c = jnp.clip(log_z_i, ssp_lgmet[0], ssp_lgmet[-1]) idx = jnp.clip( jnp.searchsorted(ssp_lgmet, log_z_c) - 1, 0, len(ssp_lgmet) - 2, ) frac = (log_z_c - ssp_lgmet[idx]) / (ssp_lgmet[idx + 1] - ssp_lgmet[idx]) return (1.0 - frac) * mr_at_age_i[idx] + frac * mr_at_age_i[idx + 1] # ssp_mass_remaining is (n_met, n_age); transpose to (n_age, n_met) mr_by_age = jnp.transpose(ssp_mass_remaining, (1, 0)) # (n_age, n_met) return jax.vmap(_interp_one_age)(log_z_per_age, mr_by_age) @jax.jit def compute_log_z_evolving( ssp_lg_age_gyr: jnp.ndarray, log_z_initial: float, log_z_final: float, t_universe_gyr: float, ) -> jnp.ndarray: """Compute per-age-bin metallicity from a linear-in-log ramp. The metallicity evolves linearly in log(Z/Zsun) space: log_z(t_lookback) = log_z_final + (log_z_initial - log_z_final) * t_lookback / t_universe where t_lookback=0 is today (log_z_final) and t_lookback=t_universe is the oldest stars (log_z_initial). SSP ages are lookback times. Parameters ---------- ssp_lg_age_gyr : array, shape (n_age,) Log10(age [Gyr]) of SSP templates (= lookback time for SSP bins). log_z_initial : float Metallicity of the oldest stars (at t_lookback = t_universe), in log10(Z/Zsun) (dimensionless). log_z_final : float Metallicity at present day (t_lookback = 0) [log10(Z/Zsun)]. t_universe_gyr : float Age of the universe at the observed redshift [Gyr]. Returns ------- array, shape (n_age,) log10(Z/Zsun) at each SSP age bin (dimensionless). Notes ----- **JIT-compatible**: yes, all operations use ``jnp`` primitives. **Gradient-safe**: yes. """ age_gyr = 10.0**ssp_lg_age_gyr # Clamp lookback time to [0, t_universe] so extrapolation is safe t_frac = jnp.clip(age_gyr / t_universe_gyr, 0.0, 1.0) return log_z_final + (log_z_initial - log_z_final) * t_frac @jax.jit def interpolate_mass_remaining( ssp_mass_remaining: jnp.ndarray, ssp_lgmet: jnp.ndarray, log_z: float ) -> jnp.ndarray: """Interpolate mass-remaining fraction to a target metallicity. Parameters ---------- ssp_mass_remaining : array, shape (n_met, n_age) Surviving mass fraction per metallicity and age (dimensionless, in [0, 1]). ssp_lgmet : array, shape (n_met,) Metallicity grid, absolute log10(Z) [dex] on tengri grids, sorted ascending. log_z : float Target metallicity [dex], in the units of ``ssp_lgmet``. Returns ------- array, shape (n_age,) Interpolated mass-remaining fraction per age (dimensionless). Notes ----- **JIT-compatible**: yes, all operations use ``jnp`` primitives. **Gradient-safe**: yes, linear interpolation is differentiable. """ log_z_clamped = jnp.clip(log_z, ssp_lgmet[0], ssp_lgmet[-1]) idx = jnp.searchsorted(ssp_lgmet, log_z_clamped) - 1 idx = jnp.clip(idx, 0, len(ssp_lgmet) - 2) frac = (log_z_clamped - ssp_lgmet[idx]) / (ssp_lgmet[idx + 1] - ssp_lgmet[idx]) return (1.0 - frac) * ssp_mass_remaining[idx] + frac * ssp_mass_remaining[idx + 1] @jax.jit def compute_surviving_mass(weights: jnp.ndarray, mass_remaining_at_met: jnp.ndarray) -> float: """Compute surviving stellar mass from CSP weights and mass-remaining. Parameters ---------- weights : array, shape (n_age,) Mass formed per age bin [Msun] from :func:`compute_csp_weights`. mass_remaining_at_met : array, shape (n_age,) Fraction of formed mass surviving at each age (dimensionless, in [0, 1]) from :func:`interpolate_mass_remaining`. Returns ------- float Total surviving stellar mass [Msun]. Notes ----- **JIT-compatible**: yes, uses ``jnp.sum`` for reduction. **Gradient-safe**: yes. """ return jnp.sum(weights * mass_remaining_at_met) def predict_surviving_mass( sfr: jnp.ndarray, t_lookback_yr: jnp.ndarray, ssp: "SSPData", log_z_zsun: float = 0.0, alpha_fe: float = 0.0, ) -> jnp.ndarray: """Predict surviving stellar mass directly from an SFR(t) array. Standalone helper for putting **priors on the surviving stellar mass** without running the full SED forward pass. Computes .. math:: M_{\\star,{\\rm surv}} = \\int \\mathrm{SFR}(t_{\\rm lb}) \\, f_{\\rm surv}(t_{\\rm lb}; Z) \\, dt_{\\rm lb} where :math:`f_{\\rm surv}(t)` is the surviving mass fraction from the SSP's ``ssp_mass_remaining`` table, evaluated at the user-supplied metallicity via linear interpolation in :math:`\\log_{10}(Z/Z_\\odot)` and resampled onto the SFH lookback grid via linear interp in :math:`\\log_{10}({\\rm age})`. This formula follows from the post-2026-05-25 SFH normalization contract (``trapezoid(sfr, t) = 10**log_total_mass`` for every parametric SFH): the survivor fraction at each age becomes a *weight* on the SFR, and the integral collapses to a single trapezoid rule on the SFH grid; no DSPS convolution required. Parameters ---------- sfr : array_like, shape (n_lb,) SFR on the lookback grid [Msun/yr]. Typically the output of one of the parametric SFH callables (e.g. ``tau(t, log_total_mass=10.0, …)``). t_lookback_yr : array_like, shape (n_lb,) Lookback time grid [yr], ascending. ssp : SSPData SSP container with populated ``ssp_mass_remaining`` (n_met, n_age) and ``ssp_lg_age_gyr``, ``ssp_lgmet`` axes. Raises if ``ssp_mass_remaining`` is ``None``. log_z_zsun : float, optional Metallicity at which to evaluate the surviving-mass fraction, :math:`\\log_{10}(Z/Z_\\odot)` with :math:`Z_\\odot = 0.0142`. Default 0.0 (solar). Subtract :data:`tengri.utils.physics_constants.LOG10_ZSUN` from an absolute :math:`\\log_{10}(Z)` to get it. A value outside the grid is held at the nearest end node. alpha_fe : float, optional [alpha/Fe] at which to evaluate the surviving-mass fraction, on a grid whose ``ssp_mass_remaining_alpha`` table is present (#2250). Default 0.0; ignored otherwise. Returns ------- jnp.ndarray (scalar) Surviving stellar mass [Msun]. Notes ----- **JIT-compatible**: yes, uses ``jnp.interp``, ``jnp.trapezoid``, and the existing :func:`interpolate_mass_remaining` helper. **Gradient-safe**: yes, differentiable w.r.t. any SFH parameter through ``sfr``. This helper evaluates the mass-remaining table at ONE supplied metallicity (``log_z_zsun``). The forward model's published ``log_mstar_surviving`` is a joint-weight contraction over all (age, Z) nodes in the history, equal to this helper's result only for a delta-Z (single-metallicity) history at a grid node. For multi-metallicity histories (two_step, bins, etc.), use the forward model's published value. This helper is the cheap standalone path for the prior layer: .. code-block:: python # Put a Gaussian prior on log10(M*,surv) sfr = tau(t_lb, log_total_mass=lgM_formed, tau=tau_yr, age=age_yr) log_mstar_surv = jnp.log10(predict_surviving_mass(sfr, t_lb, ssp)) log_prior = -0.5 * ((log_mstar_surv - 10.5) / 0.3) ** 2 Raises ------ ValueError If ``ssp.ssp_mass_remaining`` is ``None`` (e.g., legacy SSP file without a stored mass-remaining table). See Also -------- compute_surviving_mass : low-level helper that takes pre-computed weights. interpolate_mass_remaining : metallicity interpolation used internally. """ if ssp.ssp_mass_remaining is None: raise ValueError( "SSP has no ssp_mass_remaining table. Surviving mass cannot be " "computed without it. Load an SSP file with stellar-evolution " "mass-loss data (see tengri.load_ssp_data)." ) mass_table = ssp.ssp_mass_remaining if ssp.ssp_mass_remaining_alpha is not None: # Collapse the alpha table at the requested [alpha/Fe] first (n_met, n_age). ia, fa = alpha_bracket(ssp.ssp_alpha_fe, alpha_fe) mass_table = collapse_alpha_axis(ssp.ssp_mass_remaining_alpha, ia, fa, axis=1) # Mass-remaining fraction on the SSP age grid at the requested metallicity. from tengri.utils.physics_constants import LOG10_ZSUN # ``ssp_lgmet`` is absolute log10(Z); the argument is relative to solar. f_surv_on_ssp = interpolate_mass_remaining( mass_table, ssp.ssp_lgmet, log_z_zsun + LOG10_ZSUN ) # (n_age,) # Resample to the SFH lookback grid via linear interp in log10(age). # SSP ages are in log10(Gyr); SFH lookback is in linear yr. Convert both # to log10(yr) for the interp x-axis. ssp_log_age_yr = ssp.ssp_lg_age_gyr + 9.0 log_lb_yr = jnp.log10(jnp.maximum(t_lookback_yr, 1.0)) f_surv_on_lb = jnp.interp(log_lb_yr, ssp_log_age_yr, f_surv_on_ssp) # Clamp to [0, 1]: extrapolation outside the SSP age range can drift. f_surv_on_lb = jnp.clip(f_surv_on_lb, 0.0, 1.0) # Trapezoid: M_surv = ∫ SFR(t) f_surv(t) dt return jnp.trapezoid(sfr * f_surv_on_lb, t_lookback_yr)