Timing Special Requirements

Timing Special Requirements (e.g. AFTER, GROUP) are used to restrict the scheduling of JWST observations by timing constraints. The Astronomer’s Proposal Tool (APT) is used to enter the requirements into the proposal.

Introduction

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.

Timing special requirements directly 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. 

(red star) As noted in the Observation Specifications article, all visits within a given observation have an implicit GROUP WITHIN 53 DAYS special requirement, and are required to be executed at the same aperture position angle. Separate observations have no such restrictions.

The Timing Special Requirements are summarized in Table 1, followed by a detailed description of each requirement.

Rules and Conventions 

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

  • A <date> specification in a Special Requirement must be a geocentric date expressed in Universal Time (UT); a heliocentric Julian Date is required for the PHASE/PERIOD/ZERO-PHASE   requirement. There are two legal date formats: DD-MMM-YYYY and YYYY.DDD (where DDD is numerical day of year). For example, 14-DEC-2011:17:05:41 refers to 14 December 2011, geocentric UT 17H05M41S. Only the necessary precision need be employed (e.g., 14-DEC-2011 or 2011.348 might be adequate), but four-digit years are mandatory.
  • You should select the units of all <duration> specifications from a list provided to you. The options are: days, hours, minutes, or seconds.
(warning) Note that users may also specify a date in day-of-year format, such as 2010.189.  Such a date must use a 4-digit year and a 3-digit integer for the day (fractions of days are not allowed).  This capability is meant for internal STScI usage, and proposers should use it with care.
  • An observation-level special requirement applies to ALL the visits within that observation.
  • For a scheduling window created by a requirement which creates a time-related constraint (BETWEEN, AFTER <observation> BY,   and the PHASE range of the PHASE/PERIOD requirement):
    • The absolute minimum window allowed is 5 minutes for an individual observation (10 minutes for AFTER <observation> BY). 
    • Windows  less than   one hour (3600 seconds) will incur Direct scheduling overhead to account for impacts to the scheduling of other observations (see Time Constrained Observations).
  • A diagnostic will be generated if the sum of the durations of the Observations in a group length is greater than the sum of their durations, plus some padding for Observatory overheads (e.g. Momentum unloads).

Note for developer: The values above are maintained in the JWST SOC PRD.

 (warning)  Timing special requirements are not allowed for Survey proposals (CATEGORY=SURVEY).

 

 Table 1. Supported Formats for Timing Special Requirements

FORMATEXAMPLE

AFTER <date>

AFTER 2018-JUL-11:12:06

AFTER <observation> [BY <duration1> TO <duration2>]

[EXCLUSIVE USE OF INSTRUMENT]

AFTER 06 BY 7 DAYS TO 9 DAYS

BEFORE <date>

BEFORE 2018-SEP-11

BETWEEN <start-date> AND <end-date>

BETWEEN 2018-DEC-21 AND 2018-DEC-31

GROUP OBSERVATIONS <observation list> [WITHIN <duration>] [NON-INTERRUPTIBLE] [EXCLUSIVE USE OF INSTRUMENT]

GROUP OBSERVATIONS 05-10 WITHIN 60 DAYS


SEQUENCE OBSERVATIONS <observation list> [WITHIN <duration>] [NON-INTERRUPTIBLE] [EXCLUSIVE USE OF INSTRUMENT]

SEQUENCE OBSERVATIONS 05-07 NON-INTERRUPTIBLE

GROUP VISITS WITHIN <duration> [NON-INTERRUPTIBLE] [EXCLUSIVE USE OF INSTRUMENT] 

GROUP VISITS WITHIN 1 DAYS EXCLUSIVE USE OF INSTRUMENT

 PHASE <number1> TO <number2> with PERIOD <duration> and ZERO-PHASE (HJD) <date>

PHASE 0.09 TO 0.11 WITH PERIOD 1.23 HOURS AND  ZERO-PHASE (HJD) 2444000

  AFTER <date> 

This requirement specifies that the observation (all visits) must start after the date given by <date>.

  AFTER <observation> [BY <duration1> TO <duration2>] [EXCLUSIVE USE OF INSTRUMENT] 

This requirement specifies that the visits in this observation must all start after the visits in the referenced <observation>. The BY <duration1> TO <duration2> option allows specification of an acceptable time interval between the observations.  For example, AFTER 6 BY 7 DAYS TO 9 DAYS requests that no visit in the current observation start earlier than 7 days after any visit in observation 6 starts, nor will any visit in the current observation start  later than 9 days after any visit in observation 6 starts.  

