webbpsf_ext.webbpsf_ext_core.MIRI_ext

class webbpsf_ext.webbpsf_ext_core.MIRI_ext(filter=None, pupil_mask=None, image_mask=None, fov_pix=None, oversample=None, **kwargs)

Bases: MIRI

MIRI instrument PSF coefficients

Subclass of STPSF’s MIRI class for generating polynomial coefficients to cache and quickly generate PSFs for arbitrary spectral types as well as WFE variations due to field-dependent OPDs and telescope thermal drifts.

__init__(filter=None, pupil_mask=None, image_mask=None, fov_pix=None, oversample=None, **kwargs)

Initialize MIRI instrument

Parameters:

• filter (str) – Name of input filter.

• pupil_mask (str, None) – Pupil elements such as grisms or lyot stops (default: None). ‘MASKFQPM’, ‘MASKLYOT’, or ‘P750L’

• image_mask (str, None) – Specify which coronagraphic occulter (default: None). ‘FQPM1065’, ‘FQPM1140’, ‘FQPM1550’, ‘LYOT2300’, or ‘LRS slit’.

• fov_pix (int) – Size of the PSF FoV in pixels (real SW or LW pixels). The defaults depend on the type of observation. Odd number place the PSF on the center of the pixel, whereas an even number centers it on the “crosshairs.”

• oversample (int) – Factor to oversample during STPSF calculations. Default 2 for coronagraphy and 4 otherwise.

Keyword Arguments:

• fovmax_wfedrift (int or None) – Maximum allowed size for coefficient modifications associated with WFE drift. Default is 256. Any pixels beyond this size will be considered to have 0 residual difference

• fovmax_wfemask (int or None) – Maximum allowed size for coefficient modifications associated with focal plane masks. Default is 256. Any pixels beyond this size will be considered to have 0 residual difference

• fovmax_wfefield (int or None) – Maximum allowed size for coefficient modifications due to field point variations such as distortion. Default is 128. Any pixels beyond this size will be considered to have 0 residual difference

Methods

__init__([filter, pupil_mask, image_mask, ...])	Initialize MIRI instrument
calc_datacube(wavelengths[, progressbar, ...])	Calculate a spectral datacube of PSFs
calc_datacube_fast(wavelengths[, ...])	Calculate a spectral datacube of PSFs: Simplified, much MUCH faster version.
calc_psf([add_distortion, fov_pixels, ...])	Compute a PSF
calc_psf_from_coeff([sp, return_oversample, ...])	Create PSF image from coefficients
calc_psfs_grid([sp, wfe_drift, osamp, ...])	PSF grid across an instrumnet FoV
calc_psfs_sgd(xoff_asec, yoff_asec[, use_coeff])	Calculate small grid dither PSFs
display()	Display the currently configured optical system on screen
drift_opd(wfe_drift[, opd])	A quick method to drift the pupil OPD.
gen_mask_image([npix, pixelscale, ...])	Return an image representation of the focal plane mask.
gen_psf_coeff(**kwargs)	Generate PSF coefficients
gen_save_name([wfe_drift])	Generate save name for polynomial coefficient output file.
gen_wfedrift_coeff([force, save])	Fit WFE drift coefficients
gen_wfefield_coeff([force, save])	Fit WFE field-dependent coefficients
gen_wfemask_coeff([large_grid, force, save])	Fit WFE changes in mask position
get_IFU_wavelengths([nlambda])	Return an array of wavelengths spanning the currently selected IFU sub-band
get_opd_file_full_path([opdfilename])	Return full path to the named OPD file.
get_opd_info([opd, pupil, HDUL_to_OTELM])	Parse out OPD information for a given OPD, which can be a file name, tuple (file,slice), HDUList, or OTE Linear Model.
get_optical_system([fft_oversample, ...])	Return an OpticalSystem instance corresponding to the instrument as currently configured.
get_wfe([kind, wavelength, plot])	Extract and return one component plane of the optical model for this instrument
interpolate_was_opd(array, newdim)	Interpolates an input 2D array to any given size.
load_wss_opd(filename[, output_path, ...])	Load an OPD produced by the JWST WSS into this instrument instance, specified by filename
load_wss_opd_by_date([date, choice, ...])	Load an OPD produced by the JWST WSS into this instrument instance, specified by filename.
plot_bandpass([ax, color, title, return_ax])	Plot the instrument bandpass on a selected axis.
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.
set_position_from_aperture_name(aperture_name)	Set the simulated center point of the array based on a named SIAF aperture.
visualize_wfe_budget([slew_delta_time, ...])	Display a visual WFE budget showing the various terms that sum into the overall WFE for a given instrument

