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. 

On this page

See also: JWST APT Help Features

 Adding Special Requirements in APT Video Tutorial

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

Timing SRs

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*). 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

See also: Aperture Position Angle Special Requirements (a proposal parameters article); JWST Position Angles, Ranges, and Offsets.

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

See also: JWST Background ModelGeneral Special Requirements (a proposal parameters article)

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).

* 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.

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 user-specified (or explicit) Special 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 Special 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.

Figure 1. Example of a cascade of windows for selecting and setting an observation's position angle range

Figure 1. Example of cascade of windows for selecting and setting an observation's position angle range

Selecting Add... in the APT SR GUI, then moving right on the Position Angle option allows the PA Range option to be selected. This pops up the box shown below it where the user can enter the desired range of position angles. Note that in this example, a range of 0° to 0° results in a highly constrained observation. For reference, differences between the astronomical PA and the V3PA of the observatory are shown directly above the OK button. (Some APT constraints reports express angles in units of V3PA.) By clicking OK after entering the SR values, the SR will be displayed in the Special Requirements box in the GUI.

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.

See also: JWST Position Angles, Ranges, and Offsets; JWST Observatory Coordinate System and Field of Regard

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).



Latest updates
    Article updated for Cycle 1 Call for Proposals release.