JWST APT Coronagraphic Sequence Examples

Examples of specifying MIRI and NIRCam standard coronagraphic sequences

On this page

See also:  High Contrast Imaging Overview 

This article walks through two examples of specifying a coronagraphic sequence, one for MIRI and one for NIRCam. Use the File --> JWST Demonstration Proposal option with the selections  MIRI Coronagraphic Example and/or NIRCam Coronagraphy Example, as directed below. A standard coronagraphic sequence involves a set of linked observations, and these simple examples demonstrate this process by showing the appropriate Special Requirements needed for the linking. More complicated combinations using multiple filters and/or coronagraphs are also possible, as described in JWST Coronagraphy Strategies. Also, there additional more complex ways of specifying PSF reference star observations than are shown in these simple examples below. These will be covered in a future article.



A MIRI example 

The APT demonstration file MIRI Coronagraphy Example can be loaded and viewed as one walks through the example below. See MIRI Coronagraphic Imaging and related pages for detailed information about coronagraph with MIRI.

The example proposal contains two targets, BET-PIC (which represents the science target) and DEL-DOR (which represents the PSF reference star). A standard coronagraphic sequence involves two 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 any thermal or other changes that could cause the PSF to vary significantly.) These observations have already been added to the example file, which looks like Figure 1. Note the template sections labeled Target Acquisition Parameters, Coron Parameters, and PSF Reference Observations, which will be described further below.

Figure 1. The APT GUI for a MIRI coronagraphic sequence

The appearance of the APT GUI for a MIRI coronagraphic sequence. Observations 1 and 2 are both on the science target, and observation 3 is of the PSF reference star. The special requirements set on the first observation are shown. The Aperture Position Angle is set to a fairly narrow 2 degree range, and an offset angle range of 10-14 degrees is set between observation 1 and 2. Finally, the non-interruptible sequence requirement is placed on the set of three observations, meaning that the science and reference star observations need to be schedulable at the same time. This is checked by the APT Visit Planner.

The two observations of the science star are observed with an offset in roll angle between the two (called a roll dither), which is limited by JWST observing constraints to be <14 degrees. In our example, we are observing with a single MIRI 4QPM/filter combination.and we have fixed the allowed range on the initial science observation. (This is only necessary if known structure around a given target, say a disk or a known planet, needs to be positioned so as to avoid structures in the instrument field of view, in this case, the boundaries of the quadrants in the 4QPM). In the example, Figure 2 shows the Special Requirements that have been set to control this sequence:

Figure 2. The Special Requirements set on Observation 1.

After opening the Special Requirements tab in the template, the special requirements set on the first observation are shown. The Aperture Position Angle is set to a fairly narrow 2 degree range, and an offset angle range of 10-14 degrees is set between observation 1 and 2. Finally, the non-interruptible sequence requirement is placed on the set of three observations, meaning that the science and reference star observations need to be schedulable at the same time. This is checked by the APT Visit Planner.
The Target Acquisition parameters that need to be entered are shown in Figure 3.
Figure 3. The Target Acquisition section of the template.

Legal (but unverified) values have been selected and/or entered. In reality, the user needs to assess the proper TA parameters for each target based on running the Exposure Time Calculator. This has not been done for this example.
The Coron Parameters block of the template is where the user should indicate the science exposure parameters for their observation. These parameters should be set based on calculations performed with the  Exposure Time Calculator, after selecting the parameters appropriate for the MIRI Coronagraph.

Finally, even though the setting of the SEQ NON-INT special requirement has grouped the observations together, information must be provided to the Data Management System as to how to connect the PSF reference star observation to each of the science observations.  The section at the bottom of each Observation template gets used for this purpose.  Note that in APT, one may have to use a scroll bar to see the bottom section of the template.  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 display 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.
When all observations in the defined coronagraphic sequence have been completely specified, one can run the Visit Planner to check the schedulability.  For the defined sequence to be schedulable, both the two science observations and the PSF reference observation must be observable without interruption.  APT will check this, as well as checking for available Guide Stars and checking 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 three 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. The observation folder containing the sequence is selected and the Visit Planner has been run.

The observation folder containing the sequence is selected and the Visit Planner has been run, returning "all green", thus confirming schedulability. Note the very narrow window in time, however, caused by the constrained Aperture PA requested under Special Requirements.
In Figure 6, although the sequence is schedulable, note the very narrow window 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 that 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.

It is not required that the user view the observations in Aladin, but it can be useful as a sanity check, both that the angle has been selected properly and that the roll dither has been specified as intended. In the example in Figure 7, we have selected the two 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 APT). Since we allowed a range of 10-14 degrees for the offset, Aladin shows the mean, which is a 12 degree offset, in the display.

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

 The Aladin display after selecting the two science observations

The Aladin display after selecting the two science observations. This shows both the absolute orientation one has selected,and the offset specified between the 2 observations. In this example, the DSS image was not displayed, because the brightness of the target star makes it difficult to see the instrument fields of view.


A NIRCam example

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

The example proposal contains two 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 two coronagraphs/filters instead of one. In this case, following the recommendations of the coronagraphic strategies article, all of 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 six observations instead of three, all of which must be schedulable together in order to be valid. Here is what the special requirement look like for this situation:

Figure 8. The APT GUI for a NIRCam two coronagraphic/filter sequence, showing the template for observation 2 of the sequence.

 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 Astrometric Confirmation Image, if desired.

First notice the observation order shown. Observations with two different coronagraph/filter combinations are done at roll 1 prior to the roll dither, then both of the observations are repeated after the roll. Finally the PSF reference star is observed in both configurations. In this case, setting the Special Requirements is a bit different for the observations with each of the masks, but all six observations are linked in the sequence. Figure 9 shows the Special Requirements from this example.

Figure 9. The Special Requirements set for Obs 1/3 (top) and 2/4 (bottom).

In addition to setting the allowed relative Aperture PA ranges between the pairs of observations, an absolute APA restriction is set as well.
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 degrees. The offset in PA is set between observations 1 and 3, that is, two observations with the same configuration (F210M Wedge). The Same PA special requirement is used on observations 1 and 2 to ensure the two different configurations are aligned, and the non-interruptible sequence special requirement is placed on the entire set.

As a word of caution, the "SEQUENCE ... NON-INTERRUPTIBLE" special requirement indicates that the specified set of observations will in done in "increasing observation number" order. In the example, the observations are shown in order 1-6 in the form editor window at left. However, for reasons of general editing in APT, users are allowed to "drag and drop" observations in the form editor. If a user reorders the observations in a sequence using this method, it does not change the order of actual sequencing of the observations, 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 on the individual observations.

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

As shown in Figure 10, even with a sequence of six observations, the Visit Planner has been able to verify that there is a time when all six 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 six-observation sequence.

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

Finally, if one desires to perform a sanity check on the angular offset between the two rolls on the science target, one can select the relevant observations in the form editor and "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

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.



Published

 

Latest updates
  •  
    Figures updated to APT 25.4.1


  • Figures 2, 8 updated