Attributes

aperturename	SIAF aperture name for detector pixel to sky coords transformations
band	MRS IFU spectral band.
bandpass
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.
fastaxis	Fast readout direction in sci coords
filter	Currently selected filter name (e.g. F200W).
filter_list	List of available filter names for this instrument
fov_pix
image_mask	Currently selected image plane mask, or None for direct imaging
is_coron	Coronagraphic observations based on pupil mask settings
is_slitspec	LRS observations based on pupil mask settings
mode	Currently selected instrument major mode, imaging or IFU
name
ndeg	Degree of polynomial fit
npsf	Number of wavelengths/PSFs to fit
options	A dictionary capable of storing other arbitrary options, for extensibility.
oversample
pixelscale	Detector pixel scale, in arcsec/pixel
pupil	Filename or fits.HDUList for JWST pupil mask.
pupil_mask	Currently selected Lyot pupil mask, or None for direct imaging
pupilopd	Filename or fits.HDUList for JWST pupil OPD.
quick	Perform quicker coeff calculation over limited bandwidth?
save_dir	Coefficient save directory
save_name	Coefficient file name
siaf_ap	SIAF Aperture object
slowaxis	Slow readout direction in sci coords
telescope
use_fov_pix_plus1	If fov_pix is even, then set use_fov_pix_plus1 to True.
wave_fit	Wavelength range to fit
include_ote_field_dependence	Should calculations include the Science Instrument internal WFE?
image_mask_list	List of available image_masks
pupil_mask_list	List of available pupil_masks

property aperturename

SIAF aperture name for detector pixel to sky coords transformations

property band

MRS IFU spectral band. E.g. ‘1A’, ‘3B’. Only applicable in IFU mode.

calc_datacube(wavelengths, progressbar=False, outfile=None, overwrite=True, *args, **kwargs)

Calculate a spectral datacube of PSFs

Parameters:

• wavelengths (iterable of floats) – List or ndarray or tuple of floating point wavelengths in meters, such as you would supply in a call to calc_psf via the “monochromatic” option

• progressbar (bool) – Optionally display a progress bar indicator for status while iterating over wavelengths. Note, this requires the optional dependency package ‘tqdm’, which is not included as a requirement.

• outfile (string) – Filename to write. If None, then result is returned as an HDUList

• overwrite (bool) – overwrite output FITS file if it already exists?

• Additional parameters are passed through to calc_datacube

calc_datacube_fast(wavelengths, compare_methods=False, outfile=None, add_distortion=True, *args, **kwargs)

Calculate a spectral datacube of PSFs: Simplified, much MUCH faster version.

This is adapted from poppy.Instrument.calc_datacube, optimized and simplified for a substantial gain in speed at minimal reduction in accuracy for some use cases.

ASSUMPTIONS:

1. Assumes the wavefront error (OPD) and amplitude are independent of wavelength, such

   that we can do the expensive propagation from sky through the optics to the exit pupil of NIRSpec only once, save that, and reuse the same exit pupil wavefront many times changing only the wavelength for just the last DFT step to the detector.

2. Assumes we do not need the binned-to-detector-resolution nor distorted versions;

   we just want the oversampled PSF datacube at many wavelengths as fast as possible. (If the binned output is also desired, it can be computed post facto. TODO: A future revision of this function may also add here an option for computing those derived versions as well.)

Testing for NIRSpec IFU indicates this achieves ~150x speedup, and the differences in computed oversampled PSF are typically ~1/100th or less relative to the local PSF values in any given pixel.

