WEP Developer Guide

Wavefront estimation pipeline (WEP) calculates the wavefront error in annular Zernike polynomials up to 22 terms based on the intra- and extra-focal donut images. The wavefront error is determined by solving the transport of intensity equation (TIE) that approximates the change of intensity mainly comes from the wavefront error. For an in-depth explanation of the algorithm that solves the TIE equation see the following technote: SITCOMTN-046: AOS Algorithm for Wavefront Estimation.

Main Classes

Important classes:

• WfEstimator calculates the wavefront error in annular Zernike polynomials up to 22 terms based on the defocal donut images.

Important Pipeline Tasks:

• task.GenerateDonutCatalogWcsTask creates a donut source catalog from available reference catalogs.

• task.CutOutDonutsScienceSensorTask cuts out donuts stamps in image from LSSTFam or ComCam sensors when provided input exposures and source catalog.

• task.CutOutDonutsCwfsTask cuts out donuts stamps in image from LSSTCam corner wavefront sensors when provided input exposures and source catalog.

• task.CalcZernikesTask calculates the Zernikes polynomials from donut stamps already stored in a butler repository.

Important enums:

• FilterType defines the type of active filter.

• CamType defines the type of camera.

• BscDbType defines the type of bright star catalog database.

Modules

The classes and files for each module are listed below.

wep

This module is a high-level module to use other modules.

Figure 1 Class diagram of wep

• WfEstimator: Calculate the wavefront error in annular Zernike polynomials up to 22 terms based on the defocal donut images.

• ParamReader: Parameter reader class to read the yaml configuration files used in the calculation.

• DonutImageCheck: Donut image check class to judge the donut image is effective or not.

• DonutDetector: Detect donuts directly from an out of focus image by convolution with a template image.

wep.cwfs

This module calculates the wavefront error by solving the TIE.

Figure 2 Class diagram of wep.cwfs

• Algorithm: Algorithm class to solve the TIE to get the wavefront error.

• CompensableImage: Compensable image class to project the donut image from the image plane to the pupil plane.

• Image: Image class to have the function to get the donut center.

• Instrument: Instrument class to have the instrument information used in the Algorithm class to solve the TIE.

• CentroidFindFactory: Factory for creating the centroid find object to calculate the centroid of donut.

• CentroidDefault: Default centroid class.

• CentroidRandomWalk: CentroidDefault child class to get the centroid of donut by the random walk model.

• CentroidOtsu: CentroidDefault child class to get the centroid of donut by the Otsu’s method.

• CentroidConvolveTemplate: CentroidDefault child class to get the centroids of one or more donuts in an image by convolution with a template donut.

• BaseCwfsTestCase: Base class for CWFS tests.

• DonutTemplateFactory: Factory for creating donut template objects used by CentroidConvolveTemplate.

• DonutTemplateDefault: Default donut template class.

• DonutTemplateModel: DonutTemplateDefault child class to make donut templates using an Instrument model.

• DonutTemplatePhosim: DonutTemplateDefault child class to make donut templates from templates created with Phosim. See here for more information on creating and using Phosim donut templates.

wep.deblend

This module does the image deblending.

Figure 3 Class diagram of wep.deblend

• DeblendDonutFactory: Factory for creating the deblend donut object to deblend the bright star donut from neighboring stars.

• DeblendDefault: Default deblend class.

• DeblendAdapt: DeblendDefault child class to do the deblending by the adaptive threshold method.

• nelderMeadModify: Do the numerical optimation according to the Nelder-Mead algorithm.

wep.task

This module has the tasks to run WEP as a pipeline with Gen 3 LSST DM middleware.

Figure 4 Class diagram of wep.task

• GenerateDonutDirectDetectTaskConnections: Connections setup for GenerateDonutDirectDetectTask to run in a pipeline with Gen 3 middleware.

• GenerateDonutDirectDetectTaskConfig: Configuration setup for GenerateDonutDirectDetectTask.

• GenerateDonutDirectDetectTask: Gen 3 middleware task to convolve the defocal postISRCCD exposure with a donut template and and create a catalog of donut sources for that exposure.

• GenerateDonutCatalogOnlineTaskConfig: Configuration setup for GenerateDonutCatalogOnlineTask.

• GenerateDonutCatalogOnlineTask: Task to take pointing information and create a catalog of donut sources in that pointing. Not a pipeline task.

• GenerateDonutCatalogWcsTaskConnections: Connections setup for GenerateDonutCatalogWcsTask to run in a pipeline with Gen 3 middleware.

• GenerateDonutCatalogWcsTaskConfig: Configuration setup for GenerateDonutCatalogWcsTask.

