SpaceTelescopeInstrument¶

class webbpsf.SpaceTelescopeInstrument(name='', pixelscale=0.064)[source]¶

Bases: Instrument

A generic Space Telescope Instrument class.

Note: Do not use this class directly - instead use one of the specific instrument subclasses!

This class provides a simple interface for modeling PSF formation through the instrument, with configuration options and software interface loosely resembling the configuration of the instrument hardware mechanisms.

This module currently only provides a modicum of error checking, and relies on the user being knowledgable enough to avoid trying to simulate some physically impossible or just plain silly configuration (such as trying to use a FQPM with the wrong filter).

The instrument constructors do not take any arguments. Instead, create an instrument object and then configure the filter or other attributes as desired. The most commonly accessed parameters are available as object attributes: filter, image_mask, pupil_mask, pupilopd. More advanced configuration can be done by editing the SpaceTelescopeInstrument.options dictionary, either by passing options to __init__ or by directly editing the dict afterwards.

Attributes Summary

`aperturename`	SIAF aperture name for detector pixel to sky coords transformations
`detector`	Detector selected for simulated PSF
`detector_list`	Detectors on which the simulated PSF could lie
`detector_position`	The pixel position in (X, Y) on the detector, relative to the currently-selected SIAF aperture subarray.
`image_mask`	Currently selected image plane mask, or None for direct imaging
`options`	A dictionary capable of storing other arbitrary options, for extensibility.
`pupil_mask`	Currently selected Lyot pupil mask, or None for direct imaging
`telescope`

Methods Summary

`get_optical_system`([fft_oversample, ...])	Return an OpticalSystem instance corresponding to the instrument as currently configured.
`psf_grid`([num_psfs, all_detectors, save, ...])	Create a PSF library in the form of a grid of PSFs across the detector based on the specified instrument, filter, and detector.

Attributes Documentation

aperturename¶: SIAF aperture name for detector pixel to sky coords transformations

detector¶

Detector selected for simulated PSF

Used in calculation of field-dependent aberrations. Must be selected from detectors in the detector_list attribute.

detector_list¶: Detectors on which the simulated PSF could lie

detector_position¶

The pixel position in (X, Y) on the detector, relative to the currently-selected SIAF aperture subarray. By default the SIAF aperture will correspond to the full-frame detector, so (X,Y) will in that case be absolute (X,Y) pixels on the detector. But if you select a subarray aperture name from the SIAF, then the (X,Y) are interpreted as (X,Y) within that subarray.

Please note, this is X,Y order - not a Pythonic y,x axes ordering.

image_mask¶: Currently selected image plane mask, or None for direct imaging

options = {}¶

A dictionary capable of storing other arbitrary options, for extensibility. The following are all optional, and may or may not be meaningful depending on which instrument is selected.

This is a superset of the options provided in poppy.Instrument.options.

Parameters:

source_offset_rfloat: Radial offset of the target from the center, in arcseconds
source_offset_thetafloat: Position angle for that offset, in degrees CCW.
pupil_shift_x, pupil_shift_yfloat: Relative shift of the intermediate (coronagraphic) pupil in X and Y relative to the telescope entrance pupil, expressed as a decimal between -1.0-1.0 Note that shifting an array too much will wrap around to the other side unphysically, but for reasonable values of shift this is a non-issue. This option only has an effect for optical models that have something at an intermediate pupil plane between the telescope aperture and the detector.
pupil_rotationfloat: Relative rotation of the intermediate (coronagraphic) pupil relative to the telescope entrance pupil, expressed in degrees counterclockwise. This option only has an effect for optical models that have something at an intermediate pupil plane between the telescope aperture and the detector.
rebinbool: For output files, write an additional FITS extension including a version of the output array rebinned down to the actual detector pixel scale?
jitterstring “gaussian” or None: Type of jitter model to apply. Currently only convolution with a Gaussian kernel of specified width jitter_sigma is implemented. (default: None)
jitter_sigmafloat: Width of the jitter kernel in arcseconds (default: 0.006 arcsec, 1 sigma per axis)
paritystring “even” or “odd”: You may wish to ensure that the output PSF grid has either an odd or even number of pixels. Setting this option will force that to be the case by increasing npix by one if necessary. Note that this applies to the number detector pixels, rather than the subsampled pixels if oversample > 1.
force_coronbool: Set this to force full coronagraphic optical propagation when it might not otherwise take place (e.g. calculate the non-coronagraphic images via explicit propagation to all optical surfaces, FFTing to intermediate pupil and image planes whether or not they contain any actual optics, rather than taking the straight-to-MFT shortcut)
no_sambool: Set this to prevent the SemiAnalyticMethod coronagraph mode from being used when possible, and instead do the brute-force FFT calculations. This is usually not what you want to do, but is available for comparison tests. The SAM code will in general be much faster than the FFT method, particularly for high oversampling.