A consequence of the above assumption 1 is that this method is not well applicable for cases that have image plane masks, nor for NIRCam in general. It does seem to be reasonably applicable for NIRSpec IFU calculations within the current limited fidelity of stpsf for that mode, IF we also neglect the image plane stop around the IFU FOV.

Parameters:

• wavelengths (iterable of floats) – List or ndarray or tuple of floating point wavelengths in meters, such as you would supply in a call to calc_psf via the “monochromatic” option

• add_distortion (bool) – Same as for regular calc_psf.

• compare_methods (bool) – If true, compute the PSF BOTH WAYS, and return both for comparisons. This is of course much slower. Default is False. This is retained for test and debug usage for assessing cases in which this method is OK or not.

Returns:

• a PSF datacube, normally (with compare_methods=False)

• A list of two PSF datacubes and two exit wavefront objects, if compare_methods is True

calc_psf(add_distortion=None, fov_pixels=None, oversample=None, wfe_drift=None, coord_vals=None, coord_frame='tel', **kwargs)

Compute a PSF

Slight modification of inherent STPSF calc_psf function. If add_distortion, fov_pixels, and oversample are not specified, then we automatically use the associated attributes.

Notes

More advanced PSF computation options (pupil shifts, source positions, jitter, …) may be set by configuring the .options dictionary attribute of this class.

Parameters:

• source (synphot.spectrum.SourceSpectrum or dict)

• nlambda (int) – How many wavelengths to model for broadband? The default depends on how wide the filter is: (5,3,1) for types (W,M,N) respectively

• monochromatic (float, optional) – Setting this to a wavelength value (in meters) will compute a monochromatic PSF at that wavelength, overriding filter and nlambda settings.

• fov_arcsec (float) – field of view in arcsec. Default=5

• fov_pixels (int) – field of view in pixels. This is an alternative to fov_arcsec.

• outfile (string) – Filename to write. If None, then result is returned as an HDUList

• oversample, detector_oversample, fft_oversample (int) – How much to oversample. Default=4. By default the same factor is used for final output pixels and intermediate optical planes, but you may optionally use different factors if so desired.

• overwrite (bool) – overwrite output FITS file if it already exists?

• display (bool) – Whether to display the PSF when done or not.

• save_intermediates, return_intermediates (bool) – Options for saving to disk or returning to the calling function the intermediate optical planes during the propagation. This is useful if you want to e.g. examine the intensity in the Lyot plane for a coronagraphic propagation.

• normalize (string) – Desired normalization for output PSFs. See doc string for OpticalSystem.calc_psf. Default is to normalize the entrance pupil to have integrated total intensity = 1.

• add_distortion (bool) – If True, will add 2 new extensions to the PSF HDUlist object. The 2nd extension will be a distorted version of the over-sampled PSF and the 3rd extension will be a distorted version of the detector-sampled PSF.

• crop_psf (bool) – If True, when the PSF is rotated to match the detector’s rotation in the focal plane, the PSF will be cropped so the shape of the distorted PSF will match it’s undistorted counterpart. This will only be used for NIRCam, NIRISS, and FGS PSFs.

Keyword Arguments:

• sp (webbpsf_ext.synphot_ext.Spectrum) – Source input spectrum. If not specified, the default is flat in phot lam. (equal number of photons per spectral bin).

• coord_vals (tuple or None) – Coordinates (in arcsec or pixels) to calculate field-dependent PSF. If multiple values, then this should be an array ([xvals], [yvals]).

• coord_frame (str) –

  Type of input coordinates relative to self.siaf_ap aperture.

  • ’tel’: arcsecs V2,V3

  • ’sci’: pixels, in DMS axes orientation; aperture-dependent

  • ’det’: pixels, in raw detector read out axes orientation

  • ’idl’: arcsecs relative to aperture reference location.

• return_hdul (bool) – Return PSFs in an HDUList rather than set of arrays (default: True).

• return_oversample (bool) – Returns the oversampled version of the PSF instead of detector-sampled PSF. Only valid for reaturn_hdul=False, otherwise full HDUList returned. Default: True.

