Concepts and conventions
Wavefront units
OPD is the canonical internal quantity and is measured in metres. A phase input
must declare quantity = "phase", unit = "rad", and
reference_wavelength_m; it is converted to OPD before propagation. Units are
never inferred from array magnitude.
The input array uses (y, x) order. Its physical extent and shape come from the
[input] table. The pupil amplitude is configured separately, so a per-frame
input is normally only the phase/OPD map. An optional per-frame amplitude
array of the same shape multiplies the configured pupil to represent
scintillation (Scintillation and subaperture flux); the
OPD still carries the phase.
Image domains
The optical engines are deterministic and return an incident photon-rate map in
photons/s/native detector pixel. getframes.Camera.expose() performs the
scalar photon-to-electron-to-ADU chain, while the optional
Camera.expose_spectral() path applies wavelength-dependent QE exactly once
and preserves the incident cube in detector truth. Optical intensities are
summed over incoherent wavelength, source, modulation, and sodium-range samples;
complex fields are never added across incoherent states.
Piston and sampling
A constant piston changes only the global complex phase and therefore cannot change intensity. The numerical implementation removes the weighted global piston before evaluating the complex exponential to keep this invariant stable in single precision.
When an input grid does not divide into the configured lenslets, OPD is resampled on physical coordinates. Wrapped phase is never interpolated.
Input wavefront RMS in frame metadata
Every frame records two RMS values of the input wavefront, both in OPD metres
(phase input is converted at input.reference_wavelength_m first). Both
describe the input array as given, without input.static_opd_path; for
expose_integrated they describe the mean of the temporal samples.
| Key | Definition |
|---|---|
wfs_input_opd_rms_m |
Pupil-weighted, piston-removed RMS, the rms of aocore CONVENTIONS 4.1: sqrt(sum a^2 (opd - <opd>_a)^2 / sum a^2), where <opd>_a is the intensity-weighted mean. |
wfs_input_opd_rms_unweighted_m |
sqrt(mean(opd^2)) over every pixel of the input grid, with piston included and pixels outside the pupil counted. This was wfs_input_opd_rms_m before 2.0. |
The weight a^2 is the intensity of the pupil the optics use, on the input
grid. The engines use the configured pupil as a field amplitude, so the
intensity is its square. An analytic pupil (diameter, obscuration, spiders,
segment gaps, rotation) is evaluated on input.shape with the same
numerics.pupil_supersampling; this is the map
WavefrontSensor.pupil_illumination() returns, computed in float64. A
telescope.custom_mask_path mask exists only on the engine's own pupil grid
(lenslets_across_pupil times the pupil samples per lenslet for a
Shack-Hartmann, pixels_across_pupil for a pyramid), so its intensity is
area-averaged onto the input grid: each input
pixel takes the mean over the mask cells it overlaps, which is exact when the
two shapes match. A piston, or OPD outside the pupil, therefore changes only
the unweighted value.
Both values are reduced on the selected device and cross to the host together with the captured photon rate in one transfer.
Closed-loop use
The package intentionally stops at the detector image. A downstream controller
may turn that image into slopes, a reconstruction, and a deformable-mirror
command, then feed the resulting residual OPD back into expose().