# Introduction¶

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

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

) - An optional graphical user interface

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

It is entirely possible (and indeed recommended for scripting) to just use the `WebbPSF`

interface without the GUI, but the
GUI can provide a quicker method for many simple interactive calculations.

## Why WebbPSF?¶

WebbPSF replaced an older PSF simulation package, `JWPSF`

, that was in use prior to 2011.
From a user’s perspective WebbPSF provides the following enhancements over JWPSF:

- Updated to the most recent JWST pupil and OPD models, Revision V.
- Added TFI and FGS models. TFI then updated to NIRISS.
- Updated lists of available filters.
- Added support for coronagraphic and spectroscopic observing modes.
- Includes the detector rotations, particularly for MIRI and NIRSpec
- Adds ability to set output image FOV size and pixel sampling, separate from the oversampling factor used for the optical propagation.
- New & improved graphical user interface.

Perhaps even more importantly, the underlying codebase has been entirely replaced and revamped. The most significant additions from a programmer’s perspective include:

- Much cleaner object-oriented interface. Better abstraction of details across layers.
- Support for optics defined by analytic functions
- Support for coordinate rotations and rotated optics.
- Arbitrary oversampling for coronagraphic models.
- Matrix Fourier Transform algorithm from Soummer et al. implemented for arbitrary detector sampling.
- Optional parallelization for improved speed and efficient use of multiple processor cores.
- Uses
`pysynphot`

library (same as the HST & JWST exposure time calculators) for consistent treatment of filter bandpasses and source spectra.

## 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¶

First, download and install the software. Then just start `python`

and

```
>>> import webbpsf
>>> webbpsf.gui()
```

and you should be able to test drive things using the GUI:

Most controls should be self-explanatory, so feel free to experiment. The article Using WebbPSF via the Graphical User Interface provides a detailed explanation of the GUI options.

WebbPSF can save a detailed log of its calculations and results. This will by default be shown on screen but can also be saved to disk.

```
>>> webbpsf.setup_logging(filename='my_log_file.txt')
```

Log settings are persistent between sessions, so you can just set this once the very first time you start WebbPSF and logging will be enabled thereafter until you explicitly change it.

For further information, consult Using WebbPSF via the Python API or Using WebbPSF via the Graphical User Interface.