HCI APT Coronagraphic Sequence Examples
Examples of specifying MIRI and NIRCam standard coronagraphic sequences
See also: High Contrast Imaging Overview
In APT, the File → JWST Demonstration Proposals1 option provides 2 coronagraphy example programs: MIRI Coronagraphic Example and NIRCam Coronagraphy Example. These 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 HCI Roadmap (Stage 3 section) for details.
Bold italics style indicates words that are also parameters or buttons in software tools like the APT and ETC. Similarly, a bold style represents menu items and panels.
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.
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 dither2.
Figure 2 shows the special requirements that have been set to control this sequence.
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.
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:
Then for each of the science observations, this reference observation needs to be selected from the pick list provided, as shown in Figure 5.
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!)
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.
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.
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 six 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.
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.
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.
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.