TieAlgorithm

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

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)

Attributes Summary

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.

opticalModel

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

requiresPairs

Whether the algorithm requires pairs to estimate Zernikes.

solver

The name of the TIE solver.

Methods Summary

estimateZk(I1[, I2, jmax, instrument, ...])

Return the wavefront Zernike coefficients in meters.

Attributes Documentation

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.

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.

opticalModel

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

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, jmax: int = 22, instrument: ~lsst.ts.wep.instrument.Instrument = <lsst.ts.wep.instrument.Instrument object>, startWithIntrinsic: bool = True, returnWfDev: bool = False, return4Up: bool = True, 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)

jmaxint, optional

The maximum Zernike Noll index to estimate. (the default is 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)

return4Upbool, optional

If True, the returned Zernike coefficients start with Noll index 4. If False, they follow the Galsim convention of starting with index 0 (which is meaningless), so the array index of the output corresponds to the Noll index. In this case, indices 0-3 are always set to zero, because they are not estimated by our pipeline. (the default is True)

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)