Instrument#

class lsst.ts.wep.Instrument(configFile='policy:instruments/LsstCam.yaml', *, name=None, diameter=None, obscuration=None, focalLength=None, defocalOffset=None, pixelSize=None, refBand=None, wavelength=None, batoidModelName=None, batoidOffsetOptic=None, batoidOffsetValue=None, maskParams=None)#

Bases: object

Object with relevant geometry of the primary mirror and focal plane.

The value of every parameter is first pulled from the configFile, and then overridden by any parameters explicitly passed as keyword arguments to the class constructor.

Parameters:

  • configFile (Path or str, optional) – Path to file specifying values for the other parameters. If the path starts with “policy:”, it will look in the policy directory. Any explicitly passed parameters override values found in this file (the default is policy:instruments/LsstCam.yaml)

  • name (str, optional) – The name of the instrument. (the default is None)

  • diameter (float, optional) – The diameter of the primary mirror in meters. If None, but batoidModelName is set, this value will be pulled from the Batoid model. (the default is None)

  • obscuration (float, optional) – The fractional obscuration of the primary mirror. If None, but batoidModelName is set, this value will be pulled from the Batoid model. (the default is None)

  • focalLength (float, optional) – The effective focal length in meters. If None, but batoidModelName is set, this value will be pulled from the Batoid model. (the default is None)

  • defocalOffset (float, optional) – The defocal offset of the images in meters. This is the equivalent single-Detector offset used for all downstream geometry (e.g. donut radius, pupil offset, image mapping). This is mutually exclusive with batoidOffsetOptic/batoidOffsetValue: either set defocalOffset directly, OR set the batoid offset parameters to derive it from the Batoid model, but not both. (the default is None)

  • pixelSize (float, optional) – The pixel size in meters. (the default is None)

  • refBand (BandLabel or str, optional) – When getting the wavelength or loading the Batoid model, use this value in place of BandLabel.REF. It should be a BandLabel Enum, or one of the corresponding strings. If set to None, this value defaults to BandLabel.REF. (the default is None)

  • wavelength (float or dict, optional) – The effective wavelength of the instrument in meters. Can be a float, or a dictionary that corresponds to different bands. The keys in this dictionary are expected to correspond to the strings specified in the BandLabel enum in ts_wep.utils.enums. If set to None, this defaults to {BandLabel.REF: 500e-9}. (the default is None)

  • batoidModelName (str, optional) – Name of Batoid model. If the string contains “{band}”, it is assumed there are different Batoid models for different photometric bands, and the names of these bands will be filled in at runtime using the strings specified in the BandLabel enum in jf_wep.utils.enums. (the default is None)

  • batoidOffsetOptic (str, list of str, or None, optional) – The optic(s) to offset in the Batoid model in order to calculate the equivalent detector offset for the model. A single string is accepted, or a list of strings to offset multiple optics simultaneously (e.g. to model both a camera and detector piston for Full Array Mode). (the default is None)

  • batoidOffsetValue (float, list of float, or None, optional) – The value(s) in meters to offset the optic(s) in the Batoid model. When defocalOffset is not set directly, it is derived from the resulting combined shift. If a list is provided, its length must match batoidOffsetOptic, and each optic is offset by its corresponding value. Note that depending on the model, the sign of this value might matter. (the default is None)

  • maskParams (dict, optional) –

    Dictionary of mask parameters. Each key in this dictionary corresponds to a different mask element. The corresponding values are dictionaries that define circles with different centers and radii. The key, value pairs are

    • thetaMin: the minimum field angle in degrees for which this mask

    element is relevant - center: list of polynomial coeffs (in meters) for np.polyval() to determine the center of the circle - radius: list of polynomial coeffs (in meters) for np.polyval() to determine the radius of the circle

    None defaults to an empty dictionary.

Notes

The following parameters are required to instantiate the Instrument:

  • diameter

  • obscuration

  • focalLength

  • defocalOffset

  • pixelSize

