WEP Developer Guide

Wavefront estimation pipeline (WEP) calculates the wavefront error in annular Zernike polynomials based on the intra- and extra-focal donut images.

Main Classes

Important classes:

• WfEstimator calculates the wavefront error in annular Zernike polynomials 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:

• BandLabel defines the type of active filter.

• 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

• Instrument: Class that defines the geometry, mask model, Batoid model, etc. for different telescopes.

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

• ImageMapper: Class that maps images between the pupil and image planes, and creates masks.

• 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.centroid

Figure 2 Class diagram of wep.centroid

This module finds the centroids of donuts.

• 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 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.

wep.estimation

Figure 3 Class diagram of wep.estimation

This module estimates the wavefront error.

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

• WfAlgorithm: Base class for algorithms that estimate Zernikes from donut images.

• WfAlgorithmFactory: Factory for creating the algorithm classes

• TieAlgorithm: Class that estimates Zernikes by solving the transport of intensity equation.

wep.deblend

This module does the image deblending.

Figure 4 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 5 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.

• EstimateZernikesBaseTask: Base class for EstimateZernikes subtasks that estimate the Zernike coefficients from donut images.

• EstimateZernikesBaseConfig: Configuration for EstimateZernikesBase.

• EstimateZernikesTieTask: Subtask that estimates Zernikes from stamps using the TIE algorithm.

• EstimateZernikesTieConfig: Configuration for EstimateZernikesTieTask.

• 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.

• maskUtils: Functions for generating a mask model for an instrument.

• 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.
Image(image, fieldAngle, defocalType[, ...])	Class to hold a donut image along with metadata.
ImageMapper([instConfig, opticalModel])	Class for mapping the pupil to the image plane, and vice versa.
Instrument([configFile, name, diameter, ...])	Object with relevant geometry of the primary mirror and focal plane.

lsst.ts.wep.centroid Package

Classes

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.

lsst.ts.wep.estimation Package

Classes

DanishAlgorithm([lstsqKwargs])	Wavefront estimation algorithm class for Danish.
TieAlgorithm([opticalModel, maxIter, ...])	Wavefront estimation algorithm class for the TIE solver.
WfAlgorithm()	Base class for wavefront estimation algorithms
WfAlgorithmFactory()	Factory for loading different wavefront estimation algorithms.
WfEstimator([algoName, algoConfig, ...])	Class providing a high-level interface for wavefront estimation.

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)	Base class for calculating Zernike coeffs from pairs of DonutStamps.
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.
EstimateZernikesBaseConfig(*args, **kw)
EstimateZernikesBaseTask(**kwargs)	Base class for estimating Zernike coefficients from DonutStamps.
EstimateZernikesDanishConfig(*args, **kw)	Danish-specific configuration parameters for Zernike estimation.
EstimateZernikesDanishTask(**kwargs)	Estimate Zernike coefficients using the TIE algorithm.
EstimateZernikesTieConfig(*args, **kw)	TIE-specific configuration parameters for Zernike estimation.
EstimateZernikesTieTask(**kwargs)	Estimate Zernike coefficients using the TIE algorithm.
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

centerWithTemplate(image, template[, rMax])	Center the image by correlating with the template.
conditionalSigmaClip(array, sigma[, stdMin, ...])	Apply conditional sigma clipping to an array.
configClass(config, classObj)	Configure the class.
convertHistoryToMetadata(history)	Convert algorithm history to be saved in task metadata.
convertMetadataToHistory(metadata)	Convert the history from the metadata back to original format.
convertZernikesToPsfWidth(zernikes[, ...])	Convert Zernike amplitudes to quadrature contribution to the PSF FWHM.
createGalsimZernike(zkCoeff[, jmin, obscuration])	Create a GalSim Zernike object with the given coefficients.
createTemplateForDetector(detector, defocalType)	Create a donut template for the given detector.
createZernikeBasis(u, v[, jmin, jmax, ...])	Create a basis of Zernike polynomials.
createZernikeGradBasis(u, v[, jmin, jmax, ...])	Create a basis of Zernike gradient polynomials.
extractArray(inArray, dim)	Extract the central image.
fitMaskModel(optic[, wavelength, deg, ...])	Fit the mask model for the telescope.
getAmpImagesFromDir(rawExpDir)	Apply regular expression to find repackaged amplifier image files.
getCameraFromButlerName(camName)	Get the proper camera object for the donuts.
getConfigDir()	Get the directory of configuration files.
getModulePath()	Get the path of module.
getObsLsstCmdTaskConfigDir()	Get the obs_lsst command line task configuration directory.
getOffsetFromExposure(exposure, camName, ...)	Get the offset from the exposure.
getPsfGradPerZernike([diameter, ...])	Get the gradient of the PSF FWHM with respect to each Zernike.
getTaskInstrument(camName, detectorName[, ...])	Get the instrument to use for the task.
getZernikeParity([jmin, jmax, axis])	Return the parity of the Zernike polynomials (Noll index >= 4).
mergeConfigWithFile(configFile, **kwargs)	Merge the passed keyword arguments with the values stored in the file.
padArray(inArray, dim)	Extend the boundary of image.
plotMapperResiduals(angle[, band, ...])	Plot the residuals between the ImageMapper and Batoid.
plotMaskFits(fitDict, dataDict)	Plot the results of the mask fitting.
plotPupilMaskElements(maskParams, fieldAngle)	Plot the mask elements as circles.
plotRoundTrip(fieldAngle, defocalType[, ...])	Plot a roundtrip of the ImageMapper
plotZernike(zkIdx, zk, unit[, saveFilePath])	Plot the Zernike polynomials (zk).
polygonContains(xGrid, yGrid, poly)	Return mask indicating if each point in the grid is inside the polygon.
printMaskModel(maskModel)	Print the yaml-formatted mask model.
pruneMaskModel(maskModel[, thetaMax, dTheta])	Prune the mask model so only necessary elements remain.
readConfigYaml(path[, recurseImports])	Read the config yaml file and return the corresponding dictionary.
readPhoSimSettingData(folderPath, fileName, ...)	Read the PhoSim setting data (segmentation or focal plane layout).
resolveRelativeConfigPath(path)	Resolve a relative config path into an absolute path.
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.
zernikeEval(u, v, zkCoeff[, jmin, obscuration])	Evaluate the Zernike series.
zernikeFit(u, v, z[, jmin, jmax, ...])	Fit Zernike polynomials to the surface.
zernikeGradEval(u, v, uOrder, vOrder, zkCoeff)	Evaluate the gradient of the Zernike series.

Classes

BandLabel(value[, names, module, qualname, ...])
BscDbType(value[, names, module, qualname, ...])
CentroidFindType(value[, names, module, ...])
DeblendDonutType(value[, names, module, ...])
DefocalType(value[, names, module, ...])
EnumDict(enum[, regularDict])	A dictionary that aliases Enums and their corresponding values.
ImageType(value[, names, module, qualname, ...])
PlaneType(value[, names, module, qualname, ...])	Specifies whether the image is on the image or pupil plane.
WfAlgorithmName(value[, names, module, ...])

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.