General Special Requirements

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

 Format definitions...

Purple text indicates the parameter is Limited Access.

Boldface italics type indicates the name of an APT parameter or a value for a parameter.

(warning)Red text indicates restrictions on a parameter.

(red star) Black text indicates an important note.

Brown text indicates notes for the developers.

Green text indicates the name of the parameter used by Commanding.

Items in brackets - <value> - are required values.

Items in square brackets - [<value>] - are optional.

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  

FORMATEXAMPLE

Target Position Requirements

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

OFFSET 1.0, 2.0


Other Requirements

ON HOLD <comment>

ON HOLD For next galactic SN

TARGET OF OPPORTUNITY RESPONSE TIME <duration>

TARGET OF OPPORTUNITY RESPONSE TIME 21.0 DAYS

MAXIMUM VISIT DURATION <duration>MAXIMUM VISIT DURATION 10 Hours

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

PARALLEL 10394001001_0002,10394001002_0001,10634012005_0001
BACKGROUND LIMITED. BACKGROUND NO MORE THAN <percentage> ABOVE MINIMUMBACKGROUND LIMITED. BACKGROUND NO MORE THAN 20% ABOVE MINIMUM

NO PARALLEL

NO PARALLEL

PARALLELS EXCLUDE POINTINGS <value(s)>

PARALLELS EXCLUDE ECLIPTIC_PLANE, GALACTIC_PLANE

PARALLELS INCLUDE POINTINGS <value(s)>

PARALLELS INCLUDE GALACTIC_CENTER

REALTIME

 REALTIME

WAVEFRONT SENSING <value>

WAVEFRONT SENSING ROUTINE

VISIT SPLITTING DISTANCE <distance>VISIT SPLITTING DISTANCE 30

REQUIRED

REQUIRED

SPECIAL COMMANDING <text>

SPECIAL COMMANDING free text

DMS PRIORITY <value>

DMS PRIORITY ELEVATED

MOMENTUM UNLOAD [BIAS_X, BIAS_Y, BIAS_Z]MOMENTUM UNLOAD
EXPOSE ONLY - NO MECHANISM COMMANDINGEXPOSE ONLY - NO MECHANISM COMMANDING
OTE TEMPERATURE MONITORINGOTE TEMPERATURE MONITORING

Guiding Requirements

PCS MODE <value>

PCS MODE Moving

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

GUIDE STAR ID S8IZ038191 IN Guider 1

GUIDE STAR LIMITS <BRIGHT> - <FAINT>

GUIDE STAR LIMITS 12-14

SEGMENT GUIDE STARSEGMENT GUIDE STAR

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.

(lightbulb) 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 <duration> 

This requirement specifies that the current Observation is to be executed as a Target of Opportunity (ToO). <duration> is the amount of time after the activation request is submitted to STScI that the observation should be started; (warning) the minimum duration  allowed is 24 hours, but durations < 14 days are considered disruptive to the scheduling process. Only a limited number of disruptive ToOs will be accepted (see Target of Opportunity Observations). If disruptive ToOs cause scheduling inefficiencies, an additional overhead may be added to the total time charged (see Direct schedulng overhead).


(red star) Note that all Targets of Opportunity will get an automatic ON HOLD requirement added by APT.

 

Note for developers: <duration> is a required field with NO default value, minimum duration is 24 hours, and the GUI should label durations < 14 days as “Disruptive”.

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.

The <min> TO <max> ITERATIONS option allows specification of the minimum and maximum number of parallel exposures to attach to the prime Visit. (warning) <max> must be greater than or equal to <min>, and <min> must be specified if a <max> value is given; note that values greater than 5 will tend to reduce or eliminate the matching opportunities for the parallel visit. 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.

 

(lightbulb) Note that values greater than or equal to 20” will tend to reduce or eliminate the matching opportunities for the parallel visit.

 

(warning) Note that the following templates MUST use the PARALLEL special requirement: MIRI Dark, MIRI Anneal , NIRCam Dark, NIRSpec Dark, and FGS Internal Flat. 

