Configuration
TOML is the canonical configuration format. A complete example is shipped at
examples/configs/shack_hartmann_minimal.toml.
The root requires schema_version = 1 and has these tables:
| Table | Purpose |
|---|---|
input |
quantity, units, array shape, physical extent, static OPD |
telescope |
pupil diameter, obstruction, spiders, custom mask |
source |
NGS/LGS, photon rate or magnitude, field angle, throughput |
sensor |
sensor kind and sensing wavelength |
shack_hartmann |
lenslet and spot sampling |
pyramid |
pupil separation and modulation |
detector |
getframes preset, exposure, temperature, binning |
numerics |
device, dtype, FFT oversampling/workers, internal sampling |
Unknown keys and conflicting normalization choices are errors. File paths are
resolved relative to the TOML file. The normalized configuration has a short
SHA-256 digest used in frame provenance. All lengths are metres unless the
key explicitly says arcsec, deg, or pixels.
Complete key reference
The loader rejects omitted required keys, unknown keys, non-finite values, and values outside the ranges below. Defaults are shown in parentheses.
At the root, schema_version = 1 is required. An optional [metadata] table
accepts arbitrary designer notes and is preserved in the normalized
configuration; it does not affect optical propagation except through the
configuration digest.
input
| Key | Meaning and constraints |
|---|---|
quantity |
"opd" or "phase" (default "opd"). |
unit |
Must be "m" for OPD or "rad" for phase; units are never inferred. |
shape |
Required [height, width], positive integers. Every dynamic input has this shape. |
grid_extent_m |
Required physical width/height of the input grid, positive. |
reference_wavelength_m |
Required positive wavelength when quantity = "phase"; otherwise unused. |
static_opd_path |
Optional .npy, .npz, or FITS OPD map with exactly shape; resolved relative to the TOML file. |
telescope
| Key | Meaning and constraints |
|---|---|
pupil_diameter_m |
Required positive entrance-pupil diameter. |
central_obscuration_ratio |
Inner radius divided by outer radius, [0, 1), default 0. |
spiders |
Array of {angle_deg, width_fraction} tables (default []); angle is measured from +x and width is a fraction of a half-turn, [0, 1]. |
pupil_rotation_deg |
Rotation applied to spider angles, default 0. |
custom_mask_path |
Optional .npy, .npz, or FITS amplitude mask; values must be finite in [0, 1] and match the configured sensor pupil grid: pixels_across_pupil square for a pyramid, lenslets_across_pupil * pupil_samples_per_lenslet square for a Shack–Hartmann (before any automatic lenslet-field refinement). |
segments_across_pupil |
Optional square segment count (integer ≥2), used with analytic segment gaps. |
segment_gap_fraction |
Gap width as a fraction of segment pitch, [0, 0.99] (default 0); nonzero values require segments_across_pupil. |
source
| Key | Meaning and constraints |
|---|---|
kind |
"ngs" or "lgs" (default "ngs"). |
normalization |
"detector_photon_rate" or "magnitude" (default "detector_photon_rate"). |
detector_photon_rate_per_s |
Non-negative total photons/s at the detector surface before QE; required for direct-rate mode. |
magnitude |
Finite magnitude; required for magnitude mode. LGS must not use magnitude mode. |
magnitude_system |
"vega" or "ab" (default "vega"); used with band. |
band |
Required band name for magnitude mode, passed to getframes radiometry. |
throughput |
Scalar optical throughput in [0, 1] (default 1), used by magnitude radiometry. |
field_angle_arcsec |
Source centroid [x, y] in arcsec (default [0, 0]). |
angular_fwhm_arcsec |
Non-negative Gaussian source FWHM (default 0); nonzero values require quadrature order at least 2. |
angular_quadrature_order |
Positive deterministic source quadrature order (default 3). |
angular_kernel_path |
Optional three-column x_arcsec y_arcsec weight source kernel; mutually exclusive with nonzero FWHM and resolved relative to the TOML file. |
wavelengths_m |
Optional positive wavelength nodes. Empty means the sensor wavelength. |
wavelength_weights |
Optional non-negative weights matching wavelengths_m; normalized internally. |
lgs_ranges_m |
Optional positive sodium range nodes; only valid for LGS. Empty means a thin layer at the configured mean. |
lgs_range_weights |
Optional non-negative weights matching lgs_ranges_m; normalized internally. |
lgs_launch_position_m |
LGS launch [x, y] in the entrance-pupil plane (default [0, 0]); only valid for LGS. |
lgs_model |
"quadrature" (default) or "kernel"; case-insensitive. "kernel" requires kind = "lgs" and a Shack–Hartmann sensor. It propagates only the wavelength states and applies the source extent (angular_fwhm_arcsec or angular_kernel_path) and the sodium range profile as one fixed convolution per subaperture; angular_quadrature_order is then unused. See Fast LGS kernel mode. |
sed_path |
Optional two-column wavelength_nm value source spectrum, non-negative and increasing. |
transmission_path |
Optional two-column wavelength_nm value transmission curve in [0, 1]. |
SED and transmission curves use trapezoid quadrature on their common wavelength nodes. The resulting normalized wavelength, source-angle, and (for SH) range states are recorded in provenance.
An angular kernel is an arbitrary incoherent source morphology. Its offsets are
added to field_angle_arcsec, its non-negative weights are normalized, and each
sample is propagated independently. For example:
# x_arcsec y_arcsec relative_weight
-0.15 0.00 1
0.00 0.00 2
0.15 0.00 1
This is useful for measured binary-guide-star or resolved-source profiles. The kernel file hash and all normalized states are included in frame provenance.
sensor, detector, and numerics
| Table/key | Meaning and constraints |
|---|---|
sensor.kind |
Required "shack_hartmann" or "pyramid". |
sensor.wavelength_m |
Required positive reference sensing wavelength. |
detector.preset |
Existing getframes camera preset; mutually exclusive with detector.camera. |
detector.camera |
Inline getframes.CameraConfig dictionary; mutually exclusive with preset. |
detector.exposure_s |
Required non-negative exposure time. |
detector.temperature_c |
Optional detector temperature in °C. |
detector.binning |
Positive integer passed to getframes. |
detector.binning_mode |
"digital" or "on_chip" (default "digital"). |
detector.precision |
"float32" or "float64" (default "float64"). |
detector.include_truth |
Boolean (default true) controlling detector truth arrays. |
detector.readout_mode |
"integrate" (default) or "cds". "integrate" runs the ordinary getframes exposure and returns unsigned ADU. "cds" runs correlated double sampling — one global-reset ramp, pedestal read, integration, signal read — and returns the signed int32 difference. Requires detector.binning = 1, is incompatible with caller-owned out storage, and needs a getframes with Camera.correlated_double_sample. |
detector.background_photon_rate_per_s |
Non-negative additive incident background in photons/s/pixel, uniform over the detector (default 0.0). Passed straight to getframes as its background term, so it collects charge and carries shot noise like any other light. Use it for sky and thermal background: makewfs does not know a field stop's solid angle or a sky surface brightness, so the caller computes the rate. It is incident light, not detector dark current, which the camera preset already owns. |
detector.cds_pedestal_interval_s |
Non-negative reset-to-pedestal-read delay in seconds (default 0.0). Only meaningful with readout_mode = "cds", and must be shorter than detector.exposure_s. It does not change the measured signal — exposure_s is the read-to-read integration — only the interval the pedestal read's own bias/noise terms are evaluated at. |
detector.qe_curve_path |
Optional configuration-relative two-column wavelength_nm qe curve passed to getframes; enables wavelength-resolved QE for broadband optical cubes. |
detector.roi |
Optional full-detector ROI table with non-negative left_px/top_px and positive width_px/height_px. Its shape must match the optical mosaic. |
numerics.dtype |
Optical real precision, "float32" or "float64" (default "float64"). |
numerics.device |
Execution device, "cpu" (default) or "gpu". GPU requires the makewfs[gpu] extra and a GPU-capable getframes; optical, truth, and ADU arrays stay device-resident. |
numerics.fft_oversampling |
Positive FFT integration oversampling (default 2). Also scales the pyramid propagation grid so diffraction beyond the detector crop is discarded instead of wrapping onto the pupil rims. The pyramid grid side is the smallest length with no prime factor above 7 that is at least fft_oversampling times the detector width; the rule is the same on CPU and GPU, and frames record it as wfs_pyramid_fft_size_px. |
numerics.fft_workers |
Positive scipy.fft worker count (default 1). |
numerics.pupil_samples_per_lenslet |
Optional integer ≥4: samples per lenslet pitch of the SH pupil grid that holds the amplitude mask, a custom mask, and lenslet illumination. Default max(8, ceil(max(input.shape) / lenslets_across_pupil)). Each lenslet field is then propagated on an integer refinement of this grid that is at least as fine as the widest detector window in lenslet lambda/d (see Lenslet-field sampling); a value already that fine is used unchanged. |
numerics.pupil_supersampling |
Positive analytic pupil boundary sub-sampling factor (default 1). |
For a device-resident atmosphere → WFS → detector loop:
[numerics]
device = "gpu"
dtype = "float32"
fft_oversampling = 2
fft_workers = 1 # CPU-only FFT control; accepted but ignored by CuPy FFTs
[shack_hartmann] keys are:
| Key | Meaning and constraints |
|---|---|
lenslets_across_pupil |
Positive square lenslet count. |
pixels_per_subaperture |
Native detector pixels per lenslet, at least 2. |
spot_sampling_pixels_per_lambda_over_d |
Positive normalized sampling; mutually exclusive with physical relay fields. Values below 1 represent detector pixels wider than lambda/D. |
minimum_illuminated_fraction |
Validity threshold in [0, 1]. |
lenslet_fill_factor |
Square clear fill fraction in [0, 1] (default 1). |
lenslet_pitch_m |
Optional positive physical lenslet pitch. When omitted, the legacy telescope-pupil pitch is used. |
lenslet_focal_length_m |
Optional positive physical lenslet focal length. |
detector_pixel_pitch_m |
Optional positive detector pitch for physical sampling. |
relay_magnification |
Positive relay magnification (default 1). |
field_stop_radius_lambda_over_d |
Optional non-negative focal-plane field-stop radius. |
optical_blur_fwhm_pixels |
Gaussian blur FWHM in native pixels (default 0). |
optical_blur_kernel_path |
Optional measured odd-sized blur kernel path; mutually exclusive with Gaussian blur. |
detector_margin_pixels |
Non-negative zero-rate mosaic margin. |
lenslet_grid_rotation_deg |
Lenslet-frame rotation in degrees (default 0). |
lenslet_grid_offset_fraction |
[x, y] offset in lenslet-pitch fractions (default [0, 0]). |
lenslet_grid_offset_states_fraction |
Optional list of [x, y] offsets in lenslet pitches (default []), each added to lenslet_grid_offset_fraction; finite values, any number of states. Selected per call with offset_state (index into this list). Empty means one state, the static offset. See Lenslet-grid offset states. |
spatial_filter_width_lambda_over_d |
Optional full width c > 0 of a square focal-plane spatial filter in front of the lenslets, in lenslet lambda/d at sensor.wavelength_m (default: no filter). It passes the pupil-plane frequencies |f_x|, |f_y| < c / (2 d) * lambda_ref / lambda; c = 1 is the anti-aliasing width. Not allowed with range-resolved LGS states (source.lgs_ranges_m). See Focal-plane spatial filter. |
crosstalk_reach_subapertures |
Integer k >= 0 (default 0): how many neighbouring subaperture windows on each side a lenslet's light may reach on the detector. 0 confines each spot to its own window, which acts as a field stop; k > 0 propagates 2k + 1 windows per axis and adds the light into the neighbours' pixels (raising samples_per_lenslet to avoid aliasing). Not allowed with source.lgs_model = "kernel". See Inter-lenslet cross-talk. |
[shack_hartmann] requires positive lenslets_across_pupil, at least two
pixels_per_subaperture, and minimum_illuminated_fraction in [0, 1].
Either positive spot_sampling_pixels_per_lambda_over_d or both
lenslet_focal_length_m and detector_pixel_pitch_m must be supplied, but
never both. The optional lenslet_fill_factor is in [0, 1],
relay_magnification is positive, field_stop_radius_lambda_over_d is
non-negative when supplied, optical_blur_fwhm_pixels is non-negative, and
optical_blur_kernel_path may reference a measured odd-sized, non-negative
.npy, .npz, or FITS PSF kernel; it is normalized to unit sum and is
mutually exclusive with optical_blur_fwhm_pixels. detector_margin_pixels
is a non-negative integer. The optional
lenslet_grid_rotation_deg rotates the lenslet coordinate frame, and
lenslet_grid_offset_fraction = [x, y] shifts its origin by fractions of one
subaperture pitch. These two controls use an explicit physical-coordinate
resampling path; the default zero values retain the fast axis-aligned path.
lenslet_grid_offset_states_fraction pre-declares several such offsets, for a
dithered or time-varying lenslet grid; every state's geometry is built once and
WavefrontSensor.photon_rate(opd, offset_state=k) (and expose,
expose_integrated, reference, valid_subapertures) selects one:
[shack_hartmann]
lenslets_across_pupil = 8
pixels_per_subaperture = 8
spot_sampling_pixels_per_lambda_over_d = 2.0
minimum_illuminated_fraction = 0.5
lenslet_grid_offset_states_fraction = [[0.0, 0.0], [0.5, 0.0], [0.0, 0.5], [0.5, 0.5]]
Integer-compatible focal grids use the batched FFT path. Arbitrary sampling, including undersampled quadcell modes, uses an exact sampled DFT at detector quadrature points so the configured plate scale is not rounded to an FFT bin.
A lenslet field sampled at s points per lenslet has a far field that repeats
every s lenslet lambda/d, so the propagated sampling must satisfy
s >= pixels_per_subaperture / spot_sampling_pixels_per_lambda_over_d at the
shortest configured wavelength (or 2 * field_stop_radius_lambda_over_d when
that is smaller). The engine enforces this by refining each lenslet field by the
smallest sufficient integer factor; it never changes the configured pupil grid.
For example, 4 pixels at 0.25 pixel per lambda/d span a 16 lambda/d window,
so pupil_samples_per_lenslet = 6 is propagated at 18 samples per lenslet.
[pyramid] requires pixels_across_pupil ≥ 8 and positive
pupil_separation_pixels. modulation_radius_lambda_over_d is non-negative;
zero radius requires exactly one sample, while nonzero modulation requires at
least four modulation_samples. detector_margin_pixels is non-negative.
numerics.pupil_supersampling sub-samples analytic circular, annular, spider,
and segment-gap boundaries before averaging each pupil pixel. Analytic features
are rotated by pupil_rotation_deg; custom masks should be supplied already
rotated because they are measured amplitude products. Custom masks may be
.npy, .npz, or FITS arrays in [0, 1].
Source normalization and morphology
For laboratory or already-calibrated flux, use:
[source]
kind = "ngs"
normalization = "detector_photon_rate"
detector_photon_rate_per_s = 2.0e9
The rate is photons/s at the detector surface before detector QE. For an NGS,
the alternative is normalization = "magnitude" with magnitude, band, and
magnitude_system = "vega" or "ab"; this uses getframes radiometry.
LGS return flux must be supplied directly because laser return prediction is out
of scope.
Shack–Hartmann sampling can be expressed either directly in normalized units or with physical lenslet optics. Do not provide both forms:
[shack_hartmann]
lenslets_across_pupil = 20
pixels_per_subaperture = 8
minimum_illuminated_fraction = 0.25
lenslet_pitch_m = 0.0002
lenslet_focal_length_m = 0.020
detector_pixel_pitch_m = 15e-6
relay_magnification = 1.0
In physical mode, makewfs derives pixels per lambda / D_subaperture as
f_lenslet * wavelength * relay_magnification /
(lenslet_pitch * detector_pixel_pitch). For backward compatibility,
lenslet_pitch_m defaults to the entrance-pupil diameter divided by the
lenslet count, but hardware models should provide the measured pitch explicitly.
field_stop_radius_lambda_over_d clips each subaperture's focal-plane field
stop, optical_blur_fwhm_pixels applies a flux-spreading optical Gaussian
before detector sampling, and detector_margin_pixels pads the assembled SH
mosaic with zero-rate margins. These are optical settings; detector binning and
noise remain in [detector]/getframes.
An extreme-AO style Shack-Hartmann adds a square spatial filter in front of the lenslets and lets spots spill into neighbouring subapertures:
[shack_hartmann]
lenslets_across_pupil = 16
pixels_per_subaperture = 8
spot_sampling_pixels_per_lambda_over_d = 2.0
spatial_filter_width_lambda_over_d = 1.0
crosstalk_reach_subapertures = 1
detector_margin_pixels = 8
Both keys are omitted from the normalized configuration at their defaults, so the digest of a configuration without them is unchanged. A per-frame pupil amplitude (scintillation) is not configuration: it is passed with each wavefront (Scintillation and subaperture flux).
Wavelength and source-size quadrature are optional. Weights are normalized, and intensities—not complex fields—are summed:
[source]
kind = "ngs"
normalization = "detector_photon_rate"
detector_photon_rate_per_s = 2.0e9
wavelengths_m = [650e-9, 700e-9, 750e-9]
wavelength_weights = [0.2, 0.5, 0.3]
angular_fwhm_arcsec = 0.25
angular_quadrature_order = 3
# Optional two-column wavelength_nm / relative_value files:
# sed_path = "source_sed.txt"
# transmission_path = "filter_transmission.txt"
field_angle_arcsec = [x, y] is the source centroid. A finite FWHM uses a
deterministic Gaussian quadrature around that centroid. By default the detector
receives one summed photon-rate map and uses its scalar QE. For broadband
scenes, detector.qe_curve_path enables wavelength-resolved exposure through
the released getframes>=2.2.0 spectral cube API, preserving the incident cube
and wavelength nodes in detector truth.
For a sodium LGS, configure a detector-surface return rate and optional range profile. The range model is currently Shack–Hartmann-specific:
[source]
kind = "lgs"
normalization = "detector_photon_rate"
detector_photon_rate_per_s = 2.0e8
lgs_ranges_m = [89000.0, 90000.0, 91000.0]
lgs_range_weights = [0.25, 0.5, 0.25]
lgs_launch_position_m = [0.0, 0.0]
The supplied OPD is interpreted at the weighted mean range. Each range slice gets the geometric perspective offset for each lenslet; this captures image elongation but does not create range-resolved turbulent OPD.
For long closed loops, lgs_model = "kernel" evaluates the same geometry as a
fixed per-subaperture convolution, one propagation per wavelength instead of
one per source angle and range:
[source]
kind = "lgs"
normalization = "detector_photon_rate"
detector_photon_rate_per_s = 2.0e8
lgs_model = "kernel"
angular_fwhm_arcsec = 0.5
lgs_ranges_m = [85753.0, 87877.0, 90000.0, 92123.0, 94247.0]
lgs_range_weights = [0.6065, 0.8825, 1.0, 0.8825, 0.6065]
lgs_launch_position_m = [4.5, 0.0]
``` See the
[guide-star guide](guide-stars.md) for the approximation and `pyturb` handoff.
## Detector choices
`detector.preset` names any installed `getframes` preset, including OCAM2K,
SAPHIRA, EMCCD, sCMOS, and generic teaching cameras. When the optical mosaic is
a hardware ROI rather than the full sensor, preserve its full-detector origin:
```toml
[detector.roi]
left_px = 4
top_px = 4
width_px = 228
height_px = 228
The ROI uses unbinned detector pixels, with left_px/top_px measured from the
full sensor's upper-left corner. Its (height_px, width_px) must equal the ideal
optical output shape. makewfs passes this geometry to getframes, which retains
the preset's native sensor size, evaluates detector effects in full-detector
coordinates, and returns the cropped image. Without detector.roi, a differing
optical shape retains the legacy behavior of replacing the camera resolution.
Detector binning and all noise physics remain in getframes.