Source code for tengri.components.agn.skirtor_agnfitter_1p

# SPDX-License-Identifier: BSD-3-Clause
r"""SKIRTOR-averaged (mean_1p) clumpy torus library (Stalevski et al. 2016).

One-parameter torus library interpolated differentiably in inclination over a
precomputed HDF5 grid derived from AGNfitter-rX's ``SKIRTOR_mean_1p.pickle``. The
sightline is the model's one inclination, ``agn_cos_inc``.

This is the coarsest of the three SKIRTOR-AGNfitter reductions tengri ships:
:mod:`tengri.components.agn.skirtor_agnfitter` (``SKIRTOR_mean_3p``, three
axes) is the AGNfitter-faithful default; :mod:`tengri.components.agn.skirtor_agnfitter_2p`
(``SKIRTOR_mean_2p``) adds the opening-angle axis; this module averages over
both opening angle and optical depth, retaining only inclination. All three
share the same inclination axis convention and extent (0-90 deg).

Axis semantics
--------------
``incl_axis``
    Inclination angle :math:`i` measured from the polar axis [deg]. Range: 0-90 deg.
    0 = face-on, 90 = edge-on. Keyed by ``agn_cos_inc`` (:math:`\cos i`) through
    ``_skirtor_agnfitter_sightline.skirtor_incl_from_cos_inc``,
    :math:`i = \arccos(\cos i)`.

Runtime normalization
---------------------
SKIRTOR computes every model for one central source luminosity (Stalevski et al. 2016,
Sect. 2.1), so its records share one scale across inclination. The stored inclination
power ratios equal those of the SKIRTOR v3 records (multiplied back by their ``norm``)
averaged over tau, p, q, opening angle and radius ratio to 0.4 % at every node, so the
reduction is on that scale (face-on/edge-on 2.12).
The template is therefore emitted as two factors
(``_torus_inclination.torus_lnu_anisotropic``): the shape of the records normalized to
unit power and interpolated as before, and the records' own powers over their model's
mean, a scalar table interpolated with the same node-exact PCHIP. The angle-integrated
torus power is ``L_bol * agn_torus_frac``, each sightline keeps the library's flux
relative to the others, and the shape between nodes is the per-sightline one exactly.

References
----------
.. [1] M. Stalevski et al., "3D radiative transfer modeling of the dusty
   torus around AGN, the influence of clumping," MNRAS, 420, 2756 (2012).
   arXiv:1109.1286. https://doi.org/10.1111/j.1365-2966.2011.19775.x
.. [2] M. Stalevski, C. Ricci, Y. Ueda, P. Lira, J. Fritz, and M. Baes,
   "The dust covering factor in active galactic nuclei," MNRAS, 458,
   2288 (2016). arXiv:1602.06954. bibcode:2016MNRAS.458.2288S.
   https://doi.org/10.1093/mnras/stw444
.. [3] L. N. Martinez-Ramirez, et al., "AGNFITTER-RX: Modeling the
   radio-to-X-ray spectral energy distributions of AGNs," A&A 688, A46
   (2024). arXiv:2405.12111.
"""

from __future__ import annotations

import functools
from collections.abc import Callable

import jax.numpy as jnp
import numpy as np

from tengri.components.agn._params import (
    DEFAULT_AGN_COS_INC,
    DEFAULT_AGN_LOG_LBOL,
    DEFAULT_AGN_TORUS_FRAC,
)
from tengri.components.agn._skirtor_agnfitter_sightline import (
    accepts_retired_incl_skirtor,
    skirtor_incl_from_cos_inc,
)
from tengri.components.agn._template_grid import (
    TorusTemplateGrid,
    cache_per_float_dtype,
    loaded_template,
)
from tengri.components.agn._torus_inclination import (
    TorusInclination,
    anisotropy_values,
    torus_lnu_anisotropic,
)

#: The library's inclination axis: the records share one radiative-transfer scale
#: across inclination, so the template carries its anisotropy as a scalar factor
#: (``_torus_inclination.torus_lnu_anisotropic``).
TORUS_INCLINATION = TorusInclination(axis=0, variable="incl_deg")

__all__ = [
    "TORUS_INCLINATION",
    "create_skirtor_agnfitter_1p_from_grid",
    "skirtor_agnfitter_1p_sed",
]


