CalcZernikesNeuralTask#

class lsst.ts.wep.task.CalcZernikesNeuralTask(**kwargs)#

Bases: CalcZernikesTask

Neural network-based Zernike estimation task using TARTS.

This class uses the TARTS (Triple-stage Alignment and Reconstruction using Transformer Systems for Active Optics) neural network models to estimate Zernike coefficients from pairs of intra and extra-focal exposures. Each exposure contains donut stamps from one focal position, and the task processes them separately to estimate Zernike coefficients for each side of the focal plane.

TARTS is a PyTorch package with a triple-stage design: (1) AlignNet for donut alignment and normalization, (2) WaveNet for per-donut Zernike regression, and (3) AggregatorNet (transformer-based) for fusing multiple donut predictions.

The TARTS system includes three main components: - Wavenet: Estimates Zernike coefficients from donut images - Alignnet: Handles image alignment and preprocessing - Aggregatornet: Combines results from multiple donuts

Detector Support#

This task only supports corner wavefront sensors with detector names ending with ‘_SW0’ (extra-focal) or ‘_SW1’ (intra-focal). Full array mode is not currently supported.

param kwargs:
type kwargs:: Any

Attributes Summary

`AVERAGE_ROW_AGGREGATION_METHOD`
`EXPECTED_IMAGE_DIMENSIONS`
`LOG_PRECISION`

Methods Summary

`calcZernikesFromExposure`(exposure, defocalType)	Calculate Zernike coefficients from a single focal position exposure.
`createDonutQualityTable`(donutStamps)	Create a quality table from donut stamps metadata.
`createDonutStampFromTarts`(exposure, ...)	Create DonutStamps from TARTS neural network output.
`createDonutTable`(donutStamps, exposure[, ...])	Create a donut source catalog table matching GenerateDonutCatalogWcsTask structure.
`empty`([qualityTable, exposure, defocalType])	Return empty results when no donuts are available for processing.
`run`(exposure[, intrinsicZernikesExtra, ...])	Run the neural network-based Zernike estimation task.
`validate`()	Validate configuration parameters for the neural Zernike task.

Attributes Documentation

AVERAGE_ROW_AGGREGATION_METHOD = 'nanmedian'#

EXPECTED_IMAGE_DIMENSIONS = 3#

LOG_PRECISION = 3#

Methods Documentation

calcZernikesFromExposure(exposure, defocalType)#

Calculate Zernike coefficients from a single focal position exposure.

This method processes either an intra-focal OR extra-focal exposure through the TARTS neural network to estimate Zernike coefficients representing wavefront aberrations. The exposure contains donut stamps from one side of the focal plane (not both).

Parameters:

exposure (lsst.afw.image.Exposure) – An exposure containing donut stamps from either the intra-focal OR extra-focal position. This is NOT a full frame exposure with both focal positions - it’s specifically one side of the focal pair. Must have valid image data and WCS information.
defocalType (str) – The defocal type indicating which side of focus the exposure represents. Should be either “intra” or “extra”.

Returns:

A tuple containing three elements: - aggregatedZernikes : np.ndarray

Aggregated Zernike coefficients from TARTS deploy_run() in microns, representing the final estimated wavefront aberrations for this focal position after neural network processing. This is the primary output from the TARTS system’s AggregatorNet component.

donutStampsDonutStamps
DonutStamps object containing the processed donut stamp data created from TARTS output, including positions, images, and metadata for downstream analysis.
rawZernikesnp.ndarray
Individual Zernike coefficients per donut from TARTS (a deep copy of self.tarts.total_zernikes). This contains the raw per-donut predictions before aggregation, useful for detailed analysis and debugging of individual donut contributions.

Return type:

tuple[np.ndarray, DonutStamps, np.ndarray]

Notes

This method processes one side of the focal pair (intra OR extra). In production, a single “exposure” typically contains both intra and extra-focal donuts in different corners, but this method expects an exposure with donut stamps from only one focal position.

The complete wavefront estimation workflow involves: 1. Processing intra-focal donuts separately (this method) 2. Processing extra-focal donuts separately (this method) 3. Combining results from both sides using AggregatorNet

The exposure should a single detector image that the TARTS models are trained to process, not full frame images.

The difference between ‘aggregatedZernikes’ and ‘rawZernikes’: - ‘aggregatedZernikes’ is the final aggregated result from TARTS’s

AggregatorNet

‘rawZernikes’ contains individual per-donut predictions before aggregation, useful for analyzing individual donut contributions

createDonutQualityTable(donutStamps)#

Create a quality table from donut stamps metadata.

Parameters:: donutStamps (DonutStamps) – The donut stamps with metadata already populated by createDonutStampsFromTarts().
Returns:: A table containing quality information for each donut.
Return type:: QTable

createDonutStampFromTarts(exposure, croppedImage, defocalType, tartsInternalData)#