• GenerateDonutCatalogWcsTask: Gen 3 middleware task to take the WCS from each detector in a postISRCCD exposure and create a catalog of donut sources for that exposure.

• DonutSourceSelectorTaskConfig: Configuration setup for DonutSourceSelectorTask.

• DonutSourceSelectorTask: Filter a reference catalog according to parameters specified in DonutSourceSelectorTaskConfig to create a catalog of donut sources acceptable for Zernike estimation.

• DonutQuickMeasurementTaskConfig Configuration setup for DonutQuickMeasurementTask.

• DonutQuickMeasurementTask: Run quick donut detection and measurement on exposures.

• DonutStamp: Storage class for a single donut postage stamp and associated metadata.

• DonutStamps: Gen 3 Butler readable storage class for a list of DonutStamp objects with helper functions to get metadata and to save DonutStamps object as FITS file.

• RefCatalogInterface: Tools to pick out the pieces of a reference catalog in the Gen3 Butler that cover the sky area of a pointing.

• CombineZernikesBaseTask: Base class for CombineZernikes tasks that combine the Zernike coefficients from multiple donuts on a detector into a single set of coefficients for the detector.

• CombineZernikesBaseConfig: Configuration setup for CombineZernikesBaseTask.

• CombineZernikesMeanTask: Gen 3 middleware task to combine the Zernike coefficients using an unweighted mean of coefficients from all donut pairs.

• CombineZernikesSigmaClipTask: Gen 3 middleware task to combine the Zernike coefficients with a sigma clipping method that will remove donuts with outlier Zernike values from the final averaging of donut pairs.

• CombineZernikesSigmaClipTaskConfig: Configuration setup for CombineZernikesSigmaClipTask.

• CalcZernikesTask: Gen 3 middleware task to calculate the zernikes from donut stamps that already exist in the butler.

• CalcZernikesTaskConnections: Connections setup for CalcZernikesTask.

• CalcZernikesTaskConfig: Configuration setup for CalcZernikesTask.

• CutOutDonutsBaseTask: Base class for CutOutDonuts tasks.

• CutOutDonutsBaseTaskConnections: Base connections class for CutOutDonuts tasks.

• CutOutDonutsBaseTaskConfig: Base configuration class for CutOutDonuts tasks.

• CutOutDonutsCwfsTask: Gen 3 middleware task to cut out donut stamps on LSST Corner Wavefront Sensors from donut catalogs produced by GenerateDonutCatalogs tasks.

• CutOutDonutsCwfsTaskConfig: Configuration setup for CutOutDonutsCwfsTask.

• CutOutDonutsScienceSensorTask: Gen 3 middleware task to cut out donut stamps on science sensors from donut catalogs produced by GenerateDonutCatalogs tasks.

• CutOutDonutsScienceSensorTaskConnections: Connections setup for CutOutDonutsScienceSensorTask.

• CutOutDonutsScienceSensorTaskConfig: Configuration setup for CutOutDonutsScienceSensorTask.

• GenerateDonutFromRefitWcsTask: Optional pipeline task to take a catalog of detected donuts from GenerateDonutDirectDetectTask and fit a WCS to the input exposure and return a donut catalog using the new WCS and a reference catalog.

• GenerateDonutFromRefitWcsTaskConnections: Connections setup for GenerateDonutFromRefitWcsTask.

• GenerateDonutFromRefitWcsTaskConfig: Configuration setup for GenerateDonutFromRefitWcsTask.

• GenerateDonutCatalogUtils: Common utility functions for the GenerateDonutCatalog…Tasks.

wep.utils

This module contains utility functions that are used elsewhere in WEP.

• enumUtils: Enum definitions and related functions.

• ioUtils: Functions for reading and writing files.

• taskUtils: Functions for running command line tasks from a python script.

• zernikeUtils: Functions for evaluating and fitting Zernike polynomials.

• plotUtils: Functions for plotting results.

• miscUtils: Miscellaneous utility functions.

Python API reference

This section is autogenerated from docstrings.

lsst.ts.wep Package

Classes

DonutDetector()	Class to detect donuts directly from an out of focus image by convolution with a template image.
ParamReader([filePath])	Initialization of parameter reader of yaml format class.
WfEstimator(algoDir)	Initialize the wavefront estimator class.

lsst.ts.wep.cwfs Package

Classes