If the difference between <duration1> and <duration2> is too small, the observation may be difficult or impossible to schedule. A difference of at least 10 minutes is required. A difference of less than one hour will incur Direct scheduling overhead (see Time Constrained Observations).  Note that if <duration 1> is not specified, it will be treated as 0. If <duration 2> is not specified, it will be treated as infinity.

The EXCLUSIVE USE OF INSTRUMENT option is used to carry out an engineering procedure for a given instrument that requires two or more visits with a substantial time separation between the first and last. While the procedure is underway, no other visits using that instrument may be scheduled.  An example is the NIRSpec MSA ANNEAL.

Note for developers: there needs to be a diagnostic if an AFTER OBSERVATION BY is created between Observations using different instruments when EXCLUSIVE USE OF INSTRUMENT is specified.

Note for developers: When an AFTER requirement is placed on two observations, APT will make the GROUP VISITS requirement into a SEQ VISITS requirement, and APT will generate two visit-to-visit after links.  One link is between the first visit in the first observation and the last visit in the second observation, with the same min and max time.  The other link is between the last visit in the first observation and the first visit in the second observation, again with the same min and max time. These requirements will guarantee that all visits in the second start within the observer's time window after all the visits in the first.  If either Observation has only 1 visit, you still need both links, but if both have only 1 visit, there is no need for the second link.  APT will have to check that.

In this example, with two observations of 3 visits each: OBSERVATION 2 AFTER OBSERVATION 1 BY 7 DAYS TO 10 DAYS, you will get Visit 2.1 AFTER Visit 1.3 BY 7 days to 10 days and Visit 2.3 AFTER Visit 1.1 BY 7 days to 10 days.

Graphically it looks like this:

  BEFORE <date> 

This requirement specifies that the observation (all visits) must start before the <date> given.

BETWEEN <start-date> AND <end-date>

This requirement specifies that the observation (all visits) must start (but not necessarily end) between <start-date> and <end-date>.   For example, BETWEEN 2018-SEP-14 AND 2018-SEP-21 indicates that all visits in the observation must be started after 14 September 2018 and before 21 September 2018.

(warning) The time interval <end-date>-<start-date> must be at least 5 minutes. Time intervals less than one hour between <start-date> and <end-date> will incur Direct scheduling overhead  (see Time Constrained Observations).

Definition of First Science Activity

For most observations the exact definition of when a visit starts is not important. But for a very tight BETWEEN requirement, it could be important. <start-date> to <end-date> is the range in which the start of the first science activity in the observation should begin.The start of the science activities in a visit is after the end of the slew and guide star acquisition activities. If the visit has a target acquisition then the start time is after the end of the target acquisition, and any slew to the first science pointing. Otherwise, the start time is the start of the science observation activity, which includes any mechanism and science instrument configuration.

(red star) The BEFORE, AFTER <date>, and BETWEEN Special Requirements are mutually exclusive. An observation which specifies one may not specify either of the other two, although multiple BETWEENs are allowed. Note that any BEFORE or AFTER <date> may be replaced by a BETWEEN with a sufficiently early start date or late end date. However, AFTER <observation> may be combined with BETWEEN or BEFORE.

Multiple BETWEEN Special Requirements

Multiple BETWEEN Special Requirements may be specified on an observation. The observation will be allowed to execute during any of the time intervals specified. For example, the combination of BETWEEN 2018-SEP-14 AND 2018-SEP-21 and BETWEEN 2018-OCT-10 AND 2018-NOV-01 means that the observation must be started either between 14 September 2018 and 21 September 2018, or between 10 October 2018 and 1 November 2018. (warning) Multiple BETWEEN intervals on the same observation may not overlap: all the other intervals must either end earlier than <start-date> or start later than <end-date>.

Software limitation with long observations

If a visit's scheduling duration exceeds the gap between BETWEEN requirements the scheduling system cannot enforce the gap. Either shorten the visit or increase the gap between BETWEEN requirements. (warning)A visit's scheduling duration may not be longer than the gap between BETWEEN requirements. 

GROUP OBSERVATIONS <observation list> [WITHIN <duration>] [NON-INTERRUPTIBLE] [EXCLUSIVE USE OF INSTRUMENT]

