APT Special Requirements
Special requirements in APT are defined parameters used to constrain observation scheduling for scientific reasons, or to indicate other situations requiring specific actions.
Special requirements (SRs) in APT are defined keywords that communicate, to the JWST planning and scheduling system, additional constraints that need to be placed on requested observations. SRs are applied at the observation level and pertain to all visits within a given observation. While they are normally used for scientific reasons, SRs can result in significant constraints on the schedulability of the affected observations. Thus, they should only be used if justified by the science goals.
The sections below provide a high-level view of the most used SRs with links to proposal parameters articles containing detailed technical specifications, along with information on how to specify SRs in APT.
Categories of special requirements
See also: Timing Special Requirements (a proposal parameters article)
Timing SRs apply constraints on when an observation needs to occur, either as an isolated observation or in relation to another observation. They also allow a user to request grouping or sequencing for sets of observations, and to make the grouping execute back-to-back (e.g., NON-INTERRUPTIBLE 1). Observations controlled by a periodic phenomenon can use the PHASE SR with various keywords to specify when an observation can occur.
Aperture position angle (APA) SRs
Aperture position angle (APA) SRs are used to constrain the orientation, on the celestial sphere, of a particular observation request. They are also used to constrain the relative or absolute orientation or orientation range that's allowed between observations. While these SRs permit the user to work in the parameter space of interest to their science, from a scheduling standpoint, APA constraints effectively become timing constraints on when the observation can be scheduled. Observers with angular constraints will find it useful to get an overview of their target visibilities and available angles versus time by using the target visibility tools.
Solar system (aka "moving target") SRs
See also: Solar System Special Requirements (a proposal parameters article)
Solar system SRs for observations of solar system objects can be challenging for a number of reasons. Not only do targets move on the celestial sphere as a function of time, but a number of additional constraints come into play, such as observing at a particular longitude on a resolved planet, observing a moon relative to its host planet at a given phase, etc. APT supports a number of SRs that help users describe the needs of their science program.
General or miscellaneous SRs
General or miscellaneous SRs are a few other SRs of potential interest to most general users (although there are a number of limited access parameters in this category that are only used by engineers for testing and calibration activities). The ON HOLD SR is used to indicate an observation that depends on the prior occurrence of another activity; for example, a NIRSpec MOS observation may need to await the availability of NIRCam pre-images. A SR for use with targets of opportunity (ToO) is also available, and serves two purposes: (1) to indicate that the observation is for a ToO, and (2) provide a required response time for a given instance of the triggering event. An OFFSET SR is also provided to permit the placement of a given target position at a position away from the defined fiducial point of a given instrument or aperture.
BACKGROUND LIMITED SR
The BACKGROUND LIMITED SR is called out here due to its potential importance, and also because it was defined late in the JWST APT development process. If you have used the ETC to assess the sensitivity of your proposed observations to the time-variable infrared background levels and made the decision to limit the scheduling windows based on this assessment, the BACKGROUND LIMITED SR may be selected in APT. By default, selecting this SR means that the observation will be scheduled only at a time where the expected background levels are within 10% of the minimum background expected at that position on the celestial sphere.
The extent to which this SR will restrict the schedulability can be assessed using the JWST Backgrounds Tool (JBT). If the default of the "within 10%" is overly restrictive for your use case, the BACKGROUND LIMITED SR provides a small selection of less-restrictive options to choose from (e.g., within 20%, 40%, and 80% of the lowest background level).
Accessing special requirements in APT
Each observation template in APT has a tab labeled Special Requirements. Upon clicking on this tab, two boxes appear in the GUI, one for Implicit Requirements and one for Explicit Requirements.
Implicit requirements are placed on observations automatically by the scheduling system, and are not editable; they are shown to the user for information only. For example, for any multi-visit observations (like mosaics), the system places an implicit GROUP WITHIN 53 DAYS special requirement to prevent the visits from being spread out unnecessarily.
Explicit SRs are SRs requested by users to control or link their observations. They can be accessed by clicking the Add... button below the Explicit Requirements box. The user is provided with a pop-up menu of possible SRs. The first two options, Timing and Position Angle, have an additional layer of options, as shown in Figure 1. Other choices work in a similar fashion, popping up the relevant interface and asking for user inputs.
The use of Position Angle can be confusing. In this context, it refers to the observation being edited, and hence means the aperture position angle for the selected instrument and mode. Since certain controls in APT allow the user to work in observatory V3PA coordinates or Aperture PA, both are reported in APT. In the Figure 1 example, one can see that they are very close, but his is not always the case, depending on instrument and position on the celestial sphere.
After specifying SRs for an observation, the visit planner needs to be run (or re-run) to evaluate the schedulability of the newly constrained observation. If necessary, any SRs can be subsequently edited or removed by highlighting the SR of interest, and clicking the appropriate box in the SR GUI (buttons adjacent to the Add... button).