Algorithm(algoDir)	Initialize the Algorithm class.
BaseCwfsTestCase()	Base class for CWFS tests
CentroidConvolveTemplate()	CentroidDefault child class to get the centroid of donut by convolution with a template donut image.
CentroidDefault()	Default Centroid class.
CentroidFindFactory()	Factory for creating the centroid find object to calculate the centroid of donut.
CentroidOtsu()	CentroidDefault child class to get the centroid of donut by the Otsu's method.
CentroidRandomWalk()	CentroidDefault child class to get the centroid of donut by the random walk model.
CompensableImage([centroidFindType])	Instantiate the class of CompensableImage.
DonutTemplateDefault()	Default Donut Template class.
DonutTemplateFactory()	Factory used to create template maker object to generate donut template images CentroidConvolveTemplate.
DonutTemplateModel()	Class to make the donut templates from the Instrument model.
DonutTemplatePhosim()	Class to make the donut templates from phosim template images.
Image([centroidFindType])	Image class for wavefront estimation.
Instrument()	Instrument class to have the instrument information used in the Algorithm class to solve the TIE.

lsst.ts.wep.deblend Package

Functions

feval(func[, vars])	Evaluate the function.
nelderMeadModify(func, x_start[, args, ...])	Optimization of the Nelder-Mead algorithm.

Classes

DeblendAdapt()	DeblendDefault child class to do the deblending by the adaptive threshold method.
DeblendDefault()	Default deblend class.
DeblendDonutFactory()	Factory for creating the deblend donut object to deblend the bright star donut from neighboring stars.

lsst.ts.wep.task Package

Functions

donutCatalogToDataFrame([donutCatalog, ...])	Reformat afwCatalog into a pandas dataframe sorted by flux with the brightest objects at the top.
runSelection(refObjLoader, detector, wcs, ...)	Match the detector area to the reference catalog and then run the LSST DM reference selection task.

Classes

CalcZernikesTask(**kwargs)	Run Zernike Estimation on corner wavefront sensors (CWFS)
CalcZernikesTaskConfig(*args, **kw)
CalcZernikesTaskConnections(*[, config])
CombineZernikesBaseConfig(*args, **kw)
CombineZernikesBaseTask(**kwargs)	Base class for algorithms that combine Zernikes from the individual pairs of donuts on a detector into a single array of Zernike values for that detector.
CombineZernikesMeanTask(**kwargs)	Combine the raw Zernike measurements into an average measurement with an unweighted mean.
CombineZernikesSigmaClipTask(**kwargs)	Combine the raw Zernike measurements into an average measurement by rejecting outliers with sigma clipping.
CombineZernikesSigmaClipTaskConfig(*args, **kw)	Configuration for combining Zernike coefficients with sigma clipping.
CutOutDonutsBaseTask(**kwargs)	Base class for CutOutDonuts tasks.
CutOutDonutsBaseTaskConfig(*args, **kw)
CutOutDonutsBaseTaskConnections(*[, config])
CutOutDonutsCwfsTask(**kwargs)	Cut out the donut postage stamps on corner wavefront sensors (CWFS)
CutOutDonutsCwfsTaskConfig(*args, **kw)
CutOutDonutsScienceSensorTask(**kwargs)	Run Zernike Estimation in full-array mode (FAM)
CutOutDonutsScienceSensorTaskConfig(*args, **kw)
CutOutDonutsScienceSensorTaskConnections(*)
DonutQuickMeasurementTask(config, *[, display])
DonutQuickMeasurementTaskConfig(*args, **kw)
DonutSourceSelectorTask(**kwargs)	Donut Source Selector that uses a nearest neighbors radius query to find all donuts within the pixel radius set in the config.
DonutSourceSelectorTaskConfig(*args, **kw)
DonutStamp(stamp_im, sky_position, ...)	Single donut stamp
DonutStamps(stamps[, metadata, use_mask, ...])	Holds a list of DonutStamp objects with additional functions to get metadata as well as save as FITS files.
GenerateDonutCatalogOnlineTask(**kwargs)	Construct a source catalog from reference catalogs and pointing information.
GenerateDonutCatalogOnlineTaskConfig(*args, **kw)	Configuration for GenerateDonutCatalogOnlineTask.
GenerateDonutCatalogWcsTask(**kwargs)	Create a WCS from boresight info and then use this with a reference catalog to select sources on the detectors for AOS.
GenerateDonutCatalogWcsTaskConfig(*args, **kw)	Configuration settings for GenerateDonutCatalogWcsTask.
GenerateDonutCatalogWcsTaskConnections(*[, ...])	Specify the pipeline connections needed for GenerateDonutCatalogWcsTask.
GenerateDonutDirectDetectTask(**kwargs)	Generate donut template and convolve with the defocal image to detect sources on the detectors for AOS.
GenerateDonutDirectDetectTaskConfig(*args, **kw)	Configuration settings for GenerateDonutDirectDetectTask.
GenerateDonutDirectDetectTaskConnections(*)	Specify the pipeline connections needed for GenerateDonutDirectDetectTask.
GenerateDonutFromRefitWcsTask(**kwargs)	Fit a new WCS to the image from a direct detect Donut Catalog and return the input exposure with the new WCS attached.
GenerateDonutFromRefitWcsTaskConfig(*args, **kw)	Configuration settings for GenerateDonutCatalogWcsTask.
GenerateDonutFromRefitWcsTaskConnections(*)	Specify the pipeline inputs and outputs needed for FitDonutWcsTask.
RefCatalogInterface(boresightRa, ...)	Class to provide tools to interact with reference catalog in Butler repository and select pieces of the catalog that cover the sky area of a pointing.