SEQUENCE OBSERVATIONS <observation list> [WITHIN <duration>] [NON-INTERRUPTIBLE] [EXCLUSIVE USE OF INSTRUMENT]

GROUP VISITS WITHIN <duration> [NON-INTERRUPTIBLE] [EXCLUSIVE USE OF INSTRUMENT] (implicit requirement)

SEQUENCE VISITS WITHIN <duration> [NON-INTERRUPTIBLE] [EXCLUSIVE USE OF INSTRUMENT] (implicit requirement)

You can link observations or visits together so that they will schedule within the <duration> specified, or in a NON-INTERRUPTIBLE manner. (warning) Data volume for linked NON-INTERRUPTIBLE observations is summed and is subject to data excess limitations.

If you GROUP OBSERVATIONS, all visits of observations included in the observation list will execute in an order determined by the scheduling system. 

If you SEQUENCE OBSERVATIONS, all visits of observations included in the sequence are ordered according to the specified order. The sequence is ordered by Observation Number (unless you reorder the sequence).  For example, SEQUENCE OBSERVATIONS 1–4 WITHIN 4 DAYS means that all visits of observation 4 must start within 4 days of the start time of observation 1, with observations 2 and 3 executing in between. SEQUENCE constrains the order of the component visits. So not only do the observations start in order, the visits from observation 1 have to be done before the visits from observation 2 begin.

To reorder the sequence of some or all of the observations, click REORDERING, then enter the new order as a list of observation numbers separated by commas. REORDERING is particularly useful for partially executed sequences of observations. For example, if Observations 1, 2, and 3 of a six observation sequence have already executed, you can reorder the remaining three unexecuted observations by entering Reordering = 6, 4, 5.

An observation implicitly has a GROUP VISITS WITHIN 53 DAYS. You can modify this requirement if you need to further restrict the window of time in which the visits will start;  (warning) <duration> must not exceed 53 days. Note that you can select NON-INTERRUPTIBLE instead of using a WITHIN.

For the NIRCam Imaging, NIRCam Engineering Imaging, NIRCam WFSS, and NIRISS SOSS templates, the SEQUENCE option is selected for certain observations to ensure filters are executed in the expected order:

  • For observations that specify multiple filters with those filters split across multiple visits, the SEQUENCE option is selected by default in the implicit GROUP VISITS WITHIN.
  • For the NIRISS SOSS template, SEQUENCE is required. 
  • For the NIRCam Imaging, NIRCam Engineering Imaging, and NIRCam WFSS templates, SEQUENCE may be edited by the user, but a warning is provided if SEQUENCE is removed.

WITHIN <duration>

If a <duration> is specified, all visits included must start within the duration given. For example, GROUP OBSERVATIONS 7–10 WITHIN 12 HOURS requests that all visits of observations 7 through 10 all start execution within a 12-hour interval.

Note that if the time interval given is shorter than the minimum interval to execute the visits, the visits will be unschedulable.

(red star) The final visit to execute will start within the <duration> specified, but may execute partially outside the window.

NON-INTERRUPTIBLE

If NON-INTERRUPTIBLE is selected, then all visits included must execute without interruption.

(warning) The total duration of a non-interruptible group may not exceed 24 hours due to scheduling concerns.

(warning) An observation may not be included in multiple non-interruptible links.

(warning) An observation included in a non-interruptible Group/Sequence link may not itself have a non-interruptible Group/Sequence special requirement.

EXCLUSIVE USE OF INSTRUMENT

This option is used to carry out an engineering procedure for a given instrument that requires two or more visits with a substantial time separation between the first and last. While the procedure is underway, no other visits using that instrument may be scheduled.  An example is the NIRSpec MSA ANNEAL.

Note for developers: there needs to be a diagnostic if a GROUP/SEQ is created between Observations using different instruments when Exclusive Use of Instrument is specified.

PHASE <number1> TO <number2> with PERIOD <duration> and ZERO-PHASE (HJD) <date>

This requirement supplies the PERIOD and ZERO-PHASE for observations to be made at a specific PHASE of a periodically variable (fixed or moving) target. <duration> is the period in days, hours, minutes or seconds. <date> is the date of the zero-phase with respect to the Sun (i.e., HJD, not a calendar date). <number1> to <number2> is the phase range in which the start of the first science activity in the observation should begin (see  Definition of First Science Activity ); <number1> and <number2> must be between -1.0 and 1.0. 

