optixstuff.disperser
====================

.. py:module:: optixstuff.disperser

.. autoapi-nested-parse::

   Disperser hardware descriptors for integral field spectrographs.

   optixstuff owns the descriptor: the interface plus a cheap closed-form
   scalar/ETC face. The heavy render logic (building the forward operator) lives
   in coronachrome. This mirrors the coronagraph split, so jaxedith and yield
   tools can read IFS hardware info without importing the render engine.



Classes
-------

.. autoapisummary::

   optixstuff.disperser.AbstractDisperser
   optixstuff.disperser.LensletDisperser


Functions
---------

.. autoapisummary::

   optixstuff.disperser._polyval_deriv


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

.. py:class:: AbstractDisperser

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


   Interface for a dispersing IFS element (lenslet array, slicer, MSA).

   Only the scalar/ETC face is defined here. Render geometry lives in
   coronachrome and dispatches on the concrete descriptor type.


   .. py:method:: spectral_resolution(wavelength_nm)
      :abstractmethod:


      Resolving power R = lambda / dlambda at the given wavelength.



   .. py:method:: spectral_sampling()
      :abstractmethod:


      Detector pixels per resolution element.



   .. py:method:: n_pix_spread(wavelength_min_nm, wavelength_max_nm)
      :abstractmethod:


      Detector pixels a single spaxel spectrum spans across a band.



   .. py:method:: throughput(wavelength_nm)
      :abstractmethod:


      Disperser optical throughput in [0, 1] at the given wavelength.



.. py:function:: _polyval_deriv(coeffs, x)

   Evaluate the derivative of a descending-order polynomial at x.


.. py:class:: LensletDisperser

   Bases: :py:obj:`AbstractDisperser`


   Lenslet-array IFS disperser (CRISPY heritage).

   Config only. The render geometry (IR build) is performed by coronachrome,
   which reads these fields. Scalar/ETC methods derive from
   ``dispersion_coeffs`` + ``pix_per_reselt`` so the dispersion model is the
   single source of truth.


   .. py:attribute:: pitch_m
      :type:  float


   .. py:attribute:: pixsize_m
      :type:  float


   .. py:attribute:: angle_rad
      :type:  float


   .. py:attribute:: lam_ref_nm
      :type:  float


   .. py:attribute:: pix_per_reselt
      :type:  float


   .. py:attribute:: dispersion_coeffs
      :type:  jax.Array


   .. py:attribute:: psflet_params
      :type:  jax.Array


   .. py:attribute:: grid_kind
      :type:  str


   .. py:attribute:: n_lenslets
      :type:  int


   .. py:attribute:: psflet_kind
      :type:  str


   .. py:attribute:: detector_shape
      :type:  tuple[int, int]


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



   .. py:method:: _dispersion_px(wavelength_nm)

      Spectral-axis detector offset [px] for the wavelength(s).



   .. py:method:: spectral_resolution(wavelength_nm)

      R = (local px per unit log-lambda) / pixels-per-resolution-element.



   .. py:method:: spectral_sampling()

      Detector pixels per resolution element.



   .. py:method:: n_pix_spread(wavelength_min_nm, wavelength_max_nm)

      Spectral trace length [px] across a band, plus a PSFlet-width margin.



   .. py:method:: throughput(wavelength_nm)

      Constant throughput in v1.