ADR 0005: pre-declared Shack-Hartmann lenslet-grid offset states
Status: accepted (2.2.0)
Context
Dithered, modulated, and time-varying Shack-Hartmann schemes move the lenslet
grid relative to the pupil from frame to frame
(#19). Before 2.2 the only
control was the static shack_hartmann.lenslet_grid_offset_fraction, so each
position needed its own WavefrontSensor, with duplicated pupil, propagation,
and detector state.
ADR 0003 makes the wavefront the only physical per-frame input, with an optional
detector seed; every instrument choice lives in versioned configuration. An
arbitrary per-call offset, such as expose(opd, lenslet_offset=(fx, fy)),
would move instrument geometry out of the configuration: frames could no longer
be reproduced from the configuration and its digest, the valid-subaperture map
would no longer be a static calibration artifact, and each new offset would
rebuild geometry inside the frame loop.
Decision
shack_hartmann.lenslet_grid_offset_states_fractiondeclares the offset states as a list of[x, y]offsets in lenslet pitches. Each is added to the staticlenslet_grid_offset_fraction. Without the key there is one state, the static offset.- The sensor builds and caches every state's geometry at construction: the
translated pupil illumination, lenslet mask, valid-subaperture map, source and
sodium-range tilts, flux normalization, and (for
lgs_model = "kernel") the LGS kernels. The compiled CUDA executor is cached per state. photon_rate,reference,expose,expose_integrated, andvalid_subaperturesaccept a keywordoffset_state: int = 0that selects a declared state;expose_manyaccepts an iterableoffset_states.lenslet_grid_offsets_fraction()lists the effective offsets in index order. An index outside the declared states is an error; a pyramid accepts only0.- Shack-Hartmann frames record
wfs_lenslet_offset_state,wfs_lenslet_grid_offset_fraction, andwfs_lenslet_offset_state_count.
The per-frame inputs are therefore the wavefront, the optional seed, and an index into configured geometry. The index selects intent that is already in the configuration; it does not introduce any instrument parameter that the configuration and digest do not record.
Consequences
- A dithered loop is one sensor and one detector; switching state is a cached lookup.
- Memory grows with the number of states times the number of propagated source states, because each state keeps its own source-tilt arrays.
- Existing configurations are unchanged: the new key is omitted from the
normalized configuration at its default, so their digests do not move, and
offset_statedefaults to0. - A continuously varying offset is not supported; declare the positions a scheme visits. A future ADR may revisit this if a use case needs it.