GR-raytracing/benchmarks/fast_mode_deposit_2026-09-18.md

Fast-mode deposition error experiment (2026-09-18)

Decision this note settles: whether --fast-mode should deposit each point source image as a single nearest supersampled pixel or as 4 adjacent (bilinear) pixels before the one global PSF convolution and downscale.

Command

python3 scripts/fast_mode_deposit_error.py --phases 12 --grid 48 --tail 1e-6 --max-radius 64

Model

Reference = pixel-area integral of the normalized circular Moffat M(r; α, β), α = FWHM / (2 sqrt(2^(1/β) - 1)), on the final grid, using 8-point Gauss-Legendre quadrature. Fast image with supersample factor N:

• deposit the event into the N x N supersampled grid (nearest = 1 cell, bilinear = 4 adjacent cells);
• convolve the whole ss buffer with the single global kernel k[m] = ∫_ss-cell m M(z; Nα, β) dz (4-point quadrature);
• downscale by averaging each N x N block, which together with the unnormalised N-scaled kernel reproduces the final pixel-area integral.

Metrics: maxErr/rmsErr are whole-image errors vs the direct image at the true position; coreErr is the worst central-3x3 pixel error; FWHMerr compares the fast image with a direct image at the same centroid, so it is a pure shape error (0 when deposition is exact at its snapped centre); centErr is the position quantization vs the true continuous star position; beterr is the deposition-induced Moffat beta change, isolated from the radial fit's own pixel-integration bias by comparing with a reference fit (reported only for FWHM >= 2 px). FWHM 1.0 / β 3.5 rows are sub-Nyquist and are not meaningful for the shape metrics.

Raw output

Fast-mode deposition error experiment
grid=48 phases=12 tail=1e-06 max_radius=64
kernel quadrature = 4-point Gauss; reference = 8-point Gauss

 FWHM  beta  N   deposit  R_ss   retain    maxErr    rmsErr   coreErr   centErr   FWHMerr    beterr