calc_psf_from_coeff(sp=None, return_oversample=True, return_hdul=True, wfe_drift=None, coord_vals=None, coord_frame='tel', **kwargs)

Create PSF image from coefficients

Create a PSF image from instrument settings. The image is noiseless and doesn’t take into account any non-linearity or saturation effects, but is convolved with the instrument throughput. Pixel values are in counts/sec. The result is effectively an idealized slope image (no background).

Returns a single image or list of images if sp is a list of spectra. By default, it returns only the oversampled PSF, but setting return_oversample=False will instead return detector-sampled images.

Parameters:

• sp (webbpsf_ext.synphot_ext.Spectrum) – If not specified, the default is flat in phot lam (equal number of photons per spectral bin). The default is normalized to produce 1 count/sec within that bandpass, assuming the telescope collecting area and instrument bandpass. Coronagraphic PSFs will further decrease this due to the smaller pupil size and coronagraphic mask.

• return_oversample (bool) – Returns the oversampled version of the PSF instead of detector-sampled PSF. Default: True.

• wfe_drift (float or None) – Wavefront error drift amplitude in nm.

• coord_vals (tuple or None) – Coordinates (in arcsec or pixels) to calculate field-dependent PSF. If multiple values, then this should be an array ([xvals], [yvals]).

• coord_frame (str) –

  Type of input coordinates relative to self.siaf_ap aperture.

  • ‘tel’: arcsecs V2,V3

  • ‘sci’: pixels, in conventional DMS axes orientation

  • ‘det’: pixels, in raw detector read out axes orientation

  • ‘idl’: arcsecs relative to aperture reference location.

• return_hdul (bool) – Return PSFs in an HDUList rather than set of arrays (default: True).

calc_psfs_grid(sp=None, wfe_drift=0, osamp=1, npsf_per_full_fov=15, xsci_vals=None, ysci_vals=None, return_coords=None, use_coeff=True, **kwargs)

PSF grid across an instrumnet FoV

Create a grid of PSFs across instrument aperture FoV. By default, imaging observations will be for full detector FoV with regularly spaced grid. Coronagraphic observations will cover nominal coronagraphic mask region (usually 10s of arcsec) and will have logarithmically spaced values where appropriate.

Keyword Arguments:

• sp (webbpsf_ext.synphot_ext.Spectrum) – If not specified, the default is flat in phot lam (equal number of photons per wavelength bin). The default is normalized to produce 1 count/sec within that bandpass, assuming the telescope collecting area and instrument bandpass. Coronagraphic PSFs will further decrease this due to the smaller pupil size and suppression of coronagraphic mask. If set, then the resulting PSF image will be scaled to generate the total observed number of photons from the spectrum (ie., not scaled by unit response).

• wfe_drift (float) – Desired WFE drift value relative to default OPD.

• osamp (int) – Sampling of output PSF relative to detector sampling.

• npsf_per_full_fov (int) – Number of PSFs across one dimension of the instrument’s field of view. If a coronagraphic observation, then this is for the nominal coronagrahic field of view.

• xsci_vals (None or ndarray) – Option to pass a custom grid values along x-axis in ‘sci’ coords. If coronagraph, this instead corresponds to coronagraphic mask axis, which has a slight rotation relative to detector axis in MIRI.

• ysci_vals (None or ndarray) – Option to pass a custom grid values along y-axis in ‘sci’ coords. If coronagraph, this instead corresponds to coronagraphic mask axis, which has a slight rotation relative to detector axis in MIRI.

• return_coords (None or str) – Option to also return coordinate values in desired frame (‘det’, ‘sci’, ‘tel’, ‘idl’). Output is then xvals, yvals, hdul_psfs.

• use_coeff (bool) – If True, uses calc_psf_from_coeff, other STPSF’s built-in calc_psf.

calc_psfs_sgd(xoff_asec, yoff_asec, use_coeff=True, **kwargs)

Calculate small grid dither PSFs

Convenience function to calculation a series of SGD PSFs. This is essentially a wrapper around the calc_psf_from_coeff and calc_psf functions. Only valid for coronagraphic observations.

Parameters:

