skyscapes.physical_model.exojax.components.mie_cloud
====================================================

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

.. autoapi-nested-parse::

   Mie-scattering cloud component.

   A drop-in replacement for :class:`GrayCloud` that uses ExoJAX's
   ``OpaMie`` to pre-compute wavelength-dependent single-scattering
   albedo and asymmetry parameter for a chosen condensate (e.g. water,
   water-ice, NH3) and particle size distribution. The cloud's vertical
   distribution and total optical depth remain fittable PyTree leaves;
   the wavelength dependence of ssa(lambda) and g(lambda) is fixed at
   engine-build time.

   ExoJAX's ``PdbCloud`` triggers a one-time download of the chosen
   condensate's refractive-index data (cached under
   ``./.database/particulates/virga/``) on first use, similar to the
   HITRAN line-list downloads.



Classes
-------

.. autoapisummary::

   skyscapes.physical_model.exojax.components.mie_cloud.MieCloud


Functions
---------

.. autoapisummary::

   skyscapes.physical_model.exojax.components.mie_cloud.build_mie_cloud


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

.. py:class:: MieCloud

   Bases: :py:obj:`skyscapes.physical_model.exojax.components.base.AbstractClouds`


   Single-layer cloud with Mie-scattering optical properties.

   The total cloud scattering optical depth is distributed vertically
   via a softmax-Gaussian in log-pressure (same as
   :class:`GrayCloud`). What's different is that the
   single-scattering albedo and asymmetry parameter come from
   pre-computed Mie cross-sections rather than being scalar
   constants -- they vary with wavelength according to the
   condensate's refractive index n(lambda) + k(lambda).

   Attributes (PyTree leaves, fittable):
       log_pressure_bar: Log10 cloud-deck pressure [bar], shape ``(K,)``.
       log_opt_depth: Log10 of the vertically-integrated cloud
           extinction optical depth, shape ``(K,)``.

   Pre-computed Mie quantities (built at engine time, shared across
   planets):
       ssa_grid: Single-scattering albedo on the wavenumber grid,
           shape ``(n_nu,)``. ``sigma_scattering / sigma_extinction``.
       g_grid: Asymmetry parameter on the wavenumber grid,
           shape ``(n_nu,)``.

   Static config:
       condensate: Condensate name (``"H2O"``, ``"H2O_ice"``,
           ``"MgSiO3"``, etc.). Matters for the repr; the actual
           Mie params are baked into ssa_grid and g_grid.
       rg_um: Geometric mean particle radius [um].
       sigmag: Geometric standard deviation of the lognormal size
           distribution.
       log_sigma: Cloud-deck vertical Gaussian half-width in
           log10(pressure) [dex].


   .. py:attribute:: log_pressure_bar
      :type:  jaxtyping.Array


   .. py:attribute:: log_opt_depth
      :type:  jaxtyping.Array


   .. py:attribute:: ssa_grid
      :type:  jaxtyping.Array


   .. py:attribute:: g_grid
      :type:  jaxtyping.Array


   .. py:attribute:: condensate
      :type:  str


   .. py:attribute:: rg_um
      :type:  float


   .. py:attribute:: sigmag
      :type:  float


   .. py:attribute:: log_sigma
      :type:  float


   .. py:method:: compute(log_pressure_bar_scalar, log_opt_depth_scalar, pressure, n_nu)

      Mie-cloud contribution: gray-depth distribution, spectral ssa/g.



.. py:function:: build_mie_cloud(*, nu_grid, log_pressure_bar, log_opt_depth, condensate = 'H2O', rg_um = 10.0, sigmag = 2.0, log_sigma = DEFAULT_CLOUD_LOG_SIGMA)

   Build a Mie cloud component by pre-computing Mie params.

   On first use for a given condensate this triggers two downloads /
   computations cached under ``./.database/particulates/virga/``:

     - **Refractive-index file** (small, fetched from Zenodo).
     - **Mie-grid lookup table** (built locally via PyMieScatt; takes
       a couple of minutes per condensate). Subsequent calls reuse
       the cache.

   Args:
       nu_grid: Wavenumber grid [cm^-1] from
           :func:`build_exojax_engines`.
       log_pressure_bar: Per-planet log10 cloud pressure [bar].
       log_opt_depth: Per-planet log10 total cloud extinction tau.
       condensate: Condensate name. ExoJAX/Virga ships e.g.
           ``"H2O"``, ``"H2O_ice"``, ``"NH3"``, ``"MgSiO3"``,
           ``"Mg2SiO4"``, ``"Fe"``, ``"KCl"``, ``"Na2S"``,
           ``"ZnS"``, ``"MnS"``, ``"Cr"``, ``"Al2O3"``,
           ``"TiO2"``.
       rg_um: Mean particle radius [um] of the lognormal size
           distribution.
       sigmag: Geometric standard deviation of the size distribution.
       log_sigma: Vertical-distribution Gaussian half-width [dex].

   Returns:
       A :class:`MieCloud` instance ready to drop into
       :class:`ExoJaxPhysicalModel`.