optixstuff.coronagraph

optixstuff.coronagraph#

Coronagraph abstractions.

Classes#

`AbstractCoronagraph`	Abstract interface for coronagraph performance models.
`AbstractTableCoronagraph`	Base for coronagraphs backed by native-grid interpolation tables.
`AbstractScalarCoronagraph`	Base for ETC-only coronagraph models that lack 2D PSF generation.
`MultiBandCoronagraph`	A broadband coronagraph as a stack of per-band models.

Functions#

_convolve_quadrants(flux, psf_datacube)

Convolve flux with a quarter-symmetric PSF datacube via fold-and-sum.

Module Contents#

optixstuff.coronagraph._convolve_quadrants(flux, psf_datacube)[source]#

Convolve flux with a quarter-symmetric PSF datacube via fold-and-sum.

Handles padding dynamically to ensure all quadrants match the shape of the first quadrant (which defines the PSF datacube shape).

class optixstuff.coronagraph.AbstractCoronagraph[source]#

Bases: equinox.Module

Abstract interface for coronagraph performance models.

Provides scalar performance curves (for ETC use), single-PSF generation, and a sampling-explicit image contract (for image simulation): stellar_map / source_psfs / background_transmission / extended_scene serve maps at the caller’s requested pixel scale and shape, so backend-internal grids never leak downstream. Implementations can be backed by pre-computed interpolation tables (subclass AbstractTableCoronagraph, which serves the image contract from native-grid tables), physical wavefront propagation, or analytical models.

All wavelength arguments are in nanometres throughout. All separations and pixel scales are in lambda/D units – the contract is dimensionless optics; angle conversions are the telescope primary’s business.

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. For a finite stellar diameter use stellar_map(), which carries the diameter axis this signature lacks.

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

abstractmethod stellar_map(wavelength_nm, stellar_diam_lod, *, pixel_scale_lod, shape)[source]#

On-axis stellar leakage map at the requested sampling.

Args:: wavelength_nm: Wavelength in nanometres. stellar_diam_lod: Stellar angular diameter in lambda/D. pixel_scale_lod: Target pixel scale in lambda/D per pixel. shape: Target array shape (ny, nx).
Returns:: Map of shape shape in fraction of pre-coronagraph stellar photons per target pixel.

Parameters:

wavelength_nm (jax.typing.ArrayLike)
stellar_diam_lod (jax.typing.ArrayLike)
pixel_scale_lod (jax.typing.ArrayLike)
shape (tuple[int, int])

Return type:

jaxtyping.Array

abstractmethod source_psfs(wavelength_nm, x_lod, y_lod, *, pixel_scale_lod, shape)[source]#

Off-axis point-source PSFs at the requested sampling.

Args:: wavelength_nm: Wavelength in nanometres. x_lod: Source x-coordinates in lambda/D, shape (K,). y_lod: Source y-coordinates in lambda/D, shape (K,). pixel_scale_lod: Target pixel scale in lambda/D per pixel. shape: Target array shape (ny, nx).
Returns:: Stack of shape (K, ny, nx) in fraction of source photons per target pixel.

Parameters:

wavelength_nm (jax.typing.ArrayLike)
x_lod (jax.typing.ArrayLike)
y_lod (jax.typing.ArrayLike)
pixel_scale_lod (jax.typing.ArrayLike)
shape (tuple[int, int])

Return type:

jaxtyping.Array

abstractmethod background_transmission(wavelength_nm, *, pixel_scale_lod, shape)[source]#

Per-pixel transmission map for a spatially uniform background.

Args:: wavelength_nm: Wavelength in nanometres. pixel_scale_lod: Target pixel scale in lambda/D per pixel. shape: Target array shape (ny, nx).
Returns:: Dimensionless transmission map of shape shape (value semantics, not a flux).

Parameters:

wavelength_nm (jax.typing.ArrayLike)
pixel_scale_lod (jax.typing.ArrayLike)
shape (tuple[int, int])

Return type:

jaxtyping.Array

abstractmethod extended_scene(scene_map, map_pixel_scale_lod, wavelength_nm, *, pixel_scale_lod, shape, rotation_deg=0.0)[source]#

Render an extended incoherent scene through the coronagraph.

Args:

scene_map: Per-pixel source intensity in any units; the: output carries the same units per target pixel.
map_pixel_scale_lod: Pixel scale of scene_map in: lambda/D per pixel.

wavelength_nm: Wavelength in nanometres. pixel_scale_lod: Target pixel scale in lambda/D per pixel. shape: Target array shape (ny, nx). rotation_deg: CCW rotation applied when mapping the scene

into the coronagraph frame (sky-to-detector roll).

Returns:

The scene redistributed by the per-position off-axis PSFs, shape shape.

Parameters:

