AnalyticOpticalElement

class poppy.AnalyticOpticalElement(shift_x=None, shift_y=None, rotation=None, inclination_x=None, inclination_y=None, **kwargs)

Bases: OpticalElement

Defines an abstract analytic optical element, i.e. one definable by some formula rather than by an input OPD or pupil file.

This class is useless on its own; instead use its various subclasses that implement appropriate get_opd and/or get_transmission functions. It exists mostly to provide some behaviors & initialization common to all analytic optical elements.

Parameters:

namestring, optional

Descriptive name.

verbosebool, optional

Whether to print verbose output. Default True.

oversampleint, optional

Oversampling factor for this plane. Default 1.

planetypePlaneType, optional

Type of the optical plane. Default PlaneType.unspecified.

transmission, opdstring

These are not allowed for Analytic optical elements, and this class will raise an error if you try to set one.

shift_x, shift_yastropy Quantity (length or angle, depending on plane type) or float, optional

Translations of this optic. Plain floats are interpreted in meters for pupil plane elements or arcseconds for image plane elements; astropy Quantities will be converted to the appropriate unit automatically.

rotationastropy Quantity angle or float, optional

Rotation of the optic around its center, in degrees counterclockwise, or an angular astropy Quantity. Note that if you apply both shift and rotation, the optic rotates around its own center, rather than the optical axis.

inclination_x, inclination_yfloat, optional

Inclination of the optic around the X or Y axis, in degrees. A non-zero inclination rescales the corresponding coordinate by 1/cos(inclination), simulating a tilted flat optic. It is physically inconsistent to set both at the same time.

Attributes Summary

shape

Return shape of the OpticalElement, as a tuple

Methods Summary

get_coordinates(wave)	Get coordinates of this optic, optionally including shifts
get_opd(wave)	Return the optical path difference, given a wavelength.
get_phasor(wave)	Compute a complex phasor from an OPD, given a wavelength.
get_transmission(wave)	Note that this is the amplitude transmission, not the total intensity transmission.
sample([wavelength, npix, grid_size, what, ...])	Sample the Analytic Optic onto a grid and return the array
to_fits([outname, what, wavelength, npix])	Save an analytic optic computed onto a grid to a FITS file

Attributes Documentation

shape

Methods Documentation

get_coordinates(wave)

Get coordinates of this optic, optionally including shifts

Method: Calls the supplied wave object’s coordinates() method, then checks for the existence of the following attributes: “shift_x”, “shift_y”, “rotation”, “inclination_x”, “inclination_y” If any of them are present, then the coordinates are modified accordingly.

Shifts are given by default implicitly in meters for pupil optics and arcseconds for image plane optics. Shifts may optionally also be given with explicit units using Astropy Quantities, which in this case must be convertible into meters or arcseconds as appropriate.

Rotations and inclinations are given implicitly in degrees.

For multiple transformations, the order of operations is:

shift, rotate, incline.

Parameters:

waveWavefront

Wavefront object defining the coordinate grid (pixel scale, shape, plane type).

Returns:

y, xndarrays

2D coordinate arrays in the plane of the optic, in meters (pupil) or arcseconds (image), after applying any shifts, rotation, and inclination.

get_opd(wave)

Return the optical path difference, given a wavelength.

In this base class instance, the wavefront parameter ‘wave’ is not used,

and the .opd attribute of the optic is returned directly. Subclasses may change this behavior, for instance to evaluate optical aberrations on the sampling defined for that wavefront, or to compute the wavelength-dependent aberrations of a refractive optic.

Parameters:

wavefloat or obj

either a scalar wavelength or a Wavefront object

Returns:

ndarray giving OPD in meters

get_phasor(wave)

Compute a complex phasor from an OPD, given a wavelength.

The returned value should be the complex phasor array as appropriate for multiplying by the wavefront amplitude.

Parameters:

wavefloat or Wavefront

Either a scalar wavelength in meters or a Wavefront object.

Returns:

phasorndarray

Complex phasor array suitable for multiplying the complex wavefront.

get_transmission(wave)

Note that this is the amplitude transmission, not the total intensity transmission.

sample(wavelength=<Quantity 1.e-06 m>, npix=512, grid_size=None, what='amplitude', return_scale=False, phase_unit='waves')

Sample the Analytic Optic onto a grid and return the array

Parameters:

wavelengthastropy.units.Quantity or float

Wavelength (in meters if unit not given explicitly)

npixinteger

Number of pixels for sampling the array

grid_sizefloat

Field of view grid size (diameter) for sampling the optic, in meters for pupil plane optics and arcseconds for image planes. Default value is taken from the optic’s properties, if defined. Otherwise defaults to 6.5 meters or 2 arcseconds depending on plane.

whatstring

What to return: optic ‘amplitude’ transmission, ‘intensity’ transmission, ‘phase’, ‘opd’, or ‘complex’ phasor. Note that the transmissions are returned as floating point values between 0 and 1, phase is returned as an angle with units depending on the value of phase_unit, the optical path difference ‘opd’ is given in meters, and the complex phasor is the product of the amplitude transmission and the complex exponential of the phase

phase_unitstring

Unit for returned phase array IF what==’phase’. One of ‘radians’, ‘waves’, ‘meters’. (‘meters’ option is deprecated; use what=’opd’ instead.)

return_scalebool

if True, will return a tuple containing the desired array and a float giving the pixel scale.

Returns:

output_arrayndarray

The sampled optic array.

pixel_scaleastropy Quantity

The pixel scale of the output array. Only returned if return_scale=True.

to_fits(outname=None, what='amplitude', wavelength=<Quantity 1.e-06 m>, npix=512, **kwargs)

Save an analytic optic computed onto a grid to a FITS file

The FITS file is returned to the calling function, and may optionally be saved directly to disk.

Parameters:

whatstring

What quantity to save. See the sample function of this class

wavelengthastropy Quantity length or float

Wavelength for evaluating the optic; passed to sample(), in meters (plain float) or an astropy Quantity.

npixinteger

Number of pixels.

outnamestring, optional

Filename to write out a FITS file to disk

See the sample() function for additional optional parameters.

Returns:

hdulastropy.io.fits.HDUList

FITS HDUList containing the sampled optic data and header metadata.