Julian Dates must be entered in the form nnnnnnn.nnn (e.g., 2444123.4). Only the required precision need be provided.  All Julian Dates will be interpreted as heliocentric.

(lightbulb) Note that the PHASE requirement you specify on a multi-visit observation will be applied to each Visit individually. If different phases are needed for the different visits then the visits need to be in separate observations. If you need your visits/observations to be in the same periodic cycle, you need to also use a GROUP VISITS/OBSERVATIONS WITHIN <duration> requirement (making <duration> the PERIOD of the system).

Developer note: As indicated in the box above, PHASE may only be used for external observations.


Definition of First Science Activity

For most observations the exact definition of when a visit starts is not important. But for a very tight PHASE requirement it could be important.  The start of the science activities in a visit is after the end of the slew and guide star acquisition activities. If the visit has a target acquisition then the start time is after the end of the target acquisition. Otherwise, the start time is the start of the science observation activity, which includes any mechanism and science instrument configuration.

Multiple periods which must be satisfied simultaneously

If a target has multiple periods which must be satisfied simultaneously, the PERIOD ZERO–PHASE Special Requirement should refer to the shorter of the two periods and the longer period can be specified using multiple BETWEEN Special Requirements that cover the next year and a half. Please contact jwsthelp if you need to use this technique.. (Example: The target is an X-ray pulsar. The observation needs to occur in a particular phase of the 35-hour binary period as well as a particular phase of the 2-month on/off period. Use the PERIOD ZERO–PHASE Special Requirement for the 35-hour period and then specify the 2-month period with multiple BETWEENs.)

PHASE range for short periods

With short periods, the phase range (difference between <number2> and <number1>) should be made as wide as possible to make scheduling easier. 

As noted above under Rules and Conventions, there are limits on the duration of the phase range: (<number2>-<number1>)*PERIOD. Phase range durations of less than one hour will incur Direct scheduling overhead (see Time Constrained Observations). The absolute limit is 5 minutes.

Software limitation with long observations

(warning)A visit's scheduling duration may not be longer than the gap between PHASE ranges. If a visit's scheduling duration exceeds the gap between acceptable PHASE ranges the scheduling system cannot enforce the PHASE special requirement.

Expressed mathematically, this software limitation occurs when:

Visit Scheduling Duration > PERIOD x (1 - (<number 2> - <number 1>))

The most straightforward workaround is to modify the Period and Phase to eliminate half of the scheduling opportunities. To do this: double the period and halve both components of the phase range.

For example if you receive an error with PERIOD = 0.8 Days and PHASE= 0.3 to 0.4 you can change the requirement to PERIOD 1.6 Days and PHASE 0.15 to 0.2.

Change log

 

  1. PROPINSTJWST-91636 Added rules for default selection of SEQUENCE for certain templates. 


 

  1. PROPINSTJWST-91620 Added restriction to Rules and Conventions section that Timing SR is not allowed for Survey proposals.


 

  1. PROPINSTJWST-91642 Added Reorder description and example to the Group/Sequence Observation Link section.



Version 10 (December 29, 2021)

  1. PROPINSTJWST-80208 Updated PHASE SR to allow negative phase range start.


Version 9 (October 19, 2021)

  1. PROPINSTJWST-91489 Added red note to Group/Sequence Observation section


Version 8 (May 18, 2021)

  1. PROPINSTJWST-90808 Added documentation of new constraint to PHASE and BETWEEN sections.
  2. Editorial change - Anchor links fixed in parameter table by removing pagename from link.


Version 7 (February 28, 2020)

  1. PROPINSTJWST-91456 Removed TIME SERIES OBSERVATION section.


Version 6 (November 22, 2019)

  1. PROPINSTJWST-91414 - Moved TIME SERIES OBSERVATION section to General Special Requirements page.
  2. PROPINSTJWST-91404 - constraints/warnings added to NON-INTERRUPTIBLE section.


Version 5 (April 16, 2019)

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


Version 4 (January 26, 2018)

  1. PR 86735 - added text describing direct scheduling overhead for tight timing windows.


Version 3 (December 27, 2017)

  1. PR 88411 - added note to TSO about needing NO PARALLEL


Version 2 (October 19, 2017)

  1. PR 87867 - added new Time Series Observation requirement


(January 18, 2017)

Updated the time minimum length of a time constraint that would not incur an special overhead. (Per meeting with Lou Strolger on 1/13/17.)


Version 1 (June 28, 2016)

This is the converted Word File from Chapter 7.