# SPDX-License-Identifier: BSD-3-Clause
"""CAT3D-Wind clumpy-disc-plus-polar-wind AGN torus, low-wind-fraction reduction
(Hönig & Kishimoto 2017).
Three-parameter torus library interpolated differentiably in
``(agn_cos_inc, agn_a_cat3d_lowfwd, agn_fwd_cat3d_lowfwd)`` over a
precomputed HDF5 grid derived from AGNfitter-rX's ``CAT3D_mean_3p.pickle``.
AGNfitter-rX's CAT3D_mean_3p pickle concatenates two disjoint
three-parameter sub-libraries at different rows: rows 0-209 (this module)
cover a low polar-wind mass fraction range (``fwd`` 0.15-0.75) at a wider
radial power-law-index range (``a`` -3 to -0.5); rows 210-377
(:mod:`tengri.components.agn.cat3d_wind`, the reduction AGNfitter-rX's own
fitter code selects by default) cover a high wind-fraction range (``fwd``
1.0-2.25) at a narrower radial-index range (``a`` -3 to -1.5). The two
sub-libraries do not overlap in ``(a, fwd)`` and are therefore vendored as
two independent grids rather than one, each a full Cartesian rectangle in
its own right (unlike the high-``fwd`` sub-library, this low-``fwd`` one is
a complete Cartesian product -- no nearest-neighbor cell filling is needed).
Axis semantics
--------------
``agn_cos_inc``
Cosine of inclination (1 = face-on, 0 = edge-on). The grid's native
``incl_axis`` is stored in degrees; this module converts at load time,
matching :mod:`tengri.components.agn.cat3d_wind`.
``agn_a_cat3d_lowfwd``
Radial power-law index of the clumpy-cloud distribution
(Hönig & Kishimoto 2017 parameter ``a``). Range: -3.0 to -0.5.
``agn_fwd_cat3d_lowfwd``
Polar-wind mass fraction (``fwd``). Range: 0.15 to 0.75.
Runtime normalization
---------------------
Template is shape-only. At runtime the module divides by the trapezoidal
integral over frequency and multiplies by ``L_bol * agn_torus_frac``,
mirroring :mod:`tengri.components.agn.cat3d_wind`.
Interpolation
-------------
Node-exact monotone cubic (PCHIP, :func:`tengri.utils.grid_interp.interp_nd_pchip`),
matching :mod:`tengri.components.agn.cat3d_wind`.
References
----------
.. [1] S. F. Hönig & M. Kishimoto, "Dusty winds in active galactic nuclei: reconciling
observations with models," ApJL 838,
L20 (2017). arXiv:1703.07781.
.. [2] L. N. Martínez-Ramírez, G. Calistro Rivera, E. Lusso, 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,
torus_lnu_from_grid,
)
__all__ = [
"cat3d_wind_lowfwd_sed",
"create_cat3d_wind_lowfwd_from_grid",
]
_DEFAULT_AGN_A_CAT3D_LOWFWD = -2.0
_DEFAULT_AGN_FWD_CAT3D_LOWFWD = 0.45
def _load_cat3d_lowfwd_arrays(grid_path: str) -> dict:
"""Load raw numpy arrays from the CAT3D-Wind low-fwd grid HDF5."""
import h5py
with h5py.File(grid_path, "r") as f:
g = f["cat3d_wind_lowfwd"]
return {
"incl_axis": np.asarray(g["incl_axis"][:], dtype=np.float64),
"a_axis": np.asarray(g["a_axis"][:], dtype=np.float64),
"fwd_axis": np.asarray(g["fwd_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_cat3d_wind_lowfwd_grid(grid_path: str) -> TorusTemplateGrid:
"""Load a CAT3D-Wind low-fwd grid HDF5 into a :class:`TorusTemplateGrid` pytree.
Parameters
----------
grid_path : str
Path to ``cat3d_wind_lowfwd_torus_grid.h5``.
Returns
-------
TorusTemplateGrid
Template arrays with axes ``(cos_inc, a, f_wd)``, as numpy arrays.
Raises
------
FileNotFoundError
If ``grid_path`` does not exist.
KeyError
If the grid file is missing any expected dataset under
``/cat3d_wind_lowfwd``.
Notes
-----
**JIT-compatible**: no, performs HDF5 I/O. Call outside the trace and
pass the result in as an argument.
"""
raw = _load_cat3d_lowfwd_arrays(grid_path)
# Convert native inclination axis (degrees, ascending) to cos(incl),
# which is tengri's canonical inclination parameterization. The
# template's leading axis must follow suit, which means reversing it
# because cos(incl) is *descending* as incl ascends.
incl_deg = raw["incl_axis"]
cos_inc_axis = np.cos(np.deg2rad(incl_deg))
order = np.argsort(cos_inc_axis)
cos_inc_axis = cos_inc_axis[order]
template_reordered = raw["template"][order]
return TorusTemplateGrid(
template=loaded_template(template_reordered),
axes=(
np.asarray(cos_inc_axis),
np.asarray(raw["a_axis"]),
np.asarray(raw["fwd_axis"]),
),
wave_grid=np.asarray(raw["wavelength"]),
)
def cat3d_wind_lowfwd_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_a_cat3d_lowfwd: float = _DEFAULT_AGN_A_CAT3D_LOWFWD,
agn_fwd_cat3d_lowfwd: float = _DEFAULT_AGN_FWD_CAT3D_LOWFWD,
agn_torus_frac: float = DEFAULT_AGN_TORUS_FRAC,
**_kwargs,
) -> jnp.ndarray:
r"""CAT3D-Wind low-fwd torus SED at a single ``(cos_inc, a, f_wd)``.
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 matches CIGALE i=30.
agn_a_cat3d_lowfwd : float, optional
Radial power-law index of the clumpy-cloud distribution. Default -2.0.
agn_fwd_cat3d_lowfwd : float, optional
Polar-wind mass fraction. Default 0.45.
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) = L_{\rm bol}\,f_{\rm torus}\,
\frac{T(\lambda;\,\cos i,\,a,\,f_{\rm wd})}
{\int T(\nu;\,\cos i,\,a,\,f_{\rm wd})
\,\mathrm{d}\nu}
**JIT-compatible**: yes.
**Approximation**: the grid is drawn from rows 0-209 of the
``CAT3D_mean_3p`` library (Hönig & Kishimoto 2017 [1]_) as packaged by
AGNfitter-rX [2]_, which averages out secondary parameters (N_0, tau_V,
sigma) of the full Hönig & Kishimoto 2017 parameter space.
**Grid completeness**: unlike
:mod:`tengri.components.agn.cat3d_wind`'s high-``fwd`` sub-library, this
low-``fwd`` sub-library is a full Cartesian product of the three axes --
no nearest-neighbor cell filling was needed at build time.
"""
# Normalized per sightline (#2851): AGNfitter-rX CAT3D_mean_3p.pickle states no common
# scale for its records across inclination (Martinez-Ramirez et al. 2024, Sect. 3.3, says
# only that the CAT3D-WIND SEDs were averaged), and the stored powers are not monotonic
# in inclination, so the library's anisotropy is not restored. Sightline: cos i,
# ascending, axis 0 (from the stored 'incl_axis' in deg, 0 face-on).
return torus_lnu_from_grid(
grid,
wavelength,
(agn_cos_inc, agn_a_cat3d_lowfwd, agn_fwd_cat3d_lowfwd),
agn_log_lbol=agn_log_lbol,
agn_torus_frac=agn_torus_frac,
)
[docs]
def create_cat3d_wind_lowfwd_from_grid(grid_path: str) -> Callable:
"""Load a CAT3D-Wind low-fwd grid and bind it to the SED evaluator.
Parameters
----------
grid_path : str
Path to ``cat3d_wind_lowfwd_torus_grid.h5``.
Returns
-------
callable
"""
return functools.partial(
cat3d_wind_lowfwd_sed_from_grid, load_cat3d_wind_lowfwd_grid(grid_path)
)
_GRID_SEARCH_PATHS: tuple[str, ...] = (
"data/cat3d_wind_lowfwd_torus_grid.h5",
"cat3d_wind_lowfwd_torus_grid.h5",
)
_NOT_FOUND_MSG = (
"CAT3D-Wind low-fwd torus grid not found. Build it with: "
"python scripts/build_agnfitter_torus_reductions.py --which cat3d_lowfwd"
)
def _find_cat3d_wind_lowfwd_grid() -> str:
from tengri._data_setup import require_data
return require_data(_GRID_SEARCH_PATHS[-1], _NOT_FOUND_MSG)
def load_cat3d_wind_lowfwd_default_grid() -> TorusTemplateGrid:
"""Load the packaged CAT3D-Wind low-fwd grid pytree (discovery + cache).
This is the ``template_loader`` the torus block registers.
Returns
-------
TorusTemplateGrid
Raises
------
FileNotFoundError
If no CAT3D-Wind low-fwd grid HDF5 is present on disk.
"""
return load_cat3d_wind_lowfwd_grid(_find_cat3d_wind_lowfwd_grid())
@cache_per_float_dtype
def _load_cat3d_wind_lowfwd_default() -> Callable:
return create_cat3d_wind_lowfwd_from_grid(_find_cat3d_wind_lowfwd_grid())
[docs]
def cat3d_wind_lowfwd_sed(
*args, _template: TorusTemplateGrid | None = None, **kwargs
) -> jnp.ndarray:
"""CAT3D-Wind low-fwd torus (auto-loaded from tabulated templates).
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 matches CIGALE i=30.
agn_a_cat3d_lowfwd : float, optional
Radial power-law index. Default -2.0.
agn_fwd_cat3d_lowfwd : float, optional
Polar-wind mass fraction. Default 0.45.
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 CAT3D-Wind low-fwd grid HDF5 is present on disk.
References
----------
.. [1] S. F. Hönig & M. Kishimoto, ApJL 838, L20 (2017). arXiv:1703.07781.
.. [2] L. N. Martínez-Ramírez et al., A&A 688, A46 (2024). arXiv:2405.12111.
"""
if _template is not None:
return cat3d_wind_lowfwd_sed_from_grid(_template, *args, **kwargs)
return _load_cat3d_wind_lowfwd_default()(*args, **kwargs)