Source code for tengri.components.agn.nenkova_agnfitter

# SPDX-License-Identifier: BSD-3-Clause
"""Nenkova et al. (2008) CLUMPY AGN torus from AGNfitter-rX.

One-parameter semi-empirical torus library keyed on inclination angle
(``agn_cos_inc``). The grid (9 bins from 10° to 90° inclination, averaged
over CLUMPY model parameters) is interpolated with node-exact monotone-cubic
(PCHIP) interpolation so gradients flow cleanly through ``agn_cos_inc``
during HMC / geoVI / MAP inference.

Grid provenance
---------------
Template data published with AGNfitter-rX (Martínez-Ramírez et al. 2024)
: see ``scripts/build_nk08_agnfitter_grid.py``. The AGNfitter-rX pickle
stores per-inclination ``log10(nu / Hz)`` and ``F_nu`` arrays; the build
script converts to ascending-wavelength [Å] and common-grid, then emits
``nenkova_agnfitter_torus_grid.h5``. This runtime module only consumes
the HDF5, not the pickle.

Runtime normalization
---------------------
CLUMPY fluxes are normalized to the bolometric AGN flux ``F_AGN = L / 4 pi D^2`` in
every direction (Nenkova et al. 2008, ApJ 685, 160, Sect. 2 and 3.6), so the records
share one scale across inclination; the AGNfitter-rX reductions are linear means on it
(``NK0_mean_3p`` averaged over its optical-depth axis is ``NK0_mean_2p`` to 5e-4).
The template is therefore emitted as two factors
(``_torus_inclination.torus_lnu_anisotropic``): the shape of the records normalized to
unit power and interpolated as before, and the records' own powers over their model's
mean, a scalar table interpolated with the same node-exact PCHIP. The angle-integrated
torus power is ``L_bol * agn_torus_frac``, each sightline keeps the library's flux
relative to the others, and the shape between nodes is the per-sightline one exactly.

References
----------
.. [1] M. Nenkova, M. M. Sirocky, R. Nikutta, Z. Ivezic, and M. Elitzur,
   "AGN Dusty Tori. II. Observational Implications of Clumpiness," ApJ 685,
   160 (2008). doi:10.1086/590483. arXiv:0806.0512. bibcode:2008ApJ...685..160N.
.. [2] L. N. Martínez-Ramírez et al., "AGNfitter-rx: Modeling the
   radio-to-X-ray spectral energy distributions of AGNs," A&A 688, A46
   (2024). arXiv:2405.12111. DOI: 10.1051/0004-6361/202449329.
"""

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._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="cos_inc")

__all__ = [
    "TORUS_INCLINATION",
    "create_nenkova_agnfitter_from_grid",
    "nenkova_agnfitter_sed",
]


