optixstuff

optixstuff#

optixstuff – Hardware abstractions for the HWO simulation suite.

Submodules#

Classes#

`AbstractCoronagraph`	Abstract interface for coronagraph performance models.
`AbstractScalarCoronagraph`	Base for ETC-only coronagraph models that lack 2D PSF generation.
`AbstractDetector`	Abstract interface for a focal-plane detector.
`Detector`	Full detector model with dark current, CIC, and read noise.
`IdealDetector`	Detector with constant QE and minimal noise sources.
`AbstractDisperser`	Interface for a dispersing IFS element (lenslet array, slicer, MSA).
`LensletDisperser`	Lenslet-array IFS disperser (CRISPY heritage).
`ExposureConfig`	The physical parameters defining a single detector integration.
`AbstractOpticalElement`	Abstract interface for an optical element in the beam path.
`AbstractUniformElement`	Base for elements with spatially uniform throughput.
`ConstantThroughput`	An optical element with wavelength-independent throughput.
`SpectralThroughput`	Wavelength-dependent throughput defined by sampled (wavelength, throughput) pairs.
`OpticalPath`	Universal hardware container for a coronagraphic telescope.
`AbstractPrimary`	Abstract interface for a primary aperture.
`SimplePrimary`	A simple circular primary mirror with a central obscuration.
`YippyCoronagraph`	Coronagraph performance model backed by a yippy YIP interpolation table.

Functions#

`clock_induced_charge`(...)	Draw clock-induced charge electrons from a Poisson distribution.
`dark_current`(dark_current_rate_e_per_s, ...)	Draw dark current electrons from a Poisson distribution.
`read_noise`(read_noise_e, num_frames, shape, prng_key)	Draw read noise from a Gaussian distribution.

Package Contents#

class optixstuff.AbstractCoronagraph[source]#

Bases: 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.

pixel_scale_lod: equinox.AbstractVar[float]#: Native pixel scale in lambda/D per pixel.

IWA: equinox.AbstractVar[float]#: Inner working angle in lambda/D.

OWA: equinox.AbstractVar[float]#: Outer working angle in lambda/D.

abstractmethod throughput(separation_lod, wavelength_nm, *, time_s=0.0)[source]#

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].

Parameters:

separation_lod (jax.typing.ArrayLike)
wavelength_nm (jax.typing.ArrayLike)
time_s (jax.typing.ArrayLike)

Return type:

jax.typing.ArrayLike

abstractmethod core_area(separation_lod, wavelength_nm, *, time_s=0.0)[source]#

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.

Parameters:

separation_lod (jax.typing.ArrayLike)
wavelength_nm (jax.typing.ArrayLike)
time_s (jax.typing.ArrayLike)

Return type:

jax.typing.ArrayLike

abstractmethod core_mean_intensity(separation_lod, wavelength_nm, *, time_s=0.0)[source]#

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.

Parameters:

separation_lod (jax.typing.ArrayLike)
wavelength_nm (jax.typing.ArrayLike)
time_s (jax.typing.ArrayLike)

Return type:

jax.typing.ArrayLike

abstractmethod occulter_transmission(separation_lod, wavelength_nm, *, time_s=0.0)[source]#

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].

Parameters:

separation_lod (jax.typing.ArrayLike)
wavelength_nm (jax.typing.ArrayLike)
time_s (jax.typing.ArrayLike)

Return type:

jax.typing.ArrayLike

abstractmethod on_axis_psf(wavelength_nm, pixel_scale_rad, npixels)[source]#

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).

Parameters:

wavelength_nm (jax.typing.ArrayLike)
pixel_scale_rad (float)
npixels (int)

Return type:

jaxtyping.Array

abstractmethod off_axis_psf(wavelength_nm, separation_lod, pixel_scale_rad, npixels)[source]#

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).

Parameters:

wavelength_nm (jax.typing.ArrayLike)
separation_lod (jax.typing.ArrayLike)
pixel_scale_rad (float)
npixels (int)

Return type:

jaxtyping.Array

