API Reference

poppy Package

Physical Optics Propagation in PYthon (POPPY)

POPPY is a Python package that simulates physical optical propagation including diffraction. It implements a flexible framework for modeling Fraunhofer (far-field) diffraction and point spread function formation, particularly in the context of astronomical telescopes. POPPY was developed as part of a simulation package for JWST, but is more broadly applicable to many kinds of imaging simulations.

Developed by Marshall Perrin and colleagues at STScI, for use simulating the James Webb Space Telescope and other NASA missions.

Documentation can be found online at https://poppy-optics.readthedocs.io/

Functions

display_psf(HDUlist_or_filename[, ext, …])	Display nicely a PSF from a given hdulist or filename
display_psf_difference([…])	Display nicely the difference of two PSFs from given files
display_ee([HDUlist_or_filename, ext, …])	Display Encircled Energy curve for a PSF
measure_ee([HDUlist_or_filename, ext, …])	measure encircled energy vs radius and return as an interpolator
measure_radius_at_ee([HDUlist_or_filename, …])	measure encircled energy vs radius and return as an interpolator Returns a function object which when called returns the radius for a given Encircled Energy.
display_profiles([HDUlist_or_filename, ext, …])	Produce two plots of PSF radial profile and encircled energy
radial_profile([hdulist_or_filename, ext, …])	Compute a radial profile of the image.
measure_radial([HDUlist_or_filename, ext, …])	measure azimuthally averaged radial profile of a PSF.
measure_fwhm(HDUlist_or_filename[, ext, …])	Improved version of measuring FWHM, without any binning of image data.
measure_sharpness([HDUlist_or_filename, ext])	Compute image sharpness, the sum of pixel squares.
measure_centroid([HDUlist_or_filename, ext, …])	Measure the center of an image via center-of-mass
measure_strehl([HDUlist_or_filename, ext, …])	Measure Strehl for a PSF
measure_anisotropy([HDUlist_or_filename, …])
specFromSpectralType(sptype[, return_list, …])	Get Pysynphot Spectrum object from a user-friendly spectral type string.
fixed_sampling_optic(optic, wavefront[, …])	Convert a variable-sampling AnalyticOpticalElement to a fixed-sampling ArrayOpticalElement

Classes

