General Special Requirements (e.g. Guiding, Target Position) are generally used to restrict the scheduling of JWST observations by various constraints. The Astronomer’s Proposal Tool (APT) is used to enter the requirements into the proposal.

Introduction

Most general special requirements directly or indirectly restrict the times when observations (and/or their component visits) can be scheduled. These should be used to provide the schedulers at STScI with enough constraints to ensure that the observations are properly scheduled. Special requirements should not be used unless necessary to accomplish the scientific objectives of the proposal. 

The general special requirements are summarized in Table 1, and a detailed description of each requirement is provided in the following subsections.

Rules and Conventions 

You should observe the following conventions and rules for special requirements:

• You should select the units of all <duration> specifications from a list provided to you. The options are: days, hours, minutes, or seconds.
• An observation-level special requirement applies to ALL the visits within that observation.

Table 1. Supported Formats for General Special Requirements  

Target Position Requirements

OFFSET <X-value>, <Y-value> 

This requirement specifies a non-default placement of the target, relative to the aperture fiducial point in the instrument field of view, for the current observation, which must be on an external target. The X and Y positions are implicitly assumed to be in units of arcseconds.

Each Science Instrument Ideal X-Y coordinate system  and the default positioning for each aperture are defined in JWST Instrument Ideal Coordinate Systems. An aperture’s fiducial point is ordinarily close to the geometric center of that aperture. Details may be found in the TBD article (future link).  

Note that if the observation has a target acquisition, the OFFSET applies only to the science exposures and not to the target acquisition unless the observation uses a NIRSpec MSA target acquisition.

If you are using the OFFSET to move an object of concern *out* of the aperture, failure to specify an APERTURE PA could result in the target getting pushed further onto the detector (e.g. if your OFFSET assumed an APERTURE PA of 0, but the observation occurred at an APERTURE PA of 180, you would move the star further onto the detector).

Note that if mosaics and/or dithers are being done in the observation, the effect is a non-default placement of the target in the entire suite of exposures.

Developer note: APT should test the OFFSET values and warn if the values take the target outside the aperture. There may be situations where we do not want such a warning, but we will not try and anticipate those cases and instead wait to they arise and react accordingly.

Other Requirements

ON HOLD <comment> 

This requirement specifies that the observation should not be executed without further guidance from the observer (such as with a Target of Opportunity proposal or for MSA early acquisition images).  A comment field is available to specify the reason for the ON HOLD requirement.

Note for developers: a required comment field will be associated with the ON HOLD special requirement. 

TARGET OF OPPORTUNITY RESPONSE TIME <response time><carry-over> 

This requirement specifies that the current Observation is to be executed as a Target of Opportunity (ToO).  For more information, see Target-of-Opportunity (ToO) Observations.

  TARGET OF OPPORTUNITY is not allowed for Survey proposals (CATEGORY=SURVEY).

<response time> is the amount of time after the activation request is submitted to STScI that the observation should be started (required).

• The minimum <response time> allowed is 48 hours. See Target-of-Opportunity (ToO) Observations.
• <response time> less than 14 days is considered Disruptive and provides a warning that limited numbers of Disruptive ToOs are accepted.
• <response time> less than 3 days is considered Ultra Disruptive and provides a warning that the proposal will incur additional overhead of 30 minutes per observation.
• Disruptive and Ultra-Disruptive ToOs are not allowed for NIRSpec MOS.

<carry-over> is a checkbox that indicates whether carry-over status is requested. Carry-over status may be requested if the target phenomena have a low probability of occurrence during one cycle. Carry-over ToOs will remain active through the subsequent cycle, and will terminate at the close of that cycle. In addition to selecting this checkbox proposers must add a scientific justification to the Special Requirements section of the Proposal PDF Attachment.

• <carry-over> is not allowed for Ultra-Disruptive ToOs.
• <carry-over> is not allowed for programs requesting time in future cycles.

MAXIMUM VISIT DURATION <duration> 

This requirement specifies that when APT splits an observation into multiple visits, the maximum scheduling duration of each visit within the observation should be less than the <duration>. The default MAXIMUM VISIT DURATION is 24 hours. This requirement can be used to make a very long visit into shorter visits for increased schedulability. It could also be used to suppress the default splitting that occurs at 24 hours. Note that such visits would be harder to schedule and APT will issue a warning.