lsst.ts.wep.utils Package

Functions

ZernikeAnnularEval(z, x, y, e)	Calculate the wavefront surface in the basis of annular Zernike polynomial.
ZernikeAnnularFit(s, x, y, numTerms, e)	Get the coefficients of annular Zernike polynomials by fitting the wavefront surface.
ZernikeAnnularGrad(z, x, y, e, axis)	Evaluate the gradient of annular Zernike polynomials in a certain direction.
ZernikeAnnularJacobian(z, x, y, e, order)	Evaluate the Jacobian of annular Zernike polynomials in a certain order.
ZernikeEval(z, x, y)	Calculate the wavefront surface in the basis of Zernike polynomial.
ZernikeFit(s, x, y, numTerms)	Get the coefficients of Zernike polynomials by fitting the wavefront surface.
ZernikeGrad(z, x, y, axis)	Evaluate the gradient of Zernike polynomials in a certain axis.
ZernikeJacobian(z, x, y, order)	Evaluate the Jacobian of Zernike polynomials in a certain order.
ZernikeMaskedFit(s, x, y, numTerms, mask, e)	Fit the wavefront surface on pupil (e.g.
createInstDictFromConfig(config)	Create configuration dictionary for the instrument.
extractArray(inArray, dim)	Extract the central image.
getAmpImagesFromDir(rawExpDir)	Apply regular expression to find repackaged amplifier image files.
getBscDbType(bscDbType)	Get the bright star catalog (BSC) database type.
getCamNameFromCamType(camType)	Get the camera name for policy files from CamType.
getCamType(instName)	Get the camera type from instrument name.
getCamTypeFromButlerName(instName, detectorType)	Get the camera type from instrument name used by the LSST DM middleware for each instrument.
getCentroidFindType(centroidFindType)	Get the centroid find type.
getConfigDir()	Get the directory of configuration files.
getDeblendDonutType(deblendDonutType)	Get the deblend donut type.
getDefocalDisInMm(instName)	Get the defocal distance for the instrument
getDonutTemplateType(donutTemplateType)	Get the donut template type.
getFilterTypeFromBandLabel(bandLabel)	Get the FilterType associated with the name of the bandpass accessed in an exposure using exposure.filter.bandLabel.
getImageType(imageType)	Get the image type.
getModulePath()	Get the path of module.
getObsLsstCmdTaskConfigDir()	Get the obs_lsst command line task configuration directory.
mapFilterRefToG(filterType)	Map the reference filter to the G filter.
padArray(inArray, dim)	Extend the boundary of image.
plotZernike(zkIdx, zk, unit[, saveFilePath])	Plot the Zernike polynomials (zk).
readPhoSimSettingData(folderPath, fileName, ...)	Read the PhoSim setting data (segmentation or focal plane layout).
rotMatrix(thetaDegrees)	Create a 2-d rotation matrix for given angle.
runProgram(command[, binDir, argstring])	Run the program w/o arguments.
searchDonutPos(img)	Search the position of donut on image.
writeCleanUpRepoCmd(repoDir, runName)	Format a command line call to clean up the data created by a pipeline.
writeFile(filePath, content)	Write the content to file.
writePipetaskCmd(repoDir, runName, ...[, ...])	Format a command line call to run a Gen 3 pipeline task.

Classes

BscDbType(value[, names, module, qualname, ...])
CamType(value[, names, module, qualname, ...])
CentroidFindType(value[, names, module, ...])
DeblendDonutType(value[, names, module, ...])
DefocalType(value[, names, module, ...])
DonutTemplateType(value[, names, module, ...])
FilterType(value[, names, module, qualname, ...])
ImageType(value[, names, module, qualname, ...])

Contributing

To contribute, please start a new pull request on GitHub. Feature requests shall be filled in JIRA with ts_aos as the component. In all cases, reaching out to the contacts for this module is recommended.