ADR 0006: per-frame pupil amplitude
Status: accepted (2.3.0)
Context
ADR 0003 makes the wavefront the only physical per-frame input, and until 2.3 the wavefront was a phase/OPD map: the pupil amplitude was the configured, static pupil. A field propagated through high turbulent layers also changes in amplitude from frame to frame (scintillation), and a Shack-Hartmann subaperture flux then measures that intensity. Studies of scintillation as a wavefront- sensing signal, and of extreme-AO Shack-Hartmann sensors with a spatial filter, could not be simulated. The roadmap allowed amplitude input only as a versioned extension of the input contract.
Two forms were considered: a complex field, or an amplitude next to the OPD. A complex field is monochromatic, so it does not define the field at the other wavelengths of a broadband source, and its phase is wrapped, so it cannot be interpolated onto another propagation grid; OPD metres are achromatic and are the canonical wavefront quantity (ADR 0001).
Decision
photon_rate,expose,expose_integrated,subaperture_flux, andsimulateaccept an optional keywordamplitude;expose_manyaccepts an iterableamplitudes. It is the dimensionless field modulus relative to the unscintillated field, and multiplies the configured pupil amplitude of both sensors. The OPD remains the only phase input.- The amplitude is one
input.shapemap for every wavelength or one map per wavelength node (WavefrontSensor.wavelengths_m), so chromatic scintillation is representable. - Its intensity is area-averaged when the propagation grid differs, so the light each cell receives is conserved. An amplitude of exactly one reproduces the OPD-only result bit for bit on the CPU.
- The configured source rate describes amplitude one; a frame's flux scales
with the pupil-weighted mean of the squared amplitude. Frames record
wfs_input_amplitude. - The spatial filter (
spatial_filter_width_lambda_over_d) and the inter-lenslet cross-talk (crosstalk_reach_subapertures) are instrument geometry, so they are configuration keys, not per-call options. WavefrontSensor.subaperture_fluxreturns the ideal per-subaperture photon rates (detector pixel blocks and pupil-plane lenslet apertures) as aSubapertureFluxvalue inmakewfs.api; the top-level exports are unchanged.
The amplitude is part of the wavefront, not instrument intent: like the OPD it comes from the atmosphere and the caller's propagation, so it is a per-frame input. The configuration and its digest still record every instrument choice.
Consequences
- Existing calls and configurations are unchanged; the new configuration keys are omitted from the normalized configuration at their defaults, so digests do not move.
- makewfs still does not propagate fields between layers or model the
atmosphere; callers (or
pyturbandaocorepropagators) produce the pupil field. - Per-wavelength phases are not representable; the OPD is shared by every wavelength.
- On a GPU, frames with an amplitude use the array-operation Shack-Hartmann path rather than the compiled kernel; the pyramid replays a second CUDA graph.