scene_map (jaxtyping.Array)
map_pixel_scale_lod (jax.typing.ArrayLike)
wavelength_nm (jax.typing.ArrayLike)
pixel_scale_lod (jax.typing.ArrayLike)
shape (tuple[int, int])
rotation_deg (jax.typing.ArrayLike)

Return type:

jaxtyping.Array

class optixstuff.coronagraph.AbstractTableCoronagraph[source]#

Bases: AbstractCoronagraph

Base for coronagraphs backed by native-grid interpolation tables.

Declares the table SPI – the native-grid maps a table backend holds (stellar_intens, create_psfs, sky_trans, psf_shape, psf_datacube) – and serves the sampling-explicit image contract from it with flux-conserving resamples to the requested target grid. Scalar performance curves remain the subclass’s business (a table backend interpolates its own curve tables).

The tables are monochromatic by construction (a YIP is a per-band file), so the served maps ignore wavelength_nm beyond the caller’s own lambda/D sampling conversion; stack per-band instances in a MultiBandCoronagraph for a broadband model.

psf_shape: equinox.AbstractVar[tuple]#: Native map shape (ny, nx) shared by the table members.

sky_trans: equinox.AbstractVar[jaxtyping.Array]#: Native-grid transmission map for a spatially uniform background.

psf_datacube: equinox.AbstractVar[jaxtyping.Array | None]#

Optional per-source-position PSF library for extended scenes.

