skyscapes.physical_model.exojax.psg_xs
======================================

.. py:module:: skyscapes.physical_model.exojax.psg_xs

.. autoapi-nested-parse::

   PSG cross-section opacity adapter.

   The PSG (NASA's Planetary Spectrum Generator) hosts pre-computed
   absorption cross-sections in a uniform ASCII format for many
   atmospheric gases that ExoJAX's line-by-line machinery
   (``MdbHitran``/``OpaPremodit``) cannot consume directly -- either
   because the band is an electronic continuum (e.g. O3 Chappuis,
   SO2 in the UV) or because HITRAN has no entries in the desired
   wavelength range. This module ships an ``Opa``-shaped adapter that
   loads any such PSG cross-section file and exposes the same
   ``xsmatrix(Tarr, pressure) -> (n_layers, n_nu)`` contract as
   ExoJAX's line-list opa engines.

   Format details (PSG xuv linelists):
       Header lines start with ``#``. The ``#TEMP:`` line lists one or
       more reference temperatures [K] (e.g. 1 column for many molecules,
       11 columns for O3's Serdyuchenko set). Data rows are
       ``wavelength_um  sigma_T1  sigma_T2 ...`` with cross-sections in
       cm^2/molecule. See
       https://psg.gsfc.nasa.gov/helpatm.php for the full catalog of
       available molecules.



Classes
-------

.. autoapisummary::

   skyscapes.physical_model.exojax.psg_xs.PsgCrossSectionOpacity


Functions
---------

.. autoapisummary::

   skyscapes.physical_model.exojax.psg_xs.fetch_psg_xs
   skyscapes.physical_model.exojax.psg_xs._load_psg_xs_table


Module Contents
---------------

.. py:function:: fetch_psg_xs(url, cache_filename, cache_dir = None)

   Download a PSG cross-section file once and cache it locally.

   Idempotent: if the cached file already exists it is returned
   without re-downloading.

   Args:
       url: PSG download URL.
       cache_filename: Name to give the cached file under
           ``cache_dir``.
       cache_dir: Directory to cache into. Defaults to
           ``~/.cache/skyscapes/`` if None.

   Returns:
       Absolute path to the cached file.


.. py:function:: _load_psg_xs_table(path)

   Parse a PSG cross-section ASCII file.

   The PSG format begins with ``#``-prefixed header lines including a
   ``#TEMP:`` row listing the temperature axis [K] (one or more
   values), followed by data rows of
   ``wavelength_um  sigma_T1  sigma_T2 ... sigma_TN`` with
   cross-sections in cm^2/molecule.

   Args:
       path: Path to the PSG ASCII file.

   Returns:
       Tuple of ``(wavelength_um, T_grid_K, sigma)`` where ``sigma``
       has shape ``(n_wavelengths, n_temperatures)`` in cm^2/molecule.


.. py:class:: PsgCrossSectionOpacity(name, url, molmass, nu_grid, cache_dir = None, xs_table_path = None, cache_filename = None)

   Cross-section-backed opacity from any PSG xs file.

   Quacks like ExoJAX's ``OpaPremodit``: exposes
   ``xsmatrix(Tarr, pressure) -> (n_layers, n_nu)`` and a ``molmass``
   attribute, so it slots into the same ``opa_engines`` tuple as the
   line-list-backed opacity engines.

   Pressure broadening is ignored. The PSG cross-section files
   describe electronic-continuum / pre-broadened absorption; the
   pressure-dependence at typical atmospheric pressures is below
   the photon-noise floor for HWO contrast levels. Temperature
   interpolation is linear against the file's temperature axis, with
   out-of-range temperatures clamped to the nearest endpoint.

   For files with a single temperature column the cross-section is
   returned independent of layer temperature.

   Attributes:
       name: Molecule name (e.g. ``"O3"``, ``"SO2"``).
       molmass: Molar mass [g/mol]. Caller supplies; used by
           ``opacity_profile_xs`` to convert mmr to column density.
       nu_grid: Wavenumber grid [cm^-1] this adapter was built for.


   .. py:attribute:: name


   .. py:attribute:: molmass


   .. py:attribute:: nu_grid


   .. py:attribute:: _T_grid


   .. py:attribute:: _sigma_at_nu


   .. py:method:: xsmatrix(Tarr, pressure)

      Cross-section matrix at the requested layer temperatures.

      ``pressure`` is accepted for interface parity with
      ``OpaPremodit`` but is unused.

      Args:
          Tarr: Layer temperatures [K], shape ``(n_layers,)``.
          pressure: Layer pressures [bar], shape ``(n_layers,)``;
              ignored.

      Returns:
          Cross-section matrix [cm^2/molecule], shape
          ``(n_layers, n_nu)``. Temperatures outside the PSG file's
          range clamp to the nearest endpoint cross-section. For
          single-temperature files the returned matrix is constant
          in T.