Source code for tengri.components.igm.dla

# SPDX-License-Identifier: BSD-3-Clause
"""Damped Lyman-alpha (DLA) absorption from individual foreground absorbers.

Computes transmission through a DLA system with known neutral hydrogen
column density N_HI, temperature T, and turbulent broadening b_turb.
The absorption profile is a Voigt function centered on Ly-alpha at the
absorber redshift.

This is distinct from the *statistical* DLA contribution in ``igm.py``
(Inoue+2014), which models the mean opacity from all DLA systems along
a random sightline.  This module handles a *specific* absorber: e.g.,
when a spectrum shows a clear damped trough.

Physics
-------
The Ly-alpha scattering cross-section is:

    σ(ν) = (√π e² f) / (m_e c Δν_D) × H(a, x)

where H(a, x) is the Voigt–Hjerting function, a = Γ/(4π Δν_D) is the
damping parameter, x = (ν − ν₀)/Δν_D is the dimensionless frequency
offset, and Δν_D is the thermal + turbulent Doppler width.

The Voigt function approximation follows Tepper-García (2006, MNRAS 369,
2025), with a first-order asymmetry correction from Lee (2013).

All functions are pure JAX (JIT-compilable, differentiable).

Parameters
----------

- ``dla_log_n_hi`` : log10(N_HI / cm⁻²), typically 19–22.
- ``dla_z`` : redshift of the absorber.
- ``dla_temp`` : gas temperature [K], typically fixed at 10⁴ K.
- ``dla_b_turb`` : turbulent broadening [km/s], typically 0–30.

References
----------

- Tepper-García 2006, MNRAS, 369, 2025 (Voigt approximation)
- Lee 2013, ApJ, 773, 120 (asymmetry correction)
- Dijkstra 2014, PASA, 31, e040 (Ly-alpha cross-section review)

"""

from __future__ import annotations

import math

import jax
import jax.numpy as jnp

from tengri.utils.host_array import device_table, host_array
from tengri.utils.physics_constants import (
    C_CGS,
    E_CHARGE_ESU,
    K_BOLTZ,
    M_ELECTRON,
    M_PROTON,
)

# ── Ly-alpha atomic data ──────────────────────────────────────────

_F_LYA: float = 0.4162
"""Oscillator strength of the Ly-alpha (2p → 1s) transition."""

_A_LYA: float = 6.265e8
"""Einstein A coefficient for Ly-alpha [s⁻¹]."""

_WL_LYA: float = 1215.6701
"""Ly-alpha rest wavelength [Å]."""

_NU_LYA: float = C_CGS / (_WL_LYA * 1e-8)
"""Ly-alpha rest frequency [Hz]."""

_K_LYA = host_array(_F_LYA * math.sqrt(math.pi) * E_CHARGE_ESU**2 / (M_ELECTRON * C_CGS))
"""Cross-section prefactor K = √π e² f / (m_e c) [cm² Hz]."""


# ── Doppler width ─────────────────────────────────────────────────


def _deltanu_doppler(temp: float, b_turb_kms: float) -> float:
    """Thermal + turbulent Doppler frequency width [Hz].

    Parameters
    ----------
    temp : float
        Gas temperature [K].
    b_turb_kms : float
        Turbulent broadening parameter [km/s].

    Returns
    -------
    float
        Δν_D [Hz].
    """
    b_turb_cgs = b_turb_kms * 1e5  # km/s → cm/s
    v_doppler = jnp.sqrt(2.0 * K_BOLTZ * temp / M_PROTON + b_turb_cgs**2)
    return _NU_LYA * v_doppler / C_CGS


# ── Voigt profile (Tepper-García 2006) ────────────────────────────


def _voigt_tepper_garcia(
    x: jnp.ndarray,
    a: float,
) -> jnp.ndarray:
    """Voigt–Hjerting function H(a, x) via Tepper-García (2006).

    Accurate to < 10⁻⁴ relative error for all (a, x) relevant to
    DLA absorption (a ~ 10⁻⁴ to 10⁻²).

    Parameters
    ----------
    x : array
        Dimensionless frequency offset (ν − ν₀) / Δν_D.
    a : float
        Voigt damping parameter Γ / (4π Δν_D).

    Returns
    -------
    array
        H(a, x) ≈ exp(-x²) + correction term.
    """
    x2 = x**2
    z = (x2 - 0.855) / (x2 + 3.42)
    # Safe gradient: pre-compute x2 under where mask to avoid huge gradients
    # through 1/(x2 + 1e-30) when x2 → 0 in the masked-off branch.
    x2_safe = jnp.where(z > 0.0, x2 + 1e-30, 1.0)
    q = jnp.where(
        z > 0.0,
        z
        * (1.0 + 21.0 / x2_safe)
        * a
        / (jnp.pi * (x2 + 1.0))
        * (0.1117 + z * (4.421 + z * (5.674 * z - 9.207))),
        0.0,
    )
    return jnp.sqrt(jnp.pi) * q + jnp.exp(-x2)


