Shack-Hartmann sensor
The Shack-Hartmann engine partitions the configured pupil into a square lenslet
grid. Each subaperture is propagated by a batched Fraunhofer transform, integrated
onto its native detector pixels, and assembled into a
(lenslet_y, lenslet_x) mosaic. Integer-compatible focal grids use an FFT;
arbitrary normalized sampling uses a directly sampled DFT so the requested
plate scale is represented exactly.
pixels_per_subaperture and
spot_sampling_pixels_per_lambda_over_d determine the detector sampling. Partial
subapertures are retained and their illumination is recorded rather than
discarded. Finite detector windows can crop diffraction wings; the lost flux is
reported in metadata and is not silently renormalized.
Detector pixels use centered cell coordinates. For an even-sized subaperture
window, zero wavefront slope lies on the boundary shared by the central four
pixels. The Fourier propagation is evaluated at half-integer samples before
flux-conserving pixel-area integration, so a symmetric flat-wavefront spot gives
equal signal in those four pixels rather than being assigned to one of them.
Positive normalized sampling below one is supported for undersampled quadcell
modes whose native detector pixels are wider than lambda/D.
Set numerics.pupil_supersampling above one when edge-area convergence matters;
this averages analytic sub-pixels rather than interpolating a binary mask.
Instead of normalized spot sampling, a configuration may provide lenslet pitch, lenslet focal length, detector pixel pitch, and relay magnification. The engine derives the same normalized sampling from those physical fields and rejects mixed modes. Supplying the measured lenslet pitch explicitly is important when the telescope pupil is reduced onto a millimetre-scale hardware array. The optional field stop, Gaussian or measured-kernel blur, and detector-margin controls are applied to the ideal photon-rate mosaic before the camera adapter.
lenslet_grid_rotation_deg and lenslet_grid_offset_fraction describe a
rotated or decentered lenslet array relative to the entrance pupil. They use
physical-coordinate interpolation and are intended for instrument registration
studies; the zero-valued defaults retain the faster aligned-grid path.
Lenslet-grid offset states
shack_hartmann.lenslet_grid_offset_states_fraction pre-declares positions of
the lenslet grid on the pupil, as [x, y] offsets in lenslet pitches added to
lenslet_grid_offset_fraction. Dithered, modulated, or otherwise time-varying
Shack-Hartmann schemes declare the positions they visit; the sensor builds each
state's geometry once and selects it per call:
wfs = makewfs.WavefrontSensor.from_toml("examples/configs/shack_hartmann_offset_states.toml")
wfs.lenslet_grid_offsets_fraction() # ((0.0, 0.0), (0.5, 0.0), (0.0, 0.5), (0.5, 0.5))
frame = wfs.expose(opd_m, seed=0, offset_state=1)
valid = wfs.valid_subapertures(offset_state=1)
frames = wfs.expose_many(stream, offset_states=itertools.cycle(range(4)))
Each state caches its translated pupil illumination, lenslet mask,
valid-subaperture map, source and sodium-range tilts, flux normalization, LGS
kernel, and (on a GPU) compiled executor, so switching state costs a lookup.
Frames record wfs_lenslet_offset_state and the effective
wfs_lenslet_grid_offset_fraction. The index only selects geometry already in
the configuration, so the configuration and its digest still reproduce every
frame (ADR 0005). Memory grows with the
number of states times the number of propagated source states.
Moving the lenslet grid by +f pitches is equivalent to translating the pupil
illumination and the OPD by -f under a fixed grid. Both are sampled at the
transformed coordinates by linear interpolation. For the area-weighted pupil
this is its exact area-weighted translation on the sampled grid, so a lenslet's
illumination changes continuously with sub-sample offsets. Since 2.2 the pupil
is zero beyond the grid with interpolation across its last half sample, and
the OPD keeps its edge value there; previously each edge column of samples
dropped to zero at once, so illumination near a grid-filling pupil's edge moved
in steps of a whole sample column. Use numerics.pupil_supersampling > 1 for
area-weighted pupil edges; with 8 sub-samples the translated lenslet
illumination matches the analytic area to better than 0.5% in the tests.
The phase-ramp sign and spot displacement are fixed by analytic tests. This repository produces the image; centroiding, slope extraction, and reconstruction belong downstream.
Verification uses centroids only as a test observable: makewfs does not expose a centroiding or reconstruction API. A direct-summation DFT checks random spot mosaics, the analytic OPD-ramp test fixes displacement in detector pixels, and optional HCIPy/OOPAO comparisons check multi-amplitude response gain, sign, and cross-axis leakage on both axes. See Validation for the numerical tolerances and why the external-package gain is not expected to match machine precision.
Lenslet-field sampling
Each lenslet field is represented by s samples across the lenslet pitch d.
The Fraunhofer transform of a field sampled at pitch d / s is periodic, with
period s lenslet lambda/d, while the detector window spans
W = pixels_per_subaperture / spot_sampling_pixels_per_lambda_over_d [lambda/d]
If W > s, the window integrates more than one period: every replica of the
spot is summed as light, so the photon rate can exceed the configured source
rate, and a spot tilted beyond +-s/2 lambda/d aliases into the wrong position
because the phase step between samples exceeds pi. The continuous lenslet field
has neither artefact. Spot sampling scales with wavelength, so W is largest at
the shortest wavelength of a spectral quadrature, and a field stop of radius r
limits it to 2 r.
The engine therefore propagates each lenslet at
samples_per_lenslet = k * pupil_samples_per_lenslet,
k = smallest integer with k * pupil_samples_per_lenslet >= W_max
The configured pupil grid is kept: each pupil cell's area-weighted transmission
is held constant over its k x k refined sub-cells, so lenslet illumination,
validity, and a custom mask (supplied on the configured grid) are unchanged. The
OPD is interpolated linearly from the input grid onto the refined grid, which
reproduces a tilt exactly. Configurations that already satisfy s >= W_max
keep k = 1 and are bit-for-bit unchanged. The resolved values are available as
sensor.engine.pupil_samples_per_lenslet, field_upsampling,
samples_per_lenslet, and detector_window_lambda_over_d.
s >= W is the minimum for an unaliased model, not a convergence guarantee. A
sampled field still carries a small amount of wing light from neighbouring
periods into the window; for fully illuminated square lenslets the captured
fraction is a few percent above the continuous sinc^2 value when s is close
to W (up to about 7% at s / W = 1.1) and about 1% or less at s = 4 W in
the test cases (tests/test_shack_hartmann_sampling.py).
Raise numerics.pupil_samples_per_lenslet when wing flux matters, for example
for wide-field or quad-cell geometries; the cost grows with s^2.
Scintillation, flux, spatial filter, and cross-talk
A frame may carry a pupil amplitude next to the OPD, so the spots, the image,
and the subaperture fluxes include scintillation, and
WavefrontSensor.subaperture_flux returns the ideal photon rate of each
subaperture's pixels and of each lenslet's aperture. Two configuration keys
model extreme-AO designs: spatial_filter_width_lambda_over_d, a square
focal-plane stop in front of the lenslets, and crosstalk_reach_subapertures,
which removes the field stop at each window so light falls on the neighbouring
subapertures' pixels. All are described in
Scintillation and subaperture flux.
Centroider choice for closed-loop use
makewfs forms images; it has no centroider, slope, or reconstruction API. Those belong to downstream AO software (for example shmpipeline-ao). When choosing a centroider for a closed loop that consumes these images, these properties are standard and worth checking against the measurement model the controller assumes:
- A linear centre of gravity over the full subaperture window with a fixed denominator (the expected reference flux rather than the measured flux) is linear in the pixel values, so its mean under zero-mean detector noise equals its noise-free response. By the centroid theorem, the centroid of a fully captured spot equals the subaperture-averaged wavefront gradient (weighted by the pupil intensity in a partially illuminated subaperture), scaled by the plate scale.
- A thresholded centre of gravity is non-linear in the pixels. Its gain depends on flux and noise, so a gain calibrated on noise-free images is biased for noisy frames.
- A weighted (for example Gaussian-weighted) centre of gravity is not the subaperture-averaged gradient: its response depends on spot shape, and it differs from the average gradient when the wavefront varies within the subaperture, for instance when one subaperture spans several actuators.
- Dividing by the measured flux makes any centre of gravity non-linear, and
window truncation (the field stop each subaperture window imposes, see
subaperture_field_of_view_arcsec()) breaks the centroid theorem for spots that extend past the window, such as elongated LGS spots. Withcrosstalk_reach_subapertures > 0the window also collects light from neighbouring spots.
Current limitations
The CPU path supports deterministic wavelength quadrature, finite NGS angular
extent and user kernels, rotated analytic pupils with square segment gaps,
static path OPD, measured blur kernels, and a configurable sodium-range
elongation model for Shack–Hartmann, with an equivalent fast
kernel mode. Lenslet-grid rotation/offset,
including pre-declared offset states, is supported through the explicit
resampling path. A per-frame pupil amplitude, a square focal-plane spatial
filter, and inter-lenslet cross-talk are supported with the limitations listed
in Scintillation and subaperture flux. LGS
return flux is always supplied by the user; makewfs does not model laser
propagation, sodium physics, or the propagation that produces scintillation.