class optixstuff.AbstractScalarCoronagraph[source]#

Bases: 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.

on_axis_psf(wavelength_nm, pixel_scale_rad, npixels)[source]#

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

Parameters:

wavelength_nm (jax.typing.ArrayLike)
pixel_scale_rad (float)
npixels (int)

Return type:

jaxtyping.Array

off_axis_psf(wavelength_nm, separation_lod, pixel_scale_rad, npixels)[source]#

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

Parameters:

wavelength_nm (jax.typing.ArrayLike)
separation_lod (jax.typing.ArrayLike)
pixel_scale_rad (float)
npixels (int)

Return type:

jaxtyping.Array

class optixstuff.AbstractDetector[source]#

Bases: equinox.Module

Abstract interface for a focal-plane detector.

Provides both scalar noise rates (for ETC use) and stochastic noise realization (for image simulation). All concrete implementations must define the hardware parameters listed as AbstractVar fields.

pixel_scale_arcsec: equinox.AbstractVar[float]#: Detector plate scale in arcsec/pixel.

quantum_efficiency: equinox.AbstractVar[float]#: Baseline quantum efficiency as a fraction in [0, 1].

dark_current_rate_e_per_s: equinox.AbstractVar[float]#: Dark current rate in electrons/pixel/second.

read_noise_e: equinox.AbstractVar[float]#: Read noise in electrons RMS per pixel per read.

clock_induced_charge_rate_e_per_frame: equinox.AbstractVar[float]#: Clock-induced charge in electrons/pixel/frame.

frame_time_s: equinox.AbstractVar[float]#: Integration time per frame/read in seconds.

read_time_s: equinox.AbstractVar[float]#: Time per read cycle in seconds (for RN^2/t_read in ETC).

dqe: equinox.AbstractVar[float]#: QE degradation factor (multiplicative correction over mission life).

shape: equinox.AbstractVar[tuple[int, int]]#: Detector dimensions (ny, nx) in pixels.

abstractmethod get_qe(wavelength_nm)[source]#

Quantum efficiency at a given wavelength.

Args:: wavelength_nm: Wavelength in nanometres.
Returns:: QE as a fraction in [0, 1].

Parameters:: wavelength_nm (jax.typing.ArrayLike)
Return type:: jax.typing.ArrayLike

abstractmethod scalar_noise_rate(n_pix, t_photon)[source]#

Total scalar noise variance rate for the ETC.

Returns the combined noise variance per unit time (electrons^2/s) for a photometric aperture of n_pix pixels.

Args:: n_pix: Number of pixels in the photometric aperture. t_photon: Photon counting integration time in seconds.
Returns:: Noise variance rate in electrons^2/second.

Parameters:

n_pix (jax.typing.ArrayLike)
t_photon (jax.typing.ArrayLike)

Return type:

jax.typing.ArrayLike

abstractmethod readout(image_rate, exposure_time_s, prng_key)[source]#

Apply stochastic noise realization to a photon rate image.

Converts photon rates to detected electrons including QE, dark current, CIC, and read noise.

Args:: image_rate: Incident photon rate array in ph/s/pixel. exposure_time_s: ExposureConfig time in seconds. prng_key: JAX PRNG key (required, no default).
Returns:: Detected electrons array, same shape as image_rate.

Parameters:

image_rate (jaxtyping.Array)
exposure_time_s (jax.typing.ArrayLike)
prng_key (jaxtyping.Array)

Return type:

jaxtyping.Array

readout_source_electrons(image_rate, exposure_time_s, prng_key)[source]#

Poisson-sample incident photons and convert to electrons via QE.

This is the source-dependent half of detector readout: photon arrival statistics and quantum-efficiency selection. Dark current, CIC, and read noise are handled separately by readout_noise_electrons() so that multi-source exposures do not double-count the source-independent noise floor.

Args:: image_rate: Incident photon rate array in ph/s/pixel. exposure_time_s: ExposureConfig time in seconds. prng_key: JAX PRNG key.
Returns:: Photo-electron counts, same shape as image_rate.

