HCI APT Coronagraphic Sequence Examples

Examples of how to specify JWST coronagraphic sequences, one for MIRI and one for NIRCam, are available in the Astronomer's Proposal Tool (APT).

On this page

See also:  High Contrast Imaging Overview 


This article has not yet been updated to include in-flight performance.

Getting started

Words in bold are GUI menus/
panels or data software packages; 
bold italics are buttons in GUI
tools or package parameters.

In APT, the File → JWST Demonstration Proposals option provides 2 coronagraphy example programs: MIRI Coronagraphic Example and NIRCam Coronagraphy ExampleThese 2 examples show how the "MIRI Coronagraphic Imaging" and "NIRCam Coronagraphic Imaging" APT templates, respectively, are filled out. 

A standard coronagraphic sequence involves a set of linked observations; these simple examples demonstrate the process by showing the appropriate special requirements needed for the linking. More complicated combinations using multiple filters and/or coronagraphs are also possible. Also, there are more complex ways of specifying PSF reference star observations than shown in these simple examples below. Refer to the JWST High-Contrast Imaging Roadmap (Stage 3 section) for details.

A MIRI example 

The MIRI Coronagraphy Example can be loaded and viewed in APT as you walk through the example below. See MIRI Coronagraphic Imaging and related articles for detailed information about coronagraphy with MIRI.

There are 2 targets in this example: BET-PIC (the science target) and DEL-DOR (the PSF reference star). A standard coronagraphic sequence involves 2 observations of the science target and at least one observation of the PSF reference star, all linked together in a non-interruptible sequence. (This is done to minimize thermal or other changes that could cause the PSF to vary significantly.)

These observations have already been added to the APT MIRI example. After loading the example into APT, select the Observations folder in the left tree menu to see the filled out template information in the active GUI window, as shown in  Figure 1. Note the template panels labeled Target Acquisition Parameters, Coron Parameters, and PSF Reference Observations, which will be further described below.

Figure 1. The APT GUI for a MIRI coronagraphic sequence

Click on the figure for a larger view.

The appearance of the APT GUI for a simple MIRI coronagraphic sequence. In the tree editor at left, observations 1 and 2 are both on the science target, and observation 3 is of the PSF reference star.  In the active GUI window, one sees template sections for the target acquisition, the coronagraphic exposure specifications, and the PSF reference star assignment section.

Special requirements

The science target is observed twice using a single MIRI 4QPM/filter combination. The initial science observation has an allowed roll angle range. (This is only necessary if there is known structure around the target, say a disk or a known planet, and the target needs to be positioned to avoid structures in the instrument field of view, in this case, the 4QPM quadrants boundaries.) The second science target observation has a roll angle offset relative to the first one, called a roll dither

Figure 2 shows the special requirements that have been set to control this sequence.

Figure 2. Special requirements set for Observation 1

Click on the figure for a larger view.

Clicking on the Special Requirements tab in this example of the APT MIRI coronagraphy template shows special requirements for the first observation. The aperture position angle is set to a fairly narrow 2° range, and an offset angle range of 10°–14° is set between observations 1 and 2. Finally, a non-interruptible sequence requirement is placed on the 3 observations, meaning that the science and reference star observations need to be schedulable at the same time (this can be checked in the APT Visit Planner).

Target acquisition parameters

Target acquisition (TA) parameters are shown in Figure 3.  Legal (but unverified) values have been entered. In reality, you will need to assess the proper TA parameters for each target using the Exposure Time Calculator to ensure a successful observation. This has not been done for this example. An important option is to cross-reference the ETC workbook and/or calculation you used using the box at right.  This can help you reconstruct your assumptions at a later time.  See the APT-ETC Connectivity article for details.

Figure 3. Target acquisition parameters for the MIRI 4QPM case.

Click on the figure for a larger view.

The MIRI target acquisition parameters section of the template is shown. The Acq Quadrant selection allows the user to avoid having a persistence spot in the quadrant where a possible source is expected to be. See MIRI Coronagraphic Target Acquisition for details.

Coronagraph parameters

The Coron Parameters block (see Figure 1) of the template is where the science exposure parameters are specified. These parameters should be set based on calculations performed with the  Exposure Time Calculator, after selecting the parameters appropriate for the MIRI coronagraph.

PSF reference star observation

Finally, even though the SEQ NON-INT special requirement has grouped the observations together, information must be provided to the Data Management System (DMS) on how to connect the PSF reference star observation to each of the science observations. The PSF Reference Observations section, at the bottom of the template, is used for this purpose. Note that in APT, you may have to scroll down to see that block.  For Observation 3 (the PSF reference star observation), simply select the appropriate check box:

Figure 4. Setting the PSF reference star observation for DMS

After selecting the check box to indicate this is a PSF reference observation, the unneeded portion of the PSF Reference Observations block goes away.

Then, for each of the science observations, this reference observation needs to be selected from the pick list provided, as shown in Figure 5.

Figure 5. Selecting the PSF reference star observation for a science observation, to be passed to DMS

After selecting the check box as shown, a legal PSF reference observation has been selected and any red error X's should go away.

Visit Planner

When all observations in the defined coronagraphic sequence have been completely specified, you can run the Visit Planner (VP) to check schedulability.  For the defined sequence to be schedulable, both of the 2 science observations and the PSF reference observation must be observable without interruption. APT will check this, as well as check for available guide stars and other constraints affecting angles and visibilities.

Figure 6 shows the VP display after selecting the observation folder containing the sequence and running the Visit Planner. If you have opened the example program in APT, it may show yellow caution signs by each observation. Simply click the red Update Display button and in a few seconds, green checks should appear, meaning not only is the visibility good for both targets at the same time, but guide stars are also available for all 3 observations as specified. Any time the parameters in the observation template are changed, a new run of the VP will be needed. (Try it!)

 Figure 6. A Successful Visit Planner run.

