Source code for tengri.forward.orchestrator

# SPDX-License-Identifier: BSD-3-Clause
"""Run a list of :class:`SEDComponent` physics blocks in order.

Internal driver behind :class:`tengri.SEDModel`. Given an ordered list
of components (stellar, dust, nebular, AGN, IGM, radio, X-ray, …), it:

1. checks every component's declared inputs are produced upstream
   (:func:`validate_pipeline`),
2. threads a :class:`ForwardState` through each component's
   :meth:`SEDComponent.apply` in order, and
3. returns the resulting :class:`ForwardState` whose
   :attr:`~ForwardState.derived` carries the cross-component
   physics quantities (``L_ir``, ``lnu_age``, ``sed_nebular``, …).

Not a public API, astronomers use :class:`tengri.SEDModel` and never
touch this module directly.
"""

from __future__ import annotations

from collections.abc import Iterable, Mapping, Sequence
from typing import Any

import jax.numpy as jnp

from tengri.protocols.component import (
    BARE_NAME_ALLOWLIST,
    ComponentIOError,
    DerivedKey,
    ForwardState,
    ParamDeclaration,
    SEDComponent,
)

__all__ = [
    "default_params_dict",
    "merge_declared_parameters",
    "run_components",
    "sample_params_dict",
    "slice_params_for_component",
    "topological_sort",
    "validate_pipeline",
]


# ── Internal accessors for the output/input contract methods ───────
#
# outputs / inputs / optional_inputs are intentionally NOT part of the
# runtime-checkable SEDComponent Protocol surface (see ADR-0009,
# specifically the "drop from runtime-checkable Protocol" amendment).
# Components that have not been annotated contribute the safe empty-tuple
# default. These three helpers live at module scope so both
# validate_pipeline and topological_sort can reuse them.
#
# Renamed from ``outputs`` / ``inputs`` / ``optional_inputs``. For one
# minor version the accessors fall back to the old names with a
# ``DeprecationWarning`` so components can be migrated incrementally;
# the old names are removed in v1.0.


def _contract_method(c: SEDComponent, new: str, old: str) -> tuple[DerivedKey, ...]:
    fn = getattr(c, new, None)
    if callable(fn):
        return tuple(fn())
    legacy = getattr(c, old, None)
    if callable(legacy):
        import warnings

        warnings.warn(
            f"Component {type(c).__name__!r} declares `{old}()`; this is "
            f"deprecated and will be removed in tengri v1.0. Rename the "
            f"method to `{new}()`.",
            DeprecationWarning,
            stacklevel=3,
        )
        return tuple(legacy())
    return ()


def _outputs(c: SEDComponent) -> tuple[DerivedKey, ...]:
    return _contract_method(c, "outputs", "publishes")


def _inputs(c: SEDComponent) -> tuple[DerivedKey, ...]:
    return _contract_method(c, "inputs", "requires")


def _optional_inputs(c: SEDComponent) -> tuple[DerivedKey, ...]:
    return _contract_method(c, "optional_inputs", "requires_optional")


def components_consuming(
    component_list: Sequence[SEDComponent], key_name: str
) -> tuple[SEDComponent, ...]:
    """Components in a chain that declare ``key_name`` as an input.

    Reads the same ``inputs()`` / ``optional_inputs()`` contract the pipeline
    already validates (ADR-0009), so the answer is *derived* from the chain
    rather than restated in a second list.

    Parameters
    ----------
    component_list : sequence of SEDComponent
        The assembled component chain.
    key_name : str
        Derived-state key to look for, e.g. ``'sed_nebular'``.

    Returns
    -------
    tuple of SEDComponent
        Every component declaring ``key_name``, required or optional, in chain
        order. Empty when nothing consumes it.

    Notes
    -----
    **JIT-compatible**: not applicable, composition-time only.

    Exists so a fast path can ask "does anything still need this?" instead of
    asserting it from a hand-written census. ``sed_nebular`` was zeroed under
    the per-Q_H nebular grid on the stated grounds that its "only live
    consumers are the exact spectrum / dust-continuum paths"; the dust energy
    balance consumes it too, and a model with dust emission then re-emitted
    the stellar absorbed budget alone, 11 % low in the far-IR, with the
    posterior gradient up to 380 % wrong, silently and in float64. A census
    written next to the code it guards goes stale the first time a consumer is
    added somewhere else; a derived one cannot.
    """
    return tuple(
        c
        for c in component_list
        if any(k.name == key_name for k in (*_inputs(c), *_optional_inputs(c)))
    )


def _materialized(c: SEDComponent) -> SEDComponent:
    """A component's publishing variant, or the component itself.

    Duck-typed like the contract accessors above: a component with no
    publication shortcut needs no method and is returned by identity.
    """
    hook = getattr(c, "materialized", None)
    return hook() if callable(hook) else c


def materialized_chain(component_list: Sequence[SEDComponent]) -> tuple[SEDComponent, ...]:
    """Chain variant in which every component publishes the outputs it declares.

    A component may skip publishing an output when :func:`components_consuming`
    says nothing needs it, :class:`~tengri.components.nebular.component.NebularSEDComponent`
    zeroes ``sed_nebular`` under the per-Q_H grid, because skipping the Cue
    forward *is* the saving.

    That census reads the ADR-0009 contract, so it finds every consumer that
    declares an input and nothing else. A reader that takes a published key off
    ``state.derived`` without declaring one is invisible to it, and the forward
    state has several: ``state_to_sed_components`` behind
    ``Posterior.sed_components``, and the accumulated ``state.sed_intrinsic``
    behind ``pred.rest_sed()``. On a dust-free Cue model that cost the whole
    nebular continuum, ``sed_nebular`` exactly zero and the published SED 97 %
    short at its peak, in float64 and silently (#1673).

    Those callers ask for this chain rather than each teaching the census about
    itself. A component opts in by defining ``materialized()``; everything else
    is returned by identity.

    Parameters
    ----------
    component_list : sequence of SEDComponent
        The assembled component chain.

    Returns
    -------
    tuple of SEDComponent
        The chain in order, each publication-skipping component replaced by its
        publishing variant.

    Notes
    -----
    **JIT-compatible**: not applicable, composition-time only. Variants come
    from :func:`dataclasses.replace` over static config, so no JAX work happens
    here and the result is safe to build outside a trace and reuse inside one.
    """
    return tuple(_materialized(c) for c in component_list)