pupil_mask¶: Currently selected Lyot pupil mask, or None for direct imaging

telescope = 'Generic Space Telescope'¶

Methods Documentation

get_optical_system(fft_oversample=2, detector_oversample=None, fov_arcsec=2, fov_pixels=None, options=None)[source]¶

Return an OpticalSystem instance corresponding to the instrument as currently configured.

When creating such an OpticalSystem, you must specify the parameters needed to define the desired sampling, specifically the oversampling and field of view.

Parameters:

fft_oversampleint: Oversampling factor for intermediate plane calculations. Default is 2
detector_oversample: int, optional: By default the detector oversampling is equal to the intermediate calculation oversampling. If you wish to use a different value for the detector, set this parameter. Note that if you just want images at detector pixel resolution you will achieve higher fidelity by still using some oversampling (i.e. not setting oversample_detector=1) and instead rebinning down the oversampled data.
fov_pixelsfloat: Field of view in pixels. Overrides fov_arcsec if both set.
fov_arcsecfloat: Field of view, in arcseconds. Default is 2

Returns:

osyspoppy.OpticalSystem: an optical system instance representing the desired configuration.

psf_grid(num_psfs=16, all_detectors=True, save=False, outdir=None, outfile=None, overwrite=True, verbose=True, use_detsampled_psf=False, single_psf_centered=True, **kwargs)[source]¶

Create a PSF library in the form of a grid of PSFs across the detector based on the specified instrument, filter, and detector. The output GriddedPSFModel object will contain a 3D array with axes [i, y, x] where i is the PSF position on the detector grid and (y,x) is the 2D PSF.

Parameters:

num_psfsint: The total number of fiducial PSFs to be created and saved in the files. This number must be a square number. Default is 16. E.g. num_psfs = 16 will create a 4x4 grid of fiducial PSFs.
all_detectorsbool: If True, run all detectors for the instrument. If False, run for the detector set in the instance. Default is True
savebool: True/False boolean if you want to save your file. Default is False.
outdirstr: If “save” keyword is set to True, your file will be saved in the specified directory. Default of None will save it in the current directory
outfilestr: If “save” keyword is set to True, your file will be saved as {outfile}_det.fits. Default of None will save it as instr_det_filt_fovp#_samp#_npsf#.fits
overwritebool: True/False boolean to overwrite the output file if it already exists. Default is True.
verbosebool: True/False boolean to print status updates. Default is True.
use_detsampled_psfbool: If True, the grid of PSFs returned will be detector sampled (made by binning down the oversampled PSF). If False, the PSFs will be oversampled by the factor defined by the oversample/detector_oversample/fft_oversample keywords. Default is False. This is rarely needed - if uncertain, leave this alone.
single_psf_centeredbool: If num_psfs is set to 1, this defines where that psf is located. If True it will be the center of the detector, if False it will be the location defined in the WebbPSF attribute detector_position (reminder - detector_position is (x,y)). Default is True This is also rarely needed.
**kwargs: Any extra arguments to pass the WebbPSF calc_psf() method call.

Returns:

gridmodelphotutils GriddedPSFModel object or list of objects: Returns a GriddedPSFModel object or a list of objects if more than one configuration is specified (1 per instrument, detector, and filter) User also has the option to save the grid as a fits.HDUlist object.