Parameters:

image_rate (jaxtyping.Array)
exposure_time_s (jax.typing.ArrayLike)
prng_key (jaxtyping.Array)

Return type:

jaxtyping.Array

readout_source_electrons_thinned(image_rate, exposure_time_s, prng_key)[source]#

Fast equivalent of readout_source_electrons() via Poisson thinning.

Distributionally identical to the explicit Poisson-then-Binomial chain (Poisson thinning theorem: Binomial(Poisson(L), p) ~ Poisson(L * p)), but ~3x faster because it skips the Binomial draw and never materialises the intermediate photon count. Use in performance-critical paths (animation rendering, yield runs) when the photon count is not needed downstream.

The marginal distribution of returned electrons is identical to readout_source_electrons(). The two methods produce different specific realisations even with the same key.

Args:: image_rate: Incident photon rate array in ph/s/pixel. exposure_time_s: ExposureConfig time in seconds. prng_key: JAX PRNG key.
Returns:: Photo-electron counts, same shape as image_rate.

Parameters:

image_rate (jaxtyping.Array)
exposure_time_s (jax.typing.ArrayLike)
prng_key (jaxtyping.Array)

Return type:

jaxtyping.Array

noise_variance(image_rate, exposure_time_s)[source]#

Deterministic per-pixel total noise variance in electrons^2.

The expected variance at each pixel for an incident photon-rate image – the deterministic companion to readout(). Combines source shot noise (Poisson on detected electrons) with the source-independent floor (dark current, clock-induced charge, read noise):

N = QE * rate * t
    + dark_rate * t
    + CIC_rate * n_frames
    + read_noise^2 * n_frames

with n_frames = ceil(t / frame_time_s). Use 1 / noise_variance(...) as inverse-variance weights for least-squares spectral extraction or its GLS covariance, where the shot term carries the wavelength dependence.

Args:: image_rate: Incident photon rate [ph/s/pixel], any shape. exposure_time_s: Exposure time in seconds.
Returns:: Per-pixel noise variance [electrons^2], same shape as image_rate.

Parameters:

image_rate (jaxtyping.Array)
exposure_time_s (jax.typing.ArrayLike)

Return type:

jaxtyping.Array

abstractmethod readout_noise_electrons(exposure_time_s, prng_key)[source]#

Source-independent detector noise (dark + CIC + read).

Each call draws a fresh noise realization of shape self.shape; consumers add exactly one such draw per exposure regardless of how many sources were co-added via readout_source_electrons().

Args:: exposure_time_s: ExposureConfig time in seconds. prng_key: JAX PRNG key.
Returns:: Noise-electron array of shape self.shape.

Parameters:

exposure_time_s (jax.typing.ArrayLike)
prng_key (jaxtyping.Array)

Return type:

jaxtyping.Array

class optixstuff.Detector(pixel_scale_arcsec, shape, quantum_efficiency=1.0, dark_current_rate_e_per_s=0.0, read_noise_e=0.0, clock_induced_charge_rate_e_per_frame=0.0, frame_time_s=1.0, read_time_s=0.05, dqe=0.0)[source]#

Bases: AbstractDetector

Full detector model with dark current, CIC, and read noise.

Suitable for detailed noise simulations where all detector noise sources matter. Uses Poisson statistics for dark/CIC and Gaussian for read noise, matching the coronagraphoto convention.

Warning: num_frames = jnp.ceil(exposure_time_s / frame_time_s) is kept as a float. Never cast it to int inside JIT – that triggers a ConcretizationTypeError when exposure_time_s is traced.

Parameters:

pixel_scale_arcsec (float)
shape (tuple[int, int])
quantum_efficiency (float)
dark_current_rate_e_per_s (float)
read_noise_e (float)
clock_induced_charge_rate_e_per_frame (float)
frame_time_s (float)
read_time_s (float)
dqe (float)

pixel_scale_arcsec: float#: Detector plate scale in arcsec/pixel.