With the exception of pixelSize, if not explicitly set, these parameters can be pulled from the Batoid model specified by batoidModelName. Note that the calculation of defocalOffset also requires that batoidOffsetOptic and batoidOffsetValue are set.

Attributes Summary

area

The primary mirror area in square meters.

batoidModelName

The Batoid model name.

batoidOffsetOptic

The optic(s) that are offset in the Batoid model.

batoidOffsetValue

Amount(s) in meters the optic(s) are offset in the Batoid model.

defocalOffset

The defocal offset in meters.

diameter

The primary mirror diameter in meters.

donutDiameter

The expected donut diameter in pixels.

donutRadius

The expected donut radius in pixels.

focalLength

The focal length in meters.

focalRatio

The f-number.

maskParams

The mask parameter dictionary.

nPupilPixels

The number of pupil pixels (on a side).

name

The name of the instrument.

obscuration

The fractional obscuration.

pixelScale

The pixel scale in arcseconds per pixel.

pixelSize

The pixel size in meters.

pupilOffset

The pupil offset in meters.

radius

The primary mirror radius in meters.

refBand

Band to use with Batoid and wavelength when band == BandLabel.REF

wavelength

Return the effective wavelength(s) in meters.

Methods Summary

checkConfig()

Access every attribute to make sure no errors are thrown.

clearCaches()

Clear the Batoid caches.

copy()

Return a deep copy of the instrument.

createImageGrid(nPixels)

Create an (nPixel x nPixel) grid for the image.

createPupilGrid()

Create a grid for the pupil.

createZernikeBasis(jmax)

createZernikeGradBasis(jmax)

getBatoidModel([band])

Return the Batoid model for the instrument and the requested band.

getIntrinsicZernikes(xAngle, yAngle[, ...])

Return the intrinsic Zernikes associated with the optical design.

getOffAxisCoeff(xAngle, yAngle, defocalType)

Return the Zernike coefficients associated with the off-axis model.

offsetToZ4Defocus(offset)

Convert the defocus offset to Z4.

Attributes Documentation

area#

The primary mirror area in square meters.

batoidModelName#

The Batoid model name.

batoidOffsetOptic#

The optic(s) that are offset in the Batoid model.

Always returned as a list (or None), even when a single optic is set.

batoidOffsetValue#

Amount(s) in meters the optic(s) are offset in the Batoid model.

Always returned as a list (or None), even when a single value is set.

defocalOffset#

The defocal offset in meters.

This is the equivalent single-Detector offset used for all downstream geometry. It is resolved as either:

  1. The value set explicitly via the setter, or

  2. A value derived from the Batoid model by shifting each batoidOffsetOptic by its batoidOffsetValue and solving for the equivalent Detector offset (cached after the first computation).

These two sources are mutually exclusive (enforced by checkConfig). A ValueError is raised if neither is available.

diameter#

The primary mirror diameter in meters.

donutDiameter#

The expected donut diameter in pixels.

donutRadius#

The expected donut radius in pixels.

focalLength#

The focal length in meters.

focalRatio#

The f-number.

maskParams#

The mask parameter dictionary.

nPupilPixels#

The number of pupil pixels (on a side).

This number is set so that the resolution of the pupil roughly matches the resolution of the image.

name#

The name of the instrument.

obscuration#

The fractional obscuration.

pixelScale#

The pixel scale in arcseconds per pixel.

pixelSize#

The pixel size in meters.

pupilOffset#

The pupil offset in meters.

radius#

The primary mirror radius in meters.

refBand#

Band to use with Batoid and wavelength when band == BandLabel.REF

wavelength#

Return the effective wavelength(s) in meters.

Methods Documentation

checkConfig()#

Access every attribute to make sure no errors are thrown.

Return type:

None

clearCaches()#

Clear the Batoid caches.

Return type:

None

copy()#

Return a deep copy of the instrument.

Return type:

Instrument

Notes

Any cached data from the original instrument will need to be repopulated in the copied instrument.

createImageGrid(nPixels)#

