APT Visit Planner
The APT visit planner tool performs a detailed check of the schedulability of observations specified in APT, including visibility, constraints checking, and whether guide stars are available to support the observation. Diagnostic information is provided when scheduling checks fail.
The visit planner (VP) for JWST observations is a tool in the Astronomer's Proposal Tool (APT) that performs a detailed schedulability assessment of proposed observations. Elements checked by the VP include the general visibility of a target to the observatory as a function of time, the impact of any constraints or special requirements levied on the observations, and whether guide stars are available as a function of time. The VP may be run on individual observations, on collections of observations, and ultimately on the entire set of proposed observations prior to submitting a proposal. Any time a parameter is changed for a given observation, the VP must be re-run to verify the schedulability analysis is still valid.
Running the Visit Planner
In the form editor in APT, select the observation or observation folder to be processed, and then select the Visit Planner* icon from the top tool bar in APT.
If the observations have not yet been checked for schedulability, or if a change has been made since the observation was last checked, the VP GUI will show a yellow warning sign on the observation(s) and the Update Display button in the active GUI window will be highlighted in red, as shown in Figure 1. Clicking that button will start the VP running on the selected observations and their associated visits.
Depending on the number of observations selected and their complexity, the VP execution may vary from a few seconds to a few minutes.
When the VP run completes, there will either be joy (green checks on the observations) or no joy (red X's, indicating there were problems detected that prevent the observation from being schedulable). Generally speaking, the less constrained your proposed observations are, the more likely that they will be schedulable without further interaction.
* 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.
Help with diagnosing and fixing problems
Observations with timing or angular special requirements or other constraints can restrict the scheduling windows significantly, and in the worst cases can actually make it impossible to schedule the observations as specified. Such cases need to be diagnosed to understand the problem so that corrective actions can be considered.
Since it can be difficult to diagnose such problems within APT, you may want to use one of the free-standing target visibility tools to get an overview of the visibility and angular information for the instrument fields of view on the sky as a function of time. Indeed, to avoid possible frustration, users with significant timing or angular constraints are encouraged to run one or more of these tools prior to getting into APT. Note, however, that these visibility tools look at the visibility of targets versus time, not at the entire schedulability of a particular observation of the target. An observation's schedulability depends on several conditions, including availability of guide stars, and can only be verified using the APT VP.
APT contains significant diagnostic help in the form of graphics and reports that can be accessed with knowledge of the appropriate usability tricks, many of which are described below. For example, after running the VP,
- you can click the small arrow to the left of an observation to open a view at the individual visit level;
- click on the arrow next to a visit and see the detailed diagnostics at the visit-level;
- a right-click on an observation or visit provides access to a menu of options for diagnostic plots or shortcuts to expanding or collapsing the display of details.
At the visit-level, you will see a set of bar graphs showing the visibility impacts induced by various constraints such as guide stars, observatory field of regard, angular constraints, and so forth. Red X's on one or more of these constraints can provide clues to why a visit is not schedulable. For the overall observation to be schedulable, all constraints for all visits need to have a window of schedulability at the same time. The bar graph at the observation level shows a roll up of the available times that satisfy the constraints at the visit level. Useful reports (described further below) are accessed from the top File → Export menu in APT.
You can right-click on an observation in the VP and access a pull-down menu with two additional plots that provide detailed information on the guide star availability.
Choosing the Guide Star Availability by Time for Observation option produces a set of bar graphs showing the guide star availability at the visit level for the observation.
Choosing the Guide Star Availability by V3PA for Observation option produces an observation-level summary plot of the number of visits with guide stars as a function of observatory V3 axis position angle. This plot is calculates over the entire range of V3PA and shows valid data at values of V3PA where the target specified can be observed. See Figure 3 for an example.
The last piece of missing information the may be of interest is the length of time the target can be observed at any particular legal V3PA. This can be checked in the VP by opening a given observation to the visit-level, and then right-clicking on the visit to access visit-level plots of guide star and angular information. Figure 4 shows the diagnostic plot produced by the Total Roll Analysis for Visit option. The top plot shows observable V3PAs as a function of time, and the bottom plot shows the length of time the observatory can point at a given V3PA. Users with large or long duration mosaics may need to pick an angle with sufficient visibility to make the observation schedulable.
Note: some users may prefer to run one of the JWST Target Visibility Tools earlier in the planning process to obtain overall summary information on the angles available for their targets. If that information was available already, you could use it to quickly establish whether the best angles in Figure 3 were available or not. This might be easier than pulling up the visit-level plot shown in Figure 4.
If there are valid V3PA ranges where all visits can get guide stars simultaneously and the angle is valid for the observatory, those are the windows of schedulability. If there are no times when all visits can simultaneously get guide stars, this will also be obvious (see Figure 3); hovering your cursor over the green line in the plot will display a pop-up window detailing which visits are causing the problem at that particular V3PA.
An example of where these diagnostics becomes most helpful arises for planning mosaic observations. The operations concept for normal mosaics is that APT looks for a time when all tiles of the mosaic can be scheduled at the same time. The larger the mosaic (that is, the more tiles that are specified), the more likely it will be that one or more tiles cannot get a guide star at the same time as the other tiles. When this happens, the entire mosaic is declared unschedulable by APT. It then becomes a process of understanding which tile or tiles caused the problem, and figuring out how to mitigate the problem. A separate article is available that details the process of splitting off problem tiles into separate observations.
Finally, there are reports generated by the APT VP that can be viewed for further insight into how APT is breaking observations into visits, and how it calculates such things as the timing, pointing, and overheads involved. These reports are accessed the main APT menu, File → Export, and the reports of most interest are called the times file and the pointings file. (The report produced by the Smart Accounting tool is also available in this list.) At this writing, these files are not very user-friendly, but may provide some assistance in diagnosing the most problematic cases.