Guide stars and source morphology
makewfs consumes a source photon budget; it does not predict laser return
power, sodium excitation, sky background, or atmospheric scintillation (a
caller-computed scintillation pattern can be passed per frame as an
amplitude). This
keeps source/radiometry assumptions visible to an AO designer and leaves
detector effects to getframes.
Natural guide stars
Use normalization = "magnitude" for an NGS when a bandpass and telescope
throughput should determine the photon budget. getframes.Bandpass and
getframes.Telescope provide the zero point, collecting area, obstruction, and
throughput calculation. Use direct detector-surface photons for a laboratory
calibration or a separately modeled source.
field_angle_arcsec applies a deterministic angular tilt. For an extended NGS,
angular_fwhm_arcsec and angular_quadrature_order form a two-dimensional
Gaussian quadrature around that centroid. Every angular state is propagated
independently and summed in intensity, preserving incoherence and total source
flux. A measured or otherwise user-defined morphology can instead be supplied
with angular_kernel_path, a three-column x_arcsec y_arcsec weight table;
kernel offsets are relative to field_angle_arcsec and are mutually exclusive
with Gaussian FWHM mode.
Wavelength states
wavelengths_m and optional wavelength_weights form a normalized photon
quadrature. The Shack–Hartmann spot sampling scales with wavelength; the ideal
pyramid mask retains its configured fixed pupil separation. Without
detector.qe_curve_path, the resulting photon-rate maps are summed before one
scalar-QE getframes exposure. With that curve, the spectral-QE path passes the
cube to the released getframes>=2.2.0 API. Detector QE is applied once per
wavelength and the incident spectral cube is retained in
FrameTruth.spectral_photon_rate.
For measured relative curves, sed_path and transmission_path point to
two-column text files with wavelength_nm value. If explicit wavelengths are
omitted, the curve knots become the quadrature grid; if they are supplied, the
curves are interpolated there and multiplied into the weights.
Sodium LGS approximation
For kind = "lgs", configure detector_photon_rate_per_s; magnitude
normalization is intentionally rejected. lgs_ranges_m and
lgs_range_weights describe a normalized sodium density quadrature, and
lgs_launch_position_m gives the launch point in pupil-plane metres. The current
Shack–Hartmann model treats the input OPD as the phase at the weighted mean
range and adds the geometric angular offset
delta_theta = (launch_position - subaperture_position)
* (1/range - 1/mean_range)
to each range state. A zero-thickness profile therefore reduces exactly to a
thin beacon, while a thicker profile elongates edge subaperture spots. The model
does not claim same-realization turbulent OPD at every sodium range; that would
require the conditional pyturb extension described in the roadmap.
Fast LGS kernel mode
The quadrature above propagates one optical state per source-angle sample and
sodium range: with a 3 x 3 source rule and five ranges, 45 propagations per
wavelength per frame, which dominates a long closed loop. Each of those states
only adds a tilt across every subaperture, and by the Fourier shift theorem a
tilt only translates that subaperture's diffraction spot. For a fixed beacon
geometry the incoherent sum is therefore the zero-offset spot convolved with a
fixed kernel per subaperture j:
K_j(theta) = sum_a sum_k w_a w_k G_sigma(theta - alpha_a - delta_theta_jk)
delta_theta_jk = (launch_position - subaperture_position_j)
* (1/range_k - 1/mean_range)
where w_k are the sodium range weights, alpha_a, w_a the optional
angular_kernel_path points, and G_sigma the Gaussian of angular_fwhm_arcsec.
This is the convolution description of elongated subaperture spots used by, for
example, Schreiber et al. (2009,
doi:10.1111/j.1365-2966.2009.14797.x).
source.lgs_model = "kernel" uses it. Only the wavelength states are
propagated, at field_angle_arcsec, and the kernel is applied as one batched
FFT convolution. It needs no new physical input: the kernel is built from the
same lgs_ranges_m, lgs_range_weights, lgs_launch_position_m,
angular_fwhm_arcsec or angular_kernel_path, and lenslet geometry as the
quadrature, once per sensor (and once per
lenslet-grid offset state).
The mean-range OPD approximation is unchanged.
Numerical choices and their consequences:
- Where the convolution acts. On the oversampled focal-plane intensity, before the field stop, any focal-plane blur, charge diffusion, and pixel-area integration, exactly where the quadrature's translations act.
- Truncation. Light the kernel moves out of a subaperture's window is lost
and reported in
wfs_captured_photons_s; it is never renormalized. Light it moves into the window comes from a margin propagated around the window: up to the kernel half-width, but no further than one alias-free period of the sampled lenslet field (samples_per_lensletlensletlambda/d). Frames record both aswfs_lgs_kernel_radius_pxandwfs_lgs_kernel_margin_px. When the margin is smaller than the radius, light from farther away is not moved in. The quadrature has the matching limit: a tilt beyond half that period aliases. For strongly elongated spots, raisenumerics.pupil_samples_per_lensletuntilsamples_per_lensletexceeds the window plus twice the streak half-length (inlambda/d); both models then agree. - Sub-sample translations are deposited by linear (cloud-in-cell)
interpolation on the focal grid, which conserves each translation's weight and
first moment exactly and keeps the kernel non-negative, at the cost of a
slight extra smoothing that shrinks with
numerics.fft_oversampling. - Source extent is the continuous Gaussian, sampled on the focal grid and
truncated at four standard deviations, rather than the quadrature's discrete
rule;
angular_quadrature_orderis unused.
Validation (validation/lgs_kernel.py, tests/test_lgs_kernel.py, and
Validation): against a quadrature with a
densely sampled Gaussian source the kernel image agrees to 0.14% (L1) and
centroids to 0.002 pixel on a side-launched 20 x 20 sensor. Without source
extent the remaining difference is the linear deposition: 3.2% of the image at
fft_oversampling = 2, 0.7% at 4, and 0.2% at 8, and below 0.01 pixel in
centroid throughout. The default
three-point quadrature itself departs from the continuous Gaussian when the
source spans several pixels, so compare against a dense reference before
reading kernel-versus-quadrature differences as kernel error.
The shipped examples/lgs_thin_beacon.py intentionally demonstrates the thin
beacon/cone-effect boundary. A range-profile SH example is covered by the
configuration and regression tests; a full gallery remains a roadmap item.