Wavefront

class poppy.poppy_core.Wavefront(wavelength=<Quantity 1.e-06 m>, npix=1024, dtype=None, diam=<Quantity 8. m>, oversample=2, pixelscale=None)[source]

Bases: poppy.poppy_core.BaseWavefront

Wavefront in the Fraunhofer approximation: a monochromatic wavefront that can be transformed between pupil and image planes only, not to intermediate planes

In a pupil plane, a wavefront object wf has

  • wf.diam, a diameter in meters

  • wf.pixelscale, a scale in meters/pixel

In an image plane, it has

  • wf.fov, a field of view in arcseconds

  • wf.pixelscale, a scale in arcsec/pixel

Use the wf.propagate_to() method to transform a wavefront between conjugate planes. This will update those properties as appropriate.

By default, Wavefronts are created in a pupil plane. Set pixelscale=# to make an image plane instead.

wavelengthfloat

Wavelength of light in meters

npixint

Size parameter for wavefront array to create, per side.

diamfloat, optional

For _PUPIL wavefronts, sets physical size corresponding to npix. Units are meters. At most one of diam or pixelscale should be set when creating a wavefront.

pixelscalefloat, optional

For PlaneType.image PLANE wavefronts, use this pixel scale.

oversampleint, optional

how much to oversample by in FFTs. Default is 2. Note that final propagations to Detectors use a different algorithm and, optionally, a separate oversampling factor.

dtypenumpy.dtype, optional

default is double complex.

Attributes Summary

amplitude

Electric field amplitude of the wavefront

intensity

Electric field intensity of the wavefront (i.e.

phase

Phase of the wavefront, in radians

shape

Shape of the wavefront array

Wavefront.totalIntensity

Methods Summary

Wavefront.asFITS

coordinates()

Return Y, X coordinates for this wavefront, in the manner of numpy.indices()

copy()

Return a copy of the wavefront as a different object.

display([what, nrows, row, showpadding, …])

Display wavefront on screen

normalize()

Set this wavefront’s total intensity to 1

Wavefront.propagateTo

rotate([angle])

Rotate a wavefront by some amount, using spline interpolation

tilt([Xangle, Yangle])

Tilt a wavefront in X and Y.

writeto(filename[, overwrite])

Write a wavefront to a FITS file.

Attributes Documentation

amplitude

Electric field amplitude of the wavefront

intensity

Electric field intensity of the wavefront (i.e. field amplitude squared)

phase

Phase of the wavefront, in radians

shape

Shape of the wavefront array

Methods Documentation

coordinates()[source]

Return Y, X coordinates for this wavefront, in the manner of numpy.indices()

This function knows about the offset resulting from FFTs. Use it whenever computing anything measured in wavefront coordinates.

Y, Xarray_like

Wavefront coordinates in either meters or arcseconds for pupil and image, respectively

copy()

Return a copy of the wavefront as a different object.

display(what='intensity', nrows=1, row=1, showpadding=False, imagecrop=None, pupilcrop=None, colorbar=False, crosshairs=False, ax=None, title=None, vmin=None, vmax=None, scale=None, use_angular_coordinates=None)

Display wavefront on screen

whatstring

What to display. Must be one of {intensity, phase, best}. ‘Best’ implies to display the phase if there is nonzero OPD, or else display the intensity for a perfect pupil.

nrowsint

Number of rows to display in current figure (used for showing steps in a calculation)

rowint

Which row to display this one in? If set to None, use the wavefront’s self.current_plane_index

vmin, vmaxfloats

min and maximum values to display. When left unspecified, these default to [0, intens.max()] for linear (scale=’linear’) intensity plots, [1e-6*intens.max(), intens.max()] for logarithmic (scale=’log’) intensity plots, and [-0.25, 0.25] waves for phase plots.

scalestring

‘log’ or ‘linear’, to define the desired display scale type for intensity. Default is log for image planes, linear otherwise.

imagecropfloat, optional

Crop the displayed image to a smaller region than the full array. For image planes in angular coordinates, this is given in units of arcseconds. The default is 5, so only the innermost 5x5 arcsecond region will be shown. This default may be changed in the POPPY config file. If the image size is < 5 arcsec then the entire image is displayed. For planes in linear physical coordinates such as pupils, this is given in units of meters, and the default is no cropping (i.e. the entire array will be displayed unless this keyword is set explicitly).

showpaddingbool, optional

For wavefronts that have been padded with zeros for oversampling, show the entire padded arrays, or just the good parts? Default is False, to show just the central region of interest.

colorbarbool

Display colorbar

crosshairsbool

Display a crosshairs indicator showing the axes centered on (0,0)

axmatplotlib Axes, optional

axes to display into. If not set, will create new axes.

use_angular_coordinatesbool, optional

Should the axes be labeled in angular units of arcseconds? This is used by FresnelWavefront, where non-angular coordinates are possible everywhere. When using Fraunhofer propagation, this should be left as None so that the coordinates are inferred from the planetype attribute. (Default: None, infer coordinates from planetype)

figurematplotlib figure

The current figure is modified.

normalize()

Set this wavefront’s total intensity to 1

rotate(angle=0.0)

Rotate a wavefront by some amount, using spline interpolation

anglefloat

Angle to rotate, in degrees counterclockwise.

tilt(Xangle=0.0, Yangle=0.0)

Tilt a wavefront in X and Y.

Recall from Fourier optics (although this is straightforwardly rederivable by drawing triangles) that for a wavefront tilted by some angle theta in radians, that a point r meters from the center of the pupil has:

extra_pathlength = sin(theta) * r extra_waves = extra_pathlength/ wavelength = r * sin(theta) / wavelength

So we calculate the U and V arrays (corresponding to r for the pupil, in meters from the center) and then multiply by the appropriate trig factors for the angle.

The sign convention is chosen such that positive Yangle tilts move the star upwards in the array at the focal plane. (This is sort of an inverse of what physically happens in the propagation to or through focus, but we’re ignoring that here and trying to just work in sky coords)

Xangle, Yanglefloat

tilt angles, specified in arcseconds

writeto(filename, overwrite=True, **kwargs)

Write a wavefront to a FITS file.

filenamestring

filename to use

whatstring

what to write. Must be one of ‘parts’, ‘intensity’, ‘complex’

overwritebool, optional

overwhat existing? default is True

outfile: file on disk

The output is written to disk.