def _load_skirtor_agnfitter_1p_arrays(grid_path: str) -> dict:
    """Load raw numpy arrays from the ``SKIRTOR_mean_1p`` grid HDF5.

    Parameters
    ----------
    grid_path : str
        Path to ``skirtor_mean1p_torus_grid.h5``.

    Returns
    -------
    dict
        Keys ``incl_axis``, ``wavelength``, and ``template``.

    Notes
    -----
    **JIT-compatible**: no, performs HDF5 I/O at grid-load time.
    """
    import h5py

    with h5py.File(grid_path, "r") as f:
        g = f["skirtor_mean1p"]
        return {
            "incl_axis": np.asarray(g["incl_axis"][:], dtype=np.float64),
            "wavelength": np.asarray(g["wavelength"][:], dtype=np.float64),
            "template": np.asarray(g["template"][:], dtype=np.float64),
        }


@cache_per_float_dtype
def load_skirtor_agnfitter_1p_grid(grid_path: str) -> TorusTemplateGrid:
    """Load a ``SKIRTOR_mean_1p`` grid HDF5 into a :class:`TorusTemplateGrid` pytree.

    Parameters
    ----------
    grid_path : str
        Path to ``skirtor_mean1p_torus_grid.h5``.

    Returns
    -------
    TorusTemplateGrid
        Template arrays with a single ``incl`` axis (degrees), as numpy
        arrays.

    Raises
    ------
    FileNotFoundError
        If ``grid_path`` does not exist.
    KeyError
        If the grid file is missing the expected ``/skirtor_mean1p``
        datasets.

    Notes
    -----
    **JIT-compatible**: no, performs HDF5 I/O. Call outside the trace and
    pass the result in as an argument.
    """
    raw = _load_skirtor_agnfitter_1p_arrays(grid_path)
    axes = (np.asarray(raw["incl_axis"]),)
    return TorusTemplateGrid(
        template=loaded_template(raw["template"]),
        axes=axes,
        wave_grid=np.asarray(raw["wavelength"]),
        anisotropy=anisotropy_values(raw["template"], raw["wavelength"], axes, TORUS_INCLINATION),
    )


@accepts_retired_incl_skirtor
def skirtor_agnfitter_1p_sed_from_grid(
    grid: TorusTemplateGrid,
    wavelength: jnp.ndarray,
    agn_log_lbol: float = DEFAULT_AGN_LOG_LBOL,
    agn_cos_inc: float = DEFAULT_AGN_COS_INC,
    agn_torus_frac: float = DEFAULT_AGN_TORUS_FRAC,
    **_kwargs,
) -> jnp.ndarray:
    r"""``SKIRTOR_mean_1p`` torus SED at a single inclination.

    Parameters
    ----------
    wavelength : array_like, shape (n_wave,)
        Rest-frame wavelength grid. [Å]
    agn_log_lbol : float, optional
        ``log10(L_bol / L_sun)``. Default 10.0.
    agn_cos_inc : float, optional
        :math:`\cos i`, the model's one inclination, :math:`i` from the polar axis
        (1 = face-on) [dimensionless]. Defaults to the declared ``agn_cos_inc`` default,
        ``cos(30 deg)``. The library is keyed at :math:`i = \arccos(\cos i)` [deg].
        The retired ``agn_incl_skirtor`` [deg] is translated with a
        ``DeprecationWarning``.
    agn_torus_frac : float, optional
        Fraction of L_bol reprocessed by the torus. Default 0.5.

    Returns
    -------
    ndarray, shape (n_wave,)
        Spectral luminosity density. [erg/s/Hz]

    Notes
    -----
    .. math::

        L_\nu(\lambda;\,\mu) = L_{\rm bol}\,f_{\rm torus}\,
                               \frac{T(\lambda;\,\mu)}{\int T(\nu;\,\mu)\,\mathrm{d}\nu}\,
                               \frac{a(\mu)}{\bar a}, \qquad
        \bar a = \int_0^1 a(\mu)\,\mathrm{d}\mu,

    where :math:`T` is the tabulated template at the parameter point (node-exact PCHIP),
    :math:`\mu = \cos i`, the frequency integral is that of the interpolant on the
    template's own wavelength nodes, and :math:`a` is each record's own power over its
    model's mean, interpolated with the same PCHIP. The angle-integrated power is
    :math:`f_{\rm torus} L_{\rm bol}`; along :math:`\mu` the torus carries
    :math:`f_{\rm torus} L_{\rm bol}\,a(\mu)/\bar a`.

    **JIT-compatible**: yes.

    **Approximation**: the grid is drawn from the ``SKIRTOR_mean_1p``
    library (Stalevski et al. 2016 [1]_, [2]_) as packaged by
    AGNfitter-rX [3]_, which averages out opening angle, clumpiness
    (p, q), and optical depth of the full SKIRTOR parameter space.
    """
    # Anisotropy restored here (#2851). Provenance: AGNfitter-rX SKIRTOR_mean_1p.pickle
    # (tag AGNfitter-rX_v0.1, models/TORUS), field 'SED' per inclination, repackaged in
    # skirtor_mean1p_torus_grid.h5 'template'; its power ratios between inclinations match
    # the SKIRTOR v3 records (the CIGALE-lineage dust_emission x spectra/norm; one central
    # source luminosity per model, Stalevski et al. 2016 Sect. 2.1) averaged over tau, p,
    # q, opening angle and R to 0.4 % at every node. Sightline: 'incl_axis' is the
    # inclination i from the polar axis [deg] (0 face-on), ascending, axis 0.
    return torus_lnu_anisotropic(
        grid,
        wavelength,
        (skirtor_incl_from_cos_inc(agn_cos_inc),),
        TORUS_INCLINATION,
        agn_log_lbol=agn_log_lbol,
        agn_torus_frac=agn_torus_frac,
    )


