Source code for tengri.components.agn.disc

# SPDX-License-Identifier: BSD-3-Clause
"""Accretion disc models for AGN emission.

Four models are provided:

1. **Simple power-law + UV cutoff**: minimal AGN disc with 3 parameters.
2. **Multi-color disc (Shakura-Sunyaev)**: physically-motivated standard thin
   disc following Kubota & Done (2018), simplified to the key parameters.
   Implements the outer standard disc zone only.
3. **Kubota & Done 3-zone disc**: full K&D (2018) model with outer standard
   disc, warm Comptonization (soft X-ray excess), and hot corona (hard X-ray
   power law). Three radially-stratified zones with self-consistent radii.
4. **ADAF + truncated disc**, for low-luminosity AGN (L/L_Edd < 0.01).
   The inner disc transitions to an advection-dominated accretion flow
   (optically thin, radiatively inefficient). Based on Mahadevan (1997)
   and Nemmen+2014.

All return specific luminosity L_nu in erg/s/Hz as a function of rest-frame
wavelength. All functions are pure JAX and JIT-compilable.

Physical constants are in CGS. Wavelength inputs are in Angstrom.

References
----------

- Shakura & Sunyaev 1973, A&A, 24, 337
- Kubota & Done 2018, MNRAS, 480, 1247
- Nandra & Pounds 1994, MNRAS, 268, 405 (power-law slopes)
- Done et al. 2012, MNRAS, 420, 1848 (QSOSED)
- Mahadevan 1997, ApJ, 477, 585 (ADAF spectra)
- Nemmen et al. 2014, MNRAS, 438, 2804 (ADAF modeling)
- Lopez et al. 2024 (ADAF + truncated disc for LLAGN)
- Beloborodov 1999, ApJ, 510, L123 (self-consistent Gamma_hot)

"""

import functools
import math
from collections.abc import Callable

import h5py
import jax
import jax.numpy as jnp
import numpy as np

from tengri.components.agn._nt_emissivity import (
    H_CEILING_FRACTION as _NT_H_CEILING_FRACTION,
    X_MAX as _NT_X_MAX,
    isco_radius as _isco_radius,
    nt_dh_dlogx as _nt_dh_dlogx,
    nt_h as _nt_h,
    nt_h_ceiling as _nt_h_ceiling,
    nt_rt as _nt_rt,
)
from tengri.components.agn._nthcomp import (
    _TABLE_AVAILABLE as _NTHCOMP_AVAILABLE,
    nthcomp_lnu_interp as _nthcomp_lnu_interp,
    nthcomp_norm_grid as _nthcomp_norm_grid,
)
from tengri.components.agn._params import (
    DEFAULT_AGN_A_SPIN,
    DEFAULT_AGN_ADAF_ALPHA,
    DEFAULT_AGN_ADAF_BETA,
    DEFAULT_AGN_ADAF_DELTA,
    DEFAULT_AGN_ALPHA,
    DEFAULT_AGN_ASTAR,
    DEFAULT_AGN_COS_INC,
    DEFAULT_AGN_F_HARD,
    DEFAULT_AGN_GAMMA_HARD,
    DEFAULT_AGN_GAMMA_WARM,
    DEFAULT_AGN_KT_HOT,
    DEFAULT_AGN_KT_WARM,
    DEFAULT_AGN_LOG_LBOL,
    DEFAULT_AGN_LOG_LEDD,
    DEFAULT_AGN_LOG_MBH,
    DEFAULT_AGN_LOG_MDOT,
    DEFAULT_AGN_LUM_RATIO,
    DEFAULT_AGN_R_WARM_RATIO,
    DEFAULT_AGN_T_MAX,
)
from tengri.components.agn._phys import (
    C_LIGHT as _C_LIGHT,
    COS_INC_ISOTROPIC_REFERENCE as _COS_INC_ISOTROPIC_REFERENCE,
    H_PLANCK as _H_PLANCK,
    K_BOLTZ as _K_BOLTZ,
    planck_lnu as _planck_lnu,
    ring_area as _ring_area,
    wavelength_to_nu as _wavelength_to_nu,
)
from tengri.components.agn._template_grid import scale_to_torus_power_native
from tengri.utils.grid_interp import library_lookup, loglog_integral, resample_template
from tengri.utils.host_array import device_table, host_array
from tengri.utils.physics_constants import (
    G_GRAV as _G_GRAV,
    K_BOLTZ_KEV as _K_BOLTZ_KEV,
    KEV_TO_ERG as _KEV_TO_ERG,
    L_SUN as _LSUN_ERG,
    M_PROTON as _M_PROTON,
    M_SUN as _MSUN_G,
    SIGMA_SB as _SIGMA_SB,
    SIGMA_T as _SIGMA_T,
)
from tengri.utils.scale import (
    apply_log10_scale,
    is_float32_arithmetic,
    pow10 as _pow10,
    representable_denominator as _representable_denominator,
    representable_exponent,
    representable_floor as _representable_floor,
)

#: Scale of the nthcomp template shape [dimensionless]. The shape integrates to 1 over frequency,
#: so it is ~1e-17 per Hz while the ring factor it multiplies is ~1e47: dividing it by this unit
#: makes it O(1), and the unit is restored as an exponent on the summed spectrum (#2767).
_NTHCOMP_UNIT: float = 1.0e-17
_LOG10_NTHCOMP_UNIT: float = math.log10(_NTHCOMP_UNIT)

# log10 of the cgs constants that make the Shakura-Sunyaev disc's bolometric /
# Eddington / accretion-rate intermediates overflow float32 (#1206). At a
# realistic AGN luminosity the LINEAR forms: L_bol ~1e44, L_Edd ~1e46, the
# ``t_in**4`` numerator ~1e58 erg/s: all exceed float32 max (3.4e38), yet the
# RESULTS (mdot ~1e24 g/s, t_in ~1e5 K, lambda_Edd ~1e-2) are representable.
# The float32 branch of ``multicolor_disc`` forms every such quantity as a log10
# sum and materializes it only at the representable result via ``pow10``.
_LOG10_LSUN_ERG: float = math.log10(_LSUN_ERG)
_LOG10_C_LIGHT: float = math.log10(_C_LIGHT)
_LOG10_MSUN_G: float = math.log10(_MSUN_G)
_LOG10_3G: float = math.log10(3.0 * _G_GRAV)
_LOG10_8PI_SIGMA_SB: float = math.log10(8.0 * math.pi * _SIGMA_SB)
# log10(L_Edd) at M_BH = 1 M_sun: L_Edd = 4*pi*G*M*m_p*c/sigma_T, linear in M_BH.
_LOG10_L_EDD_1MSUN: float = math.log10(
    4.0 * math.pi * _G_GRAV * _MSUN_G * _M_PROTON * _C_LIGHT / _SIGMA_T
)
# Constants for the Kubota & Done float32 path (#1206): the three-zone model
# carries absolute cgs luminosities (l_edd ~1e46, l0 ~1e42, energy integrals
# ~1e44) that overflow float32. The float32 branch works those in L_sun units
# (÷ L_sun) via pre-divided constants so no ~1e44 intermediate ever forms.
# L_Edd(1 M_sun) in L_sun; l_edd_lsun = _L_EDD_1MSUN_LSUN * 10**log_mbh.
_L_EDD_1MSUN_LSUN: float = float(
    4.0 * math.pi * _G_GRAV * _MSUN_G * _M_PROTON * _C_LIGHT / _SIGMA_T
) / float(_LSUN_ERG)
# ENERGY BUDGET. ``agn_log_lbol`` is the accretion power ``L_acc = int (D_nu + H_nu) dnu``: the
# radiation of the disc and warm zones, ``D_nu`` (BOTH faces, all directions), plus that of the
# corona, ``H_nu`` (isotropic). Every annulus emits ``dL_nu(i) = 4 pi B_nu(T) 2 pi r dr cos i``
# (``_ring_area``), the luminosity density an observer at inclination i assigns assuming
# isotropy; its frequency integral is ``4 sigma T^4 2 pi r dr cos i = 2 cos i dD`` with
# ``dD = 2 sigma T^4 2 pi r dr`` the two-face power of the ring. The bolometric normalizers sum
# ``D`` through ``_TWO_FACES * sigma T^4 2 pi r dr`` (no cos i), so the returned spectrum is
# ``2 cos i D_nu + H_nu``: its mean over cos i in [0, 1] is ``L_acc`` and its power at
# cos i = 0.5 is ``L_acc``. The hot corona enters ``kubota_done``'s normalizer as its FULL power
# ``l_hot_erg`` (K&D 2018 Eq. 2's two-face dissipation, isotropic), and ``l_seed`` is not
# summed: it only sets Gamma_hot.
# int B_nu(T) dnu = (2 pi^4 k^4 / 15 h^3 c^2) T^4 = sigma_Planck T^4 / pi, built from the very
# h, k, c that ``planck_lnu`` uses so the identity is exact for it (it differs from the tabulated
# sigma_SB by the constants' rounding). [erg s^-1 cm^-2 Hz^0 sr^-1 K^-4]. Used wherever a ring
# or disc bolometric content is needed: analytic, never a quadrature on the caller's grid (#2572).
_BNU_BOL_PER_T4: float = float(
    2.0 * math.pi**4 * _K_BOLTZ**4 / (15.0 * _H_PLANCK**3 * _C_LIGHT**2)
)
# Temperature unit [K] of the float32 bolometric sum: keeps c * T^4 / L_sun normal (#3105).
_T_BOL_NORM: float = 1.0e5
# 4*pi*sigma_SB / L_sun; l0_lsun = _4PI_SIGMA_SB_OVER_LSUN * r_isco_cm**2 * t_in**4.
_4PI_SIGMA_SB_OVER_LSUN: float = float(4.0 * math.pi * _SIGMA_SB) / float(_LSUN_ERG)
# 2*pi*sigma_SB / L_sun; per-annulus (sigma T^4 * 2*pi*r*dr) energy in L_sun.
_2PI_SIGMA_SB_OVER_LSUN: float = float(2.0 * math.pi * _SIGMA_SB) / float(_LSUN_ERG)
# L_sun / c^2; mdot [g/s] = _LSUN_OVER_C2 * 10**log_lbol / eta (avoids l_bol_erg).
_LSUN_OVER_C2: float = float(_LSUN_ERG) / float(_C_LIGHT) ** 2
# R_g = G*M_bh/c^2 = _GRAV_RADIUS_PER_MSUN * 10**log_mbh [cm] (#2210): folding
# G*M_sun/c^2 into one ~1.477e5 constant keeps the product inside float32 range
# across the whole declared agn_log_mbh prior, unlike forming M_bh in grams
# (``10**log_mbh * M_sun``) as a standalone ~1e39-1e43 intermediate first.
_GRAV_RADIUS_PER_MSUN: float = _G_GRAV * _MSUN_G / _C_LIGHT**2

# ── Model 1: Simple power-law disc + UV cutoff ────────────────────


#: End points [Angstrom] of the power-law normalization band, shared with ``powerlaw_disc_model``
#: (its published band and this normalization are the same 10 A to 1e8 A range).
_PL_BAND_LO_AA: float = 10.0
_PL_BAND_HI_AA: float = 1.0e8
#: Internal normalization band of ``powerlaw_disc`` [Angstrom] (descending = ascending nu).
#: Integrated by :func:`loglog_integral` (power law between nodes): at 8001 nodes the
#: normalization is 3e-8 from its 40980-node value (a trapezoid at 2049 nodes was 1.2e-5 off).
_PL_BAND_NODES: int = 8001


def _pl_band_aa(dtype) -> jnp.ndarray:
    """The power-law normalization band [Angstrom], descending, built in the trace."""
    hi, lo = math.log(_PL_BAND_HI_AA), math.log(_PL_BAND_LO_AA)
    return jnp.exp(jnp.linspace(hi, lo, _PL_BAND_NODES, dtype=dtype))


def _powerlaw_shape_unit(nu, agn_alpha, agn_T_max, nu_ref):
    """``powerlaw_disc`` shape with its reference power removed: ``(nu/nu_ref)**alpha exp(-x)``.

    The shape is ``nu**alpha exp(-x)`` with ``x = h nu / k T`` clipped to [0, 500]; this returns
    it divided by ``nu_ref**alpha``, so an O(1) reference keeps the values inside float32 range
    where the raw ``nu**alpha`` would underflow.

    Parameters
    ----------
    nu : array_like, shape (n,)
        Frequency [Hz].
    agn_alpha : float
        Power-law index [dimensionless].
    agn_T_max : float
        Cutoff temperature [K].
    nu_ref : float
        Reference frequency [Hz], a positive scalar stop-gradient'd by the caller.

    Returns
    -------
    ndarray, shape (n,)
        Shape divided by ``nu_ref**alpha`` [dimensionless].
    """
    x = _H_PLANCK * nu / (_K_BOLTZ * jnp.maximum(agn_T_max, 1.0))
    x_clip = jnp.clip(x, 0.0, representable_exponent(500.0, base=math.e))
    return (nu / nu_ref) ** agn_alpha * jnp.exp(-x_clip)