Note for developer: If any of the above templates do not include the PARALLEL requirement, APT should issue a warning. Also, issue a warning if <min> greater than 5 or <min-sep> greater than or equal to 20”.

(warning) Note that the SLEW-ONLY option should only be used for the following templates: NIRSpec Internal Lamp, NIRISS Internal Flat, MIRI Anneal, and MIRI External  Flat.

Note for developer: APT should put the PARALLEL SLEW-ONLY requirement on those templates by default. If that requirement is missing from any of those templates, APT should issue a warning. If PARALLEL is used on any of those templates without the SLEW-ONLY option, APT should issue an error. If any templates other than these have PARALLEL SLEW-ONLY set, APT should issue an error.

Note that the SLEW-ONLY option can be used for the NIRISS External Calibration template.

BACKGROUND LIMITED. BACKGROUND NO MORE THAN <percentage> 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 <percentage> above that of its minimum possible value. If 10% above minimum creates scheduling conflict with other scheduling constraints, higher values of 20%, 40% and 80% ABOVE MINIMUM are also available.

The lowest value (10% ABOVE MINIMUM) means that the plan windows will not allow the background noise (including both instrumental and sky backgrounds) to be more than 10% higher than its best possible value (i.e. will not allow background noise to exceed 1.1 times its best possible value). The major sources of sky background are discussed in JWST Background Model. The estimated background used in this calculation is the rms pixel-to-pixel noise including detector readout and dark current, thermal backgrounds, and sky backgrounds. Computations use the same data that are used by the STScI Exposure Time Calculators.

If this requirement is not present, the background will not be a factor in determining schedulability.

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

NO PARALLEL 

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

Note to developer: If on observation has a NO PARALLEL special requirement, is cannot also have a PARALLEL special requirement. (A NO PARALLEL observation is by definition a PRIME observation.) Either make the requirement not selectable or give an error that they are inconsistent.

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; (warning) 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 2.

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


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

NameDefinitionNotes

ECLIPTIC_ALL

ECLIPTIC_PLANE and ECLIPTIC_MID_LATITUDE

 

ECLIPTIC_MID_LATITUDE

10° < |β| <30° from ecliptic plane

absolute value of β

ECLIPTIC_NORTH_CAP

a 30° diameter circular region centered on the North Ecliptic Pole

 

ECLIPTIC_PLANE

ecliptic plane ±10°

 

ECLIPTIC_SOUTH_CAP

a 30° diameter circular region centered on the South Ecliptic Pole

 

GALACTIC_CENTER

30° diameter circular region around the galactic center

 

GALACTIC_MID_LATITUDE

10° < |b| <30°  from galactic plane

absolute value of b

GALACTIC_NORTH_CAP

a 30° diameter circular region centered on the North Galactic Pole

 

GALACTIC_PLANE

galactic plane ±10°

 

GALACTIC_SOUTH_CAP

a 30° diameter circular region centered on the South Galactic Pole

 

GALAXY_ALL

GALACTIC_PLANE and GALACTIC_MID_LATITUDE and GALACTIC_CENTER

 

HIGH_STAR_COUNT

GALAXY_ALL and REGION_OF_LMC and REGION_OF_SMC and REGION_OF_M31 and REGION_OF_M33

 

REGION_OF_LMC

8° diameter circular region centered on the LMC

 

REGION_OF_M31

5° diameter circular region centered on M31

 

REGION_OF_M33

2° diameter circular region centered on M33

 

REGION_OF_SMC

5° diameter circular region centered on the SMC

 

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; (warning) 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 the above table).

(red star) 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 3. Other templates, in particular the templates for NIRCam Engineering , NIRISS External Calibration , and FGS External Calibration may use SENSING_ONLY to indicate the data should be delivered to the WSS. However, no other templates may use either SENSING_CONTROL or ROUTINE.


(red star) All observations with the WAVEFRONT SENSING special requirement must have the DMS PRIORITY of ELEVATED.


Table 3. Wavefront Sensing Values for each Templates

Template Name

Required Value

MIRI Multi-Instrument, Multi-Field Imaging 

SENSING_ONLY

 NIRSpec Multi-Instrument, Multi-Field Imaging