PARALLEL [<min> to <max> ITERATIONS] [WITH <min_sep> MINIMUM SEPARATION] [SLEW ONLY] 

This requirement specifies that the current observation is to execute as a parallel (see JWST Parallel Observations). Any number of prime slots from any proposals can be specified for one pure parallel observation.

• An observation with the NO PARALLEL ATTACHMENTS special requirement may not also have a PARALLEL special requirement.
• PARALLEL may be allowed, disallowed, required, or expected for each APT template (see Parallel and No Parallel Special Requirement Rules).

For observations with the PARALLEL special requirement:

• TARGET must be set to NONE. 
• Dithering is not allowed.
• Mosaics are not allowed.
• No more than one exposure specification is allowed.

The <min> TO <max> ITERATIONS option allows specification of the minimum and maximum number of parallel exposures to attach to the prime Visit. <max> must be greater than or equal to <min>, and <min> must be specified if a <max> value is given. Values of <min> greater than 5 will tend to reduce or eliminate the matching opportunities for the parallel visit.

  ITERATIONS are not allowed for the four instrument Dark templates.

The <min_sep> MINIMUM SEPARATION option allows the specification of the minimum distance (in arcseconds) between ANY two pointings. If the observation is to be obtained as a slew-only parallel, use the SLEW-ONLY option.

Note that values of <min_sep> greater than or equal to 20” will tend to reduce or eliminate the matching opportunities for the parallel visit.

For observations using PARALLEL SLEW ONLY, Scheduling Duration may not be longer than the duration of the longest slew duration (currently 3963 seconds).

• Scheduling Duration is Science Duration plus Overhead Duration.
• Longest slew duration is specified in the PRD by worst_case_slew_duration in spacecraft_parameters.    

BACKGROUND LIMITED. BACKGROUND NO MORE THAN <percentile> ABOVE MINIMUM

This requirement specifies that the current observation is background limited, and it should be scheduled such that the total background noise is not more than the 10th percentile above that of the minimum background expected at that position on the celestial sphere. Allowed options are 10th, (default), 20th, 30th, 40th, and 50th percentile above minimum. If 10th percentile above minimum creates scheduling conflict with other scheduling constraints, selecting a higher percentile may allow scheduling. If this requirement is not present, the background will not be a factor in determining schedulability. For more information see JWST Background-Limited Observations.

Note that the BACKGROUND LIMITED special requirement is not available for FGS or SC observations.

FIDUCIAL POINT OVERRIDE 

This requirement specifies an aperture to be used (instead of the default aperture) for all exposure pointings in the observation. Users may enter the name of any aperture defined in the Science Instrument Aperture File (SIAF). The SIAF defines apertures and their fiducial points. This override allows the target to be placed in the detector at the fiducial point of the override aperture.

APT does not check that the fiducial point of the FIDUCIAL POINT OVERRIDE aperture coincides with a detector or with the subarray that is being read out. APT provides a selection list with a subset of recommended apertures for the selected instrument (although users may enter any aperture in the SIAF). Recommended apertures are shown in Table 2. 

FULL subarray for NIRCam Coronography

Several apertures available for the NIRCam Coronographic Imaging Template are allowed depending on the selected subarray:

• NRCA4_MASKSWB_NARROW and NRCA5_MASKLWB_NARROW may not be used with the FULL subarray
• NRCA4_FULL_MASKSWB_NARROW and NRCA5_FULL_MASKLWB_NARROW may only be used with the FULL subarray

Table 2. Recommended apertures for FIDUCIAL POINT OVERRIDE selection list

Note to developer: 

• Give an error if the user enters an aperture that is not in the SIAF. 
• Give a warning if the user enters an aperture that not one of the recommended apertures for the selected instrument (see Table 2). For WFSC and SC engineering templates, there are no recommended apertures, so the warning is always generated.

NO PARALLEL ATTACHMENTS 

This requirement specifies that the current observation should not be allowed to have any parallel observations attached to it.

• An observation with the NO PARALLEL ATTACHMENTS special requirement may not also have a PARALLEL special requirement.
• NO PARALLEL ATTACHMENTS may be allowed, disallowed, required, or expected for each APT template (see Parallel and No Parallel Special Requirement Rules).
• An implicit NO PARALLEL ATTACHMENTS is added to an observation if any of the visits would result in too many SAMs (Small Angle Maneuvers).