quantum_efficiency: float#: Baseline quantum efficiency as a fraction in [0, 1].

dark_current_rate_e_per_s: float#: Dark current rate in electrons/pixel/second.

read_noise_e: float#: Read noise in electrons RMS per pixel per read.

clock_induced_charge_rate_e_per_frame: float#: Clock-induced charge in electrons/pixel/frame.

frame_time_s: float#: Integration time per frame/read in seconds.

read_time_s: float#: Time per read cycle in seconds (for RN^2/t_read in ETC).

dqe: float#: QE degradation factor (multiplicative correction over mission life).

shape: tuple[int, int]#: Detector dimensions (ny, nx) in pixels.

get_qe(wavelength_nm)[source]#

Return constant QE, ignoring wavelength.

Parameters:: wavelength_nm (jax.typing.ArrayLike)
Return type:: jax.typing.ArrayLike

scalar_noise_rate(n_pix, t_photon)[source]#

Combined dark + CIC noise variance rate.

Parameters:

n_pix (jax.typing.ArrayLike)
t_photon (jax.typing.ArrayLike)

Return type:

jax.typing.ArrayLike

readout_noise_electrons(exposure_time_s, prng_key)[source]#

Dark current + CIC + read noise (source-independent).

Parameters:

exposure_time_s (jax.typing.ArrayLike)
prng_key (jaxtyping.Array)

Return type:

jaxtyping.Array

readout(image_rate, exposure_time_s, prng_key)[source]#

Full detector readout: source electrons + all noise sources.

Parameters:

image_rate (jaxtyping.Array)
exposure_time_s (jax.typing.ArrayLike)
prng_key (jaxtyping.Array)

Return type:

jaxtyping.Array

__repr__()[source]#

One-line summary of shape, plate scale, QE, and noise sources.

Return type:: str

class optixstuff.IdealDetector(pixel_scale_arcsec, shape, quantum_efficiency=1.0, dark_current_rate_e_per_s=0.0, read_noise_e=0.0, clock_induced_charge_rate_e_per_frame=0.0, frame_time_s=1.0, read_time_s=0.05, dqe=0.0)[source]#

Bases: AbstractDetector

Detector with constant QE and minimal noise sources.

Suitable for broadband imager studies where wavelength-dependent QE variation is not important and CIC/read noise are negligible.

Parameters:

pixel_scale_arcsec (float)
shape (tuple[int, int])
quantum_efficiency (float)
dark_current_rate_e_per_s (float)
read_noise_e (float)
clock_induced_charge_rate_e_per_frame (float)
frame_time_s (float)
read_time_s (float)
dqe (float)

pixel_scale_arcsec: float#: Detector plate scale in arcsec/pixel.

quantum_efficiency: float#: Baseline quantum efficiency as a fraction in [0, 1].

dark_current_rate_e_per_s: float#: Dark current rate in electrons/pixel/second.

read_noise_e: float#: Read noise in electrons RMS per pixel per read.

clock_induced_charge_rate_e_per_frame: float#: Clock-induced charge in electrons/pixel/frame.

frame_time_s: float#: Integration time per frame/read in seconds.

read_time_s: float#: Time per read cycle in seconds (for RN^2/t_read in ETC).

dqe: float#: QE degradation factor (multiplicative correction over mission life).

shape: tuple[int, int]#: Detector dimensions (ny, nx) in pixels.

get_qe(wavelength_nm)[source]#

Return constant QE, ignoring wavelength.

Parameters:: wavelength_nm (jax.typing.ArrayLike)
Return type:: jax.typing.ArrayLike

scalar_noise_rate(n_pix, t_photon)[source]#

Combined dark + CIC noise variance rate.

Read noise is not included here as it scales per-read, not per-second. Callers add (read_noise_e^2 * n_reads) / t_exp separately.

Parameters:

n_pix (jax.typing.ArrayLike)
t_photon (jax.typing.ArrayLike)

Return type:

jax.typing.ArrayLike

readout_noise_electrons(exposure_time_s, prng_key)[source]#

