Instrument

class lsst.ts.wep.Instrument(configFile: Optional[Union[Path, str]] = 'policy:instruments/LsstCam.yaml', *, name: Optional[str] = None, diameter: Optional[float] = None, obscuration: Optional[float] = None, focalLength: Optional[float] = None, defocalOffset: Optional[float] = None, pixelSize: Optional[float] = None, refBand: Optional[Union[BandLabel, str]] = None, wavelength: Optional[Union[float, dict]] = None, batoidModelName: Optional[str] = None, batoidOffsetOptic: Optional[str] = None, batoidOffsetValue: Optional[float] = None, maskParams: Optional[dict] = 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)

diameterfloat, 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)

obscurationfloat, 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)

focalLengthfloat, 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)

defocalOffsetfloat, optional

The defocal offset of the images in meters. If None, but batoidModelName, batoidOffsetOptic, and batoidOffsetValue are set, this value will be calculated using the Batoid model. (the default is None)

pixelSizefloat, optional

The pixel size in meters. (the default is None)

refBandBandLabel 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)

wavelengthfloat 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)

batoidModelNamestr, 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)

batoidOffsetOpticstr or None, optional

The optic to offset in the Batoid model in order to calculate the equivalent detector offset for the model. (the default is None)

batoidOffsetValuefloat or None, optional

The value in meters to offset the optic in the Batoid model to calculate the equivalent detector offset for the model. The detector offset is then used for everything else. Note that depending on the model, the sign of this value might matter. (the default is None)

maskParamsdict, 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 that is offset in the Batoid model.
batoidOffsetValue	Amount in meters the optic is 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.
getBatoidModel([band])	Return the Batoid model for the instrument and the requested band.
getIntrinsicZernikes(xAngle, yAngle[, band, ...])	Return the intrinsic Zernikes associated with the optical design.
getOffAxisCoeff(xAngle, yAngle, defocalType)	Return the Zernike coefficients associated with the off-axis model.

Attributes Documentation

area

The primary mirror area in square meters.

batoidModelName

The Batoid model name.

batoidOffsetOptic

The optic that is offset in the Batoid model.

batoidOffsetValue

Amount in meters the optic is 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).

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() → None

Access every attribute to make sure no errors are thrown.

clearCaches() → None

Clear the Batoid caches.

copy() → Instrument

Return a deep copy of the instrument.

Notes

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

createImageGrid(nPixels: int) → Tuple[ndarray, ndarray]

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

nPixelsint

The number of pixels on a side.

Returns

np.ndarray

The 2D u-grid on the image plane

np.ndarray

The 2D v-grid on the image plane

createPupilGrid() → Tuple[ndarray, ndarray]

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.

Returns

np.ndarray

The 2D u-grid on the pupil plane

np.ndarray

The 2D v-grid on the pupil plane

getBatoidModel(band: Union[BandLabel, str] = BandLabel.REF) → Optic

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

Parameters

bandBandLabel 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)

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

Return the intrinsic Zernikes associated with the optical design.

Parameters

xAnglefloat

The x-component of the field angle in degrees.

yAnglefloat

The y-component of the field angle in degrees.

bandBandLabel 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)

nollIndicesnp.ndarray, optional

Noll indices for which to return Zernikes. (the default is indices 4-78)

Returns

np.ndarray

The Zernike coefficients in meters

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

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

Parameters

xAnglefloat

The x-component of the field angle in degrees.

yAnglefloat

The y-component of the field angle in degrees.

defocalTypeDefocalType or str

The DefocalType Enum or corresponding string, specifying which side of focus to model.

bandBandLabel 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)

nollIndicesModelnp.ndarray, optional

Noll indices of Zernikes retrieved for the off-axis model. (the default is indices 4-78)

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

np.ndarray

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