Instrument([name])	A generic astronomical instrument, composed of
Wavefront([wavelength, npix, dtype, diam, …])	Wavefront in the Fraunhofer approximation: a monochromatic wavefront that can be transformed between pupil and image planes only, not to intermediate planes
OpticalSystem([name, verbose, oversample, …])	A class representing a series of optical elements, either Pupil, Image, or Detector planes, through which light can be propagated.
CompoundOpticalSystem([optsyslist, name])	A concatenation of two or more optical systems, acting as a single larger optical system.
OpticalElement([name, verbose, planetype, …])	Base class for all optical elements, whether from FITS files or analytic functions.
ArrayOpticalElement([opd, transmission, …])	Defines an arbitrary optic, based on amplitude transmission and/or OPD given as numpy arrays.
FITSOpticalElement([name, transmission, …])	Defines an arbitrary optic, based on amplitude transmission and/or OPD FITS files.
Rotation([angle, units, hide])	Performs a rotation of the axes in the optical train.
Detector([pixelscale, fov_pixels, …])	A Detector is a specialized type of OpticalElement that forces a wavefront onto a specific fixed pixelization of an Image plane.
AnalyticOpticalElement([shift_x, shift_y, …])	Defines an abstract analytic optical element, i.e.
ScalarTransmission([name, transmission])	Uniform transmission between 0 and 1.0 in intensity.
InverseTransmission([optic])	Given any arbitrary OpticalElement with transmission T(x,y) return the inverse transmission 1 - T(x,y)
BandLimitedCoron	alias of poppy.optics.BandLimitedCoronagraph
BandLimitedCoronagraph([name, kind, sigma, …])	Defines an ideal band limited coronagraph occulting mask.
IdealFQPM([name, wavelength])	Defines an ideal 4-quadrant phase mask coronagraph, with its retardance set perfectly to 0.5 waves at one specific wavelength and varying linearly on either side of that.
CircularPhaseMask([name, radius, …])	Circular phase mask coronagraph, with its retardance set perfectly at one specific wavelength and varying linearly on either side of that.
RectangularFieldStop([name, width, height])	Defines an ideal rectangular field stop
SquareFieldStop([name, size])	Defines an ideal square field stop
AnnularFieldStop([name, radius_inner, …])	Defines a circular field stop with an (optional) opaque circular center region
HexagonFieldStop([name, side, diameter, …])	Defines an ideal hexagonal field stop
CircularOcculter([name, radius])	Defines an ideal circular occulter (opaque circle)
BarOcculter([name, width, height])	Defines an ideal bar occulter (like in MIRI’s Lyot coronagraph)
FQPM_FFT_aligner([name, direction])	Helper class for modeling FQPMs accurately
CircularAperture([name, radius, pad_factor, …])	Defines an ideal circular pupil aperture
HexagonAperture([name, side, diameter, …])	Defines an ideal hexagonal pupil aperture
MultiHexagonAperture([name, flattoflat, …])	Defines a hexagonally segmented aperture
NgonAperture([name, nsides, radius, rotation])	Defines an ideal N-gon pupil aperture.
RectangleAperture([name, width, height, …])	Defines an ideal rectangular pupil aperture
SquareAperture([name, size])	Defines an ideal square pupil aperture
SecondaryObscuration([name, …])	Defines the central obscuration of an on-axis telescope including secondary mirror and supports
AsymmetricSecondaryObscuration([…])	Defines a central obscuration with one or more supports which can be oriented at arbitrary angles around the primary mirror, a la the three supports of JWST
ThinLens([name, nwaves, …])	An idealized thin lens, implemented as a Zernike defocus term.
GaussianAperture([name, fwhm, w, pupil_diam])	Defines an ideal Gaussian apodized pupil aperture, or at least as much of one as can be fit into a finite-sized array
KnifeEdge([name, rotation])	A half-infinite opaque plane, with a perfectly sharp edge through the origin.
CompoundAnalyticOptic([opticslist, name, …])	Define a compound analytic optical element made up of the combination of two or more individual optical elements.
QuadPhase([z, planetype, name])	Quadratic phase factor, q(z) suitable for representing a radially-dependent wavefront curvature.
QuadraticLens([f_lens, planetype, name])	Gaussian Lens
FresnelWavefront(beam_radius[, units, …])	Wavefront for Fresnel diffraction calculation.
FresnelOpticalSystem([name, pupil_diameter, …])	Class representing a series of optical elements, through which light can be propagated using the Fresnel formalism.
WavefrontError(**kwargs)	A base class for different sources of wavefront error
ParameterizedWFE([name, coefficients, …])	Define an optical element in terms of its distortion as decomposed into a set of orthonormal basis functions (e.g.
ZernikeWFE([name, coefficients, radius, …])	Define an optical element in terms of its Zernike components by providing coefficients for each Zernike term contributing to the analytic optical element.
SineWaveWFE([name, spatialfreq, amplitude, …])	A single sine wave ripple across the optic
StatisticalPSDWFE([name, index, wfe, …])	Statistical PSD WFE class from power law for optical noise.

Class Inheritance Diagram

poppy.zernike Module

Zernike & Related Polynomials

This module implements several sets of orthonormal polynomials for measuring and modeling wavefronts:

• the classical Zernike polynomials, which are orthonormal over the unit circle.
• ‘Hexikes’, orthonormal over the unit hexagon

• tools for creating a custom set orthonormal over a numerically supplied JWST pupil,

  or other generalized pupil

• Segmented bases with piston, tip, & tilt of independent hexagonal segments.

For definitions of Zernikes and a basic introduction to why they are a useful way to

parametrize data, see e.g.

Hardy’s ‘Adaptive Optics for Astronomical Telescopes’ section 3.5.1 or even just the Wikipedia page is pretty decent.

For definition of the hexagon and arbitrary pupil polynomials, a good reference to the

Gram-Schmidt orthonormalization process as applied to this case is

Mahajan and Dai, 2006. Optics Letters Vol 31, 16, p 2462:

Functions

R(n, m, rho)	Compute R[n, m], the Zernike radial polynomial
cached_zernike1	Compute Zernike based on Noll index j, using an LRU cache for efficiency.
hex_aperture([npix, rho, theta, vertical, …])	Return an aperture function for a hexagon.
hexike_basis([nterms, npix, rho, theta, …])	Return a list of hexike polynomials 1-N following the method of Mahajan and Dai 2006 for numerical orthonormalization
noll_indices(j)	Convert from 1-D to 2-D indexing for Zernikes or Hexikes.
opd_expand(opd[, aperture, nterms, basis])	Given a wavefront OPD map, return the list of coefficients in a given basis set (by default, Zernikes) that best fit the OPD map.
opd_expand_nonorthonormal(opd[, aperture, …])	Modified version of opd_expand, for cases where the basis function is not orthonormal, for instance using the regular Zernike functions on obscured apertures.
opd_expand_segments(opd[, aperture, nterms, …])	Expand OPD into a basis defined by segments, typically with piston, tip, & tilt of each.
opd_from_zernikes(coeffs[, basis, aperture, …])	Synthesize an OPD from a set of coefficients
str_zernike(n, m)	Return analytic expression for a given Zernike in LaTeX syntax
zern_name(i)	Return a human-readable text name corresponding to some Zernike term as specified by j, the index
zernike(n, m[, npix, rho, theta, outside, …])	Return the Zernike polynomial Z[m,n] for a given pupil.
zernike1(j, **kwargs)	Return the Zernike polynomial Z_j for pupil points {r,theta}.
zernike_basis([nterms, npix, rho, theta])	Return a cube of Zernike terms from 1 to N each as a 2D array showing the value at each point.
arbitrary_basis(aperture[, nterms, rho, …])	Orthonormal basis on arbitrary aperture, via Gram-Schmidt

Classes

Segment_Piston_Basis([rings, flattoflat, …])	Eigenbasis of segment pistons, tips, tilts.
Segment_PTT_Basis([rings, flattoflat, gap, …])	Eigenbasis of segment pistons, tips, tilts.

Class Inheritance Diagram