optixstuff.coronagraph
======================

.. py:module:: optixstuff.coronagraph

.. autoapi-nested-parse::

   Coronagraph abstractions.



Classes
-------

.. autoapisummary::

   optixstuff.coronagraph.AbstractCoronagraph
   optixstuff.coronagraph.AbstractScalarCoronagraph


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

.. py:class:: AbstractCoronagraph

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


   Abstract interface for coronagraph performance models.

   Provides both scalar performance curves (for ETC use) and 2D PSF
   generation (for image simulation). Implementations can be backed by
   pre-computed interpolation tables (yippy), physical wavefront
   propagation, or analytical models.

   All wavelength arguments are in nanometres throughout.
   All separations are in lambda/D units.


   .. py:attribute:: pixel_scale_lod
      :type:  equinox.AbstractVar[float]

      Native pixel scale in lambda/D per pixel.



   .. py:attribute:: IWA
      :type:  equinox.AbstractVar[float]

      Inner working angle in lambda/D.



   .. py:attribute:: OWA
      :type:  equinox.AbstractVar[float]

      Outer working angle in lambda/D.



   .. py:method:: throughput(separation_lod, wavelength_nm, *, time_s = 0.0)
      :abstractmethod:


      Core (off-axis planet) throughput.

      Args:
          separation_lod: Angular separation in lambda/D.
          wavelength_nm: Wavelength in nanometres.
          time_s: Time since mission start in seconds.

      Returns:
          Fractional throughput in [0, 1].



   .. py:method:: core_area(separation_lod, wavelength_nm, *, time_s = 0.0)
      :abstractmethod:


      Photometric aperture area in (lambda/D)^2.

      Args:
          separation_lod: Angular separation in lambda/D.
          wavelength_nm: Wavelength in nanometres.
          time_s: Time since mission start in seconds.

      Returns:
          Core area in (lambda/D)^2.



   .. py:method:: core_mean_intensity(separation_lod, wavelength_nm, *, time_s = 0.0)
      :abstractmethod:


      Mean stellar intensity within the photometric aperture.

      Args:
          separation_lod: Angular separation in lambda/D.
          wavelength_nm: Wavelength in nanometres.
          time_s: Time since mission start in seconds.

      Returns:
          Mean stellar leakage intensity in (lambda/D)^-2.



   .. py:method:: occulter_transmission(separation_lod, wavelength_nm, *, time_s = 0.0)
      :abstractmethod:


      Off-axis (sky/zodi) transmission through the occulter.

      Args:
          separation_lod: Angular separation in lambda/D.
          wavelength_nm: Wavelength in nanometres.
          time_s: Time since mission start in seconds.

      Returns:
          Fractional sky transmission in [0, 1].



   .. py:method:: on_axis_psf(wavelength_nm, pixel_scale_rad, npixels)
      :abstractmethod:


      On-axis (stellar leakage) PSF.

      Returns the coronagraphic PSF for an on-axis point source,
      normalized to unit stellar flux before the coronagraph.

      Args:
          wavelength_nm: Wavelength in nanometres.
          pixel_scale_rad: Output pixel scale in radians/pixel.
          npixels: Output array side length in pixels. Must be a
              Python int (not a JAX array) as it determines the
              output shape at compile time.

      Returns:
          2D float array of shape (npixels, npixels).



   .. py:method:: off_axis_psf(wavelength_nm, separation_lod, pixel_scale_rad, npixels)
      :abstractmethod:


      Off-axis PSF at a given angular separation.

      Args:
          wavelength_nm: Wavelength in nanometres.
          separation_lod: Source separation in lambda/D.
          pixel_scale_rad: Output pixel scale in radians/pixel.
          npixels: Output array side length in pixels. Must be a
              Python int (not a JAX array) as it determines the
              output shape at compile time.

      Returns:
          2D float array of shape (npixels, npixels).



.. py:class:: AbstractScalarCoronagraph

   Bases: :py:obj:`AbstractCoronagraph`


   Base for ETC-only coronagraph models that lack 2D PSF generation.

   Stubs out the image interface with zero arrays so the class satisfies
   AbstractCoronagraph without requiring a full optical model.


   .. py:method:: on_axis_psf(wavelength_nm, pixel_scale_rad, npixels)

      Return a zero PSF (not implemented for scalar-only models).



   .. py:method:: off_axis_psf(wavelength_nm, separation_lod, pixel_scale_rad, npixels)

      Return a zero PSF (not implemented for scalar-only models).