skyscapes.physical_model.exojax.presets
=======================================

.. py:module:: skyscapes.physical_model.exojax.presets

.. autoapi-nested-parse::

   Atmospheric-composition archetypes (VMR / MMR conversion helpers).

   Each preset is a dict mapping molecule name to volume mixing ratio
   (``VMR`` = mole fraction, the convention used in atmospheric science
   literature). :func:`vmr_dict_to_log_mmr_dict` converts to log10
   mass-mixing ratios at construction time using a bulk gas (default
   N2) to fill the residual, returning the dict shape
   ``ExoJaxPhysicalModel.from_default_setup`` consumes for ``log_mmrs``.

   The four Earth-epoch presets bracket the modern oxygenated atmosphere
   plus three earlier states (Archean, Early Proterozoic, Late
   Proterozoic) drawn from a published "Earth through time" biosignature
   table. Source attribution lives with whoever updates these values --
   update the table here and note the source in your commit message or
   local documentation.

   I got these from Natasha Latouf and she has citations... somewhere.

   Example::

       import jax.numpy as jnp
       from skyscapes.physical_model import ExoJaxPhysicalModel
       from skyscapes.physical_model.exojax.presets import (
           EARTH_MODERN_VMRS, vmr_dict_to_log_mmr_dict,
       )

       log_mmrs = vmr_dict_to_log_mmr_dict(EARTH_MODERN_VMRS, K=1)
       model = ExoJaxPhysicalModel.from_default_setup(
           log_mmrs=log_mmrs,
           T_eq_K=jnp.full((1,), 288.0),
           T_alpha=jnp.full((1,), 0.07),
           log_surface_albedo=jnp.full((1,), jnp.log10(0.3)),
           log_gravity_cgs=jnp.full((1,), jnp.log10(981.0)),
       )



Attributes
----------

.. autoapisummary::

   skyscapes.physical_model.exojax.presets.EARTH_ARCHEAN_VMRS
   skyscapes.physical_model.exojax.presets.EARTH_EARLY_PROTEROZOIC_VMRS
   skyscapes.physical_model.exojax.presets.EARTH_LATE_PROTEROZOIC_VMRS
   skyscapes.physical_model.exojax.presets.EARTH_MODERN_VMRS


Functions
---------

.. autoapisummary::

   skyscapes.physical_model.exojax.presets.vmr_dict_to_mmr_dict
   skyscapes.physical_model.exojax.presets.vmr_dict_to_log_mmr_dict
   skyscapes.physical_model.exojax.presets.vmr_dict_to_earth_profile_dict


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

.. py:data:: EARTH_ARCHEAN_VMRS
   :type:  dict[str, float]

.. py:data:: EARTH_EARLY_PROTEROZOIC_VMRS
   :type:  dict[str, float]

.. py:data:: EARTH_LATE_PROTEROZOIC_VMRS
   :type:  dict[str, float]

.. py:data:: EARTH_MODERN_VMRS
   :type:  dict[str, float]

.. py:function:: vmr_dict_to_mmr_dict(vmrs, bulk_gas = 'N2')

   Convert volume-mixing-ratio dict to mass-mixing-ratio dict.

   Computes mean molecular weight from the supplied VMRs plus the
   bulk-gas residual (mmr_bulk = 1 - sum(vmrs_tracked), in VMR
   space; then convert all to mass). Used internally by
   :func:`vmr_dict_to_log_mmr_dict`; exposed here for inspection.

   Args:
       vmrs: ``{name: VMR}`` for tracked molecules. Sum must be < 1
           (the residual is the bulk gas).
       bulk_gas: Name of the implicit residual gas (``"N2"`` for
           terrestrial atmospheres, ``"H2"`` for gas giants, ...).
           Must appear in :data:`BULK_GAS_RECIPES`.

   Returns:
       ``{name: MMR}`` for the tracked molecules. The bulk gas's
       MMR is *not* returned -- ``ExoJaxPhysicalModel`` computes it
       dynamically as the residual.


.. py:function:: vmr_dict_to_log_mmr_dict(vmrs, K = 1, bulk_gas = 'N2')

   Convert VMR dict to log10 MMR dict with K-shaped arrays.

   Each value in the returned dict is shape ``(K,)`` so it can be
   passed directly as ``log_mmrs=`` to
   :meth:`ExoJaxPhysicalModel.from_default_setup`. The same VMR is used
   for every planet -- to give per-planet variation, modify the
   returned arrays before constructing the atmosphere.

   Every species gets a :class:`ConstantMmr` profile by default
   (uniform mmr at every altitude). For Earth-realistic profiles
   (O3 stratospheric peak, H2O cold-trap drop) use
   :func:`vmr_dict_to_earth_profile_dict` instead.


.. py:function:: vmr_dict_to_earth_profile_dict(vmrs, K = 1, bulk_gas = 'N2')

   VMRs -> dict of Earth-realistic profiles per species.

   Most species get a :class:`ConstantMmr` (well-mixed assumption).
   For H2O and O3, where Earth's altitude profile differs sharply
   from uniform, the function builds:

     - **H2O**: :class:`TroposphericMmr` with the supplied VMR below
       the cold trap and a 3-decade drop above (parametrized at
       ``P = 0.1 bar``).
     - **O3**: :class:`StratosphericPeakMmr` with the supplied VMR as
       the peak value at ``P = 10 mbar`` (Gaussian width 0.5 dex).

   All values are taken from canonical Earth-atmosphere structure --
   customize by constructing your own profile dict if you need to
   fit per-planet profile parameters in an HMC retrieval.

   Args:
       vmrs: ``{name: VMR}``; H2O VMR is interpreted as the
           tropospheric value, O3 VMR as the stratospheric peak.
       K: Number of planets (per-planet broadcasting).
       bulk_gas: Implicit residual gas name.

   Returns:
       ``{name: AbstractMmrProfile}`` ready to pass as
       ``log_mmrs=`` to :meth:`ExoJaxPhysicalModel.from_default_setup`.