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