[docs] def create_skirtor_agnfitter_1p_from_grid(grid_path: str) -> Callable: """Load a ``SKIRTOR_mean_1p`` grid and bind it to the SED evaluator. Parameters ---------- grid_path : str Path to ``skirtor_mean1p_torus_grid.h5``. Returns ------- callable """ return functools.partial( skirtor_agnfitter_1p_sed_from_grid, load_skirtor_agnfitter_1p_grid(grid_path) )
_GRID_SEARCH_PATHS: tuple[str, ...] = ( "data/skirtor_mean1p_torus_grid.h5", "skirtor_mean1p_torus_grid.h5", ) _NOT_FOUND_MSG = ( "SKIRTOR_mean_1p torus grid not found. Build it with: " "python scripts/build_agnfitter_torus_reductions.py --which skirtor_mean1p" ) def _find_skirtor_agnfitter_1p_grid() -> str: from tengri._data_setup import require_data return require_data(_GRID_SEARCH_PATHS[-1], _NOT_FOUND_MSG) def load_skirtor_agnfitter_1p_default_grid() -> TorusTemplateGrid: """Load the packaged ``SKIRTOR_mean_1p`` grid pytree (discovery + cache). This is the ``template_loader`` the torus block registers. Returns ------- TorusTemplateGrid Raises ------ FileNotFoundError If no ``SKIRTOR_mean_1p`` grid HDF5 is present on disk. """ return load_skirtor_agnfitter_1p_grid(_find_skirtor_agnfitter_1p_grid()) @cache_per_float_dtype def _load_skirtor_agnfitter_1p_default() -> Callable: return create_skirtor_agnfitter_1p_from_grid(_find_skirtor_agnfitter_1p_grid())
[docs] def skirtor_agnfitter_1p_sed( *args, _template: TorusTemplateGrid | None = None, **kwargs ) -> jnp.ndarray: r"""``SKIRTOR_mean_1p`` torus (auto-loaded from the packaged HDF5 grid). Parameters ---------- wavelength : array_like, shape (n_wave,) Rest-frame wavelength. [Å] agn_log_lbol : float, optional ``log10(L_bol / L_sun)``. Default 10.0. agn_cos_inc : float, optional :math:`\cos i`, the model's one inclination (1 = face-on) [dimensionless]. Default ``cos(30 deg)``. agn_torus_frac : float, optional Torus reprocessing fraction. Default 0.5. **kwargs Accepted and ignored for unified-dispatch compatibility. Returns ------- ndarray, shape (n_wave,) Torus SED [erg/s/Hz]. Notes ----- This function auto-discovers the grid file from the package data directory or the current working directory. To use a non-standard grid location, call :func:`create_skirtor_agnfitter_1p_from_grid` directly. """ if _template is not None: return skirtor_agnfitter_1p_sed_from_grid(_template, *args, **kwargs) fn = _load_skirtor_agnfitter_1p_default() return fn(*args, **kwargs)