# Introduction¶

**What this software does:**

- Uses OPD maps precomputed by detailed optical simulations of JWST and WFIRST, and in the case of JWST based on instrument and telescope flight hardware cryo-vacuum test results.
- For JWST, computes PSF images with requested properties for any of JWST’s instruments. Supports imaging, coronagraphy, and most spectrographic modes with all of JWST’s instruments. IFUs are yet to come.
- For WFIRST, computes PSFs with the Wide Field Imager, based on recent GSFC optical models, including field- and wavelength-dependent aberrations. A preliminary version of the Coronagraph Instrument is also available.
- Provides a suite of tools for quantifying PSF properties such as FWHM, Strehl ratio, etc.

**What this software does NOT do:**

- Contain in itself any detailed thermal or optical model of JWST or WFIRST. For the results of end-to-end integrated simulations of JWST, see for instance Predicted JWST imaging performance (Knight, Lightsey, & Barto; Proc. SPIE 2012). For WFIRST modeling, see the WFIRST Reference Info page
- Model spectrally dispersed PSFs produced by any of the spectrograph gratings. It does, however, let you produce monochromatic PSFs in these modes, suitable for stitching together into spectra using some other software.
- Model most detector effects such as pixel MTF, intrapixel sensitivity variations, interpixel capacitance, or any noise sources. Add those separately with your favorite detector model code. (*Note, one particularly significant detector scattering for MIRI imaging has now been added.)

- Conceptually, this simulation code has two layers of abstraction:
- A base package for wavefront propagation through generic optical systems (provided by
`POPPY`

) - Models of the JWST and WFIRST instruments implemented on top of that base system (provided by
`WebbPSF`

)

- A base package for wavefront propagation through generic optical systems (provided by

(There has formerly been a basic GUI front end, but that GUI is now deprecated and no longer recommended for use.)

## Why WebbPSF?¶

For any space telescope, an ability to predict the properties of point spread functions (PSFs) is needed before launch for a wide range of preparatory science studies and tool development. Tools for producing high quality model PSFs must be easily accessible to the entire astronomical community. WebbPSF provides an easy-to-use tool for PSF simulations of JWST and WFIRST, in the style of the highly successful “Tiny Tim” PSF simulator for Hubble.

WebbPSF simulations are based on a mixture of observatory design parameters and as-built properties. The software provides a highly flexible and scriptable toolkit in Python for simulating a very wide range of observing modes and science scenarios, using efficient computational methods (including optional parallelization and use of GPUs). WebbPSF is a key building block in higher-level observatory simulators, including the JWST Exposure Time Calculator.

## Algorithms Overview¶

Read on if you’re interested in details of how the computations are performed. Otherwise, jump to Quick Start.

The problem at hand is to transform supplied, precomputed OPDs (derived from a detailed optomechanical model of the telescope) into observed PSFs as seen with one or more of JWST’s various detectors. This requires knowledge of the location and orientation of the detector planes, the properties of relevant optics such as bandpass filters and/or coronagraphic image and pupil plane masks, and a model of light propagation between them.

Instrumental properties are taken from project documentation and the published literature as appropriate; see the References for detailed provenance information. Optics may be described either numerically (for instance, a FITS file containing a mask image for a Lyot plane or a FITS bintable giving a spectral bandpass) or analytically (for instance, a coronagraph occulter described as a circle of a given radius or a band-limited mask function with given free parameters).

WebbPSF computes PSFs under the assumption that JWST’s instruments are well described by Fraunhofer diffraction, as implemented using the usual Fourier relationship between optical pupil and image planes (e.g. Goodman et al. 1996). Two specific types of 2D Fourier transform are implemented: a Fast Fourier Transform and a discrete Matrix Fourier Transform.

The familiar Fast Fourier Transform (FFT) algorithm achieves its speed at the cost of imposing a specific fixed relationship between pixel
sampling in the pupil and image planes. As a result, obtaining finely sampled PSFs requires transforming very large arrays consisting
mostly of zero-padding. A more computationally attractive method is to use a discrete matrix Fourier transform, which
provides flexibility to compute PSFs on any desired output sampling without requiring any excess padding of the input arrays.
While this algorithm’s computational cost grows as `O(N^3)`

versus `O(N log N)`

for the FFT, the FFT’s apparent advantage is immediately lost
due to the need to resample the output onto the real pixel grid, which is an `O(N^2)`

operation. By performing a matrix fourier transform
directly to the desired output pixel scale, we can achieve arbitrarily fine sampling without the use of memory-intensive large padded arrays, and
with lower overall computation time.

Further optimizations are available in coronagraphic mode using the semi-analytic coronagraphic propagation algorithm of Soummer et al. 2007. In this approach, rather than propagating the entire wavefront from pupil to image and back to pupil in order to account for the coronagraphic masks, we can propagate only the subset of the wavefront that is actually blocked by the image occulter and then subtract it from the rest of the wavefront at the Lyot plane. This relies on Babinet’s principle to achieve the same final PSF with more computational efficiency, particularly for the case of highly oversampled image planes (as is necessary to account for fine structure in image plane occulter masks). See Soummer et al. 2007 for a detailed description of this algorithm.

### Types of Fourier Transform Calculation in WebbPSF¶

- Any direct imaging calculation, any instrument: Matrix DFT
- NIRCam coronagraphy with circular occulters: Semi-Analytic Fast Coronagraphy and Matrix DFT
- NIRCam coronagraphy with wedge occulters: FFT and Matrix DFT
- MIRI Coronagraphy: FFT and Matrix DFT
- NIRISS NRM, GR799XD: Matrix DFT
- NIRSpec and NIRISS slit spectroscopy: FFT and Matrix DFT

See Optimizing Performance and Parallelization in the POPPY documentation for more details on calculation performance.

## Getting WebbPSF¶

The WebbPSF software is installable through pip, but it depends on data files distributed through STScI. Since there is more than one way to install scientific Python software, the possibilities are covered in Requirements & Installation.

The AstroConda distribution includes WebbPSF and its associated data files. If you installed the packages into an environment named `astroconda`

, the command to upgrade all STScI software (including WebbPSF) to the latest version would be `conda update --name astroconda stsci`

.

For those who prefer to use pip (and have NumPy, SciPy, and matplotlib already installed) the command is:

```
$ pip install -U webbpsf
```

This command installs (or upgrades) WebbPSF to the latest version on PyPI. Before WebbPSF will run, you must download the WebbPSF data files and set the `WEBBPSF_DATA`

environment variable to point to the place you extracted them. You may also want to install Pysynphot, an optional dependency, to improve PSF fidelity.

For detailed installation instructions, refer to Requirements & Installation. (This document also explains how to install optional dependencies, install supporting data files, install from GitHub source, etc.)

## Quick Start¶

Once you have installed the software and data files, we recommend you begin with the Jupyter Notebook quickstart tutorial. Downloading and running that notebook is a great way to get started using WebbPSF.