Click on the figure for a larger view.

The observation folder containing the sequence is selected and the Visit Planner has been run, returning "all green" check marks, thus confirming schedulability. Note the very narrow windows in time, however, caused by the constrained aperture PA requested in the Special Requirements panel.  These are highly constrained observations.

In Figure 6, although the sequence is schedulable, note the very narrow windows in time, thus making the scheduling of this sequence very constrained. This highlights the fact that users should only constrain the requested angles when necessary to support their science goals and even when an angular constraint is placed, the larger the range that can be allowed the better (from the standpoint of allowing scheduling flexibility). As an exercise, the user can try editing the special requirement that sets the allowed range of angles on the first observation and re-run the Visit Planner to see how the allowed time window changes.


While not required, viewing the observations in Aladin can be a useful sanity check to confirm that that the angle had been selected properly and the roll dither had been specified as intended. In Figure 7, we selected the 2 science observations (that is, in the form editor, select Observation 1, then shift-select Observation 2, which should highlight both observations, then choose View in Aladin from the top tool bar in the APT GUI). Since we allowed a range of 10°–14° for the offset, Aladin shows the mean, which is a 12° offset, in the display.

 Figure 7. The Aladin display after selecting the two science observations

Click on the figure for a larger view.

The Aladin display after selecting the 2 science observations. (Select one, then shift-click the second one; Aladin will display both.) This shows both the selected absolute orientation and the offset specified between the 2 observations. In this example, the Digital Sky Survey (DSS) image was not displayed because the brightness of the target star makes it difficult to see the instrument fields of view.

 Roll dithers are limited by JWST observing constraints to be <14°. See the JWST Dithering Overview.

A NIRCam example

The NIRCam Coronagraphy Example demonstration in APT can be loaded and viewed as you walk through the example below. Refer to the NIRCam Coronagraphy and related support pages for detailed information.

The example proposal contains 2 targets, BET-PIC (which represents the science target) and ALF-PIC (which represents the PSF reference star). In this example, we step up the complexity only slightly from the previous MIRI example by having the sequence contain observations with 2 coronagraphs/filters instead of one. In this case, all the observations are done at the initial position angle (roll 1) before moving to the offset roll dither position angle (roll 2). Of course, a single observation in each setup is used on the PSF reference star, so they are put together at the end of the sequence. Hence, this sequence contains a total of 6 observations instead of 3, all of which must be schedulable together in order to be valid.

Figure 8. The APT GUI for NIRCam observations using two coronagraphic/filter sequences, showing the Observation 2 template

Click on the figure for a larger view.

The APT GUI for a NIRCam coronagraphic observation. This template has blocks for Target Acquisition Parameters, Science Exposures, and PSF Reference Observations selections (similar to the MIRI template) but also has a section for specifying parameters for an optional Astrometric Confirmation Image, if desired.

Special requirements

First notice the observation order: observations with the 2 different coronagraph/filter combinations are done at roll 1 prior to the roll dither. Then, both of the observations are repeated after the roll dither. Finally, the PSF reference star is observed in both coronagraph/filter configurations but at a single roll angle. Figure 9 shows the Special Requirements for this example.  Setting the special requirements in this case is a bit different from the MIRI case above, but notice all 6 observations are linked in the sequence, so they will execute together.  Of course, this means that the PSF reference star must be observable at the same time as the science target.

Figure 9. The special requirements for Observations 1 (top) and 2 (bottom)

Click on the figure for a larger view.

An absolute aperture position angle restriction is set, and then the desired relative aperture PA ranges between the pairs of observations with the same configuration is set (e.g., obs. 1 & 3, and obs. 2 &4).  The "Sequence...Non-interruptible" means the entire set of observations will by executed back-to-back, and hence at the same absolute orientation.

In this example, as with MIRI above, we have assumed that the aperture PA needs to be constrained, and we have specified a range from 30°–34°. The offset in PA is set between observations 1 and 3, that is, two observations with the same configuration (F210M Wedge). The "Sequence...Non-interruptible" special requirement ensures the two different configurations execute together and are hence aligned.

The "SEQUENCE ... NON-INTERRUPTIBLE" special requirement indicates that the specified set of observations will be done in "increasing observation number" order. In the example, the observations are shown in order of 1 to 6 in the tree editor (left sidebar). However, for general editing in APT, users are allowed to drag and drop observations in the tree editor. If a user reorders the observations in a sequence using this method, it does not change the execution order, which is done via the observation number. Hence, users should check that their desired order for the sequence is consistent with the ordering on the listed observation numbers.

The specification of PSF reference observations and their proper attachment to each of the science observations proceeds exactly as outlined in the MIRI example.

Visit Planner

As shown in Figure 10, even with a sequence of 6 observations, the Visit Planner has been able to verify that there is a time when all 6 observations can be scheduled together. Again, as with the MIRI example above, the fairly narrow range of allowed absolute PA placed on observation 1 results in a rather small window of schedulability, so this type of restriction should only be placed when necessary for the science.

Figure 10. A successful Visit Planner run for the 6-observation sequence

Click on the figure for a larger view.

A successful VP run for NIRCam, demonstrating schedulability despite the setting of the angular offset special requirements needed in this example.


Finally, if you wish to perform a sanity check on the angular offset between the 2 rolls on the science target, you can select the relevant observations in the tree editor and click View in Aladin, as shown in Figure 11.

Figure 11. This Aladin view confirms the desired roll offset between observations 1 and 3

This Aladin view confirms the desired roll offset between observations 1 and 3. Note that only the small field of view relevant to the NIRCam coronagraph is shown rather than the full NIRCam imaging field of view.

Notable updates
    Updated for Cycle 1
Originally published