TieAlgorithm

class lsst.ts.wep.estimation.TieAlgorithm(opticalModel: str = 'offAxis', maxIter: int = 30, compSequence: Iterable = (4, 4, 6, 6, 13, 13, 13, 13, 22, 22, 22, 22), compGain: float = 0.6, centerTol: float = 1e-09, centerBinary: bool = True, convergeTol: float = 1e-09, maskKwargs: Optional[dict] = None, modelPupilKernelSize: float = 2, binning: int = 1, requireConverge: bool = False)

Bases: WfAlgorithm

Wavefront estimation algorithm class for the TIE solver.

The following sources discuss the details of the TIE algorithm: - https://sitcomtn-111.lsst.io - Xin (2015): http://arxiv.org/abs/1506.04839

Parameters

opticalModelstr, optional

The optical model to use for mapping between the image and pupil planes. Can be “offAxis”, “onAxis”, or “paraxial”. offAxis is a numerical model that is valid for all optical systems, but requires an accurate Batoid model. onAxis is an analytic model that is valid for all optical systems near the optical axis. paraxial is an analytic model that is valid for slow optical systems near the optical axis. offAxis is recommended when you have a Batoid model and onAxis is recommended when you do not. paraxial is primarily meant for testing (the default is “offAxis”) (the default is “offAxis”)

maxIterint, optional

The maximum number of iterations of the TIE loop. (the default is 30)

compSequenceiterable, optional

An iterable that determines the maximum Noll index to compensate on each iteration of the TIE loop. For example, if compSequence = [4, 10], then on the first iteration, only Zk4 is used in image compensation and on iteration 2, Zk4-Zk10 are used. Once the end of the sequence has been reached, all Zernike coefficients are used during compensation. (the default is (4, 4, 6, 6, 13, 13, 13, 13, 22, 22, 22, 22))

compGainfloat, optional

The gain used to update the Zernikes for image compensation. (the default is 0.6)

centerTolfloat, optional

The maximum absolute change in any Zernike amplitude (in meters) for which the images need to be recentered. A smaller value causes the images to be recentered more often. If 0, images are recentered on every iteration. (the default is 1e-9)

centerBinarybool, optional

Whether to use a binary template when centering the image. (the default is True)

convergeTolfloat, optional

The maximum absolute change in any Zernike amplitude (in meters) between subsequent TIE iterations below which convergence is declared and iteration is stopped. (the default is 1e-9)

maskKwargsdict or None, optional

Dictionary of mask keyword arguments to pass to mask creation. To see possibilities, see the docstring for lsst.ts.wep.imageMapper.ImageMapper.createPupilMasks(). (the default is None)

modelPupilKernelSizefloat, optional

The size of the Gaussian kernel to convolve with the model pupil when estimating Zernikes with a single donut. (the default is 2)

binningint, optional

Binning factor to apply to the donut stamps before estimating Zernike coefficients. The default value of 1 means no binning. (the default is 1)

requireConvergebool, optional

Whether to require that the TIE converges. If True, and the TIE did not converge, the TIE returns NaNs. (the default is False)

Attributes Summary

binning	The binning factor to apply to donut stamps.
centerBinary	Whether to center donuts using a binary template.
centerTol	Max abs.
compGain	The compensation gain for the TIE loop.
compSequence	The compensation sequence for the TIE loop.
convergeTol	Mean abs.
history	The algorithm history.
maskKwargs	Mask keyword arguments to pass to ImageMapper.createPupilMasks().
maxIter	The maximum number of iterations in the TIE loop.
modelPupilKernelSize	Return the Gaussian kernel size for the model pupil.
opticalModel	The optical model to use for mapping the image to the pupil.
requireConverge	Whether to require that the TIE converges.
requiresPairs	Whether the algorithm requires pairs to estimate Zernikes.
solver	The name of the TIE solver.

Methods Summary

estimateZk(I1[, I2, nollIndices, ...])

Return the wavefront Zernike coefficients in meters.

Attributes Documentation

binning

The binning factor to apply to donut stamps.

centerBinary

Whether to center donuts using a binary template.

