Skip to content

API reference

makewfs.WavefrontSensor

Configured wavefront-sensor facade.

Construct once and call :meth:expose for each closed-loop residual OPD. photon_rate exposes the deterministic optical result for workflows that use another detector or need an ideal reference image.

wavelengths_m property

wavelengths_m

Wavelength nodes of the source quadrature, in metres.

The order is that of the spectral photon-rate cube and of a per-wavelength amplitude stack: an amplitude of shape (len(wavelengths_m), *input.shape) gives map k to wavelengths_m[k].

charge_diffusion_fwhm_px property

charge_diffusion_fwhm_px

Return the resolved sensor's lateral charge-diffusion FWHM in pixels.

Charge diffusion is detector physics owned by getframes; this only reports the resolved value, so a consumer recording provenance does not have to restate a detector measurement of its own.

from_toml classmethod

from_toml(path)

Build a sensor from a validated TOML file.

lenslet_grid_offsets_fraction

lenslet_grid_offsets_fraction()

Return the effective [x, y] lenslet-grid offset of each offset state.

Shack--Hartmann only. Offsets are in lenslet pitches: each entry of shack_hartmann.lenslet_grid_offset_states_fraction added to the static lenslet_grid_offset_fraction, or the static offset alone when no states are declared. The position in this tuple is the offset_state index that :meth:photon_rate, :meth:expose and the other render methods accept.

photon_rate

photon_rate(wavefront, *, amplitude=None, offset_state=0)

Return the ideal native-pixel photon rate before detector noise.

offset_state selects one of the configured Shack--Hartmann lenslet-grid offset states (see :meth:lenslet_grid_offsets_fraction); it must be 0 for a sensor with one state and for a pyramid.

amplitude is an optional per-frame pupil-plane field amplitude |U| / |U_0| (dimensionless, non-negative), relative to the unscintillated field the source normalization describes. It multiplies the configured pupil amplitude, so the pupil intensity, and with it the photon rate, scales with its square; the wavefront still carries the phase. Pass an input.shape map for every wavelength, or a (len(wavelengths_m), *input.shape) stack with one map per wavelength node. None (the default) and an amplitude of exactly one give the OPD-only result. See docs/scintillation.md.

subaperture_flux

subaperture_flux(wavefront, *, amplitude=None, offset_state=0)

Return the ideal per-subaperture photon rates of one wavefront.

Shack--Hartmann only. One render gives the ideal image and, for each lenslet, the photon rate its pixel block collects and the photon rate entering its aperture in the pupil plane (see :class:SubapertureFlux). Under scintillation (amplitude, as in :meth:photon_rate) these fluxes measure the pupil intensity. They are noise-free; a measured flux comes from summing the same pixel blocks of an exposed frame.

reference

reference(*, offset_state=0)

Return the ideal image for a zero dynamic OPD in one offset state.

valid_subapertures

valid_subapertures(*, offset_state=0)

Return the configured static Shack--Hartmann lenslet-valid mask.

The mask is derived from pupil illumination and the configured minimum illuminated fraction, not from a detector frame. It is therefore safe to freeze into a calibration artifact and use for active-slope vector ordering. Each lenslet-grid offset state has its own map, selected by offset_state. Pyramid sensors do not have lenslet subapertures.

subaperture_plate_scale_arcsec

subaperture_plate_scale_arcsec()

Return the on-sky angle one detector pixel subtends per subaperture.

Shack--Hartmann only. Derived from the configured spot sampling and the subaperture's own size on sky, so it stays consistent with the geometry that actually forms the spots rather than restating it.

subaperture_field_of_view_arcsec

subaperture_field_of_view_arcsec()

Return the on-sky field of view one subaperture's window spans.

By default a Shack--Hartmann's detector window is itself a field stop. Each subaperture's spot is formed and integrated only over its own pixels_per_subaperture block, and the blocks are tiled without overlap, so light beyond this field is neither recorded nor allowed to contaminate a neighbour. An instrument whose physical field stop matches its pixel field is therefore already represented. One without such a stop spills light between subapertures: set shack_hartmann.crosstalk_reach_subapertures to model that. Reporting the value makes the assumption checkable instead of leaving it implied by the pixel count.