PARALLELS EXCLUDE POINTINGS <value(s)> 

This requirement specifies that the region(s) of the sky specified by <value> should be excluded from consideration when attaching this external calibration parallel to a particular primary observation; note that the PARALLEL special requirement must be used. If multiple entries for <value> are selected, they are treated as an “and” requirement. The allowed entries for <value> are defined in Table 3.

If multiple entries for <value> are selected, they are treated as an “and” requirement.

Table 3. Regions Supported for PARALLELS EXCLUDE and PARALLELS INCLUDE POINTINGS 

Note that PARALLELS EXCLUDE POINTINGS and PARALLELS INCLUDE POINTINGS can be combined as long as the requirements are not contradictory (e.g. PARALLELS EXCLUDE POINTINGS REGION_OF_M31 and PARALLELS INCLUDE POINTINGS HIGH_STAR_COUNT are inconsistent).

Note to developers: If the PARALLEL special requirement is not specified, a diagnostic should be issued.

PARALLELS INCLUDE POINTINGS <value(s)> 

This requirement specifies that the region(s) of the sky specified by <value> should be included when attaching this external calibration parallel to a particular primary observation; note that the PARALLEL special requirement must be used. Note that if this requirement is specified, all regions not listed in the <value> list are by definition excluded. The allowed entries for <value> are defined in Table 3. 

If multiple entries for <value> are selected, they are treated as an “or” requirement.

Note that PARALLELS INCLUDE POINTINGS and PARALLELS EXCLUDE POINTINGS can be combined as long as the requirements are not contradictory (e.g. PARALLELS INCLUDE POINTINGS HIGH_STAR_COUNT and PARALLELS EXCLUDE POINTINGS REGION_OF_M31 are inconsistent).

Note to developers: If the PARALLEL special requirement is not specified, a diagnostic should be issued.

REALTIME 

This requirement specifies that the current (engineering) observation should have real time access (i.e. be executed during a contact) to JWST.  This will support station-keeping and flight software updates. Realtime visits should be limited in length to 3.5 hours due to the length of normal realtime contacts. (Special contacts can be requested, but would not be longer than 8 hours.)

Note for developer: Visits exceeding 3.5 hours should get a warning, and visits exceeding 8 hours should get an error.

WAVEFRONT SENSING <value> 

This requirement specifies that the current observation is a Wavefront Sensing observation.

If <value> = ROUTINE, this is a routine wavefront sensing observation. When executed this observation may or may not be used for mirror adjustment. When the value is set to ROUTINE, APT creates five independent (unlinked) visits per target. These visits are scheduled as needed by VSS to meet several relative timing and pointing constraints. If a mirror adjustment is desired, a WFC file (provided by the WFSC Scientist) will be attached to the visit by the PPS operator.

If <value> = SENSING_CONTROL, this is a wavefront sensing and control observation. When executed, this observation will be used for mirror sensing, with the option for mirror adjustment. This value is set by APT for wave-front sensing and control templates. These visits are not subject to the routine Wavefront Sensing and Control timing and pointing constraints. If a mirror adjustment is desired, a WFC file (provided by the WFSC Scientist) will be attached to the visit by the PPS operator.

If <value> = SENSING_ONLY, this is a data-collecting observation that is used for wavefront analysis data collecting only. No mirror adjustments are performed. This visit is a data-collecting visit that is used for wavefront analysis through the WAVEFRONT SENSING special requirement (i.e., not a wavefront sensing template). This visit cannot be used for mirror adjustment. These visits are not subject to the routine Wavefront Sensing and Control timing and pointing constraints.

Note that this requirement will be added to all  Wave Front Sensing and Control templates with the values listed in Table 4. Other templates, in particular the templates for NIRCam Engineering Imaging, NIRISS External Calibration, and FGS External Calibration may use SENSING_ONLY to indicate the data should be delivered to the WSS. Table 4 shows required values However, no other templates may use either SENSING_CONTROL or ROUTINE.

All observations with the WAVEFRONT SENSING special requirement must have the DMS PRIORITY of ELEVATED.

Table 4. Wavefront Sensing Values for each Template

VISIT SPLITTING DISTANCE <distance> 

This requirement specifies the distance (in arcseconds) between two sets of pointings in an observation that would cause those pointings to be placed in separate visits. The default value for this distance is a function of Galactic Latitude (see the table), but it can be overridden with this limited access special requirement.