centerTol

Max abs. deviation in Zernike coeff. that requires re-centering.

compGain

The compensation gain for the TIE loop.

compSequence

The compensation sequence for the TIE loop.

convergeTol

Mean abs. deviation in Zernikes (meters) at which TIE terminates.

history

The algorithm history.

The history is a dictionary saving the intermediate products from each iteration of the TIE solver.

The initial products before the iteration begins are stored in history[0], which is a dictionary with the keys:

• “intraInit” - the initial intrafocal image

• “extraInit” - the initial extrafocal image

• “zkStartIntra” - the starting intrafocal Zernikes

• “zkStartExtra” - the starting extrafocal Zernikes

• “zkStartMean” - the mean of the starting Zernikes. Note these

  Zernikes are added to zkBest to estimate the full OPD.

• “pupil” - model pupil image, in the case where only one image

  was passed to the estimator.

• “nollIndices” - array of Noll indices corresponding to the

  estimated Zernikes values.

Each iteration of the solver is then stored under indices >= 1. The entry for each iteration is also a dictionary, containing the following keys:

• “intraComp” - the compensated intrafocal image

• “extraComp” - the compensated extrafocal image

• “I0” - the estimate of the beam intensity on the pupil

• “dIdz” - estimate of z-derivative of intensity across the pupil

• “zkCompIntra” - Zernikes for compensating the intrafocal image

• “zkCompExtra” - Zernikes for compensating the extrafocal image

• “zkResid” - the estimated residual Zernikes

• “zkBest” - the best cumulative estimate the wavefront residual.

• “zkSum” - the sum of zkBest and zkStartMean from history[0].

  This is the best estimate of the OPD at the end of this iteration.

• “converged” - flag indicating if Zernike estimation has converged

• “caustic” - flag indicating if a caustic has been hit

Note the units for all Zernikes are in meters, and the z-derivative in dIdz is also in meters. Furthermore, all Zernikes start with Noll index 4.

maskKwargs

Mask keyword arguments to pass to ImageMapper.createPupilMasks().

maxIter

The maximum number of iterations in the TIE loop.

modelPupilKernelSize

Return the Gaussian kernel size for the model pupil.

opticalModel

The optical model to use for mapping the image to the pupil.

requireConverge

Whether to require that the TIE converges.

requiresPairs

Whether the algorithm requires pairs to estimate Zernikes.

solver

The name of the TIE solver.

Methods Documentation

estimateZk(I1: ~lsst.ts.wep.image.Image, I2: ~typing.Optional[~lsst.ts.wep.image.Image] = None, nollIndices: ~typing.Sequence = (4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22), instrument: ~lsst.ts.wep.instrument.Instrument = <lsst.ts.wep.instrument.Instrument object>, startWithIntrinsic: bool = True, returnWfDev: bool = False, units: str = 'm', saveHistory: bool = False) → ndarray

Return the wavefront Zernike coefficients in meters.

Parameters

I1DonutStamp

An Image object containing an intra- or extra-focal donut image.

I2DonutStamp, optional

A second image, on the opposite side of focus from I1. (the default is None)

nollIndicesSequence, optional

List, tuple, or array of Noll indices for which you wish to estimate Zernike coefficients. Note these values must be unique, ascending, and >= 4. (the default is indices 4-22)

instrumentInstrument, optional

The Instrument object associated with the DonutStamps. (the default is the default Instrument)

startWithIntrinsicbool, optional

Whether to start the Zernike estimation process from the intrinsic Zernikes rather than zero. (the default is True)

returnWfDevbool, optional

If False, the full OPD is returned. If True, the wavefront deviation is returned. The wavefront deviation is defined as the OPD - intrinsic Zernikes. (the default is False)

unitsstr, optional

Units in which the Zernike amplitudes are returned. Options are “m”, “nm”, “um”, or “arcsecs”. (the default is “m”)

saveHistorybool, optional

Whether to save the algorithm history in the self.history attribute. If True, then self.history contains information about the most recent time the algorithm was run. (the default is False)

Returns

np.ndarray

Zernike coefficients estimated from the image (or pair of images)