[docs] def powerlaw_disc( wavelength: jnp.ndarray, agn_log_lbol: float, agn_lum_ratio: float = DEFAULT_AGN_LUM_RATIO, agn_alpha: float = DEFAULT_AGN_ALPHA, agn_T_max: float = DEFAULT_AGN_T_MAX, **_kwargs, ) -> jnp.ndarray: """Simple power-law accretion disc with exponential UV cutoff (deprecated). A phenomenological single-component AGN disc model that approximates the optical/UV emission as a power law with an exponential cutoff at high frequencies. This is a faster alternative to multi-color disc models when fine spectral details are not required. .. deprecated:: This bare power-law disc lacks physical motivation and citations. For science fits, use :func:`multicolor_disc` (Shakura-Sunyaev thin disc) or :func:`kubota_done_disc` (K&D 3-zone model) instead. Will be removed in tengri v1.0. Parameters ---------- wavelength : array_like, shape (n_wave,) Rest-frame wavelength grid. [Angstrom] agn_log_lbol : float Total AGN bolometric luminosity. [log10(L_sun)] agn_lum_ratio : float, optional Fraction of bolometric luminosity emitted by this disc component. Default: 1.0. [dimensionless, 0–1] agn_alpha : float, optional Power-law spectral index. Typical range: -1.5 to -0.5. Default: -1.0 (flat in nu*L_nu). [dimensionless] agn_T_max : float, optional Maximum blackbody temperature, setting the UV cutoff frequency. Typical range: 10^4 to 10^6. Default: 10^5. [K] Returns ------- ndarray, shape (n_wave,) Spectral luminosity density L_ν [erg/s/Hz]; exactly zero outside 10 A - 1e8 A. Notes ----- **JIT-compatible**: yes, all operations use ``jnp`` primitives; the band truncation is a ``jnp.where`` on the wavelength. The unnormalized spectral shape is: .. math:: L_\\nu^{\\rm unnorm} = \\nu^\\alpha \\exp\\left(-\\frac{h\\nu}{k_B T_{\\rm max}}\\right) where :math:`\\alpha` is the spectral index, :math:`h` is Planck's constant, :math:`\\nu` is frequency [Hz], :math:`k_B` is Boltzmann's constant, and :math:`T_{\\rm max}` is the cutoff temperature [K]. The normalization constant :math:`C` is computed numerically by integrating the shape over the fixed band 10 A - 1e8 A (8001 log-spaced internal nodes, a power law between nodes; the caller's wavelength grid plays no part), so that the integral over frequency of the shape over that band equals the target luminosity :math:`L_{\\rm bol} \\cdot f_{\\rm disc}` and the SED is the same on any grid. The SED is zero outside that band (both edges inclusive), so its frequency integral is the whole budget :math:`L_{\\rm bol} \\cdot f_{\\rm disc}`. This is by design: the band is the model's definition, the power law does not converge beyond it (:math:`\\nu L_\\nu` is constant at long wavelength for :math:`\\alpha = -1`), and other components own the radio (> 1e8 A) and hard X-ray (< 10 A) regimes. A disc of this type contributes nothing to either. **Approximation**: This model is a simplified representation of the true accretion disc spectrum, which consists of multiple temperature zones (see :func:`multicolor_disc` and :func:`kubota_done_disc` for more realistic models). The power-law form breaks down at low frequencies (radio/submm) where the SED transitions to a different regime, and does not capture the soft X-ray excess or hard X-ray corona. Use this model only when computational speed is prioritized over spectral fidelity. """ import warnings warnings.warn( "powerlaw_disc is deprecated (no physical derivation; bare phenomenological " "model) and will be removed in tengri v1.0. For science fits, use " "multicolor_disc (Shakura-Sunyaev) or kubota_done_disc (K&D 3-zone) instead.", DeprecationWarning, stacklevel=2, ) nu = _wavelength_to_nu(wavelength) # Each frequency reference is a pure factorization constant (stop_gradient), removed from the # power and restored as alpha * log10(nu_ref) in the log-scale below. nu_ref = jax.lax.stop_gradient(jnp.min(nu)) shape_unit = _powerlaw_shape_unit(nu, agn_alpha, agn_T_max, nu_ref) # Normalize over the FIXED band [_pl_band_aa] (log-spaced internal nodes), not over the # caller's grid: the same SED must come out whichever grid it is evaluated on (#2572). The # band integral is peak-factored the same way, and the 1e-100 floor is the one the linear # form used. nu_int = _wavelength_to_nu(_pl_band_aa(nu.dtype)) nu_int_ref = jax.lax.stop_gradient(jnp.min(nu_int)) shape_int_unit = _powerlaw_shape_unit(nu_int, agn_alpha, agn_T_max, nu_int_ref) int_peak = jax.lax.stop_gradient(jnp.max(shape_int_unit)) integral_hat = loglog_integral(nu_int, shape_int_unit / int_peak) log_integral = jnp.maximum( agn_alpha * jnp.log10(nu_int_ref) + jnp.log10(int_peak) + jnp.log10(integral_hat), math.log10(_representable_denominator(1e-100)), ) # L_nu = L_bol * ratio * shape / integral with L_bol = 10**agn_log_lbol * L_sun and # shape = nu_ref**alpha * shape_unit. The luminosity scale enters last as a log10 offset # (apply_log10_scale factors the O(1) peak of ``shape_unit``); ``10**agn_log_lbol * L_sun`` # is never formed as a linear intermediate. log_scale = agn_log_lbol + _LOG10_LSUN_ERG - log_integral + agn_alpha * jnp.log10(nu_ref) # The SED is the band-limited disc: zero outside [_PL_BAND_LO_AA, _PL_BAND_HI_AA], the band it # is normalized on (both edges inclusive). Beyond it the power law is not defined and its tail # carried up to 1e4 times the budget, uncounted; every caller (the standalone component, the # composable ``disc='powerlaw'`` block and its lookup table) inherits the truncation here. wave = jnp.asarray(wavelength) in_band = (wave >= _PL_BAND_LO_AA) & (wave <= _PL_BAND_HI_AA) return jnp.where(in_band, agn_lum_ratio * apply_log10_scale(shape_unit, log_scale), 0.0)
# ── Model 2: Multi-color disc (Shakura-Sunyaev thin disc) ───────── def _log10_eddington_luminosity(log_mbh: float) -> float: r"""log10 Eddington luminosity, :math:`\log_{10} L_{\rm Edd}` [log10(erg/s)]. Carried in log space (#2210): the linear form is ~1.26e44 erg/s at the bottom of the declared ``agn_log_mbh`` prior, past float32's 3.403e38 ceiling. Callers form only the Eddington ratio or other log-domain combinations; the linear :math:`L_{\rm Edd}` is never materialized. """ return _LOG10_L_EDD_1MSUN + log_mbh def _gravitational_radius(log_mbh: float) -> float: r"""Gravitational radius :math:`R_g = GM/c^2` [cm]. Regrouped (#2210) so the precomputed :math:`GM_\odot/c^2` (``_GRAV_RADIUS_PER_MSUN``, ~1.477e5, in float32 range) multiplies :math:`10^{\log_{10} M_{\rm BH}}`, rather than forming :math:`M_{\rm BH}` in grams as a standalone ~1e39-1e43 intermediate first. """ return _GRAV_RADIUS_PER_MSUN * _pow10(log_mbh) def _nt_l_diss_analytic(x_hot: float, r_isco_cm: float, t_in: float, a_spin: float = 0.0) -> float: """NT dissipation of the hot flow, K&D 2018 Eq. 2, with the Page-Thorne emissivity. Integrates ``F_NT = sigma T_NT^4`` over the disc annuli from R_ISCO to R_hot, both faces:: L_diss = 2 * int_{R_isco}^{R_hot} sigma T_NT^4 * 2 pi R dR = L_0 * h(x_hot) with ``L_0 = 4 pi R_isco^2 sigma T_in^4``, ``x = R / R_isco`` and ``sigma T_NT^4 = sigma T_in^4 x^-3 Rt(x; a)``, where ``Rt`` is the Page & Thorne (1974, ApJ 191, 499) factor of ``tengri.components.agn._nt_emissivity`` (zero at the ISCO, -> 1 far out):: h(x) = int_1^x x'^-2 Rt(x'; a) dx' evaluated by fixed-node Gauss-Legendre quadrature in ``ln x`` (no closed form for a != 0). ``h(1) = 0`` (empty corona); for the Newtonian zero-torque profile ``Rt = 1 - x^-1/2`` it would be ``1/3 - 1/x + 2/(3 x^{3/2})``. The trailing ``x`` of the integrand ``x^-3 Rt x`` is the ``R dR`` area element. Parameters ---------- x_hot : float R_hot / R_ISCO >= 1. r_isco_cm : float ISCO radius [cm]. t_in : float Reference temperature ``T_in = (3 G M Mdot / 8 pi sigma R_isco^3)^(1/4)`` [K]. a_spin : float, optional Dimensionless BH spin (default 0). Returns ------- float L_diss [erg s^-1]. """ l0 = 4.0 * jnp.pi * r_isco_cm**2 * _SIGMA_SB * t_in**4 h_hot = _nt_h(jnp.log(x_hot), a_spin) # a dissipated power: >= 0 up to round-off return l0 * jnp.where(h_hot > 0.0, h_hot, 0.0) def _nt_l0(r_isco_cm: float, t_in: float, float32: bool = False) -> float: """``L_0 = 4 pi R_isco^2 sigma T_in^4`` [erg/s; L_sun on the float32 path (#1206)]. The NT disc's total dissipation is ``L_0 * h(inf)``; ``h(inf) = 1/3`` for the Newtonian profile and 0.233 (a=0) .. 0.1 (a=0.998) for Page-Thorne. """ if float32: # Formed from logarithms: the reverse pass of ``r^2 T^4`` multiplies an incoming cotangent # by ``T^4`` (~3e20) before the small constant can bring it back, and that product leaves # float32 (#2767). The derivative through the exponent is ``L_0 * d(log)``, which does not. return _pow10( math.log10(_4PI_SIGMA_SB_OVER_LSUN) + 2.0 * jnp.log10(r_isco_cm) + 4.0 * jnp.log10(t_in) ) return 4.0 * jnp.pi * r_isco_cm**2 * _SIGMA_SB * t_in**4 def _r_hot_bisect( r_isco_cm: float, t_in: float, l_hot_target: float, n_iter: int = 40, float32: bool = False, a_spin: float = 0.0, ) -> float: r"""Solve for R_hot from K&D 2018 Eq. 2 by bisection in log(x_hot). :math:`L_{\rm diss}(x) = L_0\,h(x)` with the Page-Thorne dissipation integral :math:`h` (see :func:`_nt_l_diss_analytic`), strictly monotone in :math:`x = R_{\rm hot}/R_{\rm ISCO}`. After ``n_iter=40`` the bracket width is :math:`< 2^{-40} \approx 10^{-12}` of its initial log-width: enough for machine precision. ``l_hot_target`` is clipped to :math:`0.99\,L_0 h(10^4)` (see ``nt_h_ceiling`` in ``tengri.components.agn._nt_emissivity``). Differentiable: see :func:`_solve_log_x_hot` (implicit-function JVP, #2572). """ # Float32 (#1206): ``l0`` is ~1e42 erg/s (overflow); the bisection needs only # the RATIO l_hot_target / l0, so compute both in L_sun units (``l_hot_target`` # arrives in L_sun on the float32 path). The pre-divided 4*pi*sigma/L_sun # constant folds first so no ~1e42 intermediate forms. l0 = _nt_l0(r_isco_cm, t_in, float32) x_hot = jnp.exp(_solve_log_x_hot(l_hot_target, l0, a_spin, n_iter)) return x_hot * r_isco_cm _X_LO = 1.001 _R_HOT_POLISH_STEPS = 3 def _bisect_log_x(l_hot_target, l0, a_spin, n_iter): """Bisect ``l0 * h(x) = l_target`` in log(x) over [log 1.001, log 1e4] (``lax.scan``). ``l_target = clip(l_hot_target, 1e-100, l0 * h_ceiling(a))``. """ l_target = jnp.clip(l_hot_target, 1e-100, l0 * _nt_h_ceiling(a_spin)) def _step(state, _): """Single bisection step in log-space to solve for R_hot.""" lo_i, hi_i = state mid = (lo_i + hi_i) * 0.5 go_right = l0 * _nt_h(mid, a_spin) < l_target return (jnp.where(go_right, mid, lo_i), jnp.where(go_right, hi_i, mid)), None (lo_f, hi_f), _ = jax.lax.scan( _step, (jnp.log(_X_LO), jnp.log(_NT_X_MAX)), None, length=n_iter ) # The bracket is 9.2 / 2^n_iter wide (8e-12 at 40), and the SED is steep enough in R_hot # that this quantizes the root into steps of ~1e-6 in the parameters. Newton steps on # F(u) = l0 h(u) - l_target, kept inside the bracket (which holds the root), converge # to the residual of the quadrature itself; a flat or pinned end leaves the midpoint. u = (lo_f + hi_f) * 0.5 for _ in range(_R_HOT_POLISH_STEPS): slope = l0 * _nt_dh_dlogx(u, a_spin) step = (l0 * _nt_h(u, a_spin) - l_target) / jnp.where(slope > 0.0, slope, 1.0) u = jnp.clip(u - jnp.where(slope > 0.0, step, 0.0), lo_f, hi_f) return u @functools.partial(jax.custom_jvp, nondiff_argnums=(3,)) def _solve_log_x_hot(l_hot_target, l0, a_spin, n_iter): """Root ``log(x_hot)`` of ``F = l0*h(x; a) - l_target``, differentiable by the IFT (#2572). The forward value is the bisection above. Differentiating *through* the ``scan`` returns exactly 0 (the bracket ends are constants and ``where`` only selects between them), so ``R_hot`` carried no sensitivity to ``M_BH``, ``L_bol``, ``f_hard`` or spin wherever it is not clipped. The rule below is the implicit-function derivative at the converged root:: d(log x) = (dl_target - h dl0 - l0 (dh/da) da) / (l0 dh/d log x), dh/d log x = Rt(x) / x (exact integrand), dh/da by autodiff of the quadrature. It is exactly 0 where the target's clip (to ``(1e-100, l0 h_ceiling)``) is active or the root is pinned to a bracket end, where ``R_hot`` really is independent of the target: evaluating the IFT there would leave ~1e-14 of bisection residual amplified by ``r_isco`` (~1e14 cm). (The weak ``a`` dependence of the saturation root itself is neglected there.) """ return _bisect_log_x(l_hot_target, l0, a_spin, n_iter) @_solve_log_x_hot.defjvp def _solve_log_x_hot_jvp(n_iter, primals, tangents): """Implicit-function-theorem JVP of :func:`_solve_log_x_hot`.""" l_hot_target, l0, a_spin = primals d_target, d_l0, d_a = tangents u = _bisect_log_x(l_hot_target, l0, a_spin, n_iter) h_u, dh_da = jax.jvp(lambda aa: _nt_h(u, aa), (a_spin,), (jnp.asarray(d_a, dtype=u.dtype),)) dF_du = l0 * _nt_dh_dlogx(u, a_spin) interior = ( (l_hot_target > l0 * _nt_h(jnp.log(_X_LO), a_spin)) & (l_hot_target < l0 * _nt_h_ceiling(a_spin)) & (l_hot_target > 1e-100) ) neg_dF_dtheta = d_target - h_u * d_l0 - l0 * dh_da # -dF/dtheta for F = l0 h - l_target safe = jnp.where(interior, dF_du, 1.0) tangent = jnp.where(interior, neg_dF_dtheta / safe, 0.0) return u, tangent def _l_seed_geometric( r_isco_cm: float, r_hot_cm: float, r_out_cm: float, t_in: float, n_radii: int = 100, float32: bool = False, a_spin: float = 0.0, ) -> float: """Geometric seed photon luminosity intercepted by the hot corona (K&D 2018 Eq. 3). Integrates over disc radii R > R_hot with the geometric covering fraction of the hot flow as seen from the disc: L_seed = 2 * ∫_{R_hot}^{R_out} F_NT(R) * [Θ(R) / π] * 2πR dR where (K&D 2018 Eq. 4, assuming H = R_hot): Θ(R) = θ_0 - (1/2)sin(2θ_0), sin θ_0 = H/R = R_hot / R The factor Θ(R)/π is the solid-angle fraction of the spherical hot flow (height H = R_hot) subtended at disc radius R. This formula assumes the hot corona is quasi-spherical with scale height equal to its truncation radius, as in the K&D 2018 geometry. Parameters ---------- r_isco_cm : float ISCO radius [cm]. r_hot_cm : float Hot corona radius [cm]. r_out_cm : float Outer disc radius [cm]. t_in : float Inner disc temperature [K]. n_radii : int Number of logarithmically spaced radial integration points. Returns ------- float L_seed [erg s^-1]. """ log_r_min = jnp.log10(r_hot_cm) log_r_max = jnp.log10(r_out_cm) log_r = jnp.linspace(log_r_min, log_r_max, n_radii) r = 10.0**log_r # [cm] d_log_r = (log_r_max - log_r_min) / (n_radii - 1) dr = r * jnp.log(10.0) * d_log_r # [cm] # NT temperature and emissivity r_ratio = r / r_isco_cm rt = jnp.maximum(_nt_rt(r_ratio, a_spin), 1e-30) ** 0.25 # Page-Thorne (1974) factor t_r = t_in * r_ratio ** (-0.75) * rt # [K] # Float32 (#1206): the seed integral (integrand * dr) reaches ~1e43 erg/s and # overflows; return L_seed in L_sun units by folding 1/L_sun into the surface # flux. Downstream ratios (Beloborodov) are unit-invariant. if float32: f_nt = (_SIGMA_SB / _LSUN_ERG) * t_r**4 # [L_sun s^-1... i.e. erg/s/cm^2 / L_sun] else: f_nt = _SIGMA_SB * t_r**4 # [erg s^-1 cm^-2] # Geometric covering factor Θ(R)/π (K&D 2018 Eq. 4), H = R_hot # Clamp sin_th0 to avoid infinite gradients at arcsin boundaries (±1). # The interior points are r >> r_hot, so sin_th0 << 1. Only the first # point (r ≈ r_hot) can approach 1. We use (0.001, 0.999) to avoid # gradient singularities while maintaining physical correctness. sin_th0 = jnp.clip(r_hot_cm / r, 0.001, 0.999) th0 = jnp.arcsin(sin_th0) # θ_0 in [0, π/2] theta_r = th0 - 0.5 * jnp.sin(2.0 * th0) # Θ(R) = θ_0 - (1/2)sin(2θ_0) covering = theta_r / jnp.pi # Θ(R)/π ∈ [0, 0.5] # L_seed = 2 * ∫ F_NT * (Θ/π) * 2πR dR integrand = f_nt * covering * 2.0 * jnp.pi * r # [erg s^-1 cm^-1] l_seed = 2.0 * jnp.sum(integrand * dr) return jnp.maximum(l_seed, _representable_floor(1e-100)) def _self_gravity_radius(log_mbh: float, l_edd_ratio: float, alpha_visc: float = 0.1) -> float: """Self-gravity (Toomre instability) radius in units of R_g. The disc becomes gravitationally unstable beyond this radius; for r > r_sg the disc fragments into clumps rather than accreting. This is the physically motivated outer boundary for the thin disc. Laor & Netzer (1989): r_sg = 2150 * alpha^{2/9} * lambda_Edd^{4/9} * (M_BH / 10^9 M_sun)^{-2/9} [R_g] where lambda_Edd = Mdot / Mdot_Edd (= L_bol / L_Edd) is the Eddington ratio and alpha is the Shakura-Sunyaev viscosity parameter (default 0.1). ``alpha`` enters as ``alpha^{2/9}`` (not ``(alpha/0.1)^{2/9}``), so at alpha = 0.1 the form is ``2150 (M/1e8)^{-2/9} lambda^{4/9}``. This is the expression evaluated by ``Sed.gravity_radius`` in qsosed (Quera-Bofarull) and ``calc_rsg`` in the QSOSED/RELQSO Fortran (Hagen & Done), and the outer radius of the K&D 2018 disc ("rout ... set to equal the self-gravity rsg (Laor & Netzer 1989)"). Reference: Laor, A. & Netzer, H. (1989), MNRAS 238, 897. Parameters ---------- log_mbh : float log10(M_BH / Msun). l_edd_ratio : float Eddington ratio lambda_Edd = L_bol / L_Edd (0 to 1). alpha_visc : float Shakura-Sunyaev viscosity parameter. Default 0.1. Returns ------- float r_sg in units of R_g. """ # M_BH / 10^9 M_sun, as one exponential of a difference: the reverse pass multiplies by this # value itself, not by ``10**log_mbh`` ahead of the division by 1e9, which leaves float32 # (#2767). m9 = _pow10(log_mbh - 9.0) m9_safe = jnp.maximum(m9, 1e-6) lambda_safe = jnp.clip(l_edd_ratio, 1e-10, 1.0) alpha_safe = jnp.maximum(alpha_visc, 1e-4) return ( 2150.0 * alpha_safe ** (2.0 / 9.0) * lambda_safe ** (4.0 / 9.0) * m9_safe ** (-2.0 / 9.0) ) # ── EUV / soft-X-ray power-law tail for the thin disc ───────────────── # A bare Shakura-Sunyaev disc Wien-cuts off in the EUV (< ~150 A), so its # emission below 100 A is negligible. Empirical AGN disc templates (e.g. # CIGALE's SKIRTOR piecewise power law) instead carry a rising power-law # tail into the EUV / soft X-ray. ``multicolor_disc`` can optionally blend # such a tail onto the Wien core (the ``euv_tail`` argument). _EUV_TAIL_LAMBDA_BREAK_AA = 912.0 # [A] Lyman limit: onset of the EUV tail _EUV_TAIL_LAMBDA_CUT_AA = 30.0 # [A] short-wavelength floor (~0.41 keV) _EUV_TAIL_DEFAULT_SLOPE = 1.0 # L_nu ~ nu^slope (CIGALE-skirtor-like rise) _EUV_TAIL_FRAC = 0.02 # tail bolometric budget as a fraction of L_disc _C_AA_PER_S = float(_C_LIGHT) * 1.0e8 # c [A/s] def _euv_tail_slope(euv_tail): """Static slope of the EUV tail, or ``None`` when the tail is off.""" if euv_tail is None or euv_tail == "wien": return None if euv_tail in ("powerlaw", "both"): return _EUV_TAIL_DEFAULT_SLOPE return float(euv_tail) def _euv_tail_lnu(wavelength, nu, slope, amplitude): """EUV tail ``amplitude * (nu/nu_break)^slope`` on 30-912 A, 0 elsewhere. [erg/s/Hz]""" nu_break = _wavelength_to_nu(jnp.asarray(_EUV_TAIL_LAMBDA_BREAK_AA)) in_euv = (wavelength <= _EUV_TAIL_LAMBDA_BREAK_AA) & (wavelength >= _EUV_TAIL_LAMBDA_CUT_AA) return jnp.where(in_euv, (nu / nu_break) ** slope, 0.0) * amplitude def _euv_tail_shape_integral(slope): r"""``int (nu/nu_break)^s dnu`` over the 30-912 A band, closed form [Hz]. :math:`\nu_b/(s+1)\,[(\nu_c/\nu_b)^{s+1} - 1]` (``nu_b ln(nu_c/nu_b)`` for ``s = -1``). """ nu_b = _C_AA_PER_S / _EUV_TAIL_LAMBDA_BREAK_AA # plain floats: static, safe under jit/grad nu_c = _C_AA_PER_S / _EUV_TAIL_LAMBDA_CUT_AA if abs(slope + 1.0) < 1e-12: return nu_b * math.log(nu_c / nu_b) return nu_b / (slope + 1.0) * ((nu_c / nu_b) ** (slope + 1.0) - 1.0) #: Internal nodes for the EUV-band excess integral (log-spaced, 912 A -> 30 A = ascending nu). _EUV_BAND_AA = np.geomspace(_EUV_TAIL_LAMBDA_BREAK_AA, _EUV_TAIL_LAMBDA_CUT_AA, 1025) def _apply_euv_tail(wavelength, nu, l_nu_wien, euv_tail, disc_bol_lsun): r"""Blend an EUV / soft-X-ray power-law tail onto a Wien-cutoff thin disc. Parameters ---------- wavelength : ndarray, shape (n_wave,) Rest-frame wavelength grid. [Angstrom] nu : ndarray, shape (n_wave,) Matching frequency grid. [Hz] l_nu_wien : ndarray, shape (n_wave,) The Wien-limited multi-color blackbody disc spectrum. [erg/s/Hz] euv_tail : None or str or float EUV behavior over :math:`\lambda \in [30, 912]` A: * ``None`` / ``"wien"``: no tail; pure Wien cutoff (bare thin disc). * ``"powerlaw"`` / ``"both"``: blend a power-law tail at the default slope ``_EUV_TAIL_DEFAULT_SLOPE``. ``"both"`` is a synonym; the Wien core is always preserved (the tail only fills where it exceeds Wien). * float: user-defined slope :math:`s` with :math:`L_\nu \propto \nu^s`. disc_bol_lsun : float Bolometric luminosity of the Wien disc, analytic (sum of the ring Stefan-Boltzmann powers), independent of the caller's grid. [L_sun] Returns ------- ndarray, shape (n_wave,) Disc spectrum with the EUV tail blended in (pre-normalization). [erg/s/Hz] Notes ----- **JIT-compatible**: yes, ``euv_tail`` is resolved to a static slope and a static on/off flag at trace time (it is not a traced array), so the branch is a Python-level decision and the math is pure ``jnp``. The tail has the **shape** :math:`L_\nu \propto \nu^s` over :math:`\lambda \in [30, 912]` A but its **amplitude** is fixed by normalizing its bolometric content to a small fraction (``_EUV_TAIL_FRAC``, default 2 %) of the disc's pre-tail bolometric luminosity, a bounded "soft-excess"-like budget. (A bare power law anchored to the disc peak would diverge in energy and swamp the optical.) The shape integral and the disc bolometric are closed-form, so the amplitude does not depend on the wavelength grid the SED is evaluated on (#2572). It is blended via ``maximum`` so the UV/optical/Wien-peak region is untouched: the tail only contributes where the Wien spectrum has already fallen below it. The caller renormalizes the blended spectrum back to :math:`L_{\rm bol}`, so total energy is conserved and the optical is reduced only by the ~2 % moved into the EUV. """ slope = _euv_tail_slope(euv_tail) if slope is None: return l_nu_wien # amplitude in erg/s/Hz: FRAC * L_disc / int shape dnu. Folding L_sun in last keeps the # ~1e43 erg/s disc bolometric (past float32's 3.4e38) from ever forming (#1206). if l_nu_wien.dtype == jnp.float32: # Float32 (#1206/#1436): peak-factor the amplitude exactly as the grid-quadrature form did, # so the reverse-mode cotangent products stay in range: ``disc_bol_hat`` is the O(1e-3..1) # bolometric in units of the peak (stop_gradient constant, multiplied back). _peak = jax.lax.stop_gradient(jnp.max(jnp.abs(l_nu_wien))) _peak = jnp.where(_peak > 0.0, _peak, 1.0) _disc_bol_hat = disc_bol_lsun * (_LSUN_ERG / _peak) amplitude = (_EUV_TAIL_FRAC * _disc_bol_hat / _euv_tail_shape_integral(slope)) * _peak else: amplitude = (_EUV_TAIL_FRAC * disc_bol_lsun / _euv_tail_shape_integral(slope)) * _LSUN_ERG tail = _euv_tail_lnu(wavelength, nu, slope, amplitude) return jnp.maximum(l_nu_wien, tail)
[docs] def multicolor_disc( wavelength: jnp.ndarray, agn_log_lbol: float, agn_lum_ratio: float = DEFAULT_AGN_LUM_RATIO, agn_log_mbh: float = DEFAULT_AGN_LOG_MBH, agn_log_ledd: float = DEFAULT_AGN_LOG_LEDD, agn_a_spin: float = DEFAULT_AGN_A_SPIN, agn_cos_inc: float = DEFAULT_AGN_COS_INC, n_radii: int = 50, euv_tail: str | float | None = "powerlaw", agn_log_lbol_shape: float | None = None, **_kwargs, ) -> jnp.ndarray: """Shakura-Sunyaev thin accretion disc with multi-color blackbody emission. Compute the SED of a standard geometrically thin, optically thick accretion disc via the Shakura-Sunyaev model. The disc is stratified into radial annuli, each radiating as a blackbody at its local temperature. This is the outer-disc component of the Kubota & Done (2018) three-zone model (see :func:`kubota_done_disc` for the full model including corona). Parameters ---------- wavelength : array_like, shape (n_wave,) Rest-frame wavelength grid. [Angstrom] agn_log_lbol : float Accretion power of the disc, integrated over all directions (both faces); independent of the inclination. [log10(L_sun)] agn_lum_ratio : float, optional Fraction of the accretion power emitted by the disc. Default: 1.0. [dimensionless, 0–1] agn_log_mbh : float, optional Black hole mass. Default: 8.0. [log10(M_sun)] agn_log_ledd : float, optional **DEPRECATED / IGNORED (#846).** The Eddington ratio is now DERIVED from ``agn_log_lbol`` and ``agn_log_mbh`` (lambda_Edd = L_bol / L_Edd), so the disc shape is self-consistent with the requested L_bol. This parameter is retained for backward compatibility but has no effect; setting or freeing it emits a build-time warning. Default: -1.0. agn_a_spin : float, optional Dimensionless black hole spin parameter (prograde). Range: [0, 0.998]. Default: 0.0 (Schwarzschild). [dimensionless] agn_cos_inc : float, optional Cosine of the inclination angle. Range: [0, 1]. The returned spectrum scales as :math:`2\\cos i`; the shape does not depend on it. Default: 0.866 (30°). [dimensionless] n_radii : int, optional Number of radial bins for numerical integration. Default: 50. euv_tail : {"powerlaw", "both", "wien"}, float, or None, optional EUV / soft-X-ray behavior below the Lyman limit (912 A). * ``"powerlaw"`` (default) / ``"both"``: blend a CIGALE-like power-law tail onto the Wien core so the disc carries flux below ~100 A. * ``"wien"`` / ``None``: pure Shakura-Sunyaev Wien cutoff (the bare thin disc; emission below ~150 A is negligible and the EUV / soft X-ray is supplied by the corona instead). * float: user-defined slope :math:`s` with :math:`L_\\nu \\propto \\nu^s`. Default: ``"powerlaw"``. The tail only fills the EUV where the Wien spectrum has already dropped below it, so the UV/optical is unchanged to sub-percent after the bolometric renormalization. See :func:`_apply_euv_tail`. Returns ------- ndarray, shape (n_wave,) Spectral luminosity density L_ν. [erg/s/Hz] Notes ----- **JIT-compatible**: yes, uses ``jnp`` primitives and ``jax.vmap``. ``euv_tail`` is a static (trace-time) selector, not a traced argument. The temperature profile is the Shakura-Sunyaev thin disc with a zero-torque inner boundary at the ISCO (a Newtonian-flux form with the Bardeen ISCO radius), *not* the relativistic Page & Thorne (1974) emissivity: that is used by the Kubota & Done family (:func:`kubota_done_disc`, see ``tengri.components.agn._nt_emissivity``), whose reference model defines it. Its total dissipation is ``1.46 eta Mdot c^2`` at a=0 (1.0 for Page-Thorne), so ``L_bol`` here is a normalization, not an energy balance: .. math:: T(r) = T_{\\rm in} \\left(\\frac{r}{r_{\\rm ISCO}}\\right)^{-3/4} \\left[1 - \\sqrt{\\frac{r_{\\rm ISCO}}{r}}\\right]^{1/4} where :math:`T_{\\rm in}` is the inner temperature determined by the accretion rate and :math:`r_{\\rm ISCO}` is the innermost stable circular orbit (radius from Bardeen et al. 1972, depends on spin). The disc luminosity is the luminosity density an observer at inclination :math:`i` assigns assuming isotropy: .. math:: L_\\nu(i) = \\sum_{j=1}^{N_r} 4\\pi B_\\nu(T_j)\\, 2\\pi r_j \\, dr_j \\cos i = 2\\cos i\\; D_\\nu , where :math:`B_\\nu(T)` is the Planck function, :math:`r_j` is the ring radius [cm], :math:`dr_j` is the ring width [cm] and :math:`D_\\nu` is the angle-integrated (two-face) spectral luminosity. ``agn_log_lbol`` fixes :math:`\\int D_\\nu\\,d\\nu`: the mean of :math:`\\int L_\\nu(i)\\,d\\nu` over :math:`\\cos i \\in [0, 1]` is :math:`L_{\\rm bol}`, and at :math:`\\cos i = 0.5` the line-of-sight power equals it. **Key physics**: - **Radiative efficiency**: :math:`\\eta = 1 - \\sqrt{1 - 2/(3 r_{\\rm ISCO})}`, computed from Novikov-Thorne theory. For Schwarzschild (a=0): η ≈ 0.057; for maximally spinning (a→0.998): η ≈ 0.32. - **Outer radius**: Uses the Laor & Netzer (1989) self-gravity (Toomre) radius, beyond which the disc fragments. This is an improvement over fixed approximations (e.g., 1000 r_ISCO) that can err by factors of a few at extreme masses or accretion rates. - **Eddington ratio clamping**: The accretion luminosity is capped at :math:`L_{\\rm Edd}` (i.e., log(L/L_Edd) is clipped to [0, 1] in linear space), reflecting the physical limit of radiatively efficient accretion. **Numerical method**: Radii are logarithmically spaced to ensure fine resolution at small radii where the temperature gradient is steep. Integration uses summation; the trapezoidal rule is applied in log-radius space via the spacing :math:`d\\log r = \\Delta(\\log r)`. References ---------- .. [1] A. Kubota and C. Done, "A physical model of the broad-band continuum of AGN and its implications for the UV/X relation and optical variability," MNRAS, 480, 1247 (2018). arXiv:1804.00171. https://doi.org/10.1093/mnras/sty1890 .. [2] J. M. Bardeen, W. H. Press, and S. A. Teukolsky, "Rotating black holes: Locally nonrotating frames, energy extraction, and scalar synchrotron radiation," ApJ, 178, 347 (1972). https://doi.org/10.1086/151796 .. [3] A. Laor and H. Netzer, "Massive thin accretion discs – I. Calculated spectra," MNRAS, 238, 897 (1989). https://doi.org/10.1093/mnras/238.3.897 """ nu = _wavelength_to_nu(wavelength) r_g = _gravitational_radius(agn_log_mbh) r_isco = _isco_radius(agn_a_spin) r_in = r_isco * r_g # [cm] # Radiative efficiency from Novikov-Thorne: eta = 1 - sqrt(1 - 2/(3*r_isco)) # For a=0 (Schwarzschild): r_isco=6, eta=0.057 # For a=0.998 (maximal spin): r_isco~1.24, eta~0.32 eta = 1.0 - jnp.sqrt(1.0 - 2.0 / (3.0 * r_isco)) # E fix (#846): agn_log_lbol is THE luminosity knob; the Eddington ratio is # DERIVED from it (lambda_Edd = L_bol / L_Edd, matching RELAGN's # mdot = L_bol/L_edd, relagn.py:288,330), so the disc shape (T_in, r_out) is # self-consistent with the requested L_bol. Previously the shape was built # from agn_log_ledd and then rescaled to agn_log_lbol, a decoupling that # left T_in / r_out corresponding to the wrong luminosity. agn_log_ledd is # now ignored here (a build-time warning fires if a user sets/frees it). # # Shape vs normalization luminosity (#1206). The disc SHAPE (T_in, r_out, # lambda_Edd) is set by ``_log_lbol_shape``; the output MAGNITUDE by # ``agn_log_lbol`` (the renorm target below). They coincide by default # (``agn_log_lbol_shape=None``), which is the float64 path. Only float32 # separates them, the AGN component evaluates the SHAPE at the true L_bol # but normalizes MAGNITUDE to a low reference so the runner's ~1e40 L_lambda # arithmetic stays in float32 range; the true magnitude is re-applied # downstream. See the float32 branch below. _log_lbol_shape = agn_log_lbol if agn_log_lbol_shape is None else agn_log_lbol_shape # Outer disc radius: Laor & Netzer (1989) self-gravity (Toomre) radius. # Beyond r_sg the disc fragments rather than accretes; this is the # physically motivated outer boundary used by qsosed (Quera-Bofarull). # r_sg = 2150 * alpha^{2/9} * lambda_Edd^{4/9} * (M/1e9)^{-2/9} R_g. if is_float32_arithmetic(wavelength): # Log-space so the ~1e44 L_bol, ~1e46 L_Edd and ~1e58 erg/s ``t_in**4`` # numerator never materialize (float32 max 3.4e38). The RESULTS # (lambda_Edd ~1e-2, mdot ~1e24 g/s, t_in ~1e5 K) are all representable. _log_l_bol_erg = _log_lbol_shape + _LOG10_LSUN_ERG _log_l_edd = _log10_eddington_luminosity(agn_log_mbh) l_edd_ratio = jnp.clip(_pow10(_log_l_bol_erg - _log_l_edd), 1e-10, 1.0) _log_mdot = _log_l_bol_erg - jnp.log10(eta) - 2.0 * _LOG10_C_LIGHT mdot = _pow10(_log_mdot) # [g s^-1] _log_t_in4 = ( _LOG10_3G + agn_log_mbh + _LOG10_MSUN_G + _log_mdot - _LOG10_8PI_SIGMA_SB - 3.0 * jnp.log10(r_in) ) t_in = _pow10(0.25 * _log_t_in4) # [K] else: l_bol_erg = 10.0**_log_lbol_shape * _LSUN_ERG _log_l_edd = _log10_eddington_luminosity(agn_log_mbh) # derived: lambda_Edd, formed in log space so L_Edd (~1e46 erg/s) never # stands alone (#2210). l_edd_ratio = jnp.clip(_pow10(_log_lbol_shape + _LOG10_LSUN_ERG - _log_l_edd), 1e-10, 1.0) mdot = l_bol_erg / (eta * _C_LIGHT**2) # [g s^-1] # Inner temperature: T_in = (3 * G * M * Mdot / (8*pi*sigma_SB * r_in^3))^(1/4) t_in = ( 3.0 * _G_GRAV * 10.0**agn_log_mbh * _MSUN_G * mdot / (8.0 * jnp.pi * _SIGMA_SB * r_in**3) ) ** 0.25 r_sg_rg = _self_gravity_radius(agn_log_mbh, l_edd_ratio) r_out = jnp.maximum(r_sg_rg, r_isco * 10.0) * r_g # at least 10 r_isco # Radial grid (logarithmic spacing) log_r_min = jnp.log10(r_in) log_r_max = jnp.log10(r_out) log_r_grid = jnp.linspace(log_r_min, log_r_max, n_radii) r_grid = 10.0**log_r_grid # [cm] # Temperature profile: T(r) = T_in * (r/r_in)^{-3/4} * (1 - sqrt(r_in/r))^{1/4} r_ratio = r_grid / r_in torque_correction = jnp.maximum(1.0 - jnp.sqrt(1.0 / r_ratio), 1e-30) ** 0.25 t_profile = t_in * r_ratio ** (-0.75) * torque_correction # [K] # Integrate: L_nu = sum_i [ B_nu(T_i) * 8 * pi^2 * r_i * dr_i * cos(i) ] = 2 cos(i) D_nu # dr from logarithmic spacing: dr = r * d(ln r) = r * ln(10) * d(log r) d_log_r = log_r_grid[1] - log_r_grid[0] dr = r_grid * jnp.log(10.0) * d_log_r # [cm] # B_nu at each (radius, wavelength): shape (n_radii, n_wave) # Use vmap over radii def _ring_lnu(r_cm, t_ring, dr_ring): """Compute Planck luminosity per unit frequency for disc annulus.""" b_nu = _planck_lnu(nu, t_ring) return b_nu * _ring_area(r_cm, dr_ring, agn_cos_inc) ring_contributions = jax.vmap(_ring_lnu)(r_grid, t_profile, dr) # (n_radii, n_wave) l_nu_wien = jnp.sum(ring_contributions, axis=0) # (n_wave,) [erg s^-1 Hz^-1] # Bolometric content of the Wien disc, closed form: each ring radiates # int B_nu dnu * area = (sigma_Planck T^4 / pi) * area. Folded in L_sun so the ~1e44 erg/s # total is representable in float32 (#1206); no quadrature on the caller's grid (#2572). def _disc_bol_lsun(cos_inc): """Closed-form power of the Wien disc seen at ``cos_inc`` [L_sun].""" ring_area_all = jax.vmap(lambda rr, drr: _ring_area(rr, drr, cos_inc))(r_grid, dr) if t_profile.dtype == jnp.float32: # The constant ``c / L_sun`` (c = _BNU_BOL_PER_T4) is ~4.7e-39, subnormal in float32. # Under the vmapped graph XLA folds it to zero (flush-to-zero), so the disc's # bolometric power vanished and the 30-75 A EUV tail with it (#3105). Measuring the # temperature in units of T_NORM keeps every constant pair normal: c * T_NORM^4 / L_sun # ~ 5e-19. Float64 keeps the expression below, bit-identical. t_hat = t_profile / _T_BOL_NORM return jnp.sum( (_BNU_BOL_PER_T4 * _T_BOL_NORM**4 * t_hat**4) * (ring_area_all / float(_LSUN_ERG)) ) return jnp.sum((_BNU_BOL_PER_T4 * t_profile**4) * (ring_area_all / float(_LSUN_ERG))) disc_bol_lsun = _disc_bol_lsun(agn_cos_inc) # Optionally blend an EUV / soft-X-ray power-law tail onto the Wien core # before renormalizing, so the tail's energy is taken out of L_bol rather # than added on top (energy-conserving). Default "powerlaw" gives the disc # a CIGALE-like rise below ~100 A; "wien" recovers the bare thin disc. l_nu_intrinsic = _apply_euv_tail(wavelength, nu, l_nu_wien, euv_tail, disc_bol_lsun) # Bolometric content of the BLENDED spectrum, in units of ``unit`` [erg/s]: the Wien disc plus # what the tail adds where it exceeds Wien, int max(0, tail - wien) dnu, on fixed internal # nodes across the 30-912 A band (the tail is zero outside it). Independent of the caller's # grid (#2572). ``unit`` lets the float32 path carry O(1)-O(1e12) numbers (below) instead of # ~1e43 erg/s, and keeps the reverse-mode cotangent of the band quadrature in range. _slope = _euv_tail_slope(euv_tail) def _blended_bol(unit, cos_inc): """Power of the blended disc seen at ``cos_inc``, in units of ``unit`` [erg/s].""" disc_u = _disc_bol_lsun(cos_inc) * (_LSUN_ERG / unit) if _slope is None: return disc_u _nu_b = _wavelength_to_nu(jnp.asarray(_EUV_BAND_AA, dtype=nu.dtype)) _tail_u = _euv_tail_lnu( device_table(_EUV_BAND_AA), _nu_b, _slope, _EUV_TAIL_FRAC * disc_u / _euv_tail_shape_integral(_slope), ) _wien_u = jnp.sum( jax.vmap( lambda rr, tt, drr: _planck_lnu(_nu_b, tt) * (_ring_area(rr, drr, cos_inc) / unit) )(r_grid, t_profile, dr), axis=0, ) _excess_u = _tail_u - _wien_u # the tail's excess over the Wien form; >= 0 by definition return disc_u + jnp.trapezoid(jnp.where(_excess_u > 0.0, _excess_u, 0.0), _nu_b) # Renormalize to the unit-ratio L_bol; agn_lum_ratio then multiplies the spectrum # (the MAGNITUDE is set by ``agn_log_lbol`` (the reference on the float32 path) NOT the shape # luminosity above). ``agn_log_lbol`` is the angle-integrated accretion power, so the # normalization is the blended power at ``_COS_INC_ISOTROPIC_REFERENCE`` (where a # ``2 cos i`` disc radiates its angle-integrated power), and the spectrum, which is # homogeneous of degree one in cos i, keeps its own ``2 cos i``. # The bolometric normalization below is closed-form / on fixed internal nodes (#2572). if is_float32_arithmetic(wavelength): # Log-space renorm: ``l_bol_requested`` ~1e44 and the integral # ``l_nu_total`` (l_nu_intrinsic ~1e28 over ~1e15 Hz → ~1e43) both # overflow float32; only their ratio (~1e-33 when normalizing a # true-shape disc to a 1e10 erg/s reference) is needed. Normalize the # integrand so the trapezoid stays in range, and take the exponent # against the normalized integral, so neither side is ever formed. # Unit agn_lum_ratio in the exponent: log10(0) is -inf and its reverse pass is NaN at # ratio 0 (#2767). The ratio multiplies the returned spectrum linearly below. _log_l_bol_req = agn_log_lbol + _LOG10_LSUN_ERG # stop_gradient: factorization constant, canceled by the peak the # returned ``_l_hat`` is divided by (#1436). _peak = jax.lax.stop_gradient(jnp.max(jnp.abs(l_nu_intrinsic))) _peak = jnp.where(_peak > 0.0, _peak, 1.0) # The RETURNED array is the peak-normalized one, and the peak is left # out of the exponent to match (#1439). Algebraically # ``(l/p) * 10**(req - log h) == l * 10**(req - log p - log h)``, but the # two differ in *reverse* mode: renormalizing makes ``sum(g * arr)`` a # cotangent of the returned array, and JAX forms exactly that inner # product when transposing ``arr * scale``. With the raw ``l`` (~1e28) # and the cotangent the AGN reference offset hands back (~10**34.6), that # sum is ~1e64 -> ``inf`` in float32, while its partner # ``d scale/d l ~ 1e-64`` flushes to 0, and ``inf * 0`` is the NaN #1439 # reported. On the O(1) ``_l_hat`` both factors are in range. Forward # mode never forms the product and was correct either way, which is why # this presented as a mode asymmetry. # # Normalized to unit L1, not to unit peak: ``sum(g * arr)`` is bounded by # ``max|g| * sum|arr|``, so unit L1 caps it at the incoming cotangent # itself, while unit peak leaves a factor of n_wave (~3e3, 3.5 decades) # on top. That factor is the difference between working and overflowing # at the top of the declared ``agn_log_lbol`` prior: at log L_bol = 12 the # AGN reference offset hands back ~10**35.6, and 3e3 * 10**35.6 is past # float32's 3.4e38 ceiling. Both divisors are stop_gradient constants, so # they cancel analytically and leave the single correct derivative path. _over_peak = l_nu_intrinsic / _peak _norm = jax.lax.stop_gradient(jnp.sum(jnp.abs(_over_peak))) _norm = jnp.where(_norm > 0.0, _norm, 1.0) _l_hat = _over_peak / _norm # The bolometric of ``_l_hat`` is the closed-form total over the same two constants it # was divided by (kept in log space: ~1e43 erg/s is past float32). # Closed-form bolometric of ``_l_hat``, in its own units (peak * norm): grid-independent, # and every factor stays O(1)..O(1e12), so neither the forward nor the reverse-mode # products leave float32 range (#1439). ``representable_floor``, not the bare 1e-100 # (#1492): float32's smallest subnormal is 1.4e-45, so the literal IS 0.0 there. _log_hat_total = jnp.log10( jnp.maximum( _blended_bol(_peak * _norm, _COS_INC_ISOTROPIC_REFERENCE), _representable_floor(1e-100), ) ) # The result's own peak, so it is in range whenever the output is. _scale_hat = _pow10(_log_l_bol_req - _log_hat_total) # optimization_barrier: without it XLA is free to re-associate # ``(l/p) * s`` back into ``l * (s/p)``, which reinstates the ~1e64 # inner product this factorization exists to avoid (the same reason the # stellar component's barriers are load-bearing, #1436). return jax.lax.optimization_barrier(_l_hat) * _scale_hat * agn_lum_ratio # Unit-ratio normalization, then the ratio multiplies linearly (same design as kubota_done). l_bol_unit = 10.0**agn_log_lbol * _LSUN_ERG l_nu_total = _blended_bol(1.0, _COS_INC_ISOTROPIC_REFERENCE) l_nu_total_safe = jnp.maximum(jnp.abs(l_nu_total), _representable_floor(1e-100)) scale = l_bol_unit / l_nu_total_safe return l_nu_intrinsic * scale * agn_lum_ratio
# ── Model 3: Kubota & Done (2018) 3-zone disc ───────────────────── def _warm_comptonization_lnu( nu: jnp.ndarray, temperature: float, nu_warm: float, gamma_warm: float, ) -> jnp.ndarray: """Modified blackbody for the warm Comptonization zone. The warm zone produces a soft X-ray excess via optically thick, warm electron scattering. The SED is a Comptonized blackbody: L_nu ~ B_nu(T_disc(r)) * (nu / nu_warm)^(Gamma_warm - 1) for nu > nu_warm, otherwise pure blackbody. Parameters ---------- nu : array Frequency [Hz]. temperature : float Local disc temperature [K]. nu_warm : float Warm electron characteristic frequency [Hz], derived from kT_warm. gamma_warm : float Warm Comptonization photon index (~2.5). Returns ------- array Modified B_nu [erg s^-1 cm^-2 Hz^-1 sr^-1]. """ b_nu = _planck_lnu(nu, temperature) # Seed frequency from the LOCAL disc blackbody temperature at this ring radius. # The warm Comptonization zone up-scatters photons from the disc temperature # to the warm electron temperature kT_warm (K&D 2018, MNRAS 480, 1247, Eq. 3). nu_seed = _K_BOLTZ * temperature / _H_PLANCK # Power-law enhancement between nu_seed and nu_warm (soft X-ray cutoff) ratio = nu / jnp.maximum(nu_seed, 1.0) # Cap the enhancement at (nu_warm/nu_seed)^(Gamma-1) to avoid divergence above cutoff max_enh = (nu_warm / jnp.maximum(nu_seed, 1.0)) ** (gamma_warm - 1.0) enhancement = jnp.where( ratio > 1.0, jnp.minimum(ratio ** (gamma_warm - 1.0), max_enh), 1.0, ) return b_nu * enhancement #: Gauss-Legendre order of the radial ring rule in ``ln r``, per zone. The disc and warm #: integrals are smooth in ``ln r`` on each zone, so the rule converges well before this order. _RING_GL_ORDER = 64 _RING_GL_T, _RING_GL_W = np.polynomial.legendre.leggauss(_RING_GL_ORDER) @jax.jit def _ring_gl_tables(): """The ring rule's nodes and weights on ``[-1, 1]``, one called computation per dtype. Every ``kubota_done`` trace on the tied path calls this jitted function, so the tables enter the outer graph once, inside one shared sub-jaxpr, rather than as literals at each of the inlined copies (#3044). The jit cache keys on the x64 state, so the dtype follows the trace. """ return device_table(_RING_GL_T), device_table(_RING_GL_W) @jax.jit def _warm_norm_grid(): """The warm-zone normalization grid [Hz], one called computation per dtype (#3044).""" return device_table(_nthcomp_norm_grid()) def _log_r_gauss_legendre(log_lo, log_hi): """Gauss-Legendre nodes ``log10 r`` on ``[log_lo, log_hi]`` and their ``d(log10 r)`` weights. The rule replaces a uniform rectangle sum, whose O(1 %) error on the zone power fed the normalization (#2733). Returned in ``log10`` units, matching the zone grids. """ half = 0.5 * (log_hi - log_lo) mid = 0.5 * (log_hi + log_lo) gl_t, gl_w = _ring_gl_tables() nodes = mid + half * gl_t weights = half * gl_w return nodes, weights # Fixed internal frequency grid for corona normalization. # Matches RELAGN (scotthgn/RELAGN) default: [1e-4, 1e4] keV → [2.418e13, 2.418e21] Hz. # Using a fixed grid makes the normalization integral grid-independent, # so the corona's optical flux doesn't change with the caller's wavelength grid. # The bare power-law nu^(1-Gamma) diverges at low frequencies for Gamma > 1; # a fixed lower bound removes this ambiguity. The normalization is the log-log integral on # 8000 log-spaced points: 1e-7 from its 40000-node value (a trapezoid on 2000 points was 1.6e-5 # off and a log-log on 2000 points 1.9e-6). _CORONA_NU_LO_HZ: float = 2.418e13 _CORONA_NU_HI_HZ: float = 2.418e21 _CORONA_NU_NODES: int = 8000 def _corona_nu_grid() -> jnp.ndarray: """The fixed corona normalization grid, built inside the trace from scalar end points. An array literal would enter the traced graph as a constant (the grid is 8000 nodes); the log-spaced nodes are computed from the two end points instead. """ return jnp.exp( jnp.linspace(math.log(_CORONA_NU_LO_HZ), math.log(_CORONA_NU_HI_HZ), _CORONA_NU_NODES) ) def _hot_corona_lnu( nu: jnp.ndarray, l_hot_erg: float, gamma_hard: float, kt_hot_erg: float, nu_seed_hz: float = 0.0, ) -> jnp.ndarray: r"""Hot corona emission: thermal-Comptonization power law with two cutoffs. The optically thin, hot corona produces hard X-ray emission via thermal Comptonization of seed photons. The spectrum is a power law bounded by a high-energy cutoff at the electron temperature *and* a low-energy rollover at the seed-photon energy: .. math:: L_\nu \propto \nu^{\,1-\Gamma_{\rm hot}} \, \exp\!\left(-\frac{h\nu}{kT_{e,\rm hot}}\right) \, \exp\!\left(-\frac{\nu_{\rm seed}}{\nu}\right) where :math:`\Gamma_{\rm hot}` is the hard X-ray photon index, :math:`kT_{e,\rm hot}` the electron temperature [erg], and :math:`\nu_{\rm seed}` the seed-photon frequency [Hz]. The low-energy rollover :math:`\exp(-\nu_{\rm seed}/\nu)` is the piece that ``nthcomp`` carries intrinsically: it tends to 1 for :math:`\nu \gg \nu_{\rm seed}` (leaving the X-ray power law untouched) and to 0 for :math:`\nu \ll \nu_{\rm seed}`. Without it the bare :math:`\nu^{1-\Gamma}` tail rises monotonically toward low frequency for :math:`\Gamma > 1`, so the corona leaks unphysically into the infrared and radio. A thermal-Comptonization spectrum is only defined *between* its seed-photon energy and the electron temperature; there are no Comptonized photons below the seed energy (Kubota & Done 2018 [1]_, Section 2.2). Normalized so that the frequency-integrated luminosity equals ``l_hot_erg``. The normalization integral is computed on a fixed internal frequency grid matching RELAGN's default [1e-4, 1e4] keV, making the result independent of the caller's wavelength grid (the corona's optical contribution does not vary with grid extent). Parameters ---------- nu : array_like, shape (n_wave,) Frequency [Hz]. l_hot_erg : float Total hot corona luminosity [erg s^-1]. gamma_hard : float Hard X-ray photon index (~1.8). kt_hot_erg : float Hot corona electron temperature [erg] (= kT_e,hot in erg). nu_seed_hz : float, optional Seed-photon frequency [Hz] setting the low-energy rollover. Default ``0.0`` disables the rollover (legacy bare power law). The three-zone ``kubota_done_disc`` passes the K&D 2018 value :math:`k\,T_{\rm NT}(R_{\rm hot})\,\exp(y_{\rm warm})/h`. Returns ------- shape : ndarray, shape (n_wave,) The Comptonization shape relative to its peak on the internal grid, so ``max <= ~1`` [dimensionless]. log10_amplitude : float ``log10(l_hot_erg / integral)`` [dex], so that :math:`L_\nu` [erg s^-1 Hz^-1] ``= shape * 10**log10_amplitude``. The product is never formed here: its factors sit at opposite ends of the float32 range, and the caller applies the exponent once, to the normalized shape, alongside its own normalization (#2767). Notes ----- **JIT-compatible**: yes, pure ``jnp`` primitives, no Python branching on traced values. References ---------- .. [1] A. Kubota and C. Done, "A physical model of the broadband continuum of AGN and its implications for the UV/X relation and optical variability," MNRAS, 480, 1247 (2018). arXiv:1804.00171. DOI:10.1093/mnras/sty1890. Section 2.2 (seed photons of the hot flow). .. [2] RELAGN (scotthgn/RELAGN) ``do_nonrelHotCompSpec``: normalizes on a fixed [1e-4, 1e4] keV grid. """ kt_safe = jnp.maximum(kt_hot_erg, 1e-30) def _comp_log_shape(freq): """Log of the band-limited Comptonization shape: rollover x power law x cutoff. Kept in log space and exponentiated only after a shift by the grid peak (see below). ``exp(-x_hi)`` and ``exp(-x_lo)`` each underflow to 0 in float32 before their product could be formed, so the product is never formed that way. """ freq_safe = jnp.maximum(freq, 1e-30) x_hi = jnp.clip( # electron-temperature cutoff _H_PLANCK * freq / kt_safe, 0.0, representable_exponent(500.0, base=math.e) ) x_lo = jnp.clip( # seed-photon rollover nu_seed_hz / freq_safe, 0.0, representable_exponent(700.0, base=math.e) ) return (1.0 - gamma_hard) * jnp.log(freq_safe) - x_hi - x_lo grid_nu = _corona_nu_grid() # Normalize on the fixed internal grid (grid-independent). The shape and the # integral are both taken relative to the grid peak in log space: shape/integral is # unchanged by the shift, the integral is O(1) per node, and the shift's own # derivative is zero, so it is stopped. Without the shift the reverse pass # multiplies cotangents by 1/peak, which overflows float32 (#2767). log_norm = _comp_log_shape(grid_nu) log_peak = jax.lax.stop_gradient(jnp.max(log_norm)) integral = loglog_integral(grid_nu, jnp.exp(log_norm - log_peak)) integral_safe = jnp.maximum(jnp.abs(integral), _representable_denominator(1e-100)) shape_scaled = jnp.exp(_comp_log_shape(nu) - log_peak) log10_amplitude = jnp.log10(jnp.maximum(l_hot_erg, _representable_floor(1e-100))) - jnp.log10( integral_safe ) return shape_scaled, log10_amplitude def _compute_bh_params( agn_log_mbh: float, agn_log_lbol: float, agn_a_spin: float, float32: bool = False, h_inf: float | None = None, ) -> tuple: """Compute black hole parameters: radius, ISCO, efficiency, and accretion rate. Derives the fundamental mass-dependent quantities: gravitational radius, ISCO radius, radiative efficiency (Novikov-Thorne), Eddington luminosity, and mass accretion rate from the black hole mass and spin parameter. Parameters ---------- agn_log_mbh : float Black hole mass. [log10(M_sun)] agn_log_lbol : float Bolometric luminosity. [log10(L_bol / L_sun)] agn_a_spin : float Dimensionless black hole spin (Kerr, prograde). [dimensionless, 0–0.998] Returns ------- tuple (r_g, r_isco_rg, r_isco_cm, eta, log10_l_edd, mdot) where: - r_g : Gravitational radius [cm] - r_isco_rg : ISCO radius in units of r_g [dimensionless] - r_isco_cm : ISCO radius [cm] - eta : Radiative efficiency (Novikov-Thorne) [dimensionless, 0–0.42] - log10_l_edd : log10 Eddington luminosity [log10(erg s^-1)] - mdot : Mass accretion rate [g s^-1] Notes ----- **JIT-compatible**: yes, uses only ``jnp`` primitives. The radiative efficiency follows the Novikov-Thorne formula for thin discs around Kerr black holes (Novikov & Thorne 1973, Kerr metric). ``log10_l_edd`` is returned in log space, not as the linear Eddington luminosity (#2210): the linear form is ~1.26e44 erg/s at the bottom of the declared ``agn_log_mbh`` prior, past float32's 3.403e38 ceiling everywhere in that prior, whether or not ``float32`` is set here -- the caller decides what to form from it. References ---------- .. [1] D. N. Page and K. S. Thorne, "Disk-Accretion onto a Black Hole. Time-Averaged Structure of Accretion Disk," ApJ, 191, 499 (1974). """ r_g = _gravitational_radius(agn_log_mbh) r_isco_rg = _isco_radius(agn_a_spin) r_isco_cm = r_isco_rg * r_g eta = _radiative_efficiency(r_isco_rg) log10_l_edd = _log10_eddington_luminosity(agn_log_mbh) # Mdot is inferred so that the disc's own total Page-Thorne dissipation, ``L_diss = Mdot c^2 # (3 h(inf) / (2 r_isco))``, equals L_bol (owner ruling 2026-10-20); ``eta`` is returned for # callers but no longer sets the accretion rate. diss_per_mdot_c2 = _disc_dissipation_per_mdot_c2(agn_a_spin, h_inf) # E fix (#846): derive the accretion rate from the requested L_bol # (agn_log_lbol) instead of the now-derived Eddington ratio, so the zone # structure (T_in, radii) is self-consistent with L_bol. lambda_Edd is # recovered downstream as L_bol / L_Edd (see _compute_zone_radii). if float32: # Float32 (#1206): the ~1e44 erg/s l_bol_erg intermediate overflows; # mdot ~1e24 g/s is representable. Fold L_sun/c^2 (a pre-divided # constant ~4e12) so only ``10**log_lbol`` (~1e11) is materialized. mdot = _LSUN_OVER_C2 * 10.0**agn_log_lbol / diss_per_mdot_c2 else: l_bol_erg = 10.0**agn_log_lbol * _LSUN_ERG mdot = l_bol_erg / (diss_per_mdot_c2 * _C_LIGHT**2) return r_g, r_isco_rg, r_isco_cm, eta, log10_l_edd, mdot def _hot_flow_luminosity( agn_f_hard: float, log10_l_edd: float, l0: float, a_spin: float = 0.0, float32: bool = False, agn_log_mbh: float = DEFAULT_AGN_LOG_MBH, x_hot_max: float | None = None, h_inf: float | None = None, ) -> float: """Hot-flow dissipation ``L_hot = f_hard L_Edd``, limited by what the disc can supply (#2572). K&D 2018 (MNRAS 480, 1247) Sec. 5.1, Table 3: "we fix Ldiss,hot = 0.02 LEdd, which defines rhot" (Sec. 2.2, Eq. 2: ``Ldiss,hot = 2 int_{R_isco}^{R_hot} sigma T_NT^4 2 pi R dR``). The public QSOSED/RELQSO source (``relqso.f``, Hagen & Done) does the same: the "disc truncation radius (Rhot) is set by the requirement that the dissipated luminosity in the corona Lx_diss=0.02Ledd", and when the integral never reaches it ("WARNING!!! Ldiss never reaches 0.02Ledd => No upper limit for r_hot") the whole flow is hot, ``rh = rout``, with no disc or warm zone. There is **no** ``L_bol / 2`` cap in either, so the corona radiates the full ``f_hard L_Edd`` (a ``min(f_hard L_Edd, L_bol / 2)`` cap would weaken it by 21% at ``log lambda_Edd = -1.5``). tengri cannot drop zones (static shapes), so the unreachable case is represented by saturating: ``L_hot`` is limited to what the annuli inside the largest admissible ``R_hot`` dissipate, ``L0 h(x_hot_max)`` with ``x_hot_max = R_out / R_isco`` (the zone clip of :func:`_compute_zone_radii`), and never above ``L0 h_ceiling(a)`` (99% of the disc's total dissipation ``L0 h(inf)``, the bisection's own ceiling). The corona then radiates exactly the power the hot flow dissipates inside ``R_hot``: ``L_diss,hot(R_hot) = L_hot`` holds by construction, saturated or not. Where the disc can supply ``f_hard L_Edd`` -- the paper's grid is ``mdot = 0.03 - 1`` -- ``L_hot = f_hard L_Edd`` exactly. Parameters ---------- x_hot_max : float, optional ``R_out / R_isco``, the largest ``R_hot / R_isco`` the zone clip allows [dimensionless]. Omitted, only the bisection's ceiling applies. Both ``R_hot`` (the zone radii) and the corona normalization (the SED) use THIS value. ``l0`` is ``4 pi R_isco^2 sigma T_in^4`` (:func:`_nt_l0`). Returns erg/s, or L_sun on the float32 path (#1206: ~1e44 erg/s overflows). """ f_hard_safe = jnp.clip(agn_f_hard, 1e-6, 0.5) if float32: l_hot = f_hard_safe * (_L_EDD_1MSUN_LSUN * 10.0**agn_log_mbh) else: l_hot = f_hard_safe * _pow10(log10_l_edd) return jnp.minimum(l_hot, l0 * _hot_flow_h_cap(a_spin, x_hot_max, h_inf)) def _radiative_efficiency(r_isco_rg: float) -> float: """Novikov-Thorne efficiency ``eta = 1 - sqrt(1 - 2 / (3 r_isco))`` [dimensionless].""" return 1.0 - jnp.sqrt(1.0 - 2.0 / (3.0 * r_isco_rg)) def _hot_flow_h_cap( a_spin: float, x_hot_max: float | None = None, h_inf: float | None = None ) -> float: """Largest ``L_diss,hot / L_0`` the disc can supply [dimensionless]. The bisection ceiling ``h_ceiling(a)``, further limited to ``h(x_hot_max)`` when the zone clip is given. :func:`_hot_flow_luminosity` caps the corona power at ``L_0`` times this. """ cap = _nt_h_ceiling(a_spin) if h_inf is None else _NT_H_CEILING_FRACTION * h_inf if x_hot_max is not None: cap = jnp.minimum(cap, _nt_h(jnp.log(x_hot_max), a_spin)) return cap def _disc_dissipation_per_mdot_c2(a_spin: float, h_inf: float | None = None) -> float: r"""Disc dissipation per rest-mass power, :math:`L_{\rm diss} / (\dot M c^2)` [dimensionless]. The Page & Thorne (1974) dissipation integral over every annulus, :math:`L_{\rm diss} = 2\int_{R_{\rm isco}}^{\infty} \sigma T_{\rm NT}^4\, 2\pi R\,{\rm d}R = L_0 h(\infty)` with :math:`L_0 = 4\pi R_{\rm isco}^2 \sigma T_{\rm in}^4 = 3 G M \dot M / (2 R_{\rm isco}) = 3 \dot M c^2 / (2 r_{\rm isco})` (Kubota & Done 2018, Eq. 2 with :math:`R_{\rm hot} \to \infty`), so the ratio is :math:`3 h(\infty) / (2 r_{\rm isco})`. It is :math:`\approx 1.019\,\eta` at zero spin and rises with spin. O(1) in :math:`\dot M c^2` units, so no large power is formed. ``h(inf)`` is evaluated at ``X_MAX = 1e4`` :math:`R_{\rm isco}` (:func:`_nt_h`), the same ceiling the :math:`R_{\rm hot}` solve uses. The integrand falls as :math:`x^{-2}`, so the truncated tail is :math:`1/X_{\rm max} = 10^{-4}` of :math:`L_0`, about 4e-4 of :math:`h(\infty)` at zero spin. Mdot is set so that :math:`L_0 h(X_{\rm max}) = L_{\rm bol}`; the integral to infinity exceeds :math:`L_{\rm bol}` by that 4e-4, below any tolerance here. Parameters ---------- a_spin : float Dimensionless spin [dimensionless]. h_inf : float, optional ``h(X_MAX)``, when the caller has it already [dimensionless]. """ if h_inf is None: h_inf = _nt_h(jnp.log(_NT_X_MAX), a_spin) return 1.5 * h_inf / _isco_radius(a_spin) def _hot_flow_fraction( agn_f_hard: float, log10_edd_over_bol: float, a_spin: float, x_hot_max: float | None = None, h_inf: float | None = None, ) -> float: r"""Corona share of the bolometric power, :math:`L_{\rm hot} / L_{\rm bol}` [dimensionless]. The cap of :func:`_hot_flow_luminosity`, :math:`L_{\rm hot} = \min(f_{\rm hard} L_{\rm Edd},\, L_0 h_{\rm cap})` (Kubota & Done 2018, Sec. 5.1 and Table 3, with :math:`L_{\rm diss,hot}` of their Eq. 2), divided through by :math:`L_{\rm bol}` analytically. The accretion rate is inferred so that the disc's own total dissipation (Page & Thorne 1974), :math:`L_0 h(\infty)`, equals :math:`L_{\rm bol}` (see :func:`_disc_dissipation_per_mdot_c2`), so .. math:: \frac{L_0}{L_{\rm bol}} = \frac{1}{h(\infty)} depends on the spin alone and the share is at most :math:`0.99` (the cap is 99% of :math:`h(\infty)`) by construction. Every factor is O(1), so the share carries a few float32 ulps instead of the ~1e-6 dex that ``log10 L_hot`` and ``log10 L_bol`` (each ~11 in L_sun) carry, which a difference of near-equal powers would amplify. Parameters ---------- agn_f_hard : float Hard fraction of Eddington [dimensionless]. log10_edd_over_bol : float ``log10(L_Edd / L_bol)`` [dex]. a_spin : float Dimensionless black hole spin [dimensionless]. x_hot_max : float, optional ``R_out / R_isco`` zone clip [dimensionless]. Returns ------- float ``L_hot / L_bol`` [dimensionless], at most 0.99. References ---------- .. [1] A. Kubota and C. Done, MNRAS, 480, 1247 (2018), arXiv:1804.00171. .. [2] D. N. Page and K. S. Thorne, ApJ, 191, 499 (1974). """ f_hard_safe = jnp.clip(agn_f_hard, 1e-6, 0.5) # One evaluation of ``h(inf)``: the disc's total dissipation and, times 0.99, the cap. if h_inf is None: h_inf = _nt_h(jnp.log(_NT_X_MAX), a_spin) cap = _NT_H_CEILING_FRACTION * h_inf if x_hot_max is not None: cap = jnp.minimum(cap, _nt_h(jnp.log(x_hot_max), a_spin)) return jnp.minimum(f_hard_safe * _pow10(log10_edd_over_bol), cap / h_inf) #: Smallest ``R_out / R_ISCO`` [dimensionless]. A numerical bound, not physics: it keeps #: ``R_hot`` (which is at least ``1.01 R_ISCO``) inside the disc when the self-gravity radius is #: smaller than the ISCO, which only a very massive, very sub-Eddington hole reaches. Above it #: ``R_out = r_sg`` exactly, as in RELAGN (``r_out = r_sg``, Hagen & Done 2023, arXiv:2304.01253). _R_OUT_MIN_OVER_ISCO = 1.01 #: Relative distance from ``R_out`` within which ``R_hot`` is ``R_out`` [dimensionless]. #: The bisection converges to 1e-12 (``_bisect_log_x``), so this is five decades above it. _R_HOT_SNAP_RTOL = 1e-7 #: Width, as a fraction of ``R_out``, below which a K&D zone is empty [dimensionless]. _ZONE_WIDTH_RTOL = 1e-7 def _zone_outer_radius_rg(r_sg_rg: float, r_isco_rg: float) -> float: """Outer disc radius of the K&D zones in ``R_g``: the self-gravity radius. ``R_out = r_sg`` (Laor & Netzer 1989; K&D 2018 Sec. 2.2), bounded below by ``_R_OUT_MIN_OVER_ISCO * R_ISCO`` for numerical safety only. """ return jnp.maximum(r_sg_rg, r_isco_rg * _R_OUT_MIN_OVER_ISCO) def _hot_zone_x_max(r_isco_rg: float, r_sg_rg: float) -> float: """Largest admissible ``R_hot / R_isco``: the outer radius ``R_out`` in units of ``R_isco``. ``R_out = r_sg`` (see :func:`_zone_outer_radius_rg`), so the ratio needs no physical constants. The clip of :func:`_clip_zone_radii` admits ``R_hot`` up to ``R_out``. """ return _zone_outer_radius_rg(r_sg_rg, r_isco_rg) / r_isco_rg
[docs] def kubota_done_unemitted_fraction( agn_log_mbh: float, agn_log_lbol: float, agn_a_spin: float = DEFAULT_AGN_A_SPIN ) -> float: r"""Share of the accretion power the K&D disc does not emit, :math:`R_{\rm unem}/L_{\rm bol}`. The disc's total Page-Thorne dissipation is :math:`L_0 h(\infty)` and equals :math:`L_{\rm bol}` (:func:`_disc_dissipation_per_mdot_c2`). The zones emit down to :math:`R_{\rm out}`, so the dissipation beyond it is not emitted (K&D 2018 Sec. 2.2, which stops the disc at the self-gravity radius): .. math:: \frac{R_{\rm unem}}{L_{\rm bol}} = 1 - \frac{h(R_{\rm out}/R_{\rm ISCO})}{h(\infty)}, with :math:`h` the dimensionless Novikov-Thorne integral (:func:`_nt_h`) and :math:`R_{\rm out} = R_{\rm sg}` as in :func:`_compute_zone_radii`. The remainder is published as ``log_L_agn_disc_unemitted`` by the composable runner (#3015). Parameters ---------- agn_log_mbh : float log10 black hole mass [log10(Msun)]. agn_log_lbol : float log10 bolometric (accretion) power [log10(Lsun)]. agn_a_spin : float, optional Dimensionless spin [dimensionless]. Returns ------- float :math:`R_{\rm unem}/L_{\rm bol}` [dimensionless], in ``[0, 1)``. Notes ----- **JIT/grad/vmap-safe**: yes. The Eddington ratio is formed in log space, as in :func:`_compute_zone_radii`. References ---------- .. [1] A. Kubota and C. Done, MNRAS, 480, 1247 (2018), arXiv:1804.00171. """ l_edd_ratio = jnp.clip( _pow10(agn_log_lbol + _LOG10_LSUN_ERG - _log10_eddington_luminosity(agn_log_mbh)), 1e-10, 1.0, ) r_isco_rg = _isco_radius(agn_a_spin) r_sg_rg = _self_gravity_radius(agn_log_mbh, l_edd_ratio) x_out = _hot_zone_x_max(r_isco_rg, r_sg_rg) h_inf = _nt_h(jnp.log(_NT_X_MAX), agn_a_spin) return 1.0 - _nt_h(jnp.log(x_out), agn_a_spin) / h_inf
def _compute_zone_radii( r_g: float, r_isco_rg: float, r_isco_cm: float, t_in: float, agn_log_mbh: float, agn_log_lbol: float, agn_f_hard: float, agn_r_warm_ratio: float, log10_l_edd: float, float32: bool = False, agn_a_spin: float = DEFAULT_AGN_A_SPIN, h_inf: float | None = None, ) -> tuple: """Compute self-consistent zone radii: R_hot, R_warm, and R_out. Solves for the radii that define the three AGN accretion zones (Kubota & Done 2018). R_hot is derived self-consistently from the energy-balance constraint that the hot corona dissipates f_hard × L_Edd. R_warm is parameterized as a multiple of R_hot. R_out is the self-gravity (Toomre) radius beyond which the disc becomes unstable. Parameters ---------- r_g : float Gravitational radius [cm]. r_isco_rg : float ISCO radius in gravitational radii [dimensionless]. r_isco_cm : float ISCO radius [cm]. t_in : float Inner disc temperature [K]. agn_log_mbh : float Black hole mass. [log10(M_sun)] agn_log_lbol : float Bolometric luminosity. [log10(L_bol / L_sun)] agn_f_hard : float Fraction of Eddington luminosity in the hot corona. [dimensionless, 0–0.5] agn_r_warm_ratio : float Radius ratio R_warm / R_hot. [dimensionless, ≥ 1.1] log10_l_edd : float log10 Eddington luminosity. [log10(erg s^-1)] Returns ------- tuple (r_hot_cm, r_warm_cm, r_out_cm) zone radii in [cm]. Notes ----- **JIT-compatible**: yes, uses ``jax.lax.scan`` for JAX-compatible bisection. **Self-consistent R_hot**: Uses bisection on the Page-Thorne (relativistic Novikov-Thorne) dissipation integral (40 iterations, exact to ~1e-12) to solve L_diss,hot(R_hot) = f_hard × L_Edd (K&D 2018 Eq. 2), spin included. **Self-consistent R_out**: Uses the Laor & Netzer (1989) self-gravity (Toomre) radius, which is more accurate for extreme BH masses and Eddington ratios than the previous fixed 1000 × r_isco approximation. References ---------- .. [1] A. Kubota and C. Done, "A physical model of the broad-band continuum of AGN and its implications for the UV/X relation and optical variability," MNRAS, 480, 1247 (2018). arXiv:1804.00171. .. [2] A. Laor and B. Netzer, "Dust Sublimation Depth in the Infrared-Emitting Accretion Disks of Quasars," MNRAS, 238, 897 (1989). """ # lambda_Edd = L_bol / L_Edd (E fix, #846), from the requested agn_log_lbol rather than the # now-derived agn_log_ledd. It is one ``pow10`` of a difference of logarithms in both # precisions (#2210): neither L_Edd (~1e46 erg/s) nor L_bol is materialized, and in reverse # mode the cotangent is multiplied by the ratio itself, not by ``L_bol`` before a division by # ``L_Edd`` (the former form overflows float32 for a cotangent of ~1e32, #2767). l_edd_ratio = jnp.clip(_pow10(agn_log_lbol + _LOG10_LSUN_ERG - log10_l_edd), 1e-10, 1.0) r_sg_rg = _self_gravity_radius(agn_log_mbh, l_edd_ratio) r_out_cm = _zone_outer_radius_rg(r_sg_rg, r_isco_rg) * r_g # R_hot is solved from the SAME L_hot the corona radiates (#2572), limited to what the # annuli inside the outer radius R_out dissipate. l_hot_target = _hot_flow_luminosity( agn_f_hard, log10_l_edd, _nt_l0(r_isco_cm, t_in, float32), agn_a_spin, float32=float32, agn_log_mbh=agn_log_mbh, x_hot_max=_hot_zone_x_max(r_isco_rg, r_sg_rg), h_inf=h_inf, ) if float32: r_hot_cm = _r_hot_bisect(r_isco_cm, t_in, l_hot_target, float32=True, a_spin=agn_a_spin) else: r_hot_cm = _r_hot_bisect(r_isco_cm, t_in, l_hot_target, a_spin=agn_a_spin) r_warm_ratio_safe = jnp.clip(agn_r_warm_ratio, 1.1, 10.0) r_warm_cm = r_hot_cm * r_warm_ratio_safe r_hot_cm, r_warm_cm = _clip_zone_radii(r_hot_cm, r_warm_cm, r_isco_cm, r_out_cm) return r_hot_cm, r_warm_cm, r_out_cm def _clip_zone_radii(r_hot_cm, r_warm_cm, r_isco_cm, r_out_cm): r"""Clip ``R_hot`` and ``R_warm`` into their ordered ranges, shared by every disc path. .. math:: R_{\rm ISCO} < R_{\rm hot} \le R_{\rm out}, \qquad R_{\rm hot} \le R_{\rm warm} \le R_{\rm out} The upper bounds are the outer radius itself, as in K&D 2018 (Sec. 2.2, ``r_warm = r_out`` is their "entire outer disc" geometry) and the RELQSO source, which sets ``r_h = r_out`` when the dissipation never reaches ``f_hard L_Edd``. Equal radii are allowed: a zone of zero width carries zero power (:func:`_zone_ring_reference`). Parameters ---------- r_hot_cm, r_warm_cm : float Unclipped hot-flow and warm-zone radii [cm]. r_isco_cm : float ISCO radius [cm]. r_out_cm : float Outer disc radius [cm]. Returns ------- tuple ``(r_hot_cm, r_warm_cm)`` clipped [cm]. """ # Where the hot flow fills the disc the bisection lands within its tolerance of ``R_out`` but # not on it; the left-over width (~1e-12 R_out) would carry a disc and warm zone of noise-level # power whose logarithm is a difference of near-equal numbers, with forward- and reverse-mode # derivatives that differ by the round-off amplified 1e12-fold (#3015). Snap it onto ``R_out``, # a zero-width zone that contributes exactly zero. r_hot_cm = jnp.where( r_hot_cm >= r_out_cm * (1.0 - _R_HOT_SNAP_RTOL), r_out_cm, jnp.clip(r_hot_cm, r_isco_cm * 1.01, r_out_cm), ) r_warm_cm = jnp.clip(r_warm_cm, r_hot_cm, r_out_cm) return r_hot_cm, r_warm_cm def _ring_area_relative(r_cm, dr_cm, cos_inc, r_ref_cm, dr_ref_cm): """Ring area in units of ``ring_area(r_ref, dr_ref, 1)``, from O(1) ratios [dimensionless]. ``ring_area`` is bilinear in ``r`` and ``dr``, so ``ring_area(r, dr, c) = ring_area(r_ref, dr_ref, 1) * ring_area(r/r_ref, dr/dr_ref, c) / ring_area(1, 1, 1)``. The ~6e31 cm^2 areas, and the cotangents that would multiply them in reverse mode, never form in float32 (#2767). """ return _ring_area(r_cm / r_ref_cm, dr_cm / dr_ref_cm, cos_inc) / _ring_area(1.0, 1.0, 1.0) def _log10_ring_area_unit(r_ref_cm, dr_ref_cm): """``log10(ring_area(r_ref, dr_ref, 1))`` [dex], the unit of :func:`_ring_area_relative`.""" return math.log10(_ring_area(1.0, 1.0, 1.0)) + jnp.log10(r_ref_cm) + jnp.log10(dr_ref_cm) def _zone_ring_reference(r_cm, dr_cm): """Factorization reference ``(r_ref, dr_ref)`` of a zone's rings, safe at zero width [cm]. ``r_ref`` is the largest radius and ``dr_ref`` the largest ring width, both held under ``stop_gradient``: they are a pure factorization constant that cancels between :func:`_ring_area_relative` and :func:`_log10_ring_area_unit`. A zero-width zone (its inner and outer radii coincide, #3015) has ``max(dr) = 0``, so ``dr_ref`` falls back to 1 there; its rings then have zero area and contribute exactly zero, with no 0/0. """ r_ref = jax.lax.stop_gradient(jnp.max(r_cm)) dr_max = jax.lax.stop_gradient(jnp.max(dr_cm)) dr_ref = jnp.where(dr_max > 0.0, dr_max, 1.0) return r_ref, dr_ref def _compute_zone_luminosities( nu: jnp.ndarray, r_isco_cm: float, r_hot_cm: float, r_warm_cm: float, r_out_cm: float, t_in: float, agn_cos_inc: float, n_radii: int, agn_gamma_warm: float, agn_kt_warm: float, agn_gamma_hard: float, agn_kt_hot: float, agn_f_hard: float, log10_l_edd: float, l_bol_erg: float, agn_self_consistent_gamma: bool, float32: bool = False, agn_log_mbh: float = DEFAULT_AGN_LOG_MBH, agn_log_lbol_shape: float = 0.0, agn_a_spin: float = DEFAULT_AGN_A_SPIN, nthcomp_table=None, h_inf: float | None = None, ) -> tuple: r"""Compute self-consistent luminosities of the three AGN zones, disc and corona apart. Integrates the Novikov-Thorne temperature profile over annuli in each zone (outer standard disc, warm Comptonization, hot corona) and combines the spectral shapes (blackbody, Comptonized, power-law) into a total L_ν. Applies a global normalization to conserve the input accretion power. Parameters ---------- nu : array, shape (n_wave,) Frequency [Hz]. r_isco_cm : float ISCO radius [cm]. r_hot_cm : float Hot corona radius [cm]. r_warm_cm : float Warm zone radius [cm]. r_out_cm : float Outer disc radius [cm]. t_in : float Inner disc temperature [K]. agn_cos_inc : float Cosine of inclination angle [dimensionless, 0–1]. n_radii : int Kept for call compatibility and not used: each zone is integrated with the fixed Gauss-Legendre rule ``_RING_GL_ORDER`` in ``ln r``, so the result does not depend on it. agn_gamma_warm : float Photon index of warm Comptonization [dimensionless, ~1.5–3.5]. agn_kt_warm : float Electron temperature in warm zone [keV]. agn_gamma_hard : float Photon index of hard X-ray power law [dimensionless, ~1.5–2.5]. agn_kt_hot : float Electron temperature in hot corona [keV]. agn_f_hard : float Fraction of Eddington luminosity in corona [dimensionless, 0–0.5]. log10_l_edd : float log10 Eddington luminosity. [log10(erg s^-1)] l_bol_erg : float Bolometric power the spectra are normalized to, at unit ``agn_lum_ratio`` [erg s^-1] (L_sun on the float32 path). The caller applies ``agn_lum_ratio`` linearly to the returned spectra; no ratio enters the logarithm here (#2767). agn_self_consistent_gamma : bool If True, derive gamma_hard self-consistently from Beloborodov (1999). Returns ------- tuple (l_nu_total, scale, l_nu_disc, l_nu_hot, corona_fraction, log10_scale) where: - l_nu_total : Total L_ν(i) = 2 cos i D_ν + H_ν, scaled so that its power at ``cos i = 0.5`` is ``l_bol_erg`` [erg s^-1 Hz^-1] - scale : The shape-to-output factor ``k = l_bol_erg / L_shape``, the factor the disc and warm zones and the corona are multiplied by. It is not a rescale of the zones: their own dissipations are kept (#3015). [dimensionless] - l_nu_disc : Disc and warm-zone part of the line-of-sight spectrum, ``2 cos i D_ν``, normalized [erg s^-1 Hz^-1] - l_nu_hot : Corona ``H_ν``, isotropic, normalized [erg s^-1 Hz^-1] - corona_fraction : ``L_hot / L_bol``, the corona's share of the accretion power, in closed form from the radial integration (no spectral grid) [dimensionless] - log10_scale : ``log10(k)``, formed as a difference of logarithms so the conversion can be applied to an unnormalized spectrum without leaving the float32 range in either autodiff mode [dex] Notes ----- **JIT-compatible**: yes, uses ``jax.vmap`` for radial integration. **Energy budget (no rescale, #3015)**: The accretion rate is inferred so that the disc's own total Page-Thorne dissipation to infinity equals ``l_bol`` (:func:`_disc_dissipation_per_mdot_c2`). Each zone emits its own dissipation: the corona ``l_hot`` (K&D 2018 Eq. 2), the warm and outer zones ``L0 (h(x_out) - h(x_hot))``. Nothing is rescaled to absorb the rest, so the dissipation beyond ``R_out`` is not emitted and is published separately (:func:`kubota_done_unemitted_fraction`). The warm shape is normalized by its own integral, so the spectra integrate to their zone powers on any grid that covers the template band. The corona power is :math:`L_{\rm diss,hot} = 2\int_{R_{\rm isco}}^{R_{\rm hot}} \sigma T_{\rm NT}^4\, 2\pi R\, {\rm d}R` (Kubota & Done 2018, Sec. 2.2, Eq. 2), set to :math:`\min(f_{\rm hard} L_{\rm Edd}, L_0 h(R_{\rm out}/R_{\rm ISCO}))` (Sec. 5.1, Table 3). Its share of :math:`L_{\rm bol}` is at most 0.99 (:func:`_hot_flow_fraction`), formed from O(1) numbers, not from two float32 logarithms of ~1e11 powers. References ---------- .. [1] A. Kubota and C. Done, MNRAS, 480, 1247 (2018). .. [2] A. M. Beloborodov, ApJL, 510, L123 (1999). """ # ── Zone 1: Outer standard disc (r > R_warm) ────────────────── log_r_warm = jnp.log10(r_warm_cm) log_r_out = jnp.log10(r_out_cm) log_r_outer, d_log_r_outer = _log_r_gauss_legendre(log_r_warm, log_r_out) r_outer = 10.0**log_r_outer r_ratio_outer = r_outer / r_isco_cm rt_outer = jnp.maximum(_nt_rt(r_ratio_outer, agn_a_spin), 1e-30) ** 0.25 t_outer = t_in * r_ratio_outer ** (-0.75) * rt_outer dr_outer = r_outer * jnp.log(10.0) * d_log_r_outer # The Planck prefactor 2 h nu (nu/c)^2 reaches ~4e11 at 0.1 A and a ring area reaches # ~6e31 cm^2, so their product (~2e43) leaves float32 even though ``exp(-h nu / k T)`` # drives the product's true value to zero there; XLA forms ``(prefactor * area) * exp(-x)`` # and gets ``inf * 0 = NaN`` (#2767). The ring areas are therefore carried relative to # their largest value, a pure factorization constant held under ``stop_gradient``, and # that scale is applied once, in log10, to the ring sum. r_outer_ref, dr_outer_ref = _zone_ring_reference(r_outer, dr_outer) log10_ring_area_ref = _log10_ring_area_unit(r_outer_ref, dr_outer_ref) def _outer_ring(r_cm, t_ring, dr_ring): """Blackbody L_nu of one outer-disk annulus, in units of the largest ring area.""" b_nu = _planck_lnu(nu, t_ring) return b_nu * _ring_area_relative(r_cm, dr_ring, agn_cos_inc, r_outer_ref, dr_outer_ref) l_nu_outer = apply_log10_scale( jnp.sum(jax.vmap(_outer_ring)(r_outer, t_outer, dr_outer), axis=0), log10_ring_area_ref ) # A zone narrower than ``_ZONE_WIDTH_RTOL R_out`` is empty (R_warm = R_out, or R_hot = R_out # where the hot flow fills the disc). Its ring widths are zero in exact arithmetic but ~1e-16 # R_out after the log10/power round trip, differently under jit and eager; the noise-level # power and its derivative are not the model's (forward and reverse mode disagreed by 2-12% # on the log-derivative, and jit differed from eager, #3015). An exact zero instead. l_nu_outer = jnp.where(r_out_cm - r_warm_cm > _ZONE_WIDTH_RTOL * r_out_cm, l_nu_outer, 0.0) # ── Zone 2: Warm Comptonization (R_hot < r < R_warm) ────────── if not _NTHCOMP_AVAILABLE: raise RuntimeError( "kubota_done_disc requires precomputed nthcomp templates. " "Build them with:\n" " python scripts/build_nthcomp_templates.py" ) log_r_hot = jnp.log10(r_hot_cm) log_r_warm_grid, d_log_r_warm = _log_r_gauss_legendre(log_r_hot, log_r_warm) r_warm_grid = 10.0**log_r_warm_grid r_ratio_warm = r_warm_grid / r_isco_cm rt_warm = jnp.maximum(_nt_rt(r_ratio_warm, agn_a_spin), 1e-30) ** 0.25 t_warm = t_in * r_ratio_warm ** (-0.75) * rt_warm dr_warm = r_warm_grid * jnp.log(10.0) * d_log_r_warm # Ring areas are carried relative to the largest one, as in the outer zone, and the scale is # applied once to the ring sum (#2767): ``p_plain * area`` is ~1e47 and the template shape is # ~1e-17 per Hz, so neither product nor cotangent is formed at its own magnitude. r_warm_ref, dr_warm_ref = _zone_ring_reference(r_warm_grid, dr_warm) log10_warm_area_ref = _log10_ring_area_unit(r_warm_ref, dr_warm_ref) nu_norm = _warm_norm_grid() def _warm_ring(r_cm, t_ring, dr_ring): """Comptonized L_nu of one warm-zone annulus, in units of the largest ring area.""" # Ring blackbody power per unit area: int B_nu dnu = (sigma_Planck/pi) T^4, closed form. # (It was trapz(B_nu, nu) on the CALLER's grid, which moved the SED by 4e-3 between # grids of different extent and density: #2572.) p_plain = _BNU_BOL_PER_T4 * t_ring**4 kTbb_keV = _K_BOLTZ_KEV * t_ring shape = _nthcomp_lnu_interp( nu, agn_gamma_warm, agn_kt_warm, kTbb_keV, _template=nthcomp_table, unit=_NTHCOMP_UNIT ) # The template is normalized by its own integral over its band, so the ring carries # exactly ``p_plain`` (the template's own normalization is ~0.5 % off, #2733). shape_band = _nthcomp_lnu_interp( nu_norm, agn_gamma_warm, agn_kt_warm, kTbb_keV, _template=nthcomp_table, unit=_NTHCOMP_UNIT, ) # The ring sum is multiplied by ``_NTHCOMP_UNIT`` at the end, so the shape carries 1/unit. shape = shape / (jnp.trapezoid(shape_band, nu_norm) * _NTHCOMP_UNIT) # The normalized ``shape`` (per ``_NTHCOMP_UNIT``) is folded in before the area, so the # ring's bolometric power is never formed on its own. return (shape * p_plain) * _ring_area_relative( r_cm, dr_ring, agn_cos_inc, r_warm_ref, dr_warm_ref ) l_nu_warm = apply_log10_scale( jnp.sum(jax.vmap(_warm_ring)(r_warm_grid, t_warm, dr_warm), axis=0), log10_warm_area_ref + _LOG10_NTHCOMP_UNIT, ) l_nu_warm = jnp.where(r_warm_cm - r_hot_cm > _ZONE_WIDTH_RTOL * r_out_cm, l_nu_warm, 0.0) # ── Zone 3: Hot corona (R_ISCO < r < R_hot) ─────────────────── # Float32 (#1206): l_hot_erg ~5e43 and l_seed ~1e44 erg/s overflow. Work both # in L_sun units (l_edd from M_BH, L_bol from the SHAPE luminosity: the # corona fraction lambda_Edd must track the TRUE L_bol, not the reference the # magnitude normalizes to). Beloborodov uses only their ratio, so units cancel. # The corona's share of the accretion power is formed from O(1) ratios (see # ``_hot_flow_fraction``), and its power is that share times the shape luminosity, so the # disc budget below subtracts a share, never two ~1e11 powers carried as logarithms. log10_bol_shape = agn_log_lbol_shape if float32 else agn_log_lbol_shape + _LOG10_LSUN_ERG if float32: log10_edd_over_bol = math.log10(_L_EDD_1MSUN_LSUN) + agn_log_mbh - log10_bol_shape else: log10_edd_over_bol = log10_l_edd - log10_bol_shape hot_fraction = _hot_flow_fraction( agn_f_hard, log10_edd_over_bol, agn_a_spin, x_hot_max=r_out_cm / r_isco_cm, h_inf=h_inf, ) l_hot_erg = hot_fraction * _pow10(log10_bol_shape) if float32: l_seed_geom = _l_seed_geometric( r_isco_cm, r_hot_cm, r_out_cm, t_in, float32=True, a_spin=agn_a_spin ) else: l_seed_geom = _l_seed_geometric(r_isco_cm, r_hot_cm, r_out_cm, t_in, a_spin=agn_a_spin) kt_hot_erg = agn_kt_hot * _KEV_TO_ERG gamma_hard_sc = beloborodov_gamma_hot(l_hot_erg, l_seed_geom) gamma_hard_eff = jnp.where(agn_self_consistent_gamma, gamma_hard_sc, agn_gamma_hard) # Seed-photon frequency for the hot flow (K&D 2018, Section 2.2): the seed # photons come from the inner edge of the warm Comptonization region at # R_hot, boosted by the warm Compton y-parameter, # kT_seed,hot = k T_NT(R_hot) * exp(y_warm), # with y_warm recovered from Gamma_warm via the standard non-relativistic # thermal-Comptonization relation Gamma = sqrt(9/4 + 4/y) - 1/2 # (Sunyaev & Titarchuk 1980), i.e. y_warm = 4 / [(Gamma_warm + 1/2)^2 - 9/4]. # This sets the low-energy rollover so the corona cannot leak into the IR/radio. x_hot = r_hot_cm / r_isco_cm t_seed_nt = ( t_in * x_hot ** (-0.75) * jnp.maximum(_nt_rt(x_hot, agn_a_spin), _representable_floor(1e-30)) ** 0.25 ) y_warm_denom = jnp.maximum((agn_gamma_warm + 0.5) ** 2 - 2.25, 1e-3) y_warm = jnp.clip(4.0 / y_warm_denom, 0.0, 10.0) t_seed_hot = t_seed_nt * jnp.exp(y_warm) # ``k/h`` is folded first (2.1e10 Hz/K): the reverse pass divides a cotangent by this factor # and ``1/h`` alone (1.5e26) takes a ~4e12 cotangent past the float32 maximum (#2767). nu_seed_hot = (_K_BOLTZ / _H_PLANCK) * t_seed_hot # The corona L_nu scales linearly with l_hot_erg. On the float32 path # l_hot_erg is in L_sun, so the corona comes out in L_sun/Hz; its exponent gains # log10(L_sun) to give erg/s/Hz, and it is applied only at the end, to the normalized shape. hot_shape, log10_hot_amplitude = _hot_corona_lnu( nu, l_hot_erg, gamma_hard_eff, kt_hot_erg, nu_seed_hot ) if float32: log10_hot_amplitude = log10_hot_amplitude + _LOG10_LSUN_ERG # ── Normalize ───────────────────────────────────────────────── l_nu_disc = l_nu_outer + l_nu_warm # No rescale (#3015). Each zone carries its own Novikov-Thorne dissipation, the disc and warm # zones ``L0 (h(x_out) - h(x_hot))`` and the corona ``L_hot`` (K&D 2018 Sec. 2.2, Eq. 2), and # the spectra are only converted from the shape's luminosity units to the output magnitude by # ``k = L_ref / L_shape``. The dissipation the disc would have beyond ``R_out`` is not # emitted; :func:`kubota_done_unemitted_fraction` gives it. # # Units: the shape powers (disc, corona) are in the shape's own luminosity units, and # ``l_bol_erg`` is the output magnitude, which the float32 path sets to a reference. The # common factor ``k = L_ref / L_shape`` takes the shapes to the output magnitude. log10_k = jnp.log10(l_bol_erg) - log10_bol_shape scale = _pow10(log10_k) log10_scale = log10_k # Applied once, to spectra whose own peak is factored out, so no unnormalized ~1e28 spectrum # (or the cotangent that would multiply it in reverse mode) is formed in float32 (#2767). l_nu_disc_norm = apply_log10_scale(l_nu_disc, log10_scale) l_nu_hot_norm = apply_log10_scale(hot_shape, log10_hot_amplitude + log10_k) return ( l_nu_disc_norm + l_nu_hot_norm, scale, l_nu_disc_norm, l_nu_hot_norm, hot_fraction, log10_scale, )
[docs] def beloborodov_gamma_hot( l_diss_hot: float, l_seed: float, ) -> float: """Self-consistent hard X-ray photon index (Beloborodov 1999). Derives the spectral index of the hot corona from the ratio of dissipated luminosity to seed photon luminosity. Kubota & Done (2018, MNRAS 480 1247) Eq. 6 rewrites the Beloborodov (1999, ApJ 510 L123) Compton-amplification result as: Gamma_hot = (7/3) * (L_diss / L_seed)^{-0.1} The exponent -0.1 is the K&D 2018 formulation of Beloborodov (1999). Parameters ---------- l_diss_hot : float Luminosity dissipated in the hot corona [any units]. l_seed : float Soft photon luminosity intercepted by the corona [same units]. Returns ------- float Hard X-ray photon index, clipped to [1.4, 3.0]. Notes ----- **JIT-compatible**: yes, uses only ``jnp`` primitives. This implementation follows Kubota & Done (2018, MNRAS 480 1247, Eq. 6), which rewrites the Beloborodov (1999) Compton-amplification result as a power law in the luminosity ratio. The exponent -0.1 encodes the energy-balance relation between the dissipated power in the corona and the seed photon luminosity intercepted from the disc. Output is clipped to [1.4, 3.0] to match the physical range of typical AGN. References ---------- .. [1] A. M. Beloborodov, "Plasma Ejection from Magnetic Flares and the X-Ray Spectrum of Cygnus X-1," ApJL, 510, L123 (1999). arXiv:astro-ph/9809383. https://doi.org/10.1086/311810 .. [2] A. Kubota and C. Done, "A physical model of the broad-band continuum of AGN and its implications for the UV/X relation and optical variability," MNRAS, 480, 1247 (2018). arXiv:1804.00171. https://doi.org/10.1093/mnras/sty1890 """ ratio = jnp.clip( l_diss_hot / jnp.maximum(l_seed, _representable_denominator(1e-30)), 1e-3, 1e3 ) gamma = (7.0 / 3.0) * ratio ** (-0.1) # K&D 2018 Eq. 6 return jnp.clip(gamma, 1.4, 3.0)
[docs] def compute_l2500( wavelength: jnp.ndarray, l_nu: jnp.ndarray, ) -> float: """Extract monochromatic luminosity at rest-frame 2500 Angstrom. Linearly interpolates L_nu onto 2500 A. Useful for computing alpha_ox and other AGN diagnostics. Parameters ---------- wavelength : array, shape (n_wave,) Rest-frame wavelength [Angstrom], need not be sorted. l_nu : array, shape (n_wave,) Specific luminosity [erg s^-1 Hz^-1]. Returns ------- float L_nu at 2500 A [erg s^-1 Hz^-1]. Notes ----- **JIT-compatible**: yes, uses ``jnp`` primitives. The 2500 Å point is a canonical AGN diagnostic wavelength, used to compute the optical-to-X-ray spectral index (alpha_ox) and as a benchmark for intrinsic AGN continuum comparisons. Linear interpolation in wavelength space is sufficient for the optical/UV continuum variability timescales. The wavelength array need not be pre-sorted; this function sorts internally before interpolation. """ sort_idx = jnp.argsort(wavelength) return jnp.interp(2500.0, wavelength[sort_idx], l_nu[sort_idx])
[docs] def kubota_done_disc_split( wavelength: jnp.ndarray, agn_log_lbol: float, agn_lum_ratio: float = DEFAULT_AGN_LUM_RATIO, agn_log_mbh: float = DEFAULT_AGN_LOG_MBH, agn_log_ledd: float = DEFAULT_AGN_LOG_LEDD, agn_a_spin: float = DEFAULT_AGN_A_SPIN, agn_cos_inc: float = DEFAULT_AGN_COS_INC, agn_f_hard: float = DEFAULT_AGN_F_HARD, agn_gamma_warm: float = DEFAULT_AGN_GAMMA_WARM, agn_kt_warm: float = DEFAULT_AGN_KT_WARM, agn_gamma_hard: float = DEFAULT_AGN_GAMMA_HARD, agn_kt_hot: float = DEFAULT_AGN_KT_HOT, agn_r_warm_ratio: float = DEFAULT_AGN_R_WARM_RATIO, n_radii: int = 50, agn_self_consistent_gamma: bool = False, agn_log_lbol_shape: float | None = None, _template=None, **_kwargs, ) -> tuple: r"""Kubota & Done (2018) disc and corona, returned apart (for the SKIRTOR tie). The same model as :func:`kubota_done_disc` (see there for the physics and the parameters), with the two parts of its line-of-sight spectrum :math:`L_\nu(i) = 2\cos i\, D_\nu + H_\nu` separated: the optically thick disc and warm Comptonization zones :math:`2\cos i\, D_\nu` and the isotropic corona :math:`H_\nu`, and the corona's share of the accretion power in closed form. Returns ------- l_nu_total : ndarray, shape (n_wave,) :math:`L_\nu(i)`, identical to :func:`kubota_done_disc` [erg/s/Hz]. l_nu_disc : ndarray, shape (n_wave,) The disc and warm-zone part :math:`2\cos i\, D_\nu` [erg/s/Hz]. l_nu_hot : ndarray, shape (n_wave,) The corona :math:`H_\nu` [erg/s/Hz]. corona_fraction : float :math:`P_H / L_{\rm bol}`, the corona's share of the accretion power, with :math:`P_H = \int H_\nu\,d\nu` the angle-integrated corona power. It is the closed-form hot-flow share (:func:`_hot_flow_fraction`) and is independent of the wavelength grid and of ``agn_cos_inc``. The disc and warm zones carry their own dissipation, so ``P_D + P_H`` is below ``L_bol`` by the unemitted share [dimensionless]. Notes ----- **JIT-compatible**: yes. ``l_nu_disc + l_nu_hot`` equals ``l_nu_total`` exactly. """ return kubota_done_disc( wavelength, agn_log_lbol=agn_log_lbol, agn_lum_ratio=agn_lum_ratio, agn_log_mbh=agn_log_mbh, agn_log_ledd=agn_log_ledd, agn_a_spin=agn_a_spin, agn_cos_inc=agn_cos_inc, agn_f_hard=agn_f_hard, agn_gamma_warm=agn_gamma_warm, agn_kt_warm=agn_kt_warm, agn_gamma_hard=agn_gamma_hard, agn_kt_hot=agn_kt_hot, agn_r_warm_ratio=agn_r_warm_ratio, n_radii=n_radii, agn_self_consistent_gamma=agn_self_consistent_gamma, agn_log_lbol_shape=agn_log_lbol_shape, _template=_template, _return_parts=True, )
[docs] def kubota_done_disc( wavelength: jnp.ndarray, agn_log_lbol: float, agn_lum_ratio: float = DEFAULT_AGN_LUM_RATIO, agn_log_mbh: float = DEFAULT_AGN_LOG_MBH, agn_log_ledd: float = DEFAULT_AGN_LOG_LEDD, agn_a_spin: float = DEFAULT_AGN_A_SPIN, agn_cos_inc: float = DEFAULT_AGN_COS_INC, agn_f_hard: float = DEFAULT_AGN_F_HARD, agn_gamma_warm: float = DEFAULT_AGN_GAMMA_WARM, agn_kt_warm: float = DEFAULT_AGN_KT_WARM, agn_gamma_hard: float = DEFAULT_AGN_GAMMA_HARD, agn_kt_hot: float = DEFAULT_AGN_KT_HOT, agn_r_warm_ratio: float = DEFAULT_AGN_R_WARM_RATIO, n_radii: int = 50, agn_self_consistent_gamma: bool = False, agn_log_lbol_shape: float | None = None, _template=None, _return_parts: bool = False, **_kwargs, ) -> jnp.ndarray: """Kubota & Done (2018) three-zone accretion disc with self-consistent corona. Model a physically stratified AGN accretion disc as three radially distinct zones, each with different physics and electron temperatures. This is the reference model for intermediate to high accretion rates and is used in tengri's default AGN configuration. The three zones share a single Novikov-Thorne temperature profile but have different radiation mechanisms: 1. **Outer standard disc** (r > R_warm): Optically thick, geometrically thin. Temperature decreases with radius (∝ r^{-3/4}). Radiates as multi-color blackbody. Dominates the optical/UV "big blue bump." 2. **Warm Comptonization zone** (R_hot < r < R_warm): Optically thick, warm electrons (kT_e ~ 0.2 keV, τ ~ 10-20). Inverse Compton-scattered disc photons plus thermal radiation. Produces the soft X-ray excess. Computed via precomputed nthcomp Kompaneets templates (when available) or a simplified modified-blackbody proxy. 3. **Hot corona** (R_ISCO < r < R_hot): Optically thin, hot electrons (kT_e ~ 100 keV, τ ~ 1). Inverse Compton scatters disc seed photons to produce hard X-ray power-law spectrum with exponential cutoff. Zone boundaries are determined self-consistently: - **R_hot**: Solved via bisection from the energy-balance constraint that the dissipated power in the corona equals f_hard × L_Edd. Uses the Page-Thorne dissipation integral (Eq. 2), spin included. - **R_warm**: Parameterized as a multiple of R_hot (default 2, per K&D). - **R_out**: Set to the Laor & Netzer (1989) self-gravity (Toomre) radius, beyond which the disc becomes unstable and fragments. The radii obey :math:`R_{\\rm ISCO} < R_{\\rm hot} \\le R_{\\rm out}` and :math:`R_{\\rm hot} < R_{\\rm warm} \\le R_{\\rm out}`. Where the disc cannot dissipate :math:`f_{\\rm hard} L_{\\rm Edd}` inside :math:`R_{\\rm out}`, :math:`R_{\\rm hot} = R_{\\rm out}` and the whole flow is hot, as in the RELQSO source of Hagen & Done (see :func:`_clip_zone_radii`). The corona power then saturates at the disc's dissipation inside :math:`R_{\\rm out}`, which gives a slope change in :math:`L_{\\rm hot}` at :math:`f_{\\rm hard}/\\lambda_{\\rm Edd} = h(R_{\\rm out}/R_{\\rm ISCO})/h(\\infty)` (about 0.93); the steep optical disc share just above that point is the corona taking most of :math:`L_{\\rm bol}`. **Emission per zone (no rescale, #3015).** Each zone emits its own Page-Thorne dissipation (Kubota & Done 2018, Sec. 2.2): the corona :math:`L_{\\rm hot}`, the warm zone and the outer disc :math:`L_0\\,[h(x_{\\rm out}) - h(x_{\\rm hot})]`, with :math:`x = R/R_{\\rm ISCO}` and :math:`L_0 h(\\infty) = L_{\\rm bol}`. Their sum is :math:`L_{\\rm bol}` less the unemitted share .. math:: L_{\\rm unemitted} = L_0\\,[h(\\infty) - h(x_{\\rm out})] = L_{\\rm bol}\\,\\frac{h(\\infty) - h(R_{\\rm out}/R_{\\rm ISCO})}{h(\\infty)}, the dissipation the disc would have beyond its self-gravity radius, which K&D do not emit. It is published as ``log_L_agn_disc_unemitted`` (:func:`kubota_done_unemitted_fraction`). **Validity domain.** The three-zone geometry of Kubota & Done (2018) applies for :math:`\\lambda_{\\rm Edd}` above about :math:`f_{\\rm hard}` (~0.02), where the disc can dissipate :math:`f_{\\rm hard} L_{\\rm Edd}` inside :math:`R_{\\rm out}`. Below it the disc truncates: there are no disc or warm zones, as in RELQSO, and the hot flow is modeled as radiatively efficient Comptonization of all the dissipation inside :math:`R_{\\rm out}` (K&D 2018 do not model radiative inefficiency). For that regime ``disc='adaf'`` is the radiatively inefficient alternative. No warning is issued. The hard X-ray photon index Γ_hot is derived self-consistently from the Beloborodov (1999) energy-balance relation if requested; otherwise uses the input value. Parameters ---------- wavelength : array_like, shape (n_wave,) Rest-frame wavelength grid. [Angstrom] agn_log_lbol : float Accretion power of all three zones, integrated over all directions (both faces of the disc); independent of the inclination. The line-of-sight luminosity is :math:`\\int L_\\nu(i)\\,d\\nu`, a derived quantity. [log10(L_sun)] agn_lum_ratio : float, optional Fraction of the accretion power emitted by the disc system (all zones). Default: 1.0. [dimensionless, 0–1] agn_log_mbh : float, optional Black hole mass. Determines the Eddington luminosity and temperature scaling. Default: 8.0. [log10(M_sun)] agn_log_ledd : float, optional **DEPRECATED / IGNORED (#846).** The Eddington ratio, and hence the inner temperature, accretion rate, and zone radii: is now DERIVED from ``agn_log_lbol`` and ``agn_log_mbh`` (lambda_Edd = L_bol / L_Edd), so the 3-zone structure is self-consistent with the requested L_bol. Retained for backward compatibility but has no effect; setting or freeing it emits a build-time warning. Default: -1.0. agn_a_spin : float, optional Dimensionless black hole spin parameter (Kerr, prograde). Range: [0, 0.998]. Higher spin → smaller R_ISCO, higher η. Default: 0.0 (Schwarzschild). [dimensionless] agn_cos_inc : float, optional Cosine of the inclination angle between the disc normal and the line of sight. Range: [0, 1]. The disc and warm zones radiate :math:`\\propto\\cos i` (Kubota & Done 2018, Sect. 2.1) and the returned spectrum is :math:`L_\\nu(i) = 2\\cos i\\,D_\\nu + H_\\nu`, with :math:`D_\\nu` the angle-integrated spectrum of the disc and warm zones and :math:`H_\\nu` that of the isotropic corona (Sect. 2.2). The zone radii, temperatures and :math:`\\dot m` do not depend on it. Default: 0.866 (30°). [dimensionless] agn_f_hard : float, optional Fraction of Eddington luminosity dissipated in the hot corona. Controls the corona zone extent R_hot. Typical range: 0.01–0.1. Default: 0.02. [dimensionless, 0–0.5] agn_gamma_warm : float, optional Photon index of the warm Comptonization zone (nthcomp). Range: ~1.5–3.5. Default: 2.5. [dimensionless] agn_kt_warm : float, optional Electron temperature in the warm Comptonization zone. Default: 0.2. [keV] agn_gamma_hard : float, optional Photon index of the hard X-ray power law (hot corona). Typical range: 1.5–2.5. Default: 1.8. Ignored if agn_self_consistent_gamma=True. [dimensionless] agn_kt_hot : float, optional Electron temperature in the hot corona. Default: 100.0. [keV] agn_r_warm_ratio : float, optional Radius ratio R_warm / R_hot. Controls the warm zone extent. Default: 2.0 (per K&D 2018). [dimensionless, ≥ 1.1] n_radii : int, optional Number of radial integration points per zone. Default: 50. Higher values increase accuracy at computational cost. agn_self_consistent_gamma : bool, optional If True, compute ``agn_gamma_hard`` self-consistently from the Beloborodov (1999) energy-balance relation: Γ = 7/3 × (L_diss / L_seed)^{-0.1} If False, use the input ``agn_gamma_hard`` value. Default: False. Returns ------- ndarray, shape (n_wave,) Spectral luminosity density L_ν. [erg/s/Hz] Notes ----- **JIT-compatible**: yes, uses ``jnp`` primitives and ``jax.vmap``. **Gradient-safe**: yes, fully differentiable w.r.t. all parameters, including the bisection-solved R_hot. **Key self-consistent physics**: All three zones share the relativistic Page & Thorne (1974) thin-disc temperature profile (as K&D 2018 and QSOSED/RELQSO; ``tengri.components.agn._nt_emissivity``): .. math:: T(r) = T_{\\rm in} \\left(\\frac{r}{r_{\\rm ISCO}}\\right)^{-3/4} R_t(r; a)^{1/4} with :math:`R_t = C/B \\to 0` at the ISCO and :math:`\\to 1` far out (the Newtonian zero-torque form :math:`1-\\sqrt{r_{\\rm ISCO}/r}` dissipates 1.46 :math:`L_{\\rm bol}` at a=0 instead of 1.02). where :math:`T_{\\rm in} = (3 G M M_{\\rm dot} / 8\\pi \\sigma_{\\rm SB} r_{\\rm ISCO}^3)^{1/4}`, and the inner temperature increases with accretion rate. The radii are ordered as R_ISCO < R_hot < R_warm < R_out. **Zone luminosity computation**: Each zone is divided into annuli at radii {r_i}, each of which contributes L_ν from its local Planck function (outer disc), nthcomp prescription (warm zone), or hot-corona power law (inner zone). All zones are summed and renormalized so that :math:`\\int (D_\\nu + H_\\nu)\\,d\\nu` equals the accretion power. **Inclination and energy** (K&D 2018, Sects. 2.1 and 2.2): the disc and warm zones are optically thick and radiate :math:`\\propto\\cos i`; the corona is optically thin and isotropic. With :math:`D_\\nu` the angle-integrated (two-face) spectrum of the disc and warm zones and :math:`H_\\nu` that of the corona, the model returns .. math:: L_\\nu(i) = 2\\cos i\\, D_\\nu + H_\\nu , \\qquad \\int (D_\\nu + H_\\nu)\\,d\\nu = L_{\\rm acc} = 10^{\\mathtt{agn\\_log\\_lbol}} L_\\odot , the luminosity density an observer at inclination :math:`i` assigns assuming isotropy (AGNSED's :math:`\\cos i / 0.5`). The mean of :math:`\\int L_\\nu(i)\\,d\\nu` over :math:`\\cos i \\in [0, 1]` is :math:`L_{\\rm acc}`, and at :math:`\\cos i = 0.5` the line-of-sight power equals it; face-on the disc is twice as luminous. The corona's power :math:`H` is the hot-flow dissipation :math:`f_{\\rm hard} L_{\\rm Edd}` (the Page-Thorne dissipation inside :math:`R_{\\rm hot}`), and :math:`D` is the dissipation of the thin disc outside it, so the split follows K&D's energy budget. The shape quantities (:math:`\\dot m`, :math:`T(r)`, :math:`R_{\\rm hot}`, :math:`R_{\\rm warm}`) follow from :math:`L_{\\rm acc}` and do not depend on :math:`i`. **Seed photon calculation** (K&D 2018 Eq. 3): The hot corona inverse-Compton scatters disc seed photons. The seed photon luminosity is computed from the geometric integral of the warm-zone blackbody flux intercepted by the corona geometry: .. math:: L_{\\rm seed} = 2 \\int_{R_{\\rm hot}}^{R_{\\rm out}} F_{\\rm NT}(r) \\cdot \\frac{\\Theta(r)}{\\pi} \\cdot 2\\pi r \\, dr where :math:`\\Theta(r) = \\theta_0 - \\sin(2\\theta_0)/2` and :math:`\\sin\\theta_0 = R_{\\rm hot}/r`. This drives the self-consistent Γ_hot via Beloborodov. **Precomputed nthcomp templates**: For maximum speed and accuracy, the warm Comptonization is computed via interpolation in precomputed nthcomp Kompaneets templates (see ``scripts/build_nthcomp_templates.py``). These templates span (Γ_warm, kT_e) parameter space and return (Γ_warm, kT_e, normalization)-dependent SED at each radius. If templates are unavailable, a simplified modified-blackbody proxy is used, which has ~5–10% shape error but allows offline computation. **Approximations and accuracy**: The reference QSOSED/RELAGN codes use non-differentiable operations (root solvers, C implementations). Tengri's JAX reimplementation makes key approximations documented in the code (see ``docs/dev/archive/design/agn_kd_model.md``): - R_hot: 40-step JAX-compatible bisection (exact to ~10^{-12}). - Warm zone: precomputed nthcomp templates with (Γ_w, kT_e) interpolation (accuracy: ≲ 2% in flux density). - Seed photons: K&D Eq. 3 integrated on 100-point log grid (exact). - Outer radius: Laor & Netzer self-gravity radius (2–4× improvement over fixed 1000 r_ISCO). References ---------- .. [1] A. Kubota and C. Done, "A physical model of the broad-band continuum of AGN and its implications for the UV/X relation and optical variability," MNRAS, 480, 1247 (2018). arXiv:1804.00171. https://doi.org/10.1093/mnras/sty1890 .. [2] C. Done et al., "Intrinsic disc emission and the soft X-ray excess in active galactic nuclei," MNRAS, 420, 1848 (2012). arXiv:1107.5429. https://doi.org/10.1111/j.1365-2966.2011.19779.x .. [3] A. M. Beloborodov, "Plasma Ejection from Magnetic Flares and the X-Ray Spectrum of Cygnus X-1," ApJL, 510, L123 (1999). arXiv:astro-ph/9809383. https://doi.org/10.1086/311810 """ nu = _wavelength_to_nu(wavelength) _f32 = is_float32_arithmetic(wavelength) # Shape luminosity (temperature, zone structure, corona fraction) vs the # normalization luminosity (output magnitude). They coincide by default (the # float64 path). On float32 the AGN component passes the TRUE L_bol for the # SHAPE while normalizing MAGNITUDE to a low reference, so the runner's ~1e40 # L_lambda arithmetic stays in float32 range; the true scale is re-applied # downstream (#1206). _lbol_shape = agn_log_lbol if agn_log_lbol_shape is None else agn_log_lbol_shape # h(inf) once per spin: it sets Mdot, the cap and the share. h_inf = _nt_h(jnp.log(_NT_X_MAX), agn_a_spin) r_g, r_isco_rg, r_isco_cm, _eta, log10_l_edd, mdot = _compute_bh_params( agn_log_mbh, _lbol_shape, agn_a_spin, float32=_f32, h_inf=h_inf ) # Reference inner-disc temperature T_in (the profile is T_in x^-3/4 Rt^1/4). if _f32: # Log-space: the ``3 G M mdot`` numerator ~1e58 erg/s overflows float32; # t_in ~1e5 K is representable. _log_t_in4 = ( _LOG10_3G + agn_log_mbh + _LOG10_MSUN_G + jnp.log10(mdot) - _LOG10_8PI_SIGMA_SB - 3.0 * jnp.log10(r_isco_cm) ) t_in = _pow10(0.25 * _log_t_in4) else: t_in = ( 3.0 * _G_GRAV * 10.0**agn_log_mbh * _MSUN_G * mdot / (8.0 * jnp.pi * _SIGMA_SB * r_isco_cm**3) ) ** 0.25 r_hot_cm, r_warm_cm, r_out_cm = _compute_zone_radii( r_g, r_isco_rg, r_isco_cm, t_in, agn_log_mbh, _lbol_shape, agn_f_hard, agn_r_warm_ratio, log10_l_edd, float32=_f32, agn_a_spin=agn_a_spin, h_inf=h_inf, ) # Normalize at UNIT agn_lum_ratio: the exponent carries agn_log_lbol only (in L_sun on the # float32 path, so the zone helper's ``scale`` is a clean ratio). The ratio then multiplies # the spectra linearly below. Folding log10(agn_lum_ratio) into the exponent gave # log10(0) = -inf and a 0 * inf = NaN reverse pass at ratio 0 (#2767); the SED is linear in # the ratio, so this form is the same physics at every ratio, with an exact zero and # gradient at 0. l_bol_unit = 10.0**agn_log_lbol if _f32 else 10.0**agn_log_lbol * _LSUN_ERG l_nu_total, _scale, l_nu_disc, l_nu_hot, corona_fraction, _log10_scale = ( _compute_zone_luminosities( nu, r_isco_cm, r_hot_cm, r_warm_cm, r_out_cm, t_in, agn_cos_inc, n_radii, agn_gamma_warm, agn_kt_warm, agn_gamma_hard, agn_kt_hot, agn_f_hard, log10_l_edd, l_bol_unit, agn_self_consistent_gamma, float32=_f32, agn_log_mbh=agn_log_mbh, agn_log_lbol_shape=_lbol_shape, agn_a_spin=agn_a_spin, nthcomp_table=_template, h_inf=h_inf, ) ) l_nu_total = l_nu_total * agn_lum_ratio l_nu_disc = l_nu_disc * agn_lum_ratio l_nu_hot = l_nu_hot * agn_lum_ratio if _return_parts: return l_nu_total, l_nu_disc, l_nu_hot, corona_fraction return l_nu_total
# ── Model 4: ADAF; DEPRECATED delegator to the faithful adaf_spectrum ────────
[docs] def adaf_disc( wavelength, agn_log_lbol, agn_lum_ratio=DEFAULT_AGN_LUM_RATIO, agn_log_mbh=DEFAULT_AGN_LOG_MBH, agn_adaf_beta=DEFAULT_AGN_ADAF_BETA, agn_adaf_delta=DEFAULT_AGN_ADAF_DELTA, agn_adaf_alpha=DEFAULT_AGN_ADAF_ALPHA, **_legacy_kwargs, ): """DEPRECATED thin alias for the faithful Mahadevan 1997 ADAF (#898). The old ``adaf_disc`` (which misapplied Eq. 49 and bundled an ad-hoc truncated outer disc) was removed; this delegates to :func:`~tengri.components.agn.adaf.adaf_spectrum`. The retired arguments ``agn_log_ledd`` / ``agn_r_tr`` / ``agn_cos_inc`` are accepted for backward compatibility but **ignored** (mdot is now derived from ``agn_log_lbol``). New code should call ``adaf_spectrum`` directly. Slated for removal once its remaining callers/tests migrate (see #898 follow-up). Parameters ---------- wavelength : array_like, shape (n_wave,) Rest-frame wavelength [Angstrom]. agn_log_lbol : float log10 of bolometric luminosity [Lsun]. agn_lum_ratio, agn_log_mbh, agn_adaf_beta, agn_adaf_delta, agn_adaf_alpha Forwarded to :func:`adaf_spectrum` (see there). Returns ------- ndarray, shape (n_wave,) L_nu [erg/s/Hz], the faithful Mahadevan 1997 ADAF. """ from tengri.components.agn.adaf import adaf_spectrum return adaf_spectrum( wavelength, agn_log_lbol=agn_log_lbol, agn_lum_ratio=agn_lum_ratio, agn_log_mbh=agn_log_mbh, agn_adaf_alpha=agn_adaf_alpha, agn_adaf_beta=agn_adaf_beta, agn_adaf_delta=agn_adaf_delta, )
# ── Model 5: RELAGN relativistic disc from precomputed grid ────────────────── def _host_edges(axis: np.ndarray) -> np.ndarray: """Bin edges for a sorted 1-D axis, as host numpy (see ``edges_for_grid``). Same construction as :func:`tengri.utils.interpolation.edges_for_grid`, which is written with ``jnp`` and so cannot run on a cached host table. """ if axis.size == 1: return np.array([axis[0], axis[0]]) half_lo = (axis[1] - axis[0]) / 2.0 half_hi = (axis[-1] - axis[-2]) / 2.0 return np.concatenate([axis[:1] - half_lo, (axis[:-1] + axis[1:]) / 2.0, axis[-1:] + half_hi]) @functools.cache def _load_relagn_disc_grid(grid_path: str) -> dict: """Load and cache the RELAGN outer-disc grid from HDF5. Parameters ---------- grid_path : str Path to ``data/relagn_disc_grid.h5``. Returns ------- dict with keys: grid_jax : jnp.ndarray, shape (n_mass, n_mdot, n_astar, n_wave) axes : tuple of jnp.ndarray (log_mbh, log_mdot, astar) edges : tuple of jnp.ndarray scatters : tuple of float wave_grid : jnp.ndarray, shape (n_wave,) """ with h5py.File(grid_path, "r") as f: grid_np = f["lnu_disc"][()] log_mbh = f["log_mbh"][()] log_mdot = f["log_mdot"][()] astar = f["astar"][()] wave_grid = f["wavelength_aa"][()] # Host numpy only. ``functools.cache`` keeps whatever this returns for the # life of the process, so a jnp array built here would be a tracer when the # first load runs under jit (#2827). Device copies are made at the call site. axes = (host_array(log_mbh), host_array(log_mdot), host_array(astar)) edges = tuple(_host_edges(ax) for ax in axes) # For non-uniform astar, use max half-spacing: triweight has compact support # (zero beyond one bandwidth), so the bandwidth must cover the largest gap. # Uniform axes use the single node spacing. import numpy as _np scatter_lm = 0.5 * float(log_mbh[1] - log_mbh[0]) scatter_ld = 0.5 * float(log_mdot[1] - log_mdot[0]) scatter_as = 0.5 * float(_np.max(_np.diff(astar))) scatters = (scatter_lm, scatter_ld, scatter_as) return { "grid_jax": host_array(grid_np), "axes": axes, "edges": edges, "scatters": scatters, "wave_grid": host_array(wave_grid), }
[docs] def create_relagn_disc_from_grid(grid_path: str) -> Callable: """Return a JIT-compatible RELAGN disc SED function from a precomputed grid. The grid was built with the real RELAGN Python class (Hagen & Done 2023) using KYCONV (Dovciak, Karas & Yaqoob 2004) per-annulus Kerr ray-tracing. It stores the outer disc alone (no warm zone, no corona) as absolute L_ν (erg/s/Hz) at cos_inc = 0.5; the inclination correction is applied analytically as 2·cos_inc (valid for the non-relativistic outer disc; approximate for the GR inner disc). Parameters ---------- grid_path : str Path to ``data/relagn_disc_grid.h5``. Returns ------- callable Function with signature:: fn(wavelength, agn_log_mbh, agn_log_mdot, agn_astar, agn_cos_inc, **kwargs) -> L_nu [erg s^-1 Hz^-1] Raises ------ FileNotFoundError If ``grid_path`` does not exist. Notes ----- **JIT-compatible**: yes, the returned function is pure JAX. Grid loading is cached via ``@functools.cache``. **Gradient-safe**: yes, triweight interpolation is C²-continuous. **Inclination**: grid stored at cos_inc = 0.5, where the line-of-sight power equals the angle-integrated power; scaled by 2·cos_inc. This is exact for r > 1000 r_g (non-relativistic regime) and approximate for the GR inner disc where KYCONV applies full Kerr ray-tracing. **Grid axes**: log_mbh ∈ [7, 10], log_mdot ∈ [−1.5, 0.3], astar ∈ [0, 0.998] (prograde only; KYCONV rejects retrograde spins). References ---------- .. [1] Dovciak, M., Karas, V., & Yaqoob, T. (2004). ApJS, 153, 205. doi:10.1086/421115 .. [2] Hagen, S. & Done, C. (2023). MNRAS, 525, 3455-3467. doi:10.1093/mnras/stad2499 """ if not __import__("pathlib").Path(grid_path).exists(): raise FileNotFoundError(f"RELAGN disc grid not found: {grid_path}") return functools.partial(relagn_disc_from_grid, _load_relagn_disc_grid(grid_path))
[docs] def load_relagn_default_grid() -> dict: """Load the packaged RELAGN disc grid (discovery + cache). This is the ``template_loader`` the RELAGN disc block registers, so the forward model can hoist the ~27 MB library out of the JIT trace and hand it to the block as an argument. Returns ------- dict Template arrays; see :func:`_load_relagn_disc_grid`. Raises ------ FileNotFoundError If ``data/relagn_disc_grid.h5`` is not present. Notes ----- ``_find_relagn_grid`` is imported inside the body on purpose: :mod:`tengri.components.agn.unified` imports *this* module, so a module-level import would close the cycle. """ from tengri.components.agn.unified import _find_relagn_grid return _load_relagn_disc_grid(_find_relagn_grid())
def _as_device_table(table): """Device copy of a host table; a jax Array or tracer passes through unchanged. When the templates are threaded as jit arguments (``threaded_template_inputs``) the grid arrives as a tracer, which ``np.asarray`` cannot convert. The cache itself stays host-only, so only the host path goes through :func:`device_table`. """ return table if isinstance(table, jax.Array) else device_table(table)
[docs] def relagn_disc_from_grid( grid: dict, wavelength: jnp.ndarray, # Kept on this branch (main's #1578 dropped it): the bolometric # renormalization below is this branch's #1206 work and reads it. Read off # the declaration rather than repeating the literal 11.0, which is #1578's # own rule. agn_log_lbol: float = DEFAULT_AGN_LOG_LBOL, agn_log_mbh: float = DEFAULT_AGN_LOG_MBH, agn_log_mdot: float = DEFAULT_AGN_LOG_MDOT, agn_astar: float = DEFAULT_AGN_ASTAR, agn_cos_inc: float = DEFAULT_AGN_COS_INC, **_kwargs, ) -> jnp.ndarray: r"""RELAGN outer disc from the relativistic template grid. Parameters ---------- grid : dict Template arrays from :func:`_load_relagn_disc_grid`. Taken as an **argument** rather than closed over, so the forward model can thread the ~27 MB library through ``jax.jit`` as a ``Parameter`` instead of baking it into the graph as ``Constant`` ops (#1383). wavelength : ndarray, shape (n_wave,) Rest-frame wavelength. [Å] agn_log_lbol : float :math:`\log_{10}(L_{\rm acc}/L_\odot)`, the accretion power the template is normalized to, integrated over all directions. [dimensionless] agn_log_mbh : float :math:`\log_{10}(M_{\rm BH}/M_\odot)`. [dimensionless] agn_log_mdot : float :math:`\log_{10}(\dot M / \dot M_{\rm Edd})`. [dimensionless] agn_astar : float Dimensionless BH spin, prograde only (0 to 0.998). [dimensionless] agn_cos_inc : float Cosine of inclination (1 = face-on). [dimensionless] Returns ------- ndarray, shape (n_wave,) Disc :math:`L_\nu`. [erg/s/Hz] Notes ----- **JIT-compatible**: yes. **Gradient-safe**: yes, triweight kernel, C²-continuous. **Normalization (behavior change, #1206).** The template *shape* comes from (M_BH, Ṁ, a\*); its **normalization** is set by ``agn_log_lbol``, matching every other disc in the composable menu (``multicolor``, ``kubota_done``, ``slone_netzer``, …). Previously the grid's own absolute normalization was used and ``agn_log_lbol`` had no effect, which both surprised users who set it and made the disc unusable in float32, since the grid's absolute ``λL_λ(5100 Å) ≈ 2.6e44`` erg/s exceeds the float32 maximum (3.4e38). The normalization integral is taken over the template's own native wavelength grid, before resampling, so the output does not depend on the caller's wavelength sampling and a grid that stops short of the template carries only the part of ``L_bol`` that falls inside it. **Inclination**: the grid holds the disc alone at cos_inc = 0.5, where the line-of-sight power is the angle-integrated power. The template is normalized to ``agn_log_lbol`` at that reference and the spectrum is then scaled by :math:`2\cos i`: the returned :math:`L_\nu(i) = 2\cos i\,D_\nu` with :math:`\int D_\nu\,d\nu = L_{\rm bol}`, as for ``multicolor_disc``. The mean of its power over :math:`\cos i \in [0, 1]` is :math:`L_{\rm bol}`. """ point = (agn_log_mbh, agn_log_mdot, agn_astar) lnu_template = library_lookup( _as_device_table(grid["grid_jax"]), tuple(_as_device_table(a) for a in grid["axes"]), point, ) # The grid holds the disc alone at the reference cos_inc = 0.5, where the line-of-sight # power is the angle-integrated power: the template is normalized AT the reference and the # inclination scaling 2 cos i is applied to the spectrum on top. wave_native = _as_device_table(grid["wave_grid"]) # Interpolate grid wavelength -> observation wavelength lnu_interp = resample_template( wavelength, wave_native, lnu_template * (2.0 * agn_cos_inc), left=0.0, right=0.0 ) # Renormalize to the requested bolometric luminosity (#1206), with the # integral taken on the template's native grid (before resampling) so the # disc does not depend on the caller's wavelength sampling or range. The # float32 peak-factoring (the template's integral is ~1e45 erg/s and would # overflow) lives in the helper. # Log-space power (#3183): the erg/s-scale linear power is never formed in float32. return scale_to_torus_power_native(lnu_template, wave_native, lnu_interp, agn_log_lbol, 1.0)