skyscapes.physical_model.exojax.components.mmr_profile
======================================================

.. py:module:: skyscapes.physical_model.exojax.components.mmr_profile

.. autoapi-nested-parse::

   Mass-mixing-ratio profiles for atmospheric species.

   Each species in a :class:`MolecularSpecies` tuple carries one of these
   profile components, replacing the previous "scalar mmr per planet"
   representation. Different molecules need different altitude variations:

     - **Well-mixed gases** (N2, O2, CO2, CH4 in our pressure range): use
       :class:`ConstantMmr` -- same mmr at every layer.
     - **O3** is concentrated in the stratosphere with column ~10x larger
       than a uniformly-mixed model would assume: use
       :class:`StratosphericPeakMmr` (Gaussian in log-pressure).
     - **H2O** has a sharp cold-trap drop at the tropopause (~0.1 bar)
       where temperatures fall below ~200 K: use :class:`TroposphericMmr`
       (sigmoid-smoothed step in log-pressure).

   The profile contract is just ``evaluate(pressure) -> (n_layers,) mmr``.
   Layer pressures come from the rt_engine; each component returns the
   per-layer mass-mixing ratio.



Classes
-------

.. autoapisummary::

   skyscapes.physical_model.exojax.components.mmr_profile.AbstractMmrProfile
   skyscapes.physical_model.exojax.components.mmr_profile.ConstantMmr
   skyscapes.physical_model.exojax.components.mmr_profile.StratosphericPeakMmr
   skyscapes.physical_model.exojax.components.mmr_profile.TroposphericMmr


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

.. py:class:: AbstractMmrProfile

   Bases: :py:obj:`equinox.Module`


   Per-species mass-mixing-ratio profile evaluated at layer pressures.


   .. py:method:: evaluate(pressure)
      :abstractmethod:


      Return shape ``(n_layers,)`` mmr values at the layer pressures.



.. py:class:: ConstantMmr

   Bases: :py:obj:`AbstractMmrProfile`


   Well-mixed gas: constant mmr at every layer.

   Use for gases with chemical lifetimes longer than mixing timescales
   in the modelled pressure range (CO2, CH4, O2, N2, etc. in
   troposphere + lower stratosphere).

   Attributes:
       log_mmr: Log10 mass-mixing ratio, shape ``(K,)`` (per planet).


   .. py:attribute:: log_mmr
      :type:  jaxtyping.Array


   .. py:method:: evaluate(pressure)

      Return ``10**log_mmr`` broadcast to ``pressure.shape``.



.. py:class:: StratosphericPeakMmr

   Bases: :py:obj:`AbstractMmrProfile`


   Gaussian-in-log-pressure peak; canonical for O3.

   ``mmr(P) = 10**log_peak_mmr * exp(-0.5 * ((log10(P) -
   log_peak_pressure_bar) / log_sigma_decades)**2)``.

   For Earth's O3: ``log_peak_pressure_bar = log10(0.01) = -2``
   (10 mbar, ~30 km altitude), ``log_sigma_decades = 0.5``.

   Attributes:
       log_peak_mmr: Log10 of the peak mmr, shape ``(K,)``.
       log_peak_pressure_bar: Log10 pressure [bar] at peak, ``(K,)``.
       log_sigma_decades: Gaussian width in log10-pressure, ``(K,)``.


   .. py:attribute:: log_peak_mmr
      :type:  jaxtyping.Array


   .. py:attribute:: log_peak_pressure_bar
      :type:  jaxtyping.Array


   .. py:attribute:: log_sigma_decades
      :type:  jaxtyping.Array


   .. py:method:: evaluate(pressure)

      Gaussian peak in log-pressure.



.. py:class:: TroposphericMmr

   Bases: :py:obj:`AbstractMmrProfile`


   Constant below a step pressure, drops sharply above; canonical for H2O.

   Uses a sigmoid in log-pressure for smooth transition (differentiable
   for HMC retrievals). For Earth's H2O: tropospheric ~3e-3 below
   0.1 bar, ~3e-6 above.

   Attributes:
       log_mmr_below: Log10 mmr at high pressure (below cold trap), ``(K,)``.
       log_mmr_above: Log10 mmr at low pressure (above cold trap), ``(K,)``.
       log_pressure_step_bar: Log10 transition pressure [bar], ``(K,)``.
       log_transition_width_decades: Width of the sigmoid transition
           in log10-pressure, ``(K,)``. Smaller = sharper step.


   .. py:attribute:: log_mmr_below
      :type:  jaxtyping.Array


   .. py:attribute:: log_mmr_above
      :type:  jaxtyping.Array


   .. py:attribute:: log_pressure_step_bar
      :type:  jaxtyping.Array


   .. py:attribute:: log_transition_width_decades
      :type:  jaxtyping.Array


   .. py:method:: evaluate(pressure)

      Sigmoid step in log-pressure.