Dark current only – IdealDetector has no CIC or read noise.

Parameters:

exposure_time_s (jax.typing.ArrayLike)
prng_key (jaxtyping.Array)

Return type:

jaxtyping.Array

readout(image_rate, exposure_time_s, prng_key)[source]#

Full detector readout: source electrons + dark current.

Parameters:

image_rate (jaxtyping.Array)
exposure_time_s (jax.typing.ArrayLike)
prng_key (jaxtyping.Array)

Return type:

jaxtyping.Array

__repr__()[source]#

One-line summary of shape, plate scale, QE, and dark current.

Return type:: str

optixstuff.clock_induced_charge(clock_induced_charge_rate_e_per_frame, num_frames, shape, prng_key)[source]#

Draw clock-induced charge electrons from a Poisson distribution.

Args:: clock_induced_charge_rate_e_per_frame: CIC rate in electrons/pixel/frame. num_frames: Number of frames (kept as float for JIT safety). shape: Detector shape (ny, nx). prng_key: PRNG key.
Returns:: CIC electrons, shape (ny, nx).

Parameters:

clock_induced_charge_rate_e_per_frame (float)
num_frames (jax.typing.ArrayLike)
shape (tuple[int, int])
prng_key (jaxtyping.Array)

Return type:

jaxtyping.Array

optixstuff.dark_current(dark_current_rate_e_per_s, exposure_time_s, shape, prng_key)[source]#

Draw dark current electrons from a Poisson distribution.

Args:: dark_current_rate_e_per_s: Dark current rate in electrons/s/pixel. exposure_time_s: ExposureConfig time in seconds. shape: Detector shape (ny, nx). prng_key: PRNG key.
Returns:: Dark current electrons, shape (ny, nx).

Parameters:

dark_current_rate_e_per_s (float)
exposure_time_s (jax.typing.ArrayLike)
shape (tuple[int, int])
prng_key (jaxtyping.Array)

Return type:

jaxtyping.Array

optixstuff.read_noise(read_noise_e, num_frames, shape, prng_key)[source]#

Draw read noise from a Gaussian distribution.

Total read noise sigma = sqrt(num_frames) * read_noise_per_read.

Args:: read_noise_e: Read noise in electrons/pixel/read. num_frames: Number of frames. shape: Detector shape (ny, nx). prng_key: PRNG key.
Returns:: Read noise electrons, shape (ny, nx).

Parameters:

read_noise_e (float)
num_frames (jax.typing.ArrayLike)
shape (tuple[int, int])
prng_key (jaxtyping.Array)

Return type:

jaxtyping.Array

class optixstuff.AbstractDisperser[source]#

Bases: 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.

abstractmethod spectral_resolution(wavelength_nm)[source]#: Resolving power R = lambda / dlambda at the given wavelength.

abstractmethod spectral_sampling()[source]#: Detector pixels per resolution element.

abstractmethod n_pix_spread(wavelength_min_nm, wavelength_max_nm)[source]#: Detector pixels a single spaxel spectrum spans across a band.

abstractmethod throughput(wavelength_nm)[source]#: Disperser optical throughput in [0, 1] at the given wavelength.

class optixstuff.LensletDisperser[source]#

Bases: 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.

pitch_m: float#

pixsize_m: float#

angle_rad: float#

lam_ref_nm: float#

pix_per_reselt: float#

dispersion_coeffs: jax.Array#

psflet_params: jax.Array#

grid_kind: str#

n_lenslets: int#

psflet_kind: str#

detector_shape: tuple[int, int]#

throughput_value: float = 1.0#

_dispersion_px(wavelength_nm)[source]#: Spectral-axis detector offset [px] for the wavelength(s).

spectral_resolution(wavelength_nm)[source]#: R = (local px per unit log-lambda) / pixels-per-resolution-element.

spectral_sampling()[source]#: Detector pixels per resolution element.

n_pix_spread(wavelength_min_nm, wavelength_max_nm)[source]#: Spectral trace length [px] across a band, plus a PSFlet-width margin.