Create an (nPixel x nPixel) grid for the image.

The coordinates of the grid are in normalized image coordinates. These coordinates are defined such that u^2 + v^2 = 1 is the outer edge of the unaberrated donut, and u^2 + v^2 = obscuration^2 is the inner edge.

Parameters:

nPixels (int) – The number of pixels on a side.

Return type:

tuple[ndarray, ndarray]

Returns:

  • np.ndarray – The 2D u-grid on the image plane

  • np.ndarray – The 2D v-grid on the image plane

createPupilGrid()#

Create a grid for the pupil.

The coordinates of the grid are in normalized pupil coordinates. These coordinates are defined such that u^2 + v^2 = 1 is the outer edge of the pupil, and u^2 + v^2 = obscuration^2 is the inner edge.

The number of pixels is chosen to match the resolution of the image.

Return type:

tuple[ndarray, ndarray]

Returns:

  • np.ndarray – The 2D u-grid on the pupil plane

  • np.ndarray – The 2D v-grid on the pupil plane

createZernikeBasis(jmax)#
Parameters:

jmax (int)

Return type:

ndarray

createZernikeGradBasis(jmax)#
Parameters:

jmax (int)

Return type:

ndarray

getBatoidModel(band=BandLabel.REF)#

Return the Batoid model for the instrument and the requested band.

Parameters:

band (BandLabel or str, optional) – The BandLabel Enum or corresponding string, specifying which Batoid model to load. Only relevant if self.batoidModelName contains “{band}”. (the default is BandLabel.REF)

Return type:

Optic

getIntrinsicZernikes(xAngle, yAngle, defocalType=None, band=BandLabel.REF, nollIndices=(np.int64(4), np.int64(5), np.int64(6), np.int64(7), np.int64(8), np.int64(9), np.int64(10), np.int64(11), np.int64(12), np.int64(13), np.int64(14), np.int64(15), np.int64(16), np.int64(17), np.int64(18), np.int64(19), np.int64(20), np.int64(21), np.int64(22), np.int64(23), np.int64(24), np.int64(25), np.int64(26), np.int64(27), np.int64(28), np.int64(29), np.int64(30), np.int64(31), np.int64(32), np.int64(33), np.int64(34), np.int64(35), np.int64(36), np.int64(37), np.int64(38), np.int64(39), np.int64(40), np.int64(41), np.int64(42), np.int64(43), np.int64(44), np.int64(45), np.int64(46), np.int64(47), np.int64(48), np.int64(49), np.int64(50), np.int64(51), np.int64(52), np.int64(53), np.int64(54), np.int64(55), np.int64(56), np.int64(57), np.int64(58), np.int64(59), np.int64(60), np.int64(61), np.int64(62), np.int64(63), np.int64(64), np.int64(65), np.int64(66), np.int64(67), np.int64(68), np.int64(69), np.int64(70), np.int64(71), np.int64(72), np.int64(73), np.int64(74), np.int64(75), np.int64(76), np.int64(77), np.int64(78)))#

Return the intrinsic Zernikes associated with the optical design.

Parameters:

  • xAngle (float) – The x-component of the field angle in degrees.

  • yAngle (float) – The y-component of the field angle in degrees.

  • defocalType (DefocalType or str or None) – The DefocalType Enum or corresponding string, specifying which side of focus to model. If None, the model is not defocused.

  • band (BandLabel or str, optional) – The BandLabel Enum or corresponding string, specifying which batoid model to load. Only relevant if self.batoidModelName contains “{band}”. (the default is BandLabel.REF)

  • nollIndices (np.ndarray, optional) – Noll indices for which to return Zernikes. (the default is indices 4-78)

Returns:

The Zernike coefficients in meters

Return type:

np.ndarray

