AiDonutAlgorithm

class lsst.ts.wep.estimation.AiDonutAlgorithm(modelPath='/opt/lsst/software/stack/conda/envs/lsst-scipipe-13.0.0/lib/python3.13/tests/testData/testAiModels/test_aidonut_model_file.pt', modelSha256='', device='cpu', temperature=0.005)

Bases: WfAlgorithm

Wavefront estimation using a PyTorch model.

Parameters:

• modelPath (str) – Path to the torchscript model file. See notes below for model requirements. Default is a test model included with ts_wep.

• modelSha256 (str, optional) – Expected SHA-256 hex digest of the model file. If provided, the file at modelPath is verified against this digest before loading and a RuntimeError is raised on mismatch. If empty (default) the check is skipped. Use this to pin an exact model version in production and to catch unfetched git-lfs pointer stubs.

• device (str, optional) – Device to load the model on (‘cpu’ or ‘cuda’). Default is ‘cpu’.

• temperature (float, optional) – Temperature parameter for softmax weighting of predictions when both intra- and extra-focal images are provided. Must be a positive float. Lower values place more weight on the prediction with lower estimated error. Default is 0.005.

Notes

Model Requirements:

• Must be saved in TorchScript format.

• Must accept the following inputs:

  • img - batch of images with shape (N, 1, H, W), where N is 1 or 2.

  • fx - field angle in x (degrees)

  • fy - field angle in y (degrees)

  • focalFlag - 1 for intra-focal, 0 for extra-focal

  • band - integer 0-5 indicating filter band (ugrizy)

• Must output one of:

  • a tensor of shape (N, n_zernikes), where n_zernikes is the number of Zernike coefficients predicted, starting with Noll index 4.

  • a 2-tuple (zk, zkScore), where zk is the tensor above and zkScore is a tensor of shape (N, n_zernikes) giving a per-coefficient confidence score (lower is better). zkScore is used for softmax weighting between intra/extra predictions.

  • a 3-tuple (zk, zkScore, fwhm), where fwhm is a tensor of shape (N, 2) giving FWHM estimates for each stamp.

• Zernikes must be returned in meters.

• Must have a nollIndices attribute listing the Noll indices corresponding to the output coefficients.

Warning

This is a breaking change from earlier versions of this algorithm, where a 2-tuple output was interpreted as (zk, fwhm). The second element of a 2-tuple is now zkScore, not fwhm. Models that previously returned (zk, fwhm) must be updated to return either zk alone or the 3-tuple (zk, zkScore, fwhm).

Attributes Summary

device	Device used for inference ('cpu' or 'cuda').
history	The algorithm history.
modelPath	Path to the PyTorch model file.
requiresPairs	This algorithm does not require a pair of images.
temperature	Temperature parameter for softmax weighting of predictions.

Attributes Documentation

device

Device used for inference (‘cpu’ or ‘cuda’).

history

The algorithm history.

The history is a dictionary with the following entries:

• “modelPath” - path to the PyTorch model file

• “device” - device used for inference

• “temperature” - temperature used for weighted averaging

• “modelNollIndices” - Noll indices the model predicts

• “intra” and/or “extra” - all Zernikes returned by the model

• “nollIndices” - Noll indices for which Zernikes are returned

• “zk” - the final, averaged Zernike estimate

Note the units for all Zernikes are in meters, and all Zernikes start with Noll index 4.

modelPath

Path to the PyTorch model file.

requiresPairs

This algorithm does not require a pair of images.

temperature

Temperature parameter for softmax weighting of predictions.