skyscapes.background
====================

.. py:module:: skyscapes.background

.. autoapi-nested-parse::

   Background sources that fill the field of view.

   A background is anything in the telescope's field of view that is not part
   of the planetary system itself: zodiacal light, extragalactic background,
   line-of-sight stars, etc. Each background type is its own concrete class;
   there is deliberately no shared abstract base yet -- the eventual taxonomy
   will be designed once a second background type beyond zodi exists.

   Currently this module exposes three zodi flavours, all returning
   ``ph/s/m^2/nm`` per ``arcsec^2``.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/skyscapes/background/zodi/index


Attributes
----------

.. autoapisummary::

   skyscapes.background.Zodi


Classes
-------

.. autoapisummary::

   skyscapes.background.AYOZodi
   skyscapes.background.LeinertZodi
   skyscapes.background.PrecomputedZodi


Package Contents
----------------

.. py:class:: AYOZodi(wavelengths_nm, surface_brightness_mag = 22.0, reference_wavelength_nm = 550.0)

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


   Zodiacal light using AYO-compatible default settings.

   Uses a fixed surface brightness at V-band with a Leinert
   wavelength-dependent color correction. Position-independent at query
   time -- the AYO convention bakes in solar longitude 135 deg.

   Example:
       >>> import jax.numpy as jnp
       >>> wavelengths = jnp.linspace(400, 1000, 50)
       >>> zodi = AYOZodi(wavelengths, surface_brightness_mag=22.0)


   .. py:attribute:: _wavelengths_nm
      :type:  jax.numpy.ndarray


   .. py:attribute:: _flux_density_phot
      :type:  jax.numpy.ndarray


   .. py:attribute:: _flux_interp
      :type:  interpax.Interpolator1D


   .. py:attribute:: _reference_wavelength_nm
      :type:  float


   .. py:attribute:: _reference_mag_arcsec2
      :type:  float


   .. py:property:: reference_wavelength_nm
      :type: float


      Reference wavelength for the zodi model in nm.



   .. py:property:: reference_mag_arcsec2
      :type: float


      Surface brightness at the reference wavelength in mag/arcsec^2.



   .. py:method:: spec_flux_density(wavelength_nm, time_jd, ecliptic_lat_deg = 0.0, solar_lon_deg = 135.0)

      Return surface brightness in ph/s/m^2/nm per arcsec^2.

      ``time_jd`` and the ecliptic/solar arguments are accepted for
      interface compatibility but ignored: the AYO convention is a
      fixed-angle assumption.



   .. py:method:: __repr__()

      One-line summary of the AYO zodi reference + wavelength grid.



.. py:class:: LeinertZodi(reference_mag_arcsec2 = 22.0, reference_wavelength_nm = 550.0)

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


   Zodiacal light using the full Leinert (1998) position-dependent model.

   Computes the surface brightness dynamically from the Leinert et al.
   (1998) tables for both position (ecliptic latitude, solar longitude)
   and wavelength dependence.

   Example:
       >>> zodi = LeinertZodi(reference_mag_arcsec2=22.0)
       >>> flux1 = zodi.spec_flux_density(550.0, 0.0, ecliptic_lat_deg=30.0)
       >>> flux2 = zodi.spec_flux_density(550.0, 0.0, ecliptic_lat_deg=45.0)


   .. py:attribute:: _reference_wavelength_nm
      :type:  float


   .. py:attribute:: _reference_mag_arcsec2
      :type:  float


   .. py:property:: reference_wavelength_nm
      :type: float


      Reference wavelength for the zodi model in nm.



   .. py:property:: reference_mag_arcsec2
      :type: float


      Surface brightness at the reference wavelength in mag/arcsec^2.



   .. py:method:: spec_flux_density(wavelength_nm, time_jd, ecliptic_lat_deg = 0.0, solar_lon_deg = 135.0)

      Return surface brightness in ph/s/m^2/nm per arcsec^2.

      Args:
          wavelength_nm: Scalar wavelength in nm.
          time_jd: Scalar time in Julian days (ignored).
          ecliptic_lat_deg: Ecliptic latitude in degrees.
          solar_lon_deg: Solar longitude in degrees.



   .. py:method:: __repr__()

      One-line summary of the Leinert zodi reference.



.. py:class:: PrecomputedZodi(wavelengths_nm, flux_phot_per_arcsec2, reference_mag_arcsec2 = 22.0)

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


   Zodiacal light from pre-computed photon flux values.

   Wraps an externally computed array of photon fluxes (e.g. extracted
   from an EXOSIMS or pyEDITH run) so the same values flow through the
   coronagraph image simulator without recomputation. Position and time
   arguments are accepted for interface compatibility but ignored.

   Example:
       >>> exosims_flux = ...  # ph/s/m^2/nm/arcsec^2 from EXOSIMS
       >>> zodi = PrecomputedZodi(wavelengths, exosims_flux)


   .. py:attribute:: _wavelengths_nm
      :type:  jax.numpy.ndarray


   .. py:attribute:: _flux_density_phot
      :type:  jax.numpy.ndarray


   .. py:attribute:: _flux_interp
      :type:  interpax.Interpolator1D


   .. py:attribute:: _reference_wavelength_nm
      :type:  float


   .. py:attribute:: _reference_mag_arcsec2
      :type:  float


   .. py:property:: reference_wavelength_nm
      :type: float


      Reference wavelength for the zodi model in nm.



   .. py:property:: reference_mag_arcsec2
      :type: float


      Surface brightness at the reference wavelength in mag/arcsec^2.



   .. py:method:: spec_flux_density(wavelength_nm, time_jd, ecliptic_lat_deg = 0.0, solar_lon_deg = 135.0)

      Return surface brightness in ph/s/m^2/nm per arcsec^2.

      All arguments other than ``wavelength_nm`` are accepted for
      interface compatibility but ignored.



   .. py:method:: __repr__()

      One-line summary of pre-tabulated zodi photon-flux source.



.. py:data:: Zodi

   Nominal union of all concrete zodi source types.

   Used as the type annotation on ``Scene.zodi`` and on coronagraphoto's
   ``gen_zodi_count_rate`` / ``sim_zodi``. Each variant must implement
   ``spec_flux_density(wavelength_nm, time_jd, ecliptic_lat_deg, solar_lon_deg)``.
   New variants must be added to this union AND implement that method.