getOffAxisCoeff(xAngle, yAngle, defocalType, band=BandLabel.REF, nollIndicesModel=(np.int64(4), np.int64(5), np.int64(6), np.int64(7), np.int64(8), np.int64(9), np.int64(10), np.int64(11), np.int64(12), np.int64(13), np.int64(14), np.int64(15), np.int64(16), np.int64(17), np.int64(18), np.int64(19), np.int64(20), np.int64(21), np.int64(22), np.int64(23), np.int64(24), np.int64(25), np.int64(26), np.int64(27), np.int64(28), np.int64(29), np.int64(30), np.int64(31), np.int64(32), np.int64(33), np.int64(34), np.int64(35), np.int64(36), np.int64(37), np.int64(38), np.int64(39), np.int64(40), np.int64(41), np.int64(42), np.int64(43), np.int64(44), np.int64(45), np.int64(46), np.int64(47), np.int64(48), np.int64(49), np.int64(50), np.int64(51), np.int64(52), np.int64(53), np.int64(54), np.int64(55), np.int64(56), np.int64(57), np.int64(58), np.int64(59), np.int64(60), np.int64(61), np.int64(62), np.int64(63), np.int64(64), np.int64(65), np.int64(66), np.int64(67), np.int64(68), np.int64(69), np.int64(70), np.int64(71), np.int64(72), np.int64(73), np.int64(74), np.int64(75), np.int64(76), np.int64(77), np.int64(78)), nollIndicesIntr=(np.int64(4), np.int64(5), np.int64(6), np.int64(7), np.int64(8), np.int64(9), np.int64(10), np.int64(11), np.int64(12), np.int64(13), np.int64(14), np.int64(15), np.int64(16), np.int64(17), np.int64(18), np.int64(19), np.int64(20), np.int64(21), np.int64(22), np.int64(23), np.int64(24), np.int64(25), np.int64(26), np.int64(27), np.int64(28), np.int64(29), np.int64(30), np.int64(31), np.int64(32), np.int64(33), np.int64(34), np.int64(35), np.int64(36), np.int64(37), np.int64(38), np.int64(39), np.int64(40), np.int64(41), np.int64(42), np.int64(43), np.int64(44), np.int64(45), np.int64(46), np.int64(47), np.int64(48), np.int64(49), np.int64(50), np.int64(51), np.int64(52), np.int64(53), np.int64(54), np.int64(55), np.int64(56), np.int64(57), np.int64(58), np.int64(59), np.int64(60), np.int64(61), np.int64(62), np.int64(63), np.int64(64), np.int64(65), np.int64(66), np.int64(67), np.int64(68), np.int64(69), np.int64(70), np.int64(71), np.int64(72), np.int64(73), np.int64(74), np.int64(75), np.int64(76), np.int64(77), np.int64(78)))#

Return the Zernike coefficients associated with the off-axis model.

Parameters:

  • xAngle (float) – The x-component of the field angle in degrees.

  • yAngle (float) – The y-component of the field angle in degrees.

  • defocalType (DefocalType or str or None) – The DefocalType Enum or corresponding string, specifying which side of focus to model. If None, the model is not defocused.

  • band (BandLabel or str, optional) – The BandLabel Enum or corresponding string, specifying which batoid model to load. Only relevant if self.batoidModelName contains “{band}”. (the default is BandLabel.REF)

  • nollIndicesModel (np.ndarray, optional) – Noll indices of Zernikes retrieved for the off-axis model. (the default is indices 4-78)

  • nollIndicesIntr (np.ndarray, optional) – Noll indices of Zernikes you are estimating in the TIE or Danish. The off-axis coefficients are calculated by retrieving coefficients from batoid.zernikeTA, and then subtracting off the intrinsic Zernikes for Noll indices you are estimating. This is allows you to determine whether intrinsic Zernikes are included in wavefront estimates when using WfEstimator. (the default is indices 4-22).

Returns:

The Zernike coefficients in meters, for Noll indices >= 4

Return type:

np.ndarray

offsetToZ4Defocus(offset)#

Convert the defocus offset to Z4.

Parameters:

offset (float) – The defocus offset in meters.

Returns:

The Z4 value in meters.

Return type:

float