skyscapes.physical_model.cached
===============================

.. py:module:: skyscapes.physical_model.cached

.. autoapi-nested-parse::

   Pre-computed reflectivity physical model.

   Holds a fixed ``(K, n_nu)`` plane-parallel-reflectivity array that was
   produced by running some other :class:`AbstractPhysicalModel`'s heavy
   radiative transfer once. ``contrast`` becomes a cubic interpolation +
   Lambert phase + ``(Rp/d)^2`` lookup -- microseconds per call vs.
   seconds for an ExoJAX 2-stream RT.

   Use cases:
     - Coronagraphoto simulations where the physics is fixed across
       many evaluations (orbits, wavelengths, time samples).
     - ETC studies where you want fast forward-modeling against a
       canonical Earth-like atmosphere.

   Not for HMC retrievals where parameters vary -- the underlying
   expensive model is the right tool there.

   The cache file format is a NumPy ``.npz`` with two keyword arrays
   (``reflectivity``, ``nu_grid``) and a small JSON-style header tag for
   version-tracking.



Attributes
----------

.. autoapisummary::

   skyscapes.physical_model.cached.CACHE_FORMAT_VERSION


Classes
-------

.. autoapisummary::

   skyscapes.physical_model.cached.PrecomputedPhysicalModel


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

.. py:data:: CACHE_FORMAT_VERSION
   :value: 2


.. py:class:: PrecomputedPhysicalModel

   Bases: :py:obj:`skyscapes.physical_model.base.AbstractPhysicalModel`


   Physical model whose reflectivity spectrum has been pre-computed.

   Attributes:
       reflectivity: Per-planet plane-parallel reflectivity ``R(nu)``
           on the wavenumber grid, shape ``(K, n_nu)``. Already
           includes all the physics of the original physical model
           (absorption, Rayleigh, clouds, surface).
       nu_grid: Wavenumber grid [cm^-1], shape ``(n_nu,)``.
       n_nu: Length of ``nu_grid`` (static for JIT).


   .. py:attribute:: reflectivity
      :type:  jaxtyping.Array


   .. py:attribute:: nu_grid
      :type:  jaxtyping.Array


   .. py:attribute:: n_nu
      :type:  int


   .. py:method:: from_physical_model(model)
      :classmethod:


      Pre-compute the reflectivity from an existing physical model.

      Calls the model's internal ``_reflectivity_all_planets``
      once and packages the result. Requires the model to expose
      ``_reflectivity_all_planets``, ``nu_grid``, and ``n_nu`` --
      presently :class:`ExoJaxPhysicalModel` is the supported source.



   .. py:method:: load(path)
      :classmethod:


      Load a previously-saved cache file.

      Args:
          path: Path to a ``.npz`` file produced by :meth:`save`.

      Returns:
          A ``PrecomputedPhysicalModel`` ready to evaluate.

      Raises:
          ValueError: if the file's ``cache_format_version`` differs
              from the current code's version (would silently
              produce wrong spectra otherwise).



   .. py:method:: save(path)

      Save the cached reflectivity to a ``.npz`` file.

      Idempotent and safe to call from JAX-traced contexts (the
      save itself is plain NumPy -- callers should not call this
      inside a JIT region, but the data is just regular arrays).



   .. py:method:: contrast(phase_angle_rad, dist_AU, wavelength_nm, Rp_Rearth)

      Per-planet, per-time geometric-albedo contrast at one wavelength.

      Args:
          phase_angle_rad: Star-planet-observer phase angle, shape ``(K, T)``.
          dist_AU: Star-planet distance [AU], shape ``(K, T)``.
          wavelength_nm: Scalar wavelength [nm].
          Rp_Rearth: Planet radius [Earth radii], shape ``(K,)``.

      Returns:
          Contrast = ``A_g(lambda) * Lambert_phase(beta) * (Rp/d)^2``,
          shape ``(K, T)``. The cached array stores the underlying
          model's plane-parallel (spherical) reflectivity; we convert
          to geometric albedo via the Lambertian-sphere factor 2/3
          (Seager 2010, eq 3.36) at call time -- same convention as
          :class:`ExoJaxPhysicalModel.contrast`.



   .. py:method:: contrast_cube(phase_angle_rad, dist_AU, wavelengths_nm, Rp_Rearth)

      Per-planet, per-time geometric-albedo contrast across wavelengths.

      Returns shape ``(W, K, T)``. Avoids per-wavelength
      recomputation by vectorising the interpolation; applies the
      Lambertian-sphere spherical-to-geometric conversion the same
      way as :meth:`contrast`.



   .. py:method:: __repr__()

      Compact summary of the cached spectrum.