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

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, jmax: int = 78, return4Up: bool = True) → 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)
jmaxint, optional: The maximum Noll index of the intrinsic Zernikes. (the default is 78)
return4Upbool, optional: Whether to only return the coefficients for Noll indices >= 4. (the default is True)

Returns:

np.ndarray: The Zernike coefficients in meters

getOffAxisCoeff(xAngle: float, yAngle: float, defocalType: DefocalType, band: Union[BandLabel, str] = BandLabel.REF, jmax: int = 78, jmaxIntrinsic: int = 78, return4Up: bool = True) → 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)
jmaxint, optional: The maximum Noll index of the off-axis model Zernikes. (the default is 78)
jmaxIntrinsicint, optional: The off-axis coefficients are calculated by subtracting the intrinsic Zernikes from batoid.zernikeTA. This value sets the maximum Noll index of the intrinsic Zernikes that are subtracted from batoid.zernikeTA. It is usually the jmax of the Zernikes being estimated by the wavefront estimators. (the default is 78)
return4Upbool, optional: Whether to only return the coefficients for Noll indices >= 4. (the default is True)

Returns:

np.ndarray: The Zernike coefficients in meters, for Noll indices >= 4

Navigation

Instrument¶