• xoff_asec (float or array-like) – Offsets in x-direction (in ‘idl’ coordinates).

• yoff_asec (float or array-like) – Offsets in y-direction (in ‘idl’ coordinates).

• use_coeff (bool) – If True, uses calc_psf_from_coeff, other STPSF’s built-in calc_psf.

property detector

Detector selected for simulated PSF

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

property detector_list

Detectors on which the simulated PSF could lie

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

display()

Display the currently configured optical system on screen

drift_opd(wfe_drift, opd=None)

A quick method to drift the pupil OPD. This function applies some WFE drift to input OPD file by breaking up the wfe_drift attribute into thermal, frill, and IEC components. If we want more realistic time evolution, then we should use the procedure in dev_utils/WebbPSF_OTE_LM.ipynb to create a time series of OPD maps, which can then be passed directly to create unique PSFs.

This outputs an OTE Linear Model. In order to update instrument class:

>>> opd_dict = inst.drift_opd()
>>> inst.pupilopd = opd_dict['opd']
>>> inst.pupil = opd_dict['opd']

property fastaxis

Fast readout direction in sci coords

property filter

Currently selected filter name (e.g. F200W)

filter_list = None

List of available filter names for this instrument

gen_mask_image(npix=None, pixelscale=None, detector_orientation=True)

Return an image representation of the focal plane mask. For 4QPM, we should the phase offsets (0 or 1), whereas the Lyot and LRS slit masks return transmission.

Parameters:

• npix (int) – Number of pixels in output image. If not set, then is automatically determined based on mask FoV and pixelscale

• pixelscale (float) – Size of output pixels in units of arcsec. If not specified, then selects nominal detector pixel scale.

• detector_orientation (bool) – Should the output image be rotated to be in detector coordinates? If set to False, then output mask is rotated along V2/V3 axes.

gen_psf_coeff(**kwargs)

Generate PSF coefficients

Creates a set of coefficients that will generate simulated PSFs for any arbitrary wavelength. This function first simulates a number of evenly- spaced PSFs throughout the specified bandpass (or the full channel). An nth-degree polynomial is then fit to each oversampled pixel using a linear-least squares fitting routine. The final set of coefficients for each pixel is returned as an image cube. The returned set of coefficient are then used to produce PSF via calc_psf_from_coeff.

Useful for quickly generated imaging and dispersed PSFs for multiple spectral types.

Keyword Arguments:

• wfe_drift (float) – Wavefront error drift amplitude in nm.

• force (bool) – Forces a recalculation of PSF even if saved PSF exists. (default: False)

• save (bool) – Save the resulting PSF coefficients to a file? (default: True)

• nproc (bool or None) – Manual setting of number of processor cores to break up PSF calculation. If set to None, this is determined based on the requested PSF size, number of available memory, and hardware processor cores. The automatic calculation endeavors to leave a number of resources available to the user so as to not crash the user’s machine.

• return_results (bool) – By default, results are saved as object the attributes psf_coeff and psf_coeff_header. If return_results=True, results are instead returned as function outputs and will not be saved to the attributes. This is mostly used for successive coeff simulations to determine varying WFE drift or focal plane dependencies.

• return_extras (bool) – Additionally returns a dictionary of monochromatic PSFs images and their corresponding wavelengths for debugging purposes. Can be used with or without return_results. If return_results=False, then only this dictionary is returned, otherwise if return_results=False then returns everything as a 3-element tuple (psf_coeff, psf_coeff_header, extras_dict).

gen_save_name(wfe_drift=0)

Generate save name for polynomial coefficient output file.

gen_wfedrift_coeff(force=False, save=True, **kwargs)

Fit WFE drift coefficients

This function finds a relationship between PSF coefficients in the presence of WFE drift. For a series of WFE drift values, we generate corresponding PSF coefficients and fit a polynomial relationship to the residual values. This allows us to quickly modify a nominal set of PSF image coefficients to generate a new PSF where the WFE has drifted by some amplitude.

It’s Legendre’s all the way down…

Parameters:

• force (bool) – Forces a recalculation of coefficients even if saved file exists. (default: False)