# Canonical units for every well-known cross-component derived key. Both
# publisher and consumer must declare a units string matching the table
# entry (where one exists). Adding a new derived key to the contract is
# a one-line edit here, in the same PR that introduces the publisher.
# Same friction model as ``tools/check_param_prefixes.py::ALLOWED_PREFIXES``.
_CANONICAL_UNITS: dict[str, str] = {
    # Stellar, surviving / formed mass + SFR variants
    "log_mstar": "dex",
    "log_mstar_formed": "dex",
    "sfr": "Msun/yr",
    "sfr_10myr": "Msun/yr",
    "sfr_100myr": "Msun/yr",
    # Stellar, age-resolved tensors (hard needs for nebular / dust2c)
    "L_age": "erg/s",
    "lnu_age": "erg/s/Hz",
    "lnu_interval": "erg/s/Hz",
    "ssp_ages_yr": "yr",
    "age_weights": "Msun",
    "age_weights_surviving": "Msun",
    "log_stellar_mass_scale": "dex",
    "stellar_alpha_bracket_index": "",
    "stellar_alpha_bracket_fraction": "",
    # Stellar, ionizing rate + SFH grid + chemistry history
    "nion": "photons/s",
    "log_nion": "dex",
    "log_L_lyc_age": "dex",
    "lnu_age_ion": "erg/s/Hz/Msun",
    "ssp_wave_ion": "Angstrom",
    "sfh_grid_lbt_yr": "yr",
    "sfh_timing_gyr": "Gyr",
    "sfr_history": "Msun/yr",
    "log_metallicity_history": "dex",
    # Stellar, photometry LUT (only published when
    # ``approx=WavePrecomp()`` is set on SEDModel).
    "stellar_phot_lnu_precomp": "erg/s/Hz",
    # Stellar, Taylor moment. Same conditions as
    # stellar_phot_lnu_precomp. Used by the filter-level dust integration.
    "stellar_phot_moment_precomp": "erg*Angstrom/s/Hz",
    # Stellar, age-resolved per-filter LUT (shape
    # (n_age, n_filter)). Sum over age axis equals stellar_phot_lnu_precomp.
    "stellar_phot_lnu_per_age_precomp": "erg/s/Hz",
    "stellar_phot_moment_per_age_precomp": "erg*Angstrom/s/Hz",
    # Stellar, Lyman-continuum (rest λ < 912 Å) split of the two tensors
    # above (#2439, #2427). Same units, since it is the same physical
    # quantity restricted to a sub-band of the filter.
    "stellar_phot_lnu_precomp_lyc": "erg/s/Hz",
    "stellar_phot_lnu_per_age_precomp_lyc": "erg/s/Hz",
    "stellar_phot_lnu_precomp_nolyc": "erg/s/Hz",
    "stellar_phot_lnu_per_age_precomp_nolyc": "erg/s/Hz",
    # Per-chunk Lyman-continuum multiplicative factor at the K-node
    # sub-band quadrature nodes (#2439, #2427): dimensionless, like
    # dust_young_indicator below.
    "stellar_subband_lyc_factor_precomp": "",
    # Filter pivot wavelengths (published by stellar when wave_precomp
    # is on; used by dust LUT, AGN LUT, IGM LUT downstream).
    "filter_eff_waves": "Angstrom",
    # Dust attenuation per filter. A(λ_eff) and A'(λ_eff).
    "dust_attenuation_precomp": "",
    # Exact IGM fold: the sub-band node of the IGM-folded stellar tensor, and the
    # dust screens evaluated there.
    "stellar_subband_waves_rest_igm_precomp": "Angstrom",
    "dust_bc_attenuation_subband_igm_precomp": "",
    "dust_diff_attenuation_subband_igm_precomp": "",
    "dust_attenuation_subband_igm_precomp": "",
    "dust_attenuation_slope_precomp": "1/Angstrom",
    # Two-component dust. BC + diffuse layer precompute.
    "dust_bc_attenuation_precomp": "",
    "dust_bc_attenuation_slope_precomp": "1/Angstrom",
    "dust_diff_attenuation_precomp": "",
    "dust_diff_attenuation_slope_precomp": "1/Angstrom",
    "dust_young_indicator": "",
    "dust_young_lyc_gate_subband_precomp": "",
    "dust_spec_neb_transmission_precomp": "",
    # Stellar: per-node formed-mass fraction younger than each requested age
    # boundary, shape (n_boundary, n_age) (components/stellar/age_boundary.py).
    "age_boundary_younger_fraction": "",
    "dust_diff_transmission": "",
    # Dust attenuation / emission outputs
    "L_ir": "erg/s",
    "L_absorbed": "erg/s",
    "log_L_ir": "dex",
    "log_L_absorbed": "dex",
    "log_L_ir_emergent": "dex",
    "log_L_lyc_dust": "dex",
    "log_L_lyc": "dex",
    "lyc_fdust": "",
    "lyc_fesc": "",
    "log_L_agn_bol": "dex",
    "log_L_agn_direct_los": "dex",
    "dust_attenuation_factor": "",
    "sed_dust_attenuated": "erg/s/Hz",
    "sed_dust_ir": "erg/s/Hz",
    "L_ir_emission": "erg/s",
    # AGN outputs
    "L_agn_bol": "erg/s",
    # Standalone AGN components publish their luminosities as log10 [dex re erg/s]: the erg/s
    # values (~1e44) are ``inf`` in float32 (NAMING_CONTRACT 4c).
    "log_L_agn_disc": "dex",
    "log_L_agn_disc_los": "dex",
    "log_L_agn_torus": "dex",
    "log_L_agn_torus_los": "dex",
    "log_L_agn_polar_dust": "dex",
    "log_L_agn_polar_dust_los": "dex",
    "agn_torus_frac_effective": "",
    "agn_ir_frac_saturated": "",
    "log_agn_ir_frac_window_host": "dex",
    "log_L_agn_absorbed": "dex",
    "log_L_agn_bol_ionizing": "dex",
    "agn_adaf_mdot": "",
    "log_L_agn_adaf_accretion": "dex",
    "L_agn_bol_lsun": "Lsun",
    "L_agn_direct_los_lsun": "Lsun",
    "L_agn_disc_lsun": "Lsun",
    "L_agn_disc_los_lsun": "Lsun",
    "L_agn_torus_lsun": "Lsun",
    "L_agn_torus_los_lsun": "Lsun",
    "L_agn_polar_dust_lsun": "Lsun",
    "L_agn_polar_dust_los_lsun": "Lsun",
    "L_agn_absorbed_lsun": "Lsun",
    "L_agn_bol_ionizing_lsun": "Lsun",
    "L_agn_adaf_accretion_lsun": "Lsun",
    "L_2500_intrinsic": "erg/s/Hz",
    "L_4400_intrinsic": "erg/s/Hz",
    "log_L_12um": "dex",
    "log_L_6um": "dex",
    "sed_agn": "erg/s/Hz",
    # Per-sub-block AGN SEDs (task13): composable-runner only, sum to sed_agn.
    "sed_agn_disc": "erg/s/Hz",
    "sed_agn_torus": "erg/s/Hz",
    "sed_agn_lines": "erg/s/Hz",
    "sed_agn_lines_attenuated": "erg/s/Hz",
    "sed_agn_polar": "erg/s/Hz",
    "sed_grahsp": "erg/s/Hz",
    # AGN, filter LUT (WavePrecomp).
    "agn_phot_lnu_precomp": "erg/s/Hz",
    # Nebular outputs (continuous SED in erg/s/Hz per the 2026-04-08
    # standard; discrete line/continuum primitives are Lsun per the
    # 2026-05-17 convention).
    "sed_nebular": "erg/s/Hz",
    "nebular_line_frac": "",
    "sed_shock": "erg/s/Hz",
    "line_waves": "Angstrom",
    "line_lums": "erg/s",
    "log_line_lums": "dex",
    # ``log_line_lums`` after the dust screen, published by whichever dust
    # component ran (#1867). The log form is the published one because line
    # luminosities are ~1e40-1e43 erg/s and the linear array is already ``inf``
    # in float32 (#1534/#1837).
    "log_line_lums_attenuated": "dex",
    # Nebular, photometry LUT (only non-BakedIn backends
    # publish, when ``approx=WavePrecomp()`` is set).
    "nebular_phot_lnu_precomp": "erg/s/Hz",
    # Its decomposition at the evaluation redshift (fast nebular grid only): line
    # rows (n_lines, n_filter) + continuum (n_filter,), and the rest wavelengths
    # of the line rows. Named to stay OUT of predict_via_precomp's
    # ``*_phot_lnu_precomp`` summation sweep: they decompose the total, they do
    # not add to it.
    "nebular_phot_lnu_lines_precomp": "erg/s/Hz",
    "nebular_phot_lnu_cont_precomp": "erg/s/Hz",
    "nebular_line_phot_waves_rest": "Angstrom",
    # The same bucket with the young-limit screen integrated THROUGH each band,
    # published by the dust component from the reddened continuum (#1738). Replaces
    # the lambda_eff screening of the key above rather than adding to it, the
    # ``_attenuated_`` infix is what keeps it out of the ``*_phot_lnu_precomp``
    # summation sweep in ``predict_via_precomp``.
    "nebular_phot_lnu_attenuated_precomp": "erg/s/Hz",
    "nebular_restband_lnu_attenuated_precomp": "erg/s/Hz",
    # Nebular sub-band channels served by the per-Q_H grid (see DerivedState).
    "nebular_phot_lnu_subband_precomp": "erg/s/Hz",
    "nebular_subband_waves_rest_precomp": "Angstrom",
    "nebular_restband_lnu_subband_precomp": "erg/s/Hz",
    "nebular_restband_subband_waves_precomp": "Angstrom",
    "nebular_eb_absorbed_per_qh_grid_precomp": "erg/s per (photon/s)",
    # Shock (MAPPINGS V), filter LUT. A separate additive component from the
    # photoionized nebular backend (#851), so it carries its own key (#1375).
    "shock_phot_lnu_precomp": "erg/s/Hz",
    # AGN filter LUT (WavePrecomp), attenuated by dust when agn_screen != 'none'.
    "agn_phot_lnu_attenuated_precomp": "erg/s/Hz",
    # The dense rest-grid SEDs the three attenuated band keys are integrated
    # from; the IGM weights its transmission by them (never summed).
    "sed_nebular_attenuated_precomp": "erg/s/Hz",
    "nebular_phot_lnu_subband_screened_precomp": "erg/s/Hz",
    "sed_shock_attenuated_precomp": "erg/s/Hz",
    "sed_agn_attenuated_precomp": "erg/s/Hz",
    # Spectrum LUT (published when approx=SpectrumPrecomp() is set).
    # Per-pixel rest-frame Lν at spectrum pixel centers.
    "spec_eff_waves": "Angstrom",
    "spec_sigma_v_kms": "km/s",
    "stellar_spec_lnu_precomp": "erg/s/Hz",
    "nebular_spec_lnu_precomp": "erg/s/Hz",
    "dust_spec_lnu_precomp": "erg/s/Hz",
    "agn_spec_lnu_precomp": "erg/s/Hz",
    "igm_spec_transmission_precomp": "",
    # Radio / X-ray / IGM
    "sed_radio": "erg/s/Hz",
    "sed_xray": "erg/s/Hz",
    "log_L_x_xrb_2_10": "dex",
    "log_L_x_agn_2_10": "dex",
    "log_L_x_hmxb_2_10": "dex",
    "log_L_x_lmxb_2_10": "dex",
    "log_L_x_hotgas_0p5_2": "dex",
    "log_L_x_agn_total": "dex",
    "log_Lnu_2keV_30deg": "dex",
    "igm_transmission": "",
    "igm_rest_transmission_precomp": "",
    "igm_reach_filters_precomp": "",
    # Shock (MAPPINGS path)
    "shock_log_lhalpha": "dex",
    "neb_log_no": "dex",
    # Spatial, 2D surface-brightness profile + the (x, y) kpc grid
    # underlying it. Published by spatial components (Sersic, Exponential,
    # FlatSlab, …). See architecture spec §3.3.
    "spatial_profile_2d": "",
    "spatial_grid_xy_kpc": "",
}


# Pairs of components that legitimately publish the same key as alternate
# implementations of the same role. The validator allows at most one of
# each pair to appear in a pipeline at once (handled implicitly: the
# build_components factory selects one variant by config), but does not
# treat their shared key as a duplicate-publish error.
_ALTERNATE_PUBLISHERS: frozenset[frozenset[str]] = frozenset(
    {
        frozenset({"DustSEDComponent", "DustAttenuationSEDComponent"}),
        frozenset({"AGNSEDComponent", "GRAHSPSEDComponent"}),
    }
)


def _did_you_mean(missing: str, known: Iterable[str]) -> str:
    """Return ' (Did you mean: <closest>?)' when a known key is within edit distance 2."""
    from tengri.utils.strings import closest

    best_name = closest(missing, known, max_distance=2)
    return f" (Did you mean: {best_name!r}?)" if best_name else ""


[docs] def validate_pipeline(components: Iterable[SEDComponent]) -> None: r"""Check that every component's inputs are produced by upstream components. Runs at :class:`tengri.SEDModel` construction time, once per model. Zero hot-path / JIT cost, all checks are pure-Python over the metadata returned by :meth:`SEDComponent.outputs` and :meth:`SEDComponent.inputs`. The five checks --------------- 1. **Duplicate output.** Two components publish the same key, unless they are listed in :data:`_ALTERNATE_PUBLISHERS` as alternate implementations of the same role (e.g. one-component vs two-component dust). 2. **Missing producer.** A key declared in :meth:`inputs` has no upstream :meth:`outputs`. The error message includes a ``Did you mean: ...`` suggestion when a published key is within edit distance 2; this is what catches the silent-rename hazard (``L_ir`` → ``L_dust_total`` produces a suggestion). 3. **Out-of-order producer.** A required key is published by a component that appears *after* the consumer in the pipeline list. 4. **Unit mismatch (publisher vs consumer).** Consumer's ``DerivedKey.units`` differs from publisher's. The validator refuses to silently paper over a unit disagreement; conversion is the publisher's or consumer's responsibility, at their own boundary, made explicit. 5. **Canonical-units mismatch.** Either side declares a units string that differs from :data:`_CANONICAL_UNITS` for that key (where the table has an entry). Catches the case where a *new* component independently invents a units convention, the contract pins the project-wide answer. Parameters ---------- components : iterable of SEDComponent Ordered list of pipeline components, in the order they will run. Raises ------ ComponentIOError On any of the five failure modes. The message names the offending component class, the offending key, the offending units strings, and (where applicable) a ``Did you mean: ...`` suggestion. """ component_list = list(components) # Stage 1: build the publish map (component-order indexed) and check # duplicate output + canonical-units agreement on the publish side. publishers: dict[str, tuple[int, SEDComponent, DerivedKey]] = {} for idx, component in enumerate(component_list): for key in _outputs(component): if not isinstance(key, DerivedKey): raise ComponentIOError( f"Component {type(component).__name__!r} outputs() returned " f"a non-DerivedKey entry of type {type(key).__name__}" ) canonical = _CANONICAL_UNITS.get(key.name) if canonical is not None and key.units != canonical: raise ComponentIOError( f"Component {type(component).__name__!r} outputs " f"{key.name!r} in {key.units!r} but the canonical-units " f"table pins it to {canonical!r}. Either fix the units " f"string or update _CANONICAL_UNITS in " f"tengri.forward.orchestrator (in the same PR)." ) if key.name in publishers: prior_idx, prior_comp, _ = publishers[key.name] pair = frozenset({type(prior_comp).__name__, type(component).__name__}) if pair not in _ALTERNATE_PUBLISHERS: raise ComponentIOError( f"Derived key {key.name!r} is published by both " f"{type(prior_comp).__name__!r} (at position {prior_idx}) " f"and {type(component).__name__!r} (at position {idx}). " f"Two components cannot publish the same key unless " f"they are registered as alternate implementations " f"in _ALTERNATE_PUBLISHERS." ) publishers[key.name] = (idx, component, key) # Stage 2: walk consumers in order; check each required key is # published by an *earlier* component with matching units. for idx, component in enumerate(component_list): for needed in _inputs(component): if not isinstance(needed, DerivedKey): raise ComponentIOError( f"Component {type(component).__name__!r} inputs() returned " f"a non-DerivedKey entry of type {type(needed).__name__}" ) canonical = _CANONICAL_UNITS.get(needed.name) if canonical is not None and needed.units != canonical: raise ComponentIOError( f"Component {type(component).__name__!r} needs " f"{needed.name!r} in {needed.units!r} but the " f"canonical-units table pins it to {canonical!r}." ) if needed.name not in publishers: hint = _did_you_mean(needed.name, publishers.keys()) raise ComponentIOError( f"Component {type(component).__name__!r} needs derived " f"key {needed.name!r} (in {needed.units!r}) but no " f"upstream component outputs it.{hint}" ) pub_idx, pub_comp, pub_key = publishers[needed.name] if pub_idx >= idx: raise ComponentIOError( f"Component {type(component).__name__!r} (position {idx}) " f"needs {needed.name!r} but it is published by " f"{type(pub_comp).__name__!r} at position {pub_idx}, " f"the producer must come strictly before the consumer." ) if pub_key.units != needed.units: raise ComponentIOError( f"Component {type(component).__name__!r} needs " f"{needed.name!r} in {needed.units!r} but " f"{type(pub_comp).__name__!r} outputs it in " f"{pub_key.units!r}. The contract refuses to silently " f"convert; fix one of the units strings (the canonical " f"answer is in _CANONICAL_UNITS)." ) # Stage 3: optional reads, Phase B of issue #21. Same checks as # required reads EXCEPT that a missing publisher is OK (the # consumer has a documented fallback). Catches a future publisher # rename or unit drift without forcing every pipeline to instantiate # the optional upstream component. for idx, component in enumerate(component_list): for needed in _optional_inputs(component): if not isinstance(needed, DerivedKey): raise ComponentIOError( f"Component {type(component).__name__!r} optional_inputs() " f"returned a non-DerivedKey entry of type {type(needed).__name__}" ) canonical = _CANONICAL_UNITS.get(needed.name) if canonical is not None and needed.units != canonical: raise ComponentIOError( f"Component {type(component).__name__!r} optionally needs " f"{needed.name!r} in {needed.units!r} but the " f"canonical-units table pins it to {canonical!r}." ) if needed.name not in publishers: continue # no upstream publisher → fallback applies; not an error pub_idx, pub_comp, pub_key = publishers[needed.name] if pub_idx >= idx: raise ComponentIOError( f"Component {type(component).__name__!r} (position {idx}) " f"optionally needs {needed.name!r} but it is published by " f"{type(pub_comp).__name__!r} at position {pub_idx}, " f"the producer must come strictly before the consumer." ) if pub_key.units != needed.units: raise ComponentIOError( f"Component {type(component).__name__!r} optionally needs " f"{needed.name!r} in {needed.units!r} but " f"{type(pub_comp).__name__!r} outputs it in " f"{pub_key.units!r}. The contract refuses to silently " f"convert; fix one of the units strings (the canonical " f"answer is in _CANONICAL_UNITS)." )
[docs] def topological_sort(components: Iterable[SEDComponent]) -> list[SEDComponent]: r"""Stable topological sort over the output/input dependency graph. Produces an ordering where every component appears strictly after every other component whose :meth:`outputs` it consumes via :meth:`inputs` or :meth:`optional_inputs`. Among components with no ordering constraint, the input order is preserved (stable sort). This is the inverse of :func:`validate_pipeline`'s "out-of-order publisher" check, instead of refusing pipelines whose hand-coded order violates declared dependencies, it *derives* the order from the declarations. See ADR-0006. Parameters ---------- components : iterable of SEDComponent The unordered (or arbitrarily-ordered) component list. Typically passed straight from :func:`tengri.forward.build_components` which appends in domain-grouped order; the sort tightens that into the dependency-respecting order before downstream consumers observe it. Returns ------- list of SEDComponent Topologically ordered. For the canonical pipeline (stellar, nebular, shock, dust, AGN, radio, X-ray, IGM), this reproduces the hand-coded order byte-for-byte, the snapshot test in :mod:`tests.integration.test_derived_contract_snapshots` is the regression guarantee. Raises ------ ComponentIOError If the dependency graph contains a cycle. The error message names every component still pending when the algorithm stalls typically the cycle's participants. Notes ----- **Algorithm.** Kahn's algorithm with stable tie-breaking: at each step, the lowest-input-index component whose dependencies are all already emitted is picked next. With deterministic-order producer resolution (first publisher wins on duplicates, see :data:`_ALTERNATE_PUBLISHERS`), the sort is fully deterministic. **Why both ``inputs`` and ``optional_inputs``.** A hard requirement establishes ordering by definition. An optional requirement *also* establishes ordering when the publisher is present: the consumer reads from ``state.derived`` with a fallback, so it can only read meaningful data if the publisher has already written. The validator enforces strict-before for both flavors (ADR-0004 Phase B); the sort must too, else :func:`validate_pipeline` would reject sort output. **Zero JIT cost.** Runs once at :func:`build_components` time. """ component_list = list(components) n = len(component_list) # Map each published derived-key name to the index of its publisher. # First-publisher-wins matches the validator's # ``_ALTERNATE_PUBLISHERS`` resolution: when two components publish # the same key as alternate implementations of the same role, the # first one in the input list takes precedence. producer: dict[str, int] = {} for i, c in enumerate(component_list): for key in _outputs(c): producer.setdefault(key.name, i) # Build incoming edges per node. An edge i ← j means "i needs # something j outputs, so j must come before i". Both hard and # optional needs contribute. deps: list[set[int]] = [set() for _ in range(n)] for i, c in enumerate(component_list): for needed in (*_inputs(c), *_optional_inputs(c)): pub = producer.get(needed.name) if pub is not None and pub != i: deps[i].add(pub) # Kahn's algorithm with stable tie-break. emitted: list[int] = [] emitted_set: set[int] = set() remaining = set(range(n)) while remaining: # Lowest input-order index whose dependencies are all already # emitted. Linear scan; n is tiny (typically 7) so this is fine. picked: int | None = None for i in range(n): if i in remaining and deps[i].issubset(emitted_set): picked = i break if picked is None: pending_names = [type(component_list[i]).__name__ for i in sorted(remaining)] raise ComponentIOError( f"Topological sort failed: cycle in output/input graph " f"involving {pending_names!r}. Every inputs() / " f"optional_inputs() declaration must be satisfiable in some " f"linear order, check the offending components." ) emitted.append(picked) emitted_set.add(picked) remaining.remove(picked) return [component_list[i] for i in emitted]
def slice_params_for_component( component: SEDComponent, params: Mapping[str, jnp.ndarray], ) -> dict[str, jnp.ndarray]: r"""Return params visible to ``component``. A component sees: 1. Every key starting with its :attr:`SEDComponent.parameter_prefix`. 2. Every key in :data:`BARE_NAME_ALLOWLIST` (currently ``redshift``). Notes ----- A component with ``parameter_prefix == ""`` would see *everything* via rule 1, that's why ``""`` is forbidden by the contract test. Components that need bare names must declare a non-empty prefix and rely on the allowlist for shared scalars. """ prefix = component.parameter_prefix # ``parameter_prefix`` may be a single str or a tuple of strings (e.g. # StellarSEDComponent owns ("sfh_", "met_", "chem_")). Normalize to # tuple so downstream logic handles one shape only. prefixes = (prefix,) if isinstance(prefix, str) else tuple(prefix) if "" in prefixes or len(prefixes) == 0: raise ValueError( f"Component {component.name!r} declares an empty parameter_prefix. " f"Use the BARE_NAME_ALLOWLIST for shared scalars (e.g. redshift) " f"and give the component at least one non-empty prefix." ) sliced = {k: v for k, v in params.items() if any(k.startswith(p) for p in prefixes)} for bare in BARE_NAME_ALLOWLIST: if bare in params: sliced[bare] = params[bare] return sliced
[docs] def merge_declared_parameters( components: Iterable[SEDComponent], ) -> dict[str, Any]: r"""Flatten ``declared_parameters()`` from each component into one prior dict. Each :class:`SEDComponent` owns a list of :class:`ParamDeclaration` entries (name + prior + description). This helper validates that: 1. Every declared name starts with the owning component's :attr:`SEDComponent.parameter_prefix` *or* is in :data:`BARE_NAME_ALLOWLIST`. 2. No two components declare the same parameter name (a collision would make the orchestrator's prefix-slicing ambiguous). The output maps each parameter name to its prior, suitable for spreading into :class:`tengri.Parameters` once the component-driven builder in :mod:`tengri.parameters.parameters` lands. Parameters ---------- components : iterable of SEDComponent Adapters whose declarations should be merged. Returns ------- dict mapping str -> Distribution Parameter name -> prior. Order is preserved by component order and within-component declaration order. Raises ------ ValueError If a name violates the prefix rule or two components declare the same name. """ out: dict[str, Any] = {} owners: dict[str, str] = {} # name -> first owner (for collision msg) for component in components: prefix = component.parameter_prefix prefixes = (prefix,) if isinstance(prefix, str) else tuple(prefix) for decl in component.declared_parameters(): if not isinstance(decl, ParamDeclaration): raise TypeError( f"Component {component.name!r} declared a non-ParamDeclaration " f"entry of type {type(decl).__name__}" ) if ( not any(decl.name.startswith(p) for p in prefixes) and decl.name not in BARE_NAME_ALLOWLIST ): raise ValueError( f"Component {component.name!r} declared parameter " f"{decl.name!r} which violates the prefix rule " f"(expected one of prefixes {prefixes!r} or a name in " f"BARE_NAME_ALLOWLIST {tuple(BARE_NAME_ALLOWLIST)})." ) if decl.name in out: raise ValueError( f"Parameter {decl.name!r} is declared by both " f"{owners[decl.name]!r} and {component.name!r}, " f"two components cannot own the same parameter." ) out[decl.name] = decl.prior owners[decl.name] = component.name return out
def sample_params_dict( components: Iterable[SEDComponent], key: jnp.ndarray, overrides: Mapping[str, Any] | None = None, ) -> dict[str, jnp.ndarray]: r"""Sample one params dict from each component's declared priors. Closes the loop ``[components] → declarations → params dict → run_components``: a user can compose adapters, sample a draw, and immediately run the pipeline without manually typing a parameter dict. Parameters ---------- components : iterable of SEDComponent Adapters whose declared priors should be sampled. key : jax.Array PRNG key. Split internally with :func:`jax.random.split` once per declared parameter. overrides : mapping, optional Fixed values that override the prior draw. Useful for pinning ``redshift`` or other scalars during a forward pass without building a custom prior. Returns ------- dict mapping str -> jnp.ndarray Parameter name -> drawn value, ready to feed :func:`run_components`. Notes ----- Not for inference, the priors here come from registry defaults, not user-tuned posteriors. Use :class:`tengri.Parameters` for proper inference workflows. This helper is for prior-predictive smoke tests and notebook demos. """ import jax merged = merge_declared_parameters(components) overrides = overrides or {} keys = jax.random.split(key, max(len(merged), 1)) out: dict[str, jnp.ndarray] = {} for (name, prior), subkey in zip(merged.items(), keys, strict=False): if name in overrides: out[name] = jnp.asarray(overrides[name]) else: out[name] = jnp.asarray(prior.sample(subkey)) # Bare-name allowlist entries that no component declared but the # caller still wants threaded through (typically redshift). for bare in BARE_NAME_ALLOWLIST: if bare in overrides and bare not in out: out[bare] = jnp.asarray(overrides[bare]) return out def default_params_dict( components: Iterable[SEDComponent], overrides: Mapping[str, Any] | None = None, ) -> dict[str, jnp.ndarray]: r"""Build one params dict from each component's declared *defaults*. The deterministic sibling of :func:`sample_params_dict`: same loop ``[components] -> declarations -> params dict -> run_components``, but each value is read off the prior's ``default`` instead of drawn from it. Use it wherever a params dict is wanted for the whole of a component chain, pipeline tests, notebook demos, a forward pass at the declared fiducial. The alternative is a literal, and a literal is a copy of the declaration that cannot follow it: eight fixtures listed the ``xray_*`` parameters by hand and broke the day ``xray_det_hmxb`` gained a reader, because that one is declared ``Uniform(-2, 2, default=0.0)`` -- free, so absent from ``spec.get_fixed_values()`` -- while the siblings they *had* listed are ``Fixed`` (#1832). Reading the declaration treats free and fixed alike, and reaches the ones nobody thought to copy. Parameters ---------- components : iterable of SEDComponent Adapters whose declared defaults should be collected. overrides : mapping, optional Values that replace the declared default. Also the only way to supply a :data:`BARE_NAME_ALLOWLIST` name (typically ``redshift``), which no component declares. Returns ------- dict mapping str -> jnp.ndarray Parameter name -> declared default, ready to feed :func:`run_components`. Raises ------ ValueError If a declared prior carries no ``default`` to read. Loudly, and naming the parameter: silently omitting it would hand back a dict missing a key the owning component indexes, which is the failure this function exists to prevent. Notes ----- **JIT-compatible**: not applicable -- builds a dict of concrete scalars, intended to be constructed outside any transform and passed in. Deliberately *not* an auto-fill inside :func:`run_components`. A parameter nobody supplies must still raise: ``xray_det_hmxb`` and ``xray_det_lmxb`` were declared, free, and read by nothing for as long as they were because a neutral default made the missing handoff look wired (#1706). Asking for the declared defaults is an explicit request; being handed them behind your back is the bug. See Also -------- sample_params_dict : the same loop, drawing from the priors instead. tengri.protocols.component.declared_default : one parameter, for a function signature default. """ merged = merge_declared_parameters(components) overrides = overrides or {} out: dict[str, jnp.ndarray] = {} for name, prior in merged.items(): if name in overrides: out[name] = jnp.asarray(overrides[name]) continue default = getattr(prior, "default", None) if default is None: raise ValueError( f"{name!r} is declared with {type(prior).__name__} but carries no " f"default to read, so no value can be supplied for it. Give the " f"declaration a `default=`, or pass overrides={{{name!r}: ...}}." ) out[name] = jnp.asarray(default) # Bare-name allowlist entries that no component declared but the # caller still wants threaded through (typically redshift). for bare in BARE_NAME_ALLOWLIST: if bare in overrides and bare not in out: out[bare] = jnp.asarray(overrides[bare]) return out def _name_missing_parameter( component: SEDComponent, sliced: Mapping[str, Any], exc: KeyError, ) -> KeyError | None: """A ``KeyError`` naming the parameter and its owner, or ``None`` to re-raise. A component reads its parameters by indexing (``params["xray_det_hmxb"]``), deliberately: a ``.get(..., 0.0)`` default is what let two declared knobs go unread for months, because a dict missing them looked complete (#1706). The cost is that the omission surfaces as a bare ``KeyError: 'xray_det_hmxb'`` from wherever the component happened to read first, which is what all fifty of #1832's failures looked like. Returns ``None`` (meaning "not mine, re-raise unchanged") unless the key is a parameter this component *declares* and the sliced dict genuinely lacks. A guard that relabels every internal dict lookup would turn real bugs into confident wrong explanations, which is worse than the bare message. Parameters ---------- component : SEDComponent The component whose ``apply`` raised. sliced : mapping The prefix-sliced params the component was given. exc : KeyError The original exception. Returns ------- KeyError or None The replacement to raise ``from exc``, or ``None`` to re-raise. Notes ----- **JIT-compatible**: yes, a missing key fails at trace time, before any array work, so this runs under ``jax.jit`` exactly as it does eagerly. The type stays ``KeyError``: :meth:`SEDModel.predict` already raises one carrying a full message for the same condition, and callers catch it. """ key = exc.args[0] if exc.args else None if not isinstance(key, str) or key in sliced: return None declared = getattr(component, "declared_parameters", None) names = {d.name for d in declared()} if callable(declared) else set() if key not in names: return None return KeyError( f"Component {getattr(component, 'name', type(component).__name__)!r} requires " f"parameter {key!r}, which is not in the params dict. The component declares " f"it, and it is free by default, so supplying a value is the caller's job. " f"Pass it explicitly, or take every declared default at once with " f"tengri.pipeline.default_params_dict([...])." ) def wire_age_boundaries(components: Iterable[SEDComponent]) -> list[SEDComponent]: """Give the stellar component the age boundaries its attenuator reads. An attenuator with a young/old split declares ``config.age_boundaries_yr`` and ``config.age_boundary_width_dex``; the stellar component publishes the per-node younger-than-boundary mass fractions only for boundaries its own config names. This is the one place a component list is reconciled, so a chain built by hand gets the same stellar configuration as one built by ``SEDModel``. Returns a new list; a stellar component whose boundaries already match is passed through unchanged. Parameters ---------- components : iterable of SEDComponent Ordered component list. Returns ------- list of SEDComponent The same components, with the stellar one replaced by a copy carrying the attenuator's boundaries when they differ. Raises ------ ValueError If two attenuators in the chain request different boundaries. """ from dataclasses import replace from tengri.components.stellar.component import StellarSEDComponent components = list(components) requests = { (tuple(c.config.age_boundaries_yr), float(c.config.age_boundary_width_dex)) for c in components if not isinstance(c, StellarSEDComponent) and hasattr(getattr(c, "config", None), "age_boundaries_yr") } if not requests: return components if len(requests) > 1: raise ValueError( f"attenuators in one chain request different age boundaries: {sorted(requests)}" ) ((boundaries, width),) = requests # An attenuator evaluating its age mixture as interval sums # (``age_mixture='grouped'``) reads the stellar component's per-interval # spectra instead of the per-age cube. grouped = any( getattr(getattr(c, "config", None), "age_mixture", "per_node") == "grouped" for c in components if not isinstance(c, StellarSEDComponent) ) wired = [] for c in components: if isinstance(c, StellarSEDComponent) and ( tuple(c.config.age_boundaries_yr) != boundaries or float(c.config.age_boundary_width_dex) != width or bool(c.config.publish_interval_spectra) != grouped ): c = replace( c, config=replace( c.config, age_boundaries_yr=boundaries, age_boundary_width_dex=width, publish_interval_spectra=grouped, ), ) wired.append(c) return wired
[docs] def run_components( components: Iterable[SEDComponent], state: ForwardState, params: Mapping[str, jnp.ndarray], ssp_data: Any | None = None, template_data: Any | None = None, ztable_data: Any | None = None, ) -> ForwardState: r"""Thread ``state`` through ``components`` in order. Parameters ---------- components : iterable of SEDComponent Ordered list. Each component reads what it needs from ``state`` and returns a *new* :class:`ForwardState`. state : ForwardState Initial pipeline state. Typically carries just ``wave`` and any seed values (e.g. ``sed_observed`` already populated). params : mapping Full parameter dict. Each component sees only its prefix-matched slice plus the bare-name allowlist. ssp_data : Any | None, optional SSP stellar population synthesis grid. When provided, is passed to each component's ``apply()`` method as a JIT runtime parameter. Components that do not need it should ignore the argument. Default ``None`` means components rely on their internal ``self.ssp_data``. template_data : Any | None, optional Nebular backend grids and weights. When provided, is passed to each component's ``apply()`` method as a JIT runtime parameter. Components that do not need it should ignore the argument. Default ``None`` means components rely on their internal template data. ztable_data : Any | None, optional Precomputed photometric redshift table for stellar component. When provided, is passed to each component's ``apply()`` method as a JIT runtime parameter instead of closure capture, preventing XLA from materializing it as a constant. Default ``None`` means components rely on their internal z-table. Returns ------- ForwardState Final state after all components have applied. Raises ------ ComponentIOError If, after every component has applied, the final ``state.derived._extras`` is non-empty, i.e. some component's ``apply()`` slipped data through the ``DerivedState``'s opt-in spillover instead of using ``state.derived.with_(X=value)`` (ADR-0007 Phase 3). The snapshot test (:mod:`tests.integration.test_derived_contract_snapshots`) catches this for the 3 snapshotted recipes; the runtime check here broadens the guard to every hand-rolled component list. Bypass with the env var ``TENGRI_ALLOW_DERIVED_EXTRAS=1``, useful during in-flight migrations or when external user code explicitly attaches non-canonical keys via ``DerivedState.from_dict(..., allow_extras=True)``. Not for production code. """ import os as _os for component in wire_age_boundaries(components): sliced = slice_params_for_component(component, params) try: state = component.apply( state, sliced, ssp_data=ssp_data, template_data=template_data, ztable_data=ztable_data, ) except KeyError as exc: named = _name_missing_parameter(component, sliced, exc) if named is None: raise raise named from exc # ADR-0007 Phase 4 invariant, strict typed-only writes (#64 # added the same check at the snapshot-test boundary; this one # makes the guard apply to *every* run_components call regardless # of whether the pipeline is snapshotted). if _os.environ.get("TENGRI_ALLOW_DERIVED_EXTRAS") != "1": extras = getattr(state.derived, "_extras", None) if extras: raise ComponentIOError( f"run_components: state.derived._extras is non-empty after the " f"forward pass: {list(extras.keys())!r}. Some component's " f"apply() is writing through DerivedState's opt-in spillover " f"instead of the typed ``state.derived.with_(X=value)`` API " f"(ADR-0007 Phase 3). Migrate the offending write site to use " f"``with_(...)``, add a matching field to DerivedState, or " f"set TENGRI_ALLOW_DERIVED_EXTRAS=1 for debugging only." ) return state