throughput(wavelength_nm)[source]#: Constant throughput in v1.

class optixstuff.ExposureConfig[source]#

Bases: equinox.Module

The physical parameters defining a single detector integration.

All fields can be scalars (for a single event) or vectors (for a sequence), depending on how the factories are composed.

start_time_jd: jax.numpy.ndarray#

exposure_time_s: jax.numpy.ndarray#

central_wavelength_nm: jax.numpy.ndarray#

bin_width_nm: jax.numpy.ndarray#

position_angle_deg: jax.numpy.ndarray#

classmethod in_axes(**vectorized_axes)[source]#

Helper to generate in_axes structure for JAX vmap over an ExposureConfig.

Usage:: # Vectorize over wavelength (axis 0), keep time constant in_axes = ExposureConfig.in_axes(central_wavelength_nm=0, bin_width_nm=0)

class optixstuff.AbstractOpticalElement[source]#

Bases: equinox.Module

Abstract interface for an optical element in the beam path.

Elements reduce photon flux via wavelength-dependent throughput. The ETC calls get_throughput() for scalar efficiency calculations. The simulator calls apply() to attenuate 2D photon arrays.

Both methods are abstract: use AbstractUniformElement for elements with spatially uniform throughput, which provides a default apply().

abstractmethod get_throughput(wavelength_nm)[source]#

Fractional throughput at a given wavelength.

Args:: wavelength_nm: Wavelength in nanometres.
Returns:: Scalar throughput in [0, 1].

Parameters:: wavelength_nm (jax.typing.ArrayLike)
Return type:: jax.typing.ArrayLike

abstractmethod apply(arr, wavelength_nm)[source]#

Apply this element to a 2D photon array.

Args:: arr: Input photon rate array [ph/s/pixel]. wavelength_nm: Wavelength in nanometres.
Returns:: Attenuated photon rate array, same shape as arr.

Parameters:

arr (jaxtyping.Array)
wavelength_nm (jax.typing.ArrayLike)

Return type:

jaxtyping.Array

class optixstuff.AbstractUniformElement[source]#

Bases: AbstractOpticalElement

Base for elements with spatially uniform throughput.

Provides a default apply() that multiplies the array by the scalar throughput. Override apply() for elements with spatially varying transmission (e.g., field-dependent filter transmission maps).

apply(arr, wavelength_nm)[source]#

Apply uniform throughput to a photon array.

Parameters:

arr (jaxtyping.Array)
wavelength_nm (jax.typing.ArrayLike)

Return type:

jaxtyping.Array

class optixstuff.ConstantThroughput[source]#

Bases: AbstractUniformElement

An optical element with wavelength-independent throughput.

Useful for modeling simple attenuators, beamsplitters, or as a placeholder during instrument design studies.

throughput: float#

name: str#

get_throughput(wavelength_nm)[source]#

Return constant throughput, ignoring wavelength.

Parameters:: wavelength_nm (jax.typing.ArrayLike)
Return type:: jax.typing.ArrayLike

__repr__()[source]#

One-line summary of throughput value.

Return type:: str

class optixstuff.SpectralThroughput(wavelengths_nm, throughputs)[source]#

Bases: AbstractUniformElement

Wavelength-dependent throughput defined by sampled (wavelength, throughput) pairs.

Linear interpolation between samples; throughput is zero outside the defined wavelength range.

Represents any tabulated wavelength-dependent throughput in the optical path: bandpass filters, dichroics, mirror reflectivity, coating losses, ADCs, blocking filters, etc.

Parameters:

wavelengths_nm (jaxtyping.Array)
throughputs (jaxtyping.Array)

wavelengths_nm: jaxtyping.Array#

throughputs: jaxtyping.Array#

interp: interpax.Interpolator1D#

get_throughput(wavelength_nm)[source]#

Interpolate throughput at the requested wavelength.

Parameters:: wavelength_nm (jax.typing.ArrayLike)
Return type:: jax.typing.ArrayLike