None means the table was built without one; extended_scene() then raises. Full (ny, nx, ny, nx) and quarter-symmetric (ny//2+1, nx//2+1, ny, nx) layouts are supported.

abstractmethod stellar_intens(stellar_diam_lod)[source]#

Native-grid stellar leakage map for a stellar angular diameter.

The diameter axis is a genuine table capability (a YIP tabulates finite-size stellar maps); implementations interpolate over it.

Parameters:: stellar_diam_lod (jax.typing.ArrayLike)
Return type:: jaxtyping.Array

abstractmethod create_psfs(x_lod, y_lod)[source]#

Native-grid off-axis PSF stack at (x_lod, y_lod), shape (K, ny, nx).

Parameters:

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

Return type:

jaxtyping.Array

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

Point-source stellar leakage map on the native grid.

Table backends serve their native sampling; the requested pixel_scale_rad / npixels are accepted for interface conformance only. Use stellar_map() for target-sampled maps and finite stellar diameters.

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 PSF at +x separation on the native grid.

Sampling arguments are accepted for interface conformance only; use source_psfs() for target-sampled maps.

Parameters:

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

Return type:

jaxtyping.Array

stellar_map(wavelength_nm, stellar_diam_lod, *, pixel_scale_lod, shape)[source]#

Native stellar_intens resampled (flux-conserving) to target.

Parameters:

wavelength_nm (jax.typing.ArrayLike)
stellar_diam_lod (jax.typing.ArrayLike)
pixel_scale_lod (jax.typing.ArrayLike)
shape (tuple[int, int])

Return type:

jaxtyping.Array

source_psfs(wavelength_nm, x_lod, y_lod, *, pixel_scale_lod, shape)[source]#

Native create_psfs stack resampled (flux-conserving) to target.

Parameters:

wavelength_nm (jax.typing.ArrayLike)
x_lod (jax.typing.ArrayLike)
y_lod (jax.typing.ArrayLike)
pixel_scale_lod (jax.typing.ArrayLike)
shape (tuple[int, int])

Return type:

jaxtyping.Array

background_transmission(wavelength_nm, *, pixel_scale_lod, shape)[source]#

Native sky_trans resampled to target with value semantics.

A transmission is a per-pixel value, not a flux, so the pixel-area scaling of the flux-conserving resample is undone.

Parameters:

wavelength_nm (jax.typing.ArrayLike)
pixel_scale_lod (jax.typing.ArrayLike)
shape (tuple[int, int])

Return type:

jaxtyping.Array

extended_scene(scene_map, map_pixel_scale_lod, wavelength_nm, *, pixel_scale_lod, shape, rotation_deg=0.0)[source]#

Scene convolved with the psf_datacube PSF library.

Resamples the scene to the native source grid (applying the sky-to-detector rotation), convolves via the full or quarter-symmetric datacube, and resamples the result to the target grid.

Raises:

ValueError: if psf_datacube is None, or its: source grid matches neither the full nor the quarter PSF shape.

Parameters:

scene_map (jaxtyping.Array)
map_pixel_scale_lod (jax.typing.ArrayLike)
wavelength_nm (jax.typing.ArrayLike)
pixel_scale_lod (jax.typing.ArrayLike)
shape (tuple[int, int])
rotation_deg (jax.typing.ArrayLike)

Return type:

jaxtyping.Array

class optixstuff.coronagraph.AbstractScalarCoronagraph[source]#

Bases: AbstractCoronagraph

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

Stubs out the single-PSF interface and the sampling-explicit image contract with zero arrays so the class satisfies AbstractCoronagraph without requiring a full optical model. Do NOT use this base for a model that carries native-grid tables – subclass AbstractTableCoronagraph instead, or the image pipeline will silently render zeros.

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

stellar_map(wavelength_nm, stellar_diam_lod, *, pixel_scale_lod, shape)[source]#

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

Parameters:

wavelength_nm (jax.typing.ArrayLike)
stellar_diam_lod (jax.typing.ArrayLike)
pixel_scale_lod (jax.typing.ArrayLike)
shape (tuple[int, int])

Return type:

jaxtyping.Array

source_psfs(wavelength_nm, x_lod, y_lod, *, pixel_scale_lod, shape)[source]#

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

Parameters:

wavelength_nm (jax.typing.ArrayLike)
x_lod (jax.typing.ArrayLike)
y_lod (jax.typing.ArrayLike)
pixel_scale_lod (jax.typing.ArrayLike)
shape (tuple[int, int])

Return type:

jaxtyping.Array

background_transmission(wavelength_nm, *, pixel_scale_lod, shape)[source]#

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

Parameters:

wavelength_nm (jax.typing.ArrayLike)
pixel_scale_lod (jax.typing.ArrayLike)
shape (tuple[int, int])

Return type:

jaxtyping.Array

extended_scene(scene_map, map_pixel_scale_lod, wavelength_nm, *, pixel_scale_lod, shape, rotation_deg=0.0)[source]#

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

Parameters:

scene_map (jaxtyping.Array)
map_pixel_scale_lod (jax.typing.ArrayLike)
wavelength_nm (jax.typing.ArrayLike)
pixel_scale_lod (jax.typing.ArrayLike)
shape (tuple[int, int])
rotation_deg (jax.typing.ArrayLike)

Return type:

jaxtyping.Array

class optixstuff.coronagraph.MultiBandCoronagraph(band_centers_nm, bands, *, reference_wavelength_nm=None)[source]#

Bases: AbstractCoronagraph

A broadband coronagraph as a stack of per-band models.

Every contract call dispatches to the band whose declared center is nearest the requested wavelength_nm and forwards the call unchanged. Because the contract is sampling-explicit in lambda/D, chromatic magnification needs no handling here: the caller already converts its detector grid to lambda/D at each wavelength.

The per-band models can be anything implementing AbstractCoronagraph – per-band YIP tables (optixstuff.YippyCoronagraph) or per-wavelength compiled views of a live propagation model – and can be mixed.

wavelength_nm must be concrete (a Python/NumPy scalar, not a traced JAX value) at dispatch time: bands are distinct pytrees with distinct shapes, so the selection is Python control flow. This matches the per-bin structure of the rate pipeline, where the wavelength is a static observation parameter.

Scalar metadata (pixel_scale_lod / IWA / OWA) is served from the band nearest reference_wavelength_nm (default: the first band).

band_centers_nm: tuple#

bands: tuple#

reference_wavelength_nm: float#

band(wavelength_nm)[source]#

The band model whose center is nearest wavelength_nm.

Return type:: AbstractCoronagraph

property pixel_scale_lod: float#

Native pixel scale of the reference band.

Return type:: float

property IWA: float#

Inner working angle of the reference band.

Return type:: float

property OWA: float#

Outer working angle of the reference band.

Return type:: float

throughput(separation_lod, wavelength_nm, *, time_s=0.0)[source]#: Core throughput from the nearest band.

core_area(separation_lod, wavelength_nm, *, time_s=0.0)[source]#: Photometric aperture area from the nearest band.

core_mean_intensity(separation_lod, wavelength_nm, *, time_s=0.0)[source]#: Mean stellar leakage from the nearest band.

occulter_transmission(separation_lod, wavelength_nm, *, time_s=0.0)[source]#: Sky transmission from the nearest band.

on_axis_psf(wavelength_nm, pixel_scale_rad, npixels)[source]#: On-axis PSF from the nearest band.

off_axis_psf(wavelength_nm, separation_lod, pixel_scale_rad, npixels)[source]#: Off-axis PSF from the nearest band.

stellar_map(wavelength_nm, stellar_diam_lod, *, pixel_scale_lod, shape)[source]#: Stellar leakage map from the nearest band.

source_psfs(wavelength_nm, x_lod, y_lod, *, pixel_scale_lod, shape)[source]#: Off-axis PSF stack from the nearest band.

background_transmission(wavelength_nm, *, pixel_scale_lod, shape)[source]#: Background transmission map from the nearest band.

extended_scene(scene_map, map_pixel_scale_lod, wavelength_nm, *, pixel_scale_lod, shape, rotation_deg=0.0)[source]#: Extended-scene render from the nearest band.