JWST Using Wavefronts Measured On Orbit

STPSF now includes code for using the results of in-flight wavefront sensing measurements, by retrieving Optical Path Difference (OPD) files which include the sensing results for the positions of the mirrors at different times. These are produced by the JWST Wavefront Sensing Subsystem (WSS), using focus diverse phase retrieval on NIRCam weak lens data taken roughly every two days in flight. The output OPDs from that are saved in MAST and can be automatically retrieved and used in STPSF.

These can be used to:

  • Produce PSFs which are matched to the measured telescope state on a given time

  • Trend and monitor telescope stability over time, including for time periods around particular observations

  • Retrieve the JWST wavefront sensing measurements themselves for additional analyses, if desired.

Generating PSFs using measured wavefronts

Finding the measured wavefront near a given date

Begin by instantiating an instrument instance in the usual manner. In this case, let’s set up a NIRCam instance for one of the detectors in module B.

[2]:

nrc = stpsf.NIRCam()
nrc.filter='F200W'

nrc.detector = 'NRCB2'
nrc.detector_position = (1024,1024)

To load an OPD corresponding to observations on some particular date, use the method load_wss_opd_by_date. This takes as its first argument a date time specified in ISO format, like “YYYY-MM-DDTHH:MM:SS”.

Let’s also set plot=True so this makes a plot which shows what’s going on.

[3]:

nrc.load_wss_opd_by_date('2022-07-01T00:00:00',plot=True)


MAST OPD query around UTC: 2022-07-01T00:00:00.000
                        MJD: 59761.0

OPD immediately preceding the given datetime:
        URI:     mast:JWST/product/R2022063002-NRCA3_FP1-2.fits
        Date (MJD):      59759.6628
        Delta time:      -1.3372 days

OPD immediately following the given datetime:
        URI:     mast:JWST/product/R2022070403-NRCA3_FP1-0.fits
        Date (MJD):      59761.5484
        Delta time:      0.5484 days
User requested choosing OPD time closest in time to 2022-07-01T00:00:00.000, which is R2022070403-NRCA3_FP1-0.fits, delta time 0.548 days
Importing and format-converting OPD from /Users/mperrin/software/stpsf-data/MAST_JWST_WSS_OPDs/R2022070403-NRCA3_FP1-0.fits
Backing out SI WFE and OTE field dependence at the WF sensing field point
_images/jwst_measured_opds_7_1.png

Given the input date, the function queries to find the closest-in-time wavefront sensing result. In this case it is a measurement about 0.5 days after the specified time. (You can set keyword choice='before' or choice='after' if you have some reason to specify which in particular). That OPD file will be automatically retrievd from MAST; downloads are cached inside your $STPSF_DATA_PATH directory for reuse in multiple calculations.

Let’s look at each plot in turn.

  • Upper Left: This is the measured OPD as sensed in NIRCam at “field point 1” which is in the upper left corner of NRCA3, relatively close to the center of the NIRCam module. This observatory total OPD measurement includes both the telescope and NIRCam contributions to the WFE.

  • Upper Middle: This is the wavefront map for the NIRCam portion of the WFE at that field point. This is known from ground calibration test data, not measured in flight.

  • Upper Right: That NIRCam WFE contribution is subtracted from the total observatory WFE to yield this estimate of the OTE-only portion of the WFE.

  • Lower Left and Middle: These are models for the field dependence of the OTE OPD between the sensing field point in NRCA3 and the requested field ooint, in this case in NRCB2. This field dependence arises mostly from the figure of the tertiary mirror. These are used to transform the estimated OTE OPD from one field position to another.

  • Lower Right: This is the resulting estimate for the OTE OPD at the requested field point, in this case in NRCB2.

All those calculations happen automatically as part of the load_wss_opd_by_date (inside the load_wss_opd function which it calls in turn).

We note that the function setup_sim_to_match_data (documented here) provides a succinct way to automate the above steps of creating an instrument model and loading a wavefront OPD.

After that it’s just a matter of calculating PSFs as usual:

[4]:

psf = nrc.calc_psf(fov_pixels=101)

[5]:

plt.figure(figsize=(16,9))
stpsf.display_psf(psf, ext=1)
_images/jwst_measured_opds_10_0.png