• save (bool) – Save the resulting PSF coefficients to a file? (default: True)

Keyword Arguments:

• wfe_list (array-like) – A list of wavefront error drift values (nm) to calculate and fit. Default is [0,1,2,5,10,20,40], which covers the most-likely scenarios (1-5nm) while also covering a range of extreme drift values (10-40nm).

• return_results (bool) – By default, results are saved in self._psf_coeff_mod dictionary. If return_results=True, results are instead returned as function outputs and will not be saved to the dictionary attributes.

• return_raw (bool) – Normally, we return the relation between PSF coefficients as a function of position. Instead this returns (as function outputs) the raw values prior to fitting. Final results will not be saved to the dictionary attributes.

gen_wfefield_coeff(force=False, save=True, **kwargs)

Fit WFE field-dependent coefficients

Find a relationship between field position and PSF coefficients for non-coronagraphic observations and when include_si_wfe is enabled.

Parameters:

• force (bool) – Forces a recalculation of coefficients even if saved file exists. (default: False)

• save (bool) – Save the resulting PSF coefficients to a file? (default: True)

Keyword Arguments:

• return_results (bool) – By default, results are saved in self._psf_coeff_mod dictionary. If return_results=True, results are instead returned as function outputs and will not be saved to the dictionary attributes.

• return_raw (bool) – Normally, we return the relation between PSF coefficients as a function of position. Instead this returns (as function outputs) the raw values prior to fitting. Final results will not be saved to the dictionary attributes.

gen_wfemask_coeff(large_grid=True, force=False, save=True, **kwargs)

Fit WFE changes in mask position

For coronagraphic masks, slight changes in the PSF location relative to the image plane mask can substantially alter the PSF speckle pattern. This function generates a number of PSF coefficients at a variety of positions, then fits polynomials to the residuals to track how the PSF changes across the mask’s field of view. Special care is taken near the 10-20mas region in order to provide accurate sampling of the SGD offsets.

Parameters:

• large_grid (bool) – Use a large number (high-density) of grid points to create coefficients. If True, then a higher fidelity PSF variations across the FoV, but could take hours to generate on the first pass. Setting to False allows for quicker coefficient creation with a smaller memory footprint, useful for testing and debugging.

• force (bool) – Forces a recalculation of coefficients even if saved file exists. (default: False)

• save (bool) – Save the resulting PSF coefficients to a file? (default: True)

Keyword Arguments:

• return_results (bool) – By default, results are saved in self._psf_coeff_mod dictionary. If return_results=True, results are instead returned as function outputs and will not be saved to the dictionary attributes.

• return_raw (bool) – Normally, we return the relation between PSF coefficients as a function of position. Instead this returns (as function outputs) the raw values prior to fitting. Final results will not be saved to the dictionary attributes.

get_IFU_wavelengths(nlambda=None)

Return an array of wavelengths spanning the currently selected IFU sub-band

get_opd_file_full_path(opdfilename=None)

Return full path to the named OPD file.

The OPD may be:

• a local or absolute path,

• or relative implicitly within an SI directory, e.g. $STPSF_PATH/NIRCam/OPD

• or relative implicitly within $STPSF_PATH

This function handles filling in the implicit path in the latter cases.

get_opd_info(opd=None, pupil=None, HDUL_to_OTELM=True)

Parse out OPD information for a given OPD, which can be a file name, tuple (file,slice), HDUList, or OTE Linear Model. Returns dictionary of some relevant information for logging purposes. The dictionary has an OPD version as an OTE LM.

This outputs an OTE Linear Model. In order to update instrument class:

>>> opd_dict = inst.get_opd_info()
>>> opd_new = opd_dict['pupilopd']
>>> inst.pupilopd = opd_new
>>> inst.pupil = opd_new

get_optical_system(fft_oversample=2, detector_oversample=None, fov_arcsec=2, fov_pixels=None, options=None)

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_oversample (int) – 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_pixels (float) – Field of view in pixels. Overrides fov_arcsec if both set.

• fov_arcsec (float) – Field of view, in arcseconds. Default is 2

Returns:

osys (poppy.OpticalSystem) – an optical system instance representing the desired configuration.

get_wfe(kind='si', wavelength=2e-06, plot=False)

Extract and return one component plane of the optical model for this instrument

This is a utility function for convenience, making it easier to access and plot various OPD maps. It doesn’t do anything unique which can’t be done otherwise, and in particular this isn’t used at all as part of the optical propagation calculations.

Note, all WFE terms are returned in OTE entrance pupil orientation (i.e. as if you were in front of the OTE and looking at it), regardless of pupil flips and orientations in the optical propagation.

Parameters:

• kind (string) – A type of WFE. Must be one of “SI”, “OTE”, “OTE_field_dep”, or other values TBD. Case insensitive.

• plot (bool) – Make a quick plot of this WFE. Not very flexible or scriptable but useful for some interactive checks

property image_mask

Currently selected image plane mask, or None for direct imaging

image_mask_list

List of available image_masks

include_ote_field_dependence

Should calculations include the Science Instrument internal WFE?

interpolate_was_opd(array, newdim)

Interpolates an input 2D array to any given size.

Parameters:

• array (float) – input array to interpolate

• newdim (int) – new size of the 2D square array (newdim x newdim)

Returns:

newopd (new array interpolated to (newdim x newdim))

property is_coron

Coronagraphic observations based on pupil mask settings

property is_slitspec

LRS observations based on pupil mask settings

load_wss_opd(filename, output_path=None, backout_si_wfe=True, verbose=True, plot=False, save_ote_wfe=False)

Load an OPD produced by the JWST WSS into this instrument instance, specified by filename

This includes:

• If necessary, downloading that OPD from MAST. Downloaded files are cached in $STPSF_PATH/MAST_JWST_WSS_OPDs

• calling import_wss_opd to load the OPD from the FITS file and perform some necessary format conversions

• Subtract off the instrument WFE for the field point used in wavefront sensing, to get an

  OTE-only wavefront. STPSF will separately add back in the SI WFE for the appropriate field point, as usual.

• Subtract off the modeled field dependence term in the OTE WFE for the sensing field point, to get

  an estimate of the OTE wavefront nominally at the master chief ray location (between the NIRCams). STPSF will automatically add back on top of this the OTE field dependent WFE for the appropriate field point. as usual.

• Scale the OPD to match the same size of the user provide pupil file

Parameters:

• filename (str) – Name of OPD file to load

• output_path (str) – Downloaded OPD are saved in this location. This option is convinient for STScI users using /grp/stpsf/stpsf-data/. Default is $STPSF_PATH/MAST_JWST_WSS_OPDs

• backout_si_wfe (bool) – Subtract model for science instrument WFE at the sensing field point? Generally this should be true which is the default.

• plot (bool) – Generate informative plots showing WFE, including the backout steps. Only works if backout_si_wfe is True.

• save_ote_wfe (bool) – Save OTE-only WFE model? This is not needed for calculations in STPSF, but can be used to export OTE WFE models for use with other software. The file will be saved in the STPSF_DATA_PATH directory and a message will be printed on screen with the filename. Note that the exported OPD file will give the OTE estimated total WFE at the selected Instrument’s field point, not the OTE global at master chief ray, since it is the OTE WFE at the selected field point which is most of use for some other tool.

load_wss_opd_by_date(date=None, choice='closest', verbose=True, plot=False, **kwargs)

Load an OPD produced by the JWST WSS into this instrument instance, specified by filename.

This does a MAST query by date to identify the relevant OPD file, then calls load_wss_opd.

Parameters:

• date (string) – Date time in UTC as ISO-format string, a la 2021-12-25T07:20:00 Note, if date is left unspecified as None, the most recent available measurement will be retrieved.

• choice (string) – Method to choose which OPD file to use, e.g. ‘before’, ‘after’

• Further keyword parameters may be passed via **kwargs to load_wss_opd

property mode

Currently selected instrument major mode, imaging or IFU

property ndeg

Degree of polynomial fit

property npsf

Number of wavelengths/PSFs to fit

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_r (float) – Radial offset of the target from the center, in arcseconds