def _load_nenkova_agnfitter_arrays(grid_path: str) -> dict:
    """Load raw numpy arrays from a Nenkova AGNfitter grid HDF5.

    Parameters
    ----------
    grid_path : str
        Path to ``nenkova_agnfitter_torus_grid.h5`` produced by
        ``scripts/build_nk08_agnfitter_grid.py``.

    Returns
    -------
    dict
        Keys ``incl_axis`` (n_incl,) in degrees, ``wavelength`` (n_wave,),
        and ``template`` (n_incl, n_wave).

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

    with h5py.File(grid_path, "r") as f:
        g = f["nenkova_agnfitter"]
        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_nenkova_agnfitter_grid(grid_path: str) -> TorusTemplateGrid:
    """Load a Nenkova AGNfitter grid HDF5 into a :class:`TorusTemplateGrid` pytree.

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

    Returns
    -------
    TorusTemplateGrid
        Template arrays with a single ``cos_inc`` axis, as numpy arrays.

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

    Notes
    -----
    **JIT-compatible**: no, performs HDF5 I/O. Call outside the trace and
    pass the result in as an argument.
    """
    raw = _load_nenkova_agnfitter_arrays(grid_path)
    grid_np = np.asarray(raw["template"], dtype=np.float64)
    wave_np = np.asarray(raw["wavelength"], dtype=np.float64)
    incl_deg_np = np.asarray(raw["incl_axis"], dtype=np.float64)

    # Convert inclination (deg, ascending) to cos(incl), which is descending.
    # Reorder both axis and template so cos(incl) is ascending (consistent
    # with cat3d_wind pattern).
    cos_inc_axis_np = np.cos(np.deg2rad(incl_deg_np))
    order = np.argsort(cos_inc_axis_np)
    cos_inc_axis_np = cos_inc_axis_np[order]
    template_reordered_np = grid_np[order]
    return TorusTemplateGrid(
        template=loaded_template(template_reordered_np),
        axes=(cos_inc_axis_np,),
        wave_grid=wave_np,
        anisotropy=anisotropy_values(
            template_reordered_np, wave_np, (cos_inc_axis_np,), TORUS_INCLINATION
        ),
    )


def nenkova_agnfitter_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"""Nenkova+08 (AGNfitter-rX) torus SED at a single inclination.

    Parameters
    ----------
    wavelength : array_like, shape (n_wave,)
        Rest-frame wavelength grid. [Å]
    agn_log_lbol : float, optional
        Bolometric luminosity, ``log10(L_bol / L_sun)``. Default 10.0.
    agn_cos_inc : float, optional
        Cosine of inclination (1 = face-on). Default 0.5.
    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 template is semi-empirical (Nenkova et al.
    2008 [1]_), based on CLUMPY radiative-transfer models averaged
    over secondary parameters. For studies requiring the full parameter
    space (N_0, σ, τ_V, Y, q), use the original CLUMPY library
    directly, not this averaged projection.
    """
    # Anisotropy restored here (#2851). Provenance: AGNfitter-rX NK0_mean_1p.pickle (tag
    # AGNfitter-rX_v0.1, models/TORUS), field 'SED' per inclination, repackaged in
    # nenkova_agnfitter_torus_grid.h5 'template'; CLUMPY fluxes are normalized to F_AGN = L / 4 pi
    # D^2 in every
    # direction (Nenkova et al. 2008, ApJ 685, 160, Sect. 2 and 3.6), so the records share
    # one scale. Sightline: 'incl_axis' is the inclination i from the polar axis [deg]
    # (0 face-on), stored here as cos i, ascending, axis 0.
    return torus_lnu_anisotropic(
        grid,
        wavelength,
        (agn_cos_inc,),
        TORUS_INCLINATION,
        agn_log_lbol=agn_log_lbol,
        agn_torus_frac=agn_torus_frac,
    )


[docs] def create_nenkova_agnfitter_from_grid(grid_path: str) -> Callable: """Load a Nenkova AGNfitter grid and bind it to the SED evaluator. Retained for callers holding the historical closure API; new code should prefer :func:`load_nenkova_agnfitter_grid` plus :func:`nenkova_agnfitter_sed_from_grid`, which keeps the grid threadable. Parameters ---------- grid_path : str Path to ``nenkova_agnfitter_torus_grid.h5``. Returns ------- callable """ return functools.partial( nenkova_agnfitter_sed_from_grid, load_nenkova_agnfitter_grid(grid_path) )
_GRID_SEARCH_PATHS: tuple[str, ...] = ( "data/nenkova_agnfitter_torus_grid.h5", "nenkova_agnfitter_torus_grid.h5", ) _NOT_FOUND_MSG = ( "Nenkova AGNfitter torus grid not found. " "Build it with: python scripts/build_nk08_agnfitter_grid.py " "--input /tmp/AGNfitter-rX/models/TORUS/NK0_mean_1p.pickle" ) def _find_nenkova_agnfitter_grid() -> str: from tengri._data_setup import require_data # _GRID_SEARCH_PATHS[-1] is the bare filename; require_data searches every # directory the old parents[4] walk reached, plus $TENGRI_DATA_DIR (#1431), # and re-raises _NOT_FOUND_MSG verbatim when the grid is absent. return require_data(_GRID_SEARCH_PATHS[-1], _NOT_FOUND_MSG) def load_nenkova_agnfitter_default_grid() -> TorusTemplateGrid: """Load the packaged Nenkova AGNfitter grid pytree (discovery + cache). This is the ``template_loader`` the torus block registers. Returns ------- TorusTemplateGrid Raises ------ FileNotFoundError If no Nenkova AGNfitter grid HDF5 is present on disk. """ return load_nenkova_agnfitter_grid(_find_nenkova_agnfitter_grid()) @cache_per_float_dtype def _load_nenkova_agnfitter_default() -> Callable: return create_nenkova_agnfitter_from_grid(_find_nenkova_agnfitter_grid())
[docs] def nenkova_agnfitter_sed( *args, _template: TorusTemplateGrid | None = None, **kwargs ) -> jnp.ndarray: """Nenkova+08 AGN torus (AGNfitter-rX, auto-loaded from tabulated templates). Wraps :func:`create_nenkova_agnfitter_from_grid` with on-disk grid discovery. Parameters ---------- wavelength : array_like, shape (n_wave,) Rest-frame wavelength grid. [Å] agn_log_lbol : float, optional ``log10(L_bol / L_sun)``. Default 10.0. agn_cos_inc : float, optional Cosine of inclination (1 = face-on). Default 0.5. agn_torus_frac : float, optional Torus reprocessing fraction. Default 0.5. **kwargs Accepted and ignored for unified-dispatch compatibility. Returns ------- ndarray, shape (n_wave,) Spectral luminosity density. [erg/s/Hz] Raises ------ FileNotFoundError If no Nenkova AGNfitter grid HDF5 is present on disk. References ---------- .. [1] M. Nenkova, M. M. Sirocky, R. Nikutta, Z. Ivezic, and M. Elitzur, "AGN Dusty Tori. II. Observational Implications of Clumpiness," ApJ 685, 160 (2008). doi:10.1086/590483. arXiv:0806.0512. bibcode:2008ApJ...685..160N. .. [2] L. N. Martínez-Ramírez et al., "AGNfitter-rx: Modeling the radio-to-X-ray spectral energy distributions of AGNs," A&A 688, A46 (2024). arXiv:2405.12111. DOI: 10.1051/0004-6361/202449329. """ if _template is not None: return nenkova_agnfitter_sed_from_grid(_template, *args, **kwargs) return _load_nenkova_agnfitter_default()(*args, **kwargs)