SENSING_ONLY

 WFSC Commissioning

SENSING_CONTROL

 WFSC Global Alignment

SENSING_CONTROL

WFSC NIRCam Coarse Phasing

SENSING_CONTROL

 WFSC NIRCam Fine Phasing

No default; user must select either SENSING_ONLY, SENSING_CONTROL or ROUTINE; if the SENSING TYPE = LOS JITTER, then SENSING_ONLY is required

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 MRS, NIRCam Engineering ImagingNIRISS 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.

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

  • PCS MODE Moving - This requirement specifies JWST is tracking a moving target.
  • PCS MODE 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.
  • PCS MODE 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). Note that when this requirement is selected, the visit splitting distance will be 180”.
  • PCS MODE None - This requirements specifies JWST is 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.


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

Template Type

Default1

Allowed

Science in “GO” mode

Fine Guide or Moving

N/A

Science in “Engineering” mode

Fine Guide

Fine Guide, Coarse, None, Track, Moving

External Engineering - Focus

Fine Guide

Fine Guide, Coarse, None, Track, Moving

External Engineering – WFSC Commissioning and Global Alignment

Coarse

Fine Guide, Coarse, None, Track, Moving

External Engineering – WFSC Coarse Phasing

Track

Fine Guide, Coarse, None, Track, Moving

Internal Engineering

None

N/A

  1 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 11-character NGSS guide star ID (e.g. S8IZ0381971) or the selection of the guide (Guider 1 or Guider 2).  (warning) Note that you must select at least one of the values.

(warning) 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> 

Use of this special requirement will override the bright and/or faint limits for guide stars on the specific observation. <BRIGHT> and <FAINT> are FGS magnitudes, where <BRIGHT> is less than <FAINT>.

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.

(red star) The GUIDE STAR special requirement MUST be specified when using SEGMENT GUIDE STAR, and both the <id> and <guider> MUST be specified.

Change log

 Click here to expand...

Version 13 (September 18, 2019)

  1. PROPINSTJWST-83804 - updated PARALLEL section to remove MSA Masking from list of templates that must use the PARALLEL special requirement.


Version 12 (June 17, 2019)

  1. PROPINSTJWST-91396 - Chapter 7: Support OTE Temperature Monitoring for WFSC visits.


Version 11 (April 16, 2019)

  1. Editorial change (moved change log to main article).


Version 10 (October 2, 2018)

 PR 90918 - added NIRISS External Calibration link to EXPOSE ONLY section.


Version 9 (July 23, 2018)

  1. PR 79707 -  updated PARALLEL special requirement section


Version 8 (July 9, 2018)

  1. PR 90457 - updated WAVEFRONT_SENSING special requirement


Version 7 (May 11, 2018)

  1. PR 89880 - updated EXPOSE ONLY special requirement
  2. PR 88877 - removed restriction on Segment Guide Star special requirement
  3.  PR 89853 - removed PRIME_SLOTi parameter and text from PARALLEL special requirement


Version 6 (November 20, 2017)

  1. PR 85811 - updates to OFFSET requirement
  2. PR 87597 - added EXPOSE ONLY requirement
  3. PR 88988 - added note the OFFSET about NIRSpec MSA TA
  4. PR 88394 - revised BACKGROUND special requirement


Version 5 (May 9,2017)

  1. PR 86816 - updates to PCS MODE
  2. PR 86698 - made BACKGROUND NOISE be LAP


Version 4 (November 4, 2016)

  1. PR 85676 - added developer note to NO PARALLEL


Version 3 (October 6, 2016)

  1. PR 85213 - added note for WAVEFRONT SENSING for LOS Jitter


Version 2 (September 1, 2016)

  1. PR 84705 - added MOMENTUM UNLOAD requirement


Version 1 (July 16, 2016)

  1. This is the converted Word File from Chapter 7.
  2. PR 84921 - added red star block to WAVEFRONT SENSING about DMS PRIORITY
  3. PR 84921 - replaced description of DMS PRIORITY
  4. PR 85044 - added red star block for SEGMENT GUIDE STAR about using GUIDE STAR requirement