• source_offset_theta (float) – Position angle for that offset, in degrees CCW.

• pupil_shift_x, pupil_shift_y (float) – 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_rotation (float) – 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.

• rebin (bool) – For output files, write an additional FITS extension including a version of the output array rebinned down to the actual detector pixel scale?

• jitter (string “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_sigma (float) – Width of the jitter kernel in arcseconds (default: 0.006 arcsec, 1 sigma per axis)

• parity (string “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_coron (bool) – 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_sam (bool) – 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.

pixelscale = 0.025

Detector pixel scale, in arcsec/pixel

plot_bandpass(ax=None, color=None, title=None, return_ax=False, **kwargs)

Plot the instrument bandpass on a selected axis. Can pass various keywords to matplotlib.plot function.

Parameters:

• ax (matplotlib.axes, optional) – Axes on which to plot bandpass.

• color – Color of bandpass curve.

• title (str) – Update plot title.

Returns:

matplotlib.axes – Updated axes

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)

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_psfs (int) – 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_detectors (bool) – If True, run all detectors for the instrument. If False, run for the detector set in the instance. Default is True

• save (bool) – True/False boolean if you want to save your file. Default is False.

• outdir (str) – 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

• outfile (str) – 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

• overwrite (bool) – True/False boolean to overwrite the output file if it already exists. Default is True.

• verbose (bool) – True/False boolean to print status updates. Default is True.

• use_detsampled_psf (bool) – 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_centered (bool) – 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 STPSF attribute detector_position (reminder - detector_position is (x,y)). Default is True This is also rarely needed.

• **kwargs – Any extra arguments to pass the STPSF calc_psf() method call.

Returns:

gridmodel (photutils 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.

Examples

nir = stpsf.NIRCam() nir.filter = “F090W” list_of_grids = nir.psf_grid(all_detectors=True, num_psfs=4)

wfi = stpsf.WFI() wfi.filter = “Z087” wfi.detector = “WFI02” grid = wfi.psf_grid(all_detectors=False, oversample=5, fov_pixels=101)

pupil = None

Filename or fits.HDUList for JWST pupil mask. Usually there is no need to change this.

property pupil_mask

Currently selected Lyot pupil mask, or None for direct imaging

pupil_mask_list

List of available pupil_masks

pupilopd = None

Filename or fits.HDUList for JWST pupil OPD.

This can be either a full absolute filename, or a relative name in which case it is assumed to be within the instrument’s data/OPDs/ directory, or an actual fits.HDUList object corresponding to such a file. If the file contains a datacube, you may set this to a tuple (filename, slice) to select a given slice, or else the first slice will be used.

property quick

Perform quicker coeff calculation over limited bandwidth?

property save_dir

Coefficient save directory

property save_name

Coefficient file name

set_position_from_aperture_name(aperture_name)

Set the simulated center point of the array based on a named SIAF aperture. This will adjust the detector and detector position attributes.

property siaf_ap

SIAF Aperture object

property slowaxis

Slow readout direction in sci coords

property use_fov_pix_plus1

If fov_pix is even, then set use_fov_pix_plus1 to True. This will create PSF coefficients with an odd number of pixels that are then cropped to fov_pix so we don’t have to generate the same data twice.

visualize_wfe_budget(slew_delta_time=<Quantity 14. d>, slew_case='EOL', ptt_only=False, verbose=True)

Display a visual WFE budget showing the various terms that sum into the overall WFE for a given instrument

Compares a STPSF instrument instance with the JWST optical budget for that instrument

Parameters:

• inst (stpsf.JWInstrument) – A JWST instrument instance

• slew_delta_time (astropy.Quantity time) – Time duration for thermal slew model

• slew_case (basestring) – ‘BOL’ or ‘EOL’ for beginning of life or end of life thermal slew model. EOL is about 3x higher amplitude

• ptt_only (bool) – When decomposing wavefront into controllable modes, use a PTT-only basis? The default is to use all controllable pose modes. (This is mostly a leftover debug option at this point, not likely useful in general)

• verbose (bool) – Be more verbose

property wave_fit

Wavelength range to fit