Thus, the above PSF is calculated using the actual as-measured-at-L2 state of the telescope WFE near the requested date, in this case 2022 July 1.

Loading a particular OPD file

If you already know the filename of a particular desired OPD file, you can simply retrieve it by name using the load_wss_opd function. Once again, this file will be automatically retrieved from MAST if necessary.

[6]:

nrc.load_wss_opd("O2022073001-NRCA3_FP1-1.fits", plot=True)

Found OPD file previously downloaded: O2022073001-NRCA3_FP1-1.fits
Importing and format-converting OPD from /Users/mperrin/software/stpsf-data/MAST_JWST_WSS_OPDs/O2022073001-NRCA3_FP1-1.fits
Backing out SI WFE and OTE field dependence at the WF sensing field point
_images/jwst_measured_opds_14_1.png

Wavefront time series and histogram plots

Other functions can provide views of wavefront changes over even longer timescales. We can retrieve a table of all available OPDs and plot the measurements over time:

[2]:

opdtable = stpsf.mast_wss.retrieve_mast_opd_table()
opdtable = stpsf.mast_wss.deduplicate_opd_table(opdtable)
stpsf.mast_wss.download_all_opds(opdtable)

[3]:

stpsf.trending.wavefront_time_series_plot(opdtable)
_images/jwst_measured_opds_29_0.png

The above shows wavefront drifts and corrections from around the middle of OTE commissioning to the early part of Cycle 1. Rapid drifts and corrections in early March are from the MIRI cryocooler gradually cooling the observatory, until reaching thermal stability in mid April.

Occasional increases in wavefront error from mirror tilts and corrections can be seen in subsequent months. There was an especially large tilt event on July 12, which was corrected on July 15.

We can also plot all measured wavefront drifts over specified time periods.

[4]:

start_time =  astropy.time.Time('2022-05-19T00:00:00')
end_time = astropy.time.Time('2022-09-19T00:00:00')

stpsf.trending.wavefront_drift_plots(opdtable, start_time=start_time, end_time=end_time, n_per_row=10)
_images/jwst_measured_opds_32_0.png

Lastly, we can plot histograms of wavefront error levels over time.

[5]:

start_time =  astropy.time.Time('2022-07-16')
stpsf.trending.wfe_histogram_plot(opdtable, thresh=80, mark_corrections='arrows')
_images/jwst_measured_opds_34_0.png

The above plot shows the wavefront error evolution over the first part of Cycle 1, starting after the ERO release on July 12 and continuing up to present (as of 2022 Dec 13, during the “First Science with JWST” conference). You can see the occasional larger tilt events which are subsequently detected and corrected. It appears possible that the frequency of the larger events may be decreasing over time.

[ ]:

Viewing wavefront observation data and deltas

In addition to the derived wavefront maps, the OPD data files in MAST contain FITS extensions with the image data from the wavefront sensing measurements, with cutouts of the weak lens sensing data. (The full images are also separately available from MAST too). Although most users will not need to refer to these, STPSF includes display tools for viewing them, for instance to help cross-check the quality of a particular wavefront retrieval.

The function plot_phase_retrieval_crosscheck shows the measured weak lens data (left column), and the models of these produced by the Wavefront Analysis Software during the phase retrieval analyses (middle column).

[3]:

most_recent_wfs_file = opdtable[-1]['fileName']

stpsf.trending.plot_phase_retrieval_crosscheck(most_recent_wfs_file);

<Figure size 640x480 with 0 Axes>
_images/jwst_measured_opds_38_1.png

The function plot_wfs_obs_delta plots the difference of two (probably successive) WFS observations. This can be a useful way to quickly visualize what changed from one observation to another, including the presence of potential spoilers such as binary companions.

Here’s an example of that from WF sensing in January 2023. The presence of a binary companion shows up clearly in the difference image.

[4]:

stpsf.trending.plot_wfs_obs_delta('R2023012904-NRCA3_FP1-1.fits', 'R2023012803-NRCA3_FP1-1.fits',
                                    vmax_fraction=0.2);

<Figure size 640x480 with 0 Axes>
_images/jwst_measured_opds_40_1.png 
[ ]: