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)

Words in bold are GUI menus/
panels or data software packages; 
bold italics are buttons in GUI
tools or package parameters.

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., the Non-interruptible constraint in Group/Sequence Observations Link). 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

See also: General Special Requirements (Link goes to Proposal Parameters documentation outside JDox)

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 2 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 in signal-to-noise calculations for faint targets. 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 at or below the 10th percentile above the minimum background expected at that position on the celestial sphere.  That is, the full range of background variation at the target position is assessed, and the 10th percentile of that range is applied as the upper limit allowed.

The extent to which this SR will restrict the schedulability can be assessed using the JWST Backgrounds Tool (JBT).  If the default of the "10th percentile" is overly restrictive for your use case, the Background Limited SR provides a small selection of options to choose from that will increase the scheduling window (e.g., within 20th, 30th, 40th and 50th percentile above the lowest background level). 

For assessment purposes, the ETC allows choices of 10th, 50th, and 90th percentiles for the background levels. Since the purpose of the Background Limited SR in APT is to limit the background, relaxing this parameter above the 50th percentile is not allowed. The finer grid of options provided by APT is for adjusting the scheduling window to meet the user's needs, but these changes can impact the signal-to-noise ratios for the faintest targets.

Accessing special requirements in APT

Each observation template in APT has a tab labeled Special Requirements. Upon clicking on this tab, 2 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 can not be removed or relaxed; they can however be made tighter. 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. You cannot remove the requirement, but you can change it in any way except to make it a longer interval.

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

Beginning with the Cycle 2 proposal opportunity, users should be aware that use of certain SRs can unintentionally force a visit or observation to be scheduled in the portion of the target's visibility that overlaps with the micrometeoroid avoidance zone; if this happens, APT will produce a warning and ask the user to consider revising their requirements to avoid this possibility.


Latest updates
    Updated description of implicit SRs; added reference information about the micrometeoroid avoidance zone.

    Background Limited section updated to use percentiles for consistency with ETC.

    Article updated for Cycle 1 Call for Proposals release. 
Originally published