OpticalSystem

class poppy.OpticalSystem(name='unnamed system', verbose=True, oversample=2, npix=None, pupil_diameter=None)

Bases: poppy.poppy_core.BaseOpticalSystem

A class representing a series of optical elements, either Pupil, Image, or Detector planes, through which light can be propagated.

The difference between Image and Detector planes is that Detectors have fixed pixels in terms of arcsec/pixel regardless of wavelength (computed via MFT) while Image planes have variable pixels scaled in terms of lambda/D. Pupil planes are some fixed size in meters, of course.

name : string

descriptive name of optical system

oversample : int

Either how many times above Nyquist we should be (for pupil or image planes), or how many times a fixed detector pixel will be sampled. E.g. oversample=2 means image plane sampling lambda/4*D (twice Nyquist) and detector plane sampling 2x2 computed pixels per real detector pixel. Default is 2.

verbose : bool

whether to be more verbose with log output while computing

pupil_diameter : astropy.Quantity of dimension length

Diameter of entrance pupil. Defaults to size of first optical element if unspecified, or else 1 meter.

Methods Summary

add_image([optic, function, index])	Add an image plane optic to the optical system
add_pupil([optic, function, index])	Add a pupil plane optic from file(s) giving transmission or OPD
describe()	Print out a string table describing all planes in an optical system
input_wavefront([wavelength])	Create a Wavefront object suitable for sending through a given optical system, based on the size of the first optical plane, assumed to be a pupil.
propagate(wavefront[, normalize, …])	Core low-level routine for propagating a wavefront through an optical system

Methods Documentation

add_image(optic=None, function=None, index=None, **kwargs)

Add an image plane optic to the optical system

That image plane optic can be specified either

1. from file(s) giving transmission or OPD

   [set arguments transmission=filename and/or opd=filename]

2. from an analytic function

   [set function='circle, fieldstop, bandlimitedcoron, or FQPM' and set additional kwargs to define shape etc.

3. from an already-created OpticalElement object

   [set optic=that object]

optic : poppy.OpticalElement

An already-created OpticalElement you would like to add

function: string

Name of some analytic function to add. Optional kwargs can be used to set the parameters of that function. Allowable function names are CircularOcculter, fieldstop, BandLimitedCoron, FQPM

opd, transmission : string

Filenames of FITS files describing the desired optic.

index : int

Index into the optical system’s planes for where to add the new optic. Defaults to appending the optic to the end of the plane list.

poppy.OpticalElement subclass

The pupil optic added (either optic passed in, or a new OpticalElement created)

Now you can use the optic argument for either an OpticalElement or a string function name, and it will do the right thing depending on type. Both existing arguments are left for back compatibility for now.

add_pupil(optic=None, function=None, index=None, **kwargs)

Add a pupil plane optic from file(s) giving transmission or OPD

1. from file(s) giving transmission and/or OPD

   [set arguments transmission=filename and/or opd=filename]

2. from an already-created OpticalElement object

   [set optic=that object]

optic : poppy.OpticalElement, optional

An already-created OpticalElement object you would like to add

function : string, optional

Deprecated. The name of some analytic function you would like to use. Optional kwargs can be used to set the parameters of that function. Allowable function names are Circle, Square, Hexagon, Rectangle, and FQPM_FFT_Aligner

opd, transmission : string, optional

Filenames of FITS files describing the desired optic.

index : int

Index into the optical system’s planes for where to add the new optic. Defaults to appending the optic to the end of the plane list.

poppy.OpticalElement subclass

The pupil optic added (either optic passed in, or a new OpticalElement created)

Note: Now you can use the optic argument for either an OpticalElement or a string function name, and it will do the right thing depending on type. Both existing arguments are left for compatibility for now.

Any provided parameters are passed to OpticalElement.

describe()

Print out a string table describing all planes in an optical system

input_wavefront(wavelength=<Quantity 1.e-06 m>)

Create a Wavefront object suitable for sending through a given optical system, based on the size of the first optical plane, assumed to be a pupil.

Defining this needs both a number of pixels (npix) and physical size (diam) to set the sampling.

If this OpticalSystem has a provided npix attribute that is not None, use that to set the input wavefront size. Otherwise, check if the first optical element has a defined sampling. If not, default to 1024 pixels.

Uses self.source_offset to assign an off-axis tilt, if requested.

The convention here is that the desired source position is specified with respect to the final focal plane of the optical system. If there are any intervening coordinate transformation planes, this function attempts to take them into account when setting the tilt of the input wavefront. This is subtle trickery and may not work properly in all instances.

wavelength : float

Wavelength in meters

wavefront : poppy.Wavefront instance

A wavefront appropriate for passing through this optical system.

propagate(wavefront, normalize='none', return_intermediates=False, display_intermediates=False)

Core low-level routine for propagating a wavefront through an optical system

This is a linear operator that acts on an input complex wavefront to give an output complex wavefront.

wavefront : Wavefront instance

Wavefront to propagate through this optical system

normalize : string

How to normalize the wavefront? * ‘first’ = set total flux = 1 after the first optic, presumably a pupil * ‘last’ = set total flux = 1 after the entire optical system. * ‘exit_pupil’ = set total flux = 1 at the last pupil of the optical system.

display_intermediates : bool

Should intermediate steps in the calculation be displayed on screen? Default: False.

return_intermediates : bool

Should intermediate steps in the calculation be returned? Default: False. If True, the second return value of the method will be a list of poppy.Wavefront objects representing intermediate optical planes from the calculation.

Returns a wavefront, and optionally also the intermediate wavefronts after each step of propagation.