---------------------------------------------------------------------------------------------------
 1.00  8.00  2   nearest    10  1.00000 6.333e-01 1.714e-02 6.333e-01 3.043e-01 1.733e-02       nan
 1.00  8.00  2  bilinear    10  1.00000 1.805e-01 3.972e-03 1.805e-01 2.722e-03 3.187e-01       nan
 1.00  8.00  3   nearest    14  1.00000 3.907e-01 1.061e-02 3.907e-01 1.847e-01 7.491e-03       nan
 1.00  8.00  3  bilinear    14  1.00000 7.587e-02 1.676e-03 7.587e-02 5.562e-03 1.816e-01       nan
 1.00  8.00  4   nearest    18  1.00000 2.608e-01 7.142e-03 2.608e-01 1.237e-01 3.665e-02       nan
 1.00  8.00  4  bilinear    18  1.00000 4.428e-02 9.775e-04 4.428e-02 3.395e-03 3.646e-02       nan

 2.70  8.00  2   nearest    24  1.00000 1.635e-01 8.693e-03 1.635e-01 2.946e-01 2.325e-08 5.061e-07
 2.70  8.00  2  bilinear    24  1.00000 4.339e-02 1.476e-03 4.339e-02 6.018e-09 4.046e-02 8.414e-02
 2.70  8.00  3   nearest    35  1.00000 9.597e-02 5.229e-03 9.597e-02 1.768e-01 1.465e-08 1.067e-06
 2.70  8.00  3  bilinear    35  1.00000 1.842e-02 6.387e-04 1.842e-02 2.437e-08 1.747e-02 4.029e-02
 2.70  8.00  4   nearest    46  1.00000 6.308e-02 3.488e-03 6.308e-02 1.179e-01 1.563e-08 2.905e-05
 2.70  8.00  4  bilinear    46  1.00000 1.011e-02 3.418e-04 1.011e-02 1.778e-08 9.355e-03 3.091e-02

 6.00  8.00  2   nearest    51  1.00000 7.012e-02 7.714e-03 7.012e-02 2.946e-01 1.617e-06 3.132e-06
 6.00  8.00  2  bilinear    51  1.00000 9.563e-03 6.146e-04 9.563e-03 8.749e-08 6.686e-03 1.039e-02
 6.00  8.00  3   nearest    64  1.00000 4.199e-02 4.631e-03 4.199e-02 1.768e-01 7.456e-10 3.315e-08
 6.00  8.00  3  bilinear    64  1.00000 4.090e-03 2.640e-04 4.090e-03 9.147e-06 2.683e-03 4.463e-03
 6.00  8.00  4   nearest    64  0.99994 2.795e-02 3.088e-03 2.795e-02 1.179e-01 2.631e-07 9.889e-06
 6.00  8.00  4  bilinear    64  0.99994 2.195e-03 1.409e-04 2.195e-03 9.262e-06 1.528e-03 2.354e-03

 1.00  4.50  2   nearest    19  1.00000 6.006e-01 1.643e-02 6.006e-01 3.041e-01 1.516e-02       nan
 1.00  4.50  2  bilinear    19  1.00000 1.745e-01 3.823e-03 1.745e-01 2.673e-03 2.485e-01       nan
 1.00  4.50  3   nearest    28  1.00000 3.712e-01 1.016e-02 3.712e-01 1.846e-01 6.881e-03       nan
 1.00  4.50  3  bilinear    28  1.00000 7.354e-02 1.616e-03 7.354e-02 5.429e-03 1.432e-01       nan
 1.00  4.50  4   nearest    36  1.00000 2.480e-01 6.842e-03 2.480e-01 1.236e-01 3.167e-02       nan
 1.00  4.50  4  bilinear    36  1.00000 4.269e-02 9.383e-04 4.269e-02 3.322e-03 3.640e-02       nan

 2.70  4.50  2   nearest    49  1.00000 1.625e-01 8.537e-03 1.625e-01 2.946e-01 9.993e-07 1.210e-06
 2.70  4.50  2  bilinear    49  1.00000 4.413e-02 1.439e-03 4.413e-02 5.868e-07 4.453e-02 4.843e-02
 2.70  4.50  3   nearest    64  1.00000 9.571e-02 5.135e-03 9.571e-02 1.768e-01 1.482e-07 2.493e-07
 2.70  4.50  3  bilinear    64  1.00000 1.871e-02 6.228e-04 1.871e-02 3.673e-06 1.867e-02 2.057e-02
 2.70  4.50  4   nearest    64  0.99999 6.299e-02 3.426e-03 6.299e-02 1.179e-01 1.817e-07 4.228e-07
 2.70  4.50  4  bilinear    64  0.99999 1.030e-02 3.333e-04 1.030e-02 3.726e-06 9.995e-03 1.353e-02

 6.00  4.50  2   nearest    64  0.99998 6.924e-02 7.554e-03 6.924e-02 2.945e-01 1.290e-04 1.735e-04
 6.00  4.50  2  bilinear    64  0.99998 9.859e-03 6.016e-04 9.859e-03 2.462e-06 7.468e-03 9.748e-03
 6.00  4.50  3   nearest    64  0.99978 4.153e-02 4.535e-03 4.153e-02 1.775e-01 2.110e-08 3.706e-08
 6.00  4.50  3  bilinear    64  0.99978 4.214e-03 2.585e-04 4.214e-03 7.436e-04 3.203e-03 4.204e-03
 6.00  4.50  4   nearest    64  0.99872 2.767e-02 3.024e-03 2.767e-02 1.185e-01 3.310e-06 1.891e-04
 6.00  4.50  4  bilinear    64  0.99872 2.264e-03 1.485e-04 2.264e-03 7.451e-04 1.709e-03 2.399e-03

 1.00  3.50  2   nearest    35  1.00000 5.809e-01 1.600e-02 5.809e-01 3.038e-01 1.370e-02       nan
 1.00  3.50  2  bilinear    35  1.00000 1.708e-01 3.732e-03 1.708e-01 2.601e-03 2.192e-01       nan
 1.00  3.50  3   nearest    52  1.00000 3.594e-01 9.895e-03 3.594e-01 1.843e-01 6.403e-03       nan
 1.00  3.50  3  bilinear    52  1.00000 7.210e-02 1.579e-03 7.210e-02 5.255e-03 1.252e-01       nan
 1.00  3.50  4   nearest    64  1.00000 2.402e-01 6.660e-03 2.402e-01 1.234e-01 2.661e-02       nan
 1.00  3.50  4  bilinear    64  1.00000 4.170e-02 9.143e-04 4.170e-02 3.223e-03 3.644e-02       nan

 2.70  3.50  2   nearest    64  1.00000 1.619e-01 8.440e-03 1.619e-01 2.946e-01 2.790e-05 2.602e-05
 2.70  3.50  2  bilinear    64  1.00000 4.461e-02 1.417e-03 4.461e-02 3.036e-07 4.689e-02 3.892e-02
 2.70  3.50  3   nearest    64  0.99997 9.553e-02 5.077e-03 9.553e-02 1.769e-01 3.421e-07 3.302e-07
 2.70  3.50  3  bilinear    64  0.99997 1.889e-02 6.133e-04 1.889e-02 8.121e-05 2.016e-02 1.646e-02
 2.70  3.50  4   nearest    64  0.99989 6.293e-02 3.387e-03 6.293e-02 1.179e-01 8.537e-07 5.529e-06
 2.70  3.50  4  bilinear    64  0.99989 1.042e-02 3.282e-04 1.042e-02 8.142e-05 1.066e-02 1.038e-02

Worst case over all tested configurations, by deposit scheme:
    nearest: maxErr=6.333e-01 rmsErr=1.714e-02 coreErr=6.333e-01 centErr=3.043e-01 FWHMerr=3.665e-02 beterr=1.891e-04
   bilinear: maxErr=1.805e-01 rmsErr=3.972e-03 coreErr=1.805e-01 centErr=5.562e-03 FWHMerr=3.187e-01 beterr=8.414e-02

Conclusion

For the production PSF (FWHM 2.7, β 4.5):

N	deposit	core HDR err	image RMS	centroid err	FWHM err	beta change
2	nearest	16.3%	0.85%	0.295 px	~0	~1.2e-6
2	bilinear	4.4%	0.14%	~0	+4.45%	+4.8%
3	nearest	9.6%	0.51%	0.177 px	~0	~2.5e-7
3	bilinear	1.9%	0.06%	~0	+1.87%	+2.1%
4	nearest	6.3%	0.34%	0.118 px	~0	~4.2e-7
4	bilinear	1.0%	0.03%	~0	+1.0%	+1.4%

• Nearest preserves the specified FWHM/β exactly (kernel-only shape and beta error at the numerical floor); its only error is a bounded position quantization of 0.5/N output pixels.
• Bilinear recovers the sub-pixel centroid exactly and roughly quarters the HDR error, but broadens the profile because it interpolates the kernel samples rather than the continuous kernel; it therefore changes the specified FWHM and beta unless separately compensated.
• A single fixed global convolution cannot provide both. --fast-mode default is therefore nearest; --fast-deposit bilinear is available as an explicit position-over-shape approximation.