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.

On this page

 APT Visit Planner Video Tutorial,   Using Aladin and APT Visit Planner Video Turorial

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.

Figure 1. The VP GUI showing that the VP needs to be run on a selected observation

The yellow caution symbols indicate the need to validate the observation by running the VP. Click the red Update Display button to run the VP.

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

See also: JWST Observatory Coordinate System and Field of Regard
See also: APT Visit Planner Constraints

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. For more information on the meaning of the various constraints, see APT Visit Planner Constraints.

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.

Figure 2. An unsuccessful run of the VP showing observation and first visit diagnostics

An unsuccessful run of the VP is shown, with the observation and first visit diagnostics shown. These were opened by clicking the small arrows to the left of each item in the active GUI window. In this example, the red X on ABSOLUTE ORIENT indicates a position angle has been selected that is not allowed.

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.

Figure 3. V3PA guide star plot shown for a modest NIRCam mosaic containing 12 visits

 V3PA guide star plot shown for a modest NIRCam mosaic containing 12 visits

A V3PA guide star plot is shown for a modest NIRCam mosaic containing 12 visits. The plot shows that there is no V3PA (and hence no time) when all 12 visits (in this case, each tile of the mosaic is a visit) can get guide stars simultaneously. This makes the entire observation unschedulable in APT.  Luckily, in this case, there are several windows where 11 of the 12 visits can get guide stars. Hence, this situation could be addressed by removing the problem tile to a separate observation where that tile has a guide star available. In some cases, multiple tiles may need to be removed to make the overall mosaic schedulable.

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.

Figure 4. An example "Total Roll Analysis for Visit" diagnostic plot

This visit-level report shows available V3PA angles as a function of time in the top plot, the number of days available at each allowed V3PA in the bottom plot, and a tabular listing of dates and V3PAs on the right. This can be used to establish how long the "best" angles in Figure 3 are actually observable by JWST, thus closing the loop on what is needed for schedulability.

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. 



Latest updates

Updated Figs. 1 and 2; added link to Constraints definition article.

Article reviewed and updated for Cycle 1 Call for Proposals release.