__repr__()[source]#

One-line summary of throughput-table extent and sample count.

Return type:: str

class optixstuff.OpticalPath[source]#

Bases: 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.

primary: optixstuff.primary.AbstractPrimary#

attenuating_elements: tuple[optixstuff.optical_elements.AbstractOpticalElement, Ellipsis]#

coronagraph: optixstuff.coronagraph.AbstractCoronagraph#

detector: optixstuff.detector.AbstractDetector#

disperser: optixstuff.disperser.AbstractDisperser | None = None#

n_channels: float = 1.0#

npix_multiplier: float = 1.0#

classmethod 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)[source]#

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 AbstractCoronagraph instance (used as-is),
a YIP path (str or pathlib.Path, wrapped with 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 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 OpticalPath.

Parameters:

coronagraph (optixstuff.coronagraph.AbstractCoronagraph | str | pathlib.Path)
diameter_m (float)
obscuration (float)
attenuating_throughput (float)
detector_shape (tuple[int, int])
pixel_scale_arcsec (float)
quantum_efficiency (float)
dark_current_rate_e_per_s (float)
n_channels (float)
npix_multiplier (float)

Return type:

OpticalPath

system_throughput(wavelength_nm)[source]#

Total throughput of all attenuating elements.

Args:: wavelength_nm: Wavelength in nanometres.
Returns:: Combined fractional throughput in [0, 1].

Parameters:: wavelength_nm (float)
Return type:: float

__repr__()[source]#

Tree-shaped summary of every component.

Return type:: str

class optixstuff.AbstractPrimary[source]#

Bases: equinox.Module

Abstract interface for a primary aperture.

Any concrete implementation must provide the diameter and collecting area of the primary mirror as scalar values in SI units. These are consumed by exposure time calculators and simulation tools alike.

diameter_m: equinox.AbstractVar[float]#: Primary mirror diameter in metres.

area_m2: equinox.AbstractVar[float]#: Effective collecting area in square metres.

class optixstuff.SimplePrimary(diameter_m, obscuration=0.0, shape_factor=1.0)[source]#

Bases: AbstractPrimary

A simple circular primary mirror with a central obscuration.

Args:: diameter_m: Primary mirror diameter in metres. obscuration: Linear obscuration fraction (0 = no obscuration). shape_factor: Fraction of unobscured area that is collecting

(accounts for struts, segment gaps, etc.). Default 1.0.

Parameters:

diameter_m (float)
obscuration (float)
shape_factor (float)

_diameter_m: float#

obscuration: float#

shape_factor: float#

property diameter_m: float#

Primary mirror diameter in metres.

Return type:: float

property area_m2: float#

Effective collecting area in square metres.

Return type:: float

__repr__()[source]#

One-line summary of diameter, obscuration, and effective area.

Return type:: str

class optixstuff.YippyCoronagraph(yip_path=None, *, backend=None, **kwargs)[source]#

Bases: optixstuff.coronagraph.AbstractCoronagraph

Coronagraph performance model backed by a yippy YIP interpolation table.

Wraps a yippy EqxCoronagraph via composition, adapting its methods to the AbstractCoronagraph interface. The _backend field is itself an eqx.Module, so its internal JAX arrays flow through filter_jit and filter_grad normally.

Construction mirrors EqxCoronagraph – pass either a YIP path or an existing EqxCoronagraph instance:

coro = YippyCoronagraph("/path/to/yip")
coro = YippyCoronagraph(backend=existing_eqx_coro)

Parameters:

yip_path (str | None)
backend (yippy.EqxCoronagraph | None)

_backend: yippy.EqxCoronagraph#

property pixel_scale_lod: float#

Native pixel scale in lambda/D per pixel.

Return type:: float

property IWA: float#

Inner working angle in lambda/D.

Return type:: float

property OWA: float#

Outer working angle in lambda/D.

Return type:: float

throughput(separation_lod, wavelength_nm, *, time_s=0.0)[source]#

Core throughput from the YIP interpolation table.

Parameters:

separation_lod (jax.typing.ArrayLike)
wavelength_nm (jax.typing.ArrayLike)
time_s (jax.typing.ArrayLike)

Return type:

jax.typing.ArrayLike

core_area(separation_lod, wavelength_nm, *, time_s=0.0)[source]#

Photometric aperture area from the YIP interpolation table.

Parameters:

separation_lod (jax.typing.ArrayLike)
wavelength_nm (jax.typing.ArrayLike)
time_s (jax.typing.ArrayLike)

Return type:

jax.typing.ArrayLike

core_mean_intensity(separation_lod, wavelength_nm, *, time_s=0.0)[source]#

Mean stellar leakage from the YIP interpolation table.

Parameters:

separation_lod (jax.typing.ArrayLike)
wavelength_nm (jax.typing.ArrayLike)
time_s (jax.typing.ArrayLike)

Return type:

jax.typing.ArrayLike

occulter_transmission(separation_lod, wavelength_nm, *, time_s=0.0)[source]#

Sky transmission from the YIP interpolation table.

Parameters:

separation_lod (jax.typing.ArrayLike)
wavelength_nm (jax.typing.ArrayLike)
time_s (jax.typing.ArrayLike)

Return type:

jax.typing.ArrayLike

on_axis_psf(wavelength_nm, pixel_scale_rad, npixels)[source]#

Stellar leakage PSF from the YIP stellar intensity model.

Parameters:

wavelength_nm (jax.typing.ArrayLike)
pixel_scale_rad (float)
npixels (int)

Return type:

jaxtyping.Array

off_axis_psf(wavelength_nm, separation_lod, pixel_scale_rad, npixels)[source]#

Off-axis planet PSF from the YIP PSF interpolator.

Places the planet along the +x axis by convention.

Parameters:

wavelength_nm (jax.typing.ArrayLike)
separation_lod (jax.typing.ArrayLike)
pixel_scale_rad (float)
npixels (int)

Return type:

jaxtyping.Array

noise_floor_ayo(separation_lod, ppf=30.0)[source]#

AYO noise floor: core_mean_intensity / ppf.

This is a convenience passthrough to the backend. Not part of the AbstractCoronagraph contract – downstream ETCs should compute noise floors as pure functions.

Parameters:

separation_lod (jax.typing.ArrayLike)
ppf (float)

Return type:

jax.typing.ArrayLike

raw_contrast(separation_lod)[source]#

Raw contrast from the YIP interpolation table.

Parameters:: separation_lod (jax.typing.ArrayLike)
Return type:: jax.typing.ArrayLike

stellar_intens(stellar_diam_lod)[source]#

Stellar intensity map for a given stellar angular diameter.

Parameters:: stellar_diam_lod (float)
Return type:: jaxtyping.Array

property psf_shape: tuple[int, int]#

Shape of the PSF arrays from the YIP file.

Return type:: tuple[int, int]

property sky_trans: jaxtyping.Array#

Full sky transmission map.

Return type:: jaxtyping.Array

create_psfs(x_lod, y_lod)[source]#

Batched off-axis PSFs at (x_lod, y_lod) source positions.

Delegates to the backend yippy create_psfs closure. Returns a stack of PSF images, one per input source coordinate.

Args:: x_lod: Source x-coordinates in lambda/D, shape (K,). y_lod: Source y-coordinates in lambda/D, shape (K,).
Returns:: PSF stack of shape (K, ny, nx) where (ny, nx) == self.psf_shape.

Parameters:

x_lod (jax.typing.ArrayLike)
y_lod (jax.typing.ArrayLike)

Return type:

jaxtyping.Array

property psf_datacube: jaxtyping.Array | None#

Pre-computed quarter-symmetric PSF datacube from the backend.

Returns None if the backing EqxCoronagraph was not built with ensure_psf_datacube=True. Consumers that need this for disk convolution should construct the backend with the flag set.

Return type:: jaxtyping.Array | None

__repr__()[source]#

One-line summary of YIP backend metadata.

Return type:: str