Create DonutStamps from TARTS neural network output.

This method processes the cropped image output from TARTS and converts it into DonutStamps objects that are compatible with the LSST WEP framework. It handles multiple donuts detected in the image and creates the appropriate data structures for downstream processing.

Parameters:

exposure (lsst.afw.image.Exposure) – The original exposure containing metadata, WCS, and other information needed for creating proper DonutStamp objects.
croppedImage (np.ndarray) – The cropped image array output from TARTS neural network containing the processed donut regions.
defocalType (str) – The defocal type indicating which side of focus the donuts represent. Should be either “intra” or “extra”.
tartsInternalData (list) – Internal data from TARTS get_internal_data() method containing per-donut information like centers, field positions, SNR, etc. Required for proper donut position and metadata extraction.

Returns:

A collection of DonutStamp objects representing the detected and processed donuts from the TARTS output. Each DonutStamp contains the necessary metadata and image data for wavefront estimation.

Return type:

DonutStamps

Notes

This method bridges the gap between TARTS neural network output and the LSST WEP framework by converting the processed image data into the expected DonutStamp format. The method handles the coordinate transformations and metadata extraction needed to create valid DonutStamp objects.

createDonutTable(donutStamps, exposure, defocalType='intra')#

Create a donut source catalog table matching GenerateDonutCatalogWcsTask structure.

This method creates an Astropy QTable containing the positions and properties of donut sources, following the same structure as GenerateDonutCatalogWcsTask.

Parameters:

donutStamps (DonutStamps) – The donut stamps collection.
exposure (afwImage.Exposure) – The exposure containing the donut data.
defocalType (str, optional) – Defocal side label for logging and metadata consistency. Must be "intra" or "extra". Default is "intra".

Returns:

A table containing donut source positions and properties matching the standard format.

Return type:

QTable

empty(qualityTable=None, exposure=None, defocalType=None)#

Return empty results when no donuts are available for processing.

This method creates empty output structures when the task cannot process any donut data. It handles two scenarios: when there are no donuts at all, and when there are donuts but they all fail quality checks.

Parameters:

qualityTable (astropy.table.QTable, optional) – Quality table created from donut stamp input. If provided, this table will be included in the output even if all donuts failed quality checks. If None, an empty quality table will be created.

Returns:

A struct containing empty or failed results: - outputZernikesRaw : np.ndarray

Array filled with NaN values for all Noll indices.

outputZernikesAvgnp.ndarray
Array filled with NaN values for all Noll indices.
donutStampsNeuralastropy.table.QTable
Empty neural network-generated donut stamps collection.
zernikesastropy.table.QTable
Empty Zernike coefficient table.
donutQualityTableastropy.table.QTable
Either the provided quality table or an empty one.

Return type:

lsst.pipe.base.Struct

Notes

The NaN values in the output arrays indicate that no valid Zernike coefficients could be calculated. The quality table preserves information about why donuts failed, which can be useful for debugging.

Parameters:

exposure (Exposure | None, default: None)
defocalType (str | None, default: None)

run(exposure, intrinsicZernikesExtra=None, intrinsicZernikesIntra=None, numCores=1)#

Run the neural network-based Zernike estimation task.

This method processes a single LSST exposure to estimate Zernike coefficients using the TARTS neural network. The method determines whether the exposure contains intra-focal or extra-focal donuts and processes them accordingly.

Parameters:

exposure (lsst.afw.image.Exposure) – The LSST exposure data containing donut stamps. This should contain proper WCS information for the TARTS neural network.
intrinsicZernikesExtra (lsst.ip.isr.IntrinsicZernikes, optional) – Intrinsic Zernike calibration for extra-focal donuts. Passed by the base runQuantum from the pipeline input collections.
intrinsicZernikesIntra (lsst.ip.isr.IntrinsicZernikes, optional) – Intrinsic Zernike calibration for intra-focal donuts. Passed by the base runQuantum from the pipeline input collections.
numCores (int, optional) – Reserved for API compatibility with the base class; not used by this neural implementation. Default is 1.

Returns:

A struct containing: - outputZernikesAvg : np.ndarray

Zernike coefficients from the exposure (in microns).

outputZernikesRawnp.ndarray
Raw Zernike coefficients from the exposure (in microns).
donutStampsNeuralastropy.table.QTable
Neural network-generated donut stamps metadata from TARTS output.
zernikesastropy.table.QTable
Zernike coefficients table with individual donut and average values.
donutQualityTableastropy.table.QTable
Quality information for donuts.

Return type:

lsst.pipe.base.Struct

Notes

This implementation processes a single exposure containing donut stamps from either the intra-focal or extra-focal position. The TARTS neural network is used to estimate Zernike coefficients representing wavefront aberrations.

The exposure should contain: - Valid image data (typically donut stamps) - Proper WCS (World Coordinate System) information - Appropriate metadata for the instrument and observation