pupil_illumination

pupil_illumination(shape=None)

Return the configured pupil illumination on a requested grid.

Consumers that own actuator or wavefront models need the illumination on the same grid their own arrays use, and pupil formation belongs here, so this evaluates the configured telescope pupil on shape (default config.input.shape) rather than the sensor's internal propagation grid. A configured custom_mask_path is not resampled: it must already match the requested shape, so supply the mask at that sampling instead of letting a mask be silently interpolated.

expose

expose(wavefront, *, amplitude=None, seed=None, out=None, offset_state=0)

Render one wavefront into optional caller-owned detector storage.

Besides provenance and timings, the frame metadata records the input wavefront's wfs_input_opd_rms_m, its RMS in OPD metres weighted by the pupil intensity with piston removed (aocore CONVENTIONS 4.1), and wfs_input_opd_rms_unweighted_m, its RMS over the whole input grid with piston kept. Both use the configured pupil, not the per-frame amplitude.

amplitude is the optional per-frame pupil amplitude of :meth:photon_rate; frames record whether one was given as wfs_input_amplitude.

offset_state selects a configured Shack--Hartmann lenslet-grid offset state (shack_hartmann.lenslet_grid_offset_states_fraction); a Shack--Hartmann frame records it as wfs_lenslet_offset_state and the effective offset as wfs_lenslet_grid_offset_fraction.

expose_many

expose_many(phases, seeds=None, *, offset_states=None, amplitudes=None)

Yield one detector frame per phase sample without stacking the stream.

offset_states optionally gives the lenslet-grid offset state of each frame, for example itertools.cycle(range(n)) for a dithered Shack--Hartmann; the default renders every frame in state 0. amplitudes optionally gives each frame's pupil amplitude (see :meth:photon_rate), consumed in step with phases.

expose_integrated

expose_integrated(phase_samples, *, amplitude=None, seed=None, out=None, offset_state=0)

Expose temporally averaged OPD into optional caller-owned detector storage.

Every sample uses the same lenslet-grid offset_state (see :meth:expose). amplitude optionally gives one pupil amplitude per temporal sample: a sequence, or an array whose leading axis is the sample axis, each entry an input.shape map or a per-wavelength stack (see :meth:photon_rate).

makewfs.api.SubapertureFlux dataclass

Ideal (noise-free) per-subaperture photon rates of one Shack--Hartmann frame.

Every array is indexed (lenslet_y, lenslet_x) like :meth:WavefrontSensor.valid_subapertures and stays on the sensor's device (a CuPy array on a GPU sensor).

Attributes:

Name Type Description
detector_photons_s Any

Photon rate collected by each subaperture's own pixels_per_subaperture x pixels_per_subaperture pixel block, in photons/s: the block sum of :attr:photon_rate without the detector margin. It excludes light its spot sends beyond the block and, with crosstalk_reach_subapertures > 0, includes light neighbouring spots send into it. This is the flux a detector reading those pixels measures, before QE and noise.

pupil_photons_s Any

Photon rate entering each lenslet's clear aperture in the pupil plane, in photons/s: the source rate times the integral of the entrance-field intensity (pupil times amplitude squared, after the spatial filter and the lenslet fill factor) over the lenslet, divided by the unscintillated pupil's integral. It does not depend on the detector window.

valid Any

Static valid-subaperture map of the offset state used.

photon_rate Any

The ideal photon-rate image the detector fluxes were summed from, in photons/s per native detector pixel.

makewfs.load_config

load_config(path)

Load a validated TOML configuration.

makewfs.simulate

simulate(wavefront, config, *, seed=None, amplitude=None)

One-shot convenience wrapper around :class:WavefrontSensor.

amplitude is the optional per-frame pupil amplitude of :meth:WavefrontSensor.photon_rate.

makewfs.config.WFSConfig dataclass

Complete immutable makewfs configuration.

digest property

digest

Short SHA-256 digest of the normalized configuration.

from_toml classmethod

from_toml(path)

Load and validate a TOML configuration, resolving relative paths.

to_dict

to_dict()

Return a JSON/TOML-friendly representation.

makewfs.config.ConfigError

Bases: ValueError

Raised when a configuration is invalid or uses an unknown field.