# ── Cross-section ─────────────────────────────────────────────────


def _sigma_lya(
    x: jnp.ndarray,
    temp: float,
    b_turb_kms: float,
) -> jnp.ndarray:
    """Ly-alpha scattering cross-section σ(x) [cm²].

    Includes the Tepper-García (2006) Voigt profile and the first-order
    asymmetry correction from Lee (2013).

    Parameters
    ----------
    x : array
        Dimensionless frequency offset.
    temp : float
        Gas temperature [K].
    b_turb_kms : float
        Turbulent broadening [km/s].

    Returns
    -------
    array
        σ [cm²] at each frequency offset.
    """
    dnu = _deltanu_doppler(temp, b_turb_kms)
    a = _A_LYA / (4.0 * jnp.pi * dnu)
    sigma = device_table(_K_LYA) / dnu * _voigt_tepper_garcia(x, a)
    # Lee (2013) asymmetry correction
    sigma = sigma * (1.0 - 1.792 * x * dnu / _NU_LYA)
    return sigma


# ── Public API ────────────────────────────────────────────────────


[docs] @jax.jit def dla_transmission( wave_rest: jnp.ndarray, log_n_hi: float, temp: float = 1e4, b_turb_kms: float = 0.0, ) -> jnp.ndarray: """Transmission through a DLA absorber at rest-frame wavelengths. Parameters ---------- wave_rest : array, shape (n_wave,) Rest-frame wavelength [Å] in the absorber frame (i.e., already de-redshifted to the absorber's rest frame). log_n_hi : float log10(N_HI / cm⁻²). Typical DLA: 20.3–22. temp : float Gas temperature [K]. Default 10⁴ K (warm neutral medium). b_turb_kms : float Turbulent broadening [km/s]. Default 0. Returns ------- ndarray, shape (n_wave,) Transmission T = exp(−τ) [dimensionless, 0–1]. Notes ----- **JIT-compatible**: yes, pure JAX function with ``@jax.jit`` decorator. Examples -------- >>> import jax.numpy as jnp >>> from tengri import dla_transmission >>> wave = jnp.linspace(1100.0, 1300.0, 200) >>> T = dla_transmission(wave, log_n_hi=21.0) >>> T.shape (200,) """ nu = C_CGS / (wave_rest * 1e-8) dnu = _deltanu_doppler(temp, b_turb_kms) x = (nu - _NU_LYA) / dnu sigma = _sigma_lya(x, temp, b_turb_kms) n_hi = 10.0**log_n_hi tau = n_hi * sigma return jnp.exp(-jnp.clip(tau, min=0.0))
[docs] @jax.jit def dla_transmission_obs( wave_obs: jnp.ndarray, z_dla: float, log_n_hi: float, temp: float = 1e4, b_turb_kms: float = 0.0, ) -> jnp.ndarray: """Transmission through a DLA absorber at observed wavelengths. Convenience wrapper that de-redshifts ``wave_obs`` to the absorber rest frame before computing the Voigt absorption. Parameters ---------- wave_obs : array, shape (n_wave,) Observed-frame wavelength [Å]. z_dla : float Redshift of the DLA absorber. log_n_hi : float log10(N_HI / cm⁻²). temp : float Gas temperature [K]. Default 10⁴ K. b_turb_kms : float Turbulent broadening [km/s]. Default 0. Returns ------- ndarray, shape (n_wave,) Transmission T = exp(−τ) [dimensionless, 0–1]. Notes ----- **JIT-compatible**: yes, pure JAX function with ``@jax.jit`` decorator. Examples -------- >>> import jax.numpy as jnp >>> from tengri import dla_transmission_obs >>> wave_obs = jnp.linspace(1100.0 * 1.5, 1300.0 * 1.5, 200) >>> T = dla_transmission_obs(wave_obs, z_dla=0.5, log_n_hi=21.0) >>> T.shape (200,) """ wave_rest = wave_obs / (1.0 + z_dla) return dla_transmission(wave_rest, log_n_hi, temp, b_turb_kms)