Developer note: Issue a warning if the override value is more than the default value.

REQUIRED 

This requirement specifies that the current observation should be treated as required by the scheduling system.  The calculated visit windows and momentum buildup values will ensure that this observation has a low probability of being skipped by the on-board event-driven commanding system.

Developer note: This parameter will be a limited use parameter because there will be some science use cases, but the user will need to be granted permission.

SPECIAL COMMANDING <text> 

Use of this special requirement indicates that the proposer is requesting a capability which is currently beyond the ability of the ground system to support. The intended use of this parameter is for engineers and Instrument Scientists to be able to investigate conditions on the spacecraft using spacecraft capabilities which are not part of the ground system. Note that the <text> field must be populated. Details of the requirements will need to be specified in the proposal text and/or in observation comments.

Note for developers: If the <text> field is not populated, an error should be given.

DMS PRIORITY <value> 

Use of this special requirement will allow DMS to automatically expedite the processing of particularly urgent visits.  The possible values are STANDARD, ELEVATED, and HIGH, with the default value being STANDARD for all visits except wavefront sensing and control visits (which require the value ELEVATED). Moreover, only observations with the WAVEFRONT SENSING special requirement may use DMS PRIORITY = ELEVATED.

When a visit enters the DMS processing it will be placed in three separate queues. This will allow HIGH and ELEVATED visits to process quicker than STANDARD visits.

MOMENTUM UNLOAD [BIAS_X, BIAS_Y, BIAS_Z] 

Specification of this special requirement will force a momentum unload (MU) to be scheduled before the first visit in this observation.  A Full MU will be scheduled unless the optional parameters are also specified. If the optional parameters are specified, then all three parameters are required, in the ECI frame, with units of Newton meter seconds.  In this case a required Biased MU will be scheduled.

EXPOSE ONLY - NO MECHANISM COMMANDING 

Mechanisms will not be commanded for exposures in observations with this requirement. This means that mechanisms will not be moved and there will be no verifying mechanism related telemetry. This requirement is only available for the following templates:  MIRI External Flat, MIRI Dark, NIRCam Engineering Imaging, NIRISS External Calibration, and NIRSpec Internal Lamp. In the case of NIRSpec Internal Lamp it is not allowed for OPERATING MODE = BRIGHTOBJ.  

Note for developer: The special requirement SPECIAL COMMANDING must be used with this requirement.

OTE TEMPERATURE MONITORING

This special requirement requests OTE temperature monitoring to be performed (used for calibration prior to mirror moves).

Note for developers: For all WFSC engineering templates,  when a WAVEFRONT SENSING=ROUTINE special requirement is included, OTE TEMPERATURE MONITORING is added by default and a warning given if it is not present.

TIME SERIES OBSERVATION

This requirement specifies that a special time series pipeline will be used to process the data. It also signals to APT to allow (warning instead of error) longer exposure times. Table 5 below indicates for which templates this requirement is valid. This list is compatible with the JWST Science and Operations Center Subsystems Interface Requirements and Control Document (JWST-STScI-000905). Note that when this requirement is specified, you MUST also specify the NO PARALLEL requirement (parallel observations are not allowed during time series observations).

  When the TIME SERIES OBSERVATION special requirement is used, NUMBER OF INTEGRATIONS/EXPOSURE must be 2 or greater.

Table 4. Availability of Time Series Observation Special Requirement in APT templates

Guiding Requirements

All observations will be performed using guide stars and the Fine Guidance Sensors.  The absolute error of positioning is one arcsecond (radial) which is dominated by the Guide Star catalog errors.  The RMS jitter is less than 7  milli-arcseconds (1σ, 1 axis).  If difficulties are encountered finding guide stars for your Observation, you are urged to contact the JWST Help Desk at jwsthelp.stsci.edu for help resolving the issue.

PCS MODE <value> 

There are four options for the <value>:

Moving - This requirement specifies JWST is tracking a moving target.

Track -This requirement specifies JWST is tracking (but not fine-guiding) using a fixed target. This mode is intended to be used when the telescope focus is not optimal, during commissioning or special engineering tests.

Coarse -This requirement specifies JWST is stabilized with the Star Trackers for the activities defined in that particular observation.

• • Note that the RMS absolute pointing error for Star Tracker Assemblies hold is 8 arcseconds (1σ, 1 axis, over 90 seconds). 
  • There is a requirement of 1 arcsecond stability (1σ, 1 axis, over 1000 seconds).
  • Visit splitting distance will be 180”.
  • Visit duration may not be longer than the maximum Coarse-mode value (currently 1800 seconds) measured from the start of the first Small Angle Maneuver (SAM).

None - This requirements specifies JWST does not need to be pointed for the observation. It will be used for special visits, such as for loading on-board scripts or other non-standard internal activities.   PCS MODE None is not available for observations with fixed targets. 

Note for developers: the following table indicates the default and allowed values for PCS MODE:

  ¹ There is no explicit requirement PCS MODE Fine Guide, but it is the default if no PCS MODE is specified for a fixed external target. For moving targets, the default is PCS MODE Moving. For Internal Engineering templates this requirement is not applicable.

GUIDE STAR [ID <id>] [IN <guider>]  

Use of this special requirement indicates that the specific guide star and/or guider listed is to be used. Provide the 10-character NGSS guide star ID (e.g. N9EI004968) or the selection of the guide (Guider 1 or Guider 2).   Note that you must select at least one of the values.

 This requirement is not consistent with the PCS MODE None or PCS MODE Coarse requirement, and cannot be used if that requirement is selected.

Note for developers: The rules for checking the legality of an NGSS guide star ID is that it is a 10 character base 36 string with the allowed  characters: A-Z and 0-9.

GUIDE STAR LIMITS <BRIGHT> - <FAINT> 

This special requirement overrides the default <BRIGHT> and <FAINT> limits for guide stars on the observation. Default limits are specified in the PRD fine_guidance_sensor table. <BRIGHT> and <FAINT> are FGS magnitudes, where <BRIGHT> is less than <FAINT>. This special requirement also applies to the FGS reference stars. 

SEGMENT GUIDE STAR 

For use during Global Alignment, this requirement is used to request segment guide stars for a WFSC commissioning observation. This causes the scheduling system to calculate which of the 18 segments to guide on.

When the SEGMENT GUIDE STAR requirement is used:

• A GUIDE STAR special requirement must be used, and both the <id> and <guider> must be specified.
• An aperture position angle must be specified by using an APERTURE PA special requirement, or by using either a SAME APERTURE PA or APERTURE PA OFFSET special requirement linked to an observation with an APERTURE PA special requirement.

MAXIMUM REFERENCE STARS

This special requirement overrides the maximum number of reference stars for NIRSpec MSATA target acquisitions. The allowable range is from 5 to 20. This special requirement may only be used when the target acquisition method is MSATA. 

Note for developers: 

• Minimum value is the PRD Timing Model nirspec_msa_ta_min_num_refstars value (currently 5). (check APT  and PRD)
• Give an error when the MAXIMUM REFERENCE STARS special requirement is present for observations that are not NIRSpec TA Method=MSATA.

PERFORM GS ID AFTER MAM

This special requirement disables Guide Star Skipping after a Medium Angle Maneuver (MAM).

Note to developer: When this SR is used, write visit.skip_first_gs_id_allowed="N" for each visit in an observation.

NO SLEW

All visits contain an initial (visit to visit) slew by default, even those visits that are non-pointed, (i.e., internal), in order to maintain the planned attitude profile, in the event that one or more visits are skipped by the onboard scripts (OSS). The NO SLEW Special Requirement allows the user to override this default behavior by excluding this initial slew from the visit(s) in the observation. 

When NO SLEW is used, no change in pointing is allowed within the visit, including slews, Small Angle Maneuvers (SAMs), and Fine Steering Mirror (FSM) moves. A change in pointing may be caused by choices such as dithers, target acquisitions, or mosaics. 

 When NO SLEW is used, the SPECIAL COMMANDING special requirement is required.

 A non-pointed visit takes on the pointing of the previous targeted visit. The Observation Plan (OP) windows of the non-pointed visit are set such that the spacecraft is at a legal pointing throughout the OP window. If a previous targeted visit is skipped and NO SLEW is performed, then the pointing may no longer be valid for the non-pointed visit. And this carries some risk of a safe mode.

Note to developers: The above warning for non-pointed visits should be communicated to the user in APT when this special requirement is chosen.

Change log