optixstuff.optical_path
=======================

.. py:module:: optixstuff.optical_path

.. autoapi-nested-parse::

   OpticalPath container -- the universal hardware configuration.



Classes
-------

.. autoapisummary::

   optixstuff.optical_path.OpticalPath


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

.. py:class:: OpticalPath

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


   Universal hardware container for a coronagraphic telescope.

   Bundles a primary mirror, ordered chain of attenuating elements,
   a coronagraph, and a detector into a single configuration object.
   This is the interface passed to simulators (coronagraphoto),
   exposure time calculators (jaxEDITH), and IFS instruments (coronachrome).

   Args:
       primary: Primary mirror description.
       attenuating_elements: Ordered tuple of throughput elements
           between the primary and coronagraph (mirrors, filters, etc.).
       coronagraph: Coronagraph performance model.
       detector: Focal-plane detector model.
       disperser: Optional IFS disperser descriptor; None for imaging mode.
       n_channels: Number of parallel identical optical-path copies
           (AYO shorthand, multiplicative factor on count rates;
           not a spectral channel count). Default 1.0.
       npix_multiplier: IFS signal-spread multiplier on detector pixel
           counts. Default 1.0.


   .. py:attribute:: primary
      :type:  optixstuff.primary.AbstractPrimary


   .. py:attribute:: attenuating_elements
      :type:  tuple[optixstuff.optical_elements.AbstractOpticalElement, Ellipsis]


   .. py:attribute:: coronagraph
      :type:  optixstuff.coronagraph.AbstractCoronagraph


   .. py:attribute:: detector
      :type:  optixstuff.detector.AbstractDetector


   .. py:attribute:: disperser
      :type:  optixstuff.disperser.AbstractDisperser | None
      :value: None



   .. py:attribute:: n_channels
      :type:  float
      :value: 1.0



   .. py:attribute:: npix_multiplier
      :type:  float
      :value: 1.0



   .. py:method:: from_default_setup(coronagraph, *, diameter_m = 6.0, obscuration = 0.0, attenuating_throughput = 1.0, detector_shape = (512, 512), pixel_scale_arcsec = 0.01, quantum_efficiency = 0.9, dark_current_rate_e_per_s = 0.0, n_channels = 1.0, npix_multiplier = 1.0)
      :classmethod:


      Build an OpticalPath with reasonable HWO-like defaults.

      Convenience for notebook / dev-script work: spin up a working
      ``OpticalPath`` by specifying only the coronagraph. All other
      parameters get sensible defaults that can be overridden.

      Args:
          coronagraph: One of:
              - an :class:`AbstractCoronagraph` instance (used as-is),
              - a YIP path (str or :class:`pathlib.Path`, wrapped with
                :class:`YippyCoronagraph`),
              - a ``yippy.EqxCoronagraph`` instance (wrapped via
                ``YippyCoronagraph(backend=...)`` so callers can keep
                using existing yippy code without rebuilding).
          diameter_m: Primary mirror diameter [m]. Default ``6.0`` (HWO
              EAC1 baseline).
          obscuration: Linear central-obscuration fraction. Default 0.
          attenuating_throughput: Combined throughput of the optical
              chain (one :class:`ConstantThroughput`). Default
              ``1.0`` -- a perfect path; override for realistic studies.
          detector_shape: Detector ``(ny, nx)`` in pixels. Default
              ``(512, 512)``.
          pixel_scale_arcsec: Detector plate scale [arcsec/px]. Default
              ``0.01``.
          quantum_efficiency: Default ``0.9``.
          dark_current_rate_e_per_s: Default ``0.0`` e-/s/px (perfect detector;
              callers add realistic noise when needed).
          n_channels: AYO parallel-path multiplier. Default ``1.0``.
          npix_multiplier: IFS signal-spread multiplier. Default ``1.0``.

      Returns:
          A ready-to-use :class:`OpticalPath`.



   .. py:method:: system_throughput(wavelength_nm)

      Total throughput of all attenuating elements.

      Args:
          wavelength_nm: Wavelength in nanometres.

      Returns:
          Combined fractional throughput in [0, 1].



   .. py:method:: __repr__()

      Tree-shaped summary of every component.