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:

name, verbose, oversample, planetypevarious

Same as for OpticalElement

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_yOptional floats

Translations of this optic, given in meters relative to the optical axis for pupil plane elements, or arcseconds relative to the optical axis for image plane elements.

rotationOptional float

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

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

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 obj

either a scalar wavelength or a Wavefront object

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’, or ‘opd’. Note that optical path difference, OPD, is given in meters.

phase_unitstring

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

return_scalefloat

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

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

wavelengthfloat

Wavelength in meters.

npixinteger

Number of pixels.

outnamestring, optional

Filename to write out a FITS file to disk

See the sample() function for additional optional parameters.