Introduction

The Visit and Exposure Specifications are used to define the proposed exposures for all the Scientific Instruments. While the number of parameters needed to define all possible instrument configurations is large, the Visit and Exposure Specifications has been simplified by using standard Instrument Configurations and Operating Modes to set most of the instrument parameters to default values. The rest of the exposure keywords are used to define parameters that usually change from one exposure to the next, such as filters, exposure times, and special scheduling requirements.

Before proceeding further, it is useful to define more carefully what is meant by an exposure, a subexposure, and by a visit. (Note: APT also uses Exposure Groups or Containers.)

Exposures

An exposure consists of the events and data corresponding to a unique Exposure_Number within a given visit. The full description of an exposure is called an Exposure Specification. Although many data samples (see APT subexposures) may result from a single execution of an Exposure Specification (due to the Instrument Configuration, Operating Mode, and Optional Parameters chosen), they are considered to be one exposure. Also, you may specify multiple exposures in an Exposure Specification by entering an integer greater than 1 for the Number_of_Iterations keyword; additional exposures will be obtained consecutively (except for possible interruptions by Earth occultations, guide star acquisitions, and SAA passages).

Exposures defined within a visit will be obtained consecutively and in the order specified within a visit.

APT subexposures

Within an Exposure Specification, each data sample that will be taken onboard HST is represented in APT by a separate entity called a subexposure. Subexposures are used to track the duration of the sample (actual_duration) and the orbit number in which it occurs (orbit_number).

Visits

A visit is an exposure or series of consecutive exposures, with overheads, on a given target, and may consist of the following parts:

1. Guide-star acquisition (to point HST at the target)
2. Target acquisition (to place the target in an instrument aperture)
3. Science exposure(s) (to obtain the data)
4. Instrument overheads (to set up the instrument and read out the data)
5. Instrument calibrations (if more than the standard calibration is required)

If the visit lasts more than one orbit, it will continue with the following for each subsequent orbit:

1. Guide-star re-acquisition (to keep HST pointed and locked after Earth occultations)
2. Science exposure(s)
3. Instrument overheads
4. Instrument calibrations

Whenever one of the following occurs, a new visit must be defined:

• A change in target position of greater than 1°. (Contact your Program Coordinator for details regarding solar system objects that move more than about 30 arcsec during the observation and thus are likely to require multiple sets of guide stars).
• Repeated, periodic, or other time-separated observations with an interval between exposures such that one or more empty orbital visibility period (orbits with no exposures) would otherwise be required.
• Required change in spacecraft roll orientation.

Visits

Visit Number and Status

[Visit_Number]

You must assign each visit a unique visit number (base 36 values ranging from 01 - ZZ).

Visit_Status

This field reflects the visit’s execution status and cannot be edited. If you are attached to the internet, the status value is read from the proposal database at STScI when the proposal is opened or saved. It is also saved in the proposal in case work is being done off line later on.

Visit_Status can have the following values: pi, implementation, scheduling, completed, failed, withdrawn. Note that visits with a status of "completed" or "failed" cannot be edited in APT. Also, if you attempt to edit visits with a status of "scheduling" or "withdrawn" you will get a pop up warning that you should let your PC know that you are changing that visit.

Visit Label [Visit_Label]

You can assign a label to each visit. This allows you to call each visit by a name that has more meaning than just the visit number. Please use only alphanumeric characters and hyphens.

Visit-level Special Requirements [Visit_Requirements]

A variety of visit-level Special Requirements may be chosen; these requirements apply to all exposures in the visit (see 6.3 Exposure-level Special Requirements). These requirements will be interpreted by the computer software that is used to schedule the observations; therefore it is essential that the specific formats shown in Conventions for Special Requirements are followed precisely. If none of the allowed Special Requirements appears to be sufficient, you can describe the requirements with a text explanation in Visit_Comments. You should contact your Program Coordinator prior to entering such a comment in your proposal.

Several of these Special Requirements require the use of limited resources or may impose serious constraints on the scheduling system (e.g., ORIENT, CVZ, BETWEEN). Use these Special Requirements with care.

The visit-level Special Requirements are described in detail in 6.2 Visit-level Special Requirements.

On Hold Comments [On_Hold_Comments]

If you have requested via the Special Requirement ON HOLD that a given visit be placed “on hold” (which means that the visit will not be scheduled until you have cleared the hold), then indicate why the visit is on hold, and how the hold is to be released. Examples of On_Hold_Comments are:

• Target of Opportunity
• Waiting for Early Acquisition data from visit <number>
• Waiting for non-HST data [to be obtained <date>]
• Conditional if <text>
• Conditional on <exposure-list> if <text>
• Select <number> of <exposure-list>

Visit Comments [Visit_Comments]

The comments field should be used only to record observing notes; it should not be used to specify scheduling requirements. Comments are not interpreted by the software, but are maintained in the database and do appear on printouts of the programs. Please contact your Program Coordinator prior to inserting comments to make certain there is no other way to specify the information. An Example of a Visit Comments is:

• UV observation of Target X

Exposures

Exposure Number [Exposure_Number]

APT will assign a unique integer number to an exposure. The smallest exposure number permitted is 1, and the largest is 999.

Note  that  exposure  numbers  for  coordinated  parallels  must  (and  will  be) sequential; see Coordinate Parallel Containers.

Exposure Label [Exposure_Label]

You can assign a label to each exposure. This allows you to call each exposure by a name that has more meaning than just the exposure number. Please use only alphanumeric characters and hyphens.

For example given three filters and multiple positions, then you might elect to call a sequence of 6 exposures North-U, North-V, North-B, Center-U, Center-V, and Center-B.

Target Name [Target_Name]

Choose a target from the Target List provided. In the case of certain external (see Table 4.1: Special External Target Names) and internal (see Table 4.2: Internal Calibration Target Names) calibration sources, a special code must be used. In general, calibration observations will be requested only rarely, since most calibrations will be carried out by STScI.

Due to scheduling constraints, fixed external targets and solar system targets may not be used in the same visit. Also, none of the external calibration targets (EARTH-CALIB, DARK-EARTH-CALIB, ANTI-SUN, ORBIT-POLE-NORTH, ORBIT-POLE-SOUTH) may be used in the same visit with another external target.

Astronomical Targets

The target name should be exactly as you entered it in the Target List (see Target Name). Only the prime target name is used; alternate names are not used.

Special Targets

If an internal calibration observation is requested on the Visit and Exposure Specifications, one of the specific “target” names in Table 4.2: Internal Calibration Target Names must be chosen. The calibration source should not be chosen in the Target List. See the Instrument Handbooks for details of the calibrations for each instrument.

The special external targets listed in Table 4.1: Special External Target Names may be specified in the Name without including them in the Target List.

Table 4.1: Special External Target Names

Specific astronomical objects used as external calibrators (e.g., standard stars) should be chosen in the Target List and Visit and Exposure Specifications as normal exposures, and the suffix -CALIB should be appended to their names, as discussed in Special Targets.

Table 4.2: Internal Calibration Target Names

Instrument Configuration [Config]

Choose the Instrument Configuration to be used. The available choices are listed in Table 4.3: Instrument Configurations and Operating Modes, along with the corresponding Operating Modes that may be chosen in Opmode. Legal Apertures, Spectral Elements, and Optional Parameters are uniquely determined by the choice of the Instrument Configuration and Operating Mode. Detailed descriptions are provided in the instruments articles and the Instrument Handbooks.

Table 4.3: Instrument Configurations and Operating Modes

Operating Mode [Opmode]

Choose the Operating Mode to be used. Table 4.3: Instrument Configurations and Operating Modes lists all possibilities. See the Instrument Handbooks and the Instrument articles in this document for detailed discussions of the Operating Modes.

Aperture or Field of View [Aperture]

The desired aperture or field of view of the Scientific Instrument should be chosen (see Table 4.4: Aperture and Field of View Names). However, observers are cautioned that not all combinations of Apertures, Operating Modes, and Spectral Elements are available. See the Instrument Handbooks for details.

Table 4.4: Aperture and Field of View Names

Spectral Element [Sp_Element]

The desired Spectral Element should be chosen. Spectral Elements include filters (F), gratings and grisms (G), echelles (E), prisms (PR), polarizers (POL), linear ramps (FR), quadrant filters (FQ) and mirrors (MIRROR). The names of the filters, gratings, grisms, and echelles include the wavelength of the approximate midpoint of the bandpass, in nanometer.

Examples of the Spectral Element designations are the following:

Polarizer or Crossed Filter

More than one element may be specified, if necessary, using these fields. Choose the desired element from the list provided in the instrument articles. They are also are described in the Instrument Handbooks.

Central Wavelength or Range [Wavelength] (if Grating or Prism Used)

If a linear ramp filter, quadrant filter, grating, or prism is to be used, the central wavelength should be entered.

Wavelengths should be expressed in Å in the observed frame (but the units should be omitted). Use vacuum wavelengths below 2000 Å, and air wavelengths above 2000 Å.

For STIS and COS exposures, the central wavelength must obey one of the legal spectral element/wavelength combinations given in 8.5.1 STIS Central Wavelengths and 11.5.2 COS Spectral Elements and Central Wavelengths.

Number of times to Iterate the Exposure [Number_of_Iterations]

Choose the number of times the defined exposure is to be iterated; Choose 1 if only one execution of the exposure is desired. Typical reasons for iterating an exposure are to monitor temporal changes in a target or to keep CCD exposures short to minimize blooming by a bright star. If more than one execution is requested, iterations (in the form of additional subexposures) will be created and executed contiguously. Also note that for STIS, these subexposures can be interrupted by a wavecal. The wavecal can be suppressed using the optional parameter, WAVECAL; see 8.3.1 CCD Modes and 8.3.2 MAMA Modes.

Time per Exposure [Time_Per_Exposure]

Enter the exposure time (in seconds) for each separate exposure. It is important that observers consult the Instrument Handbooks, and the tools on the STScI Web pages.

Note that the exposure time is the total time for one execution of a defined exposure. Multiple executions may be specified by entering a value for Number_of_Iterations, or with certain Special Requirements. The exposure time entered may be divided among many samples or spectra (subexposures), depending on the Instrument Configuration, Operating Mode, and Optional Parameters. Generally, the exposure time is used only for the collection of photons, but there are exceptions for which instrumental overheads are included in the exposure time. For details, see the specification for each Operating Mode in the instrument articles. In the normal case, the exposure time entered may be used to obtain a single image, to obtain a series of spectra, or to perform a target acquisition.

Routine calibration exposures will be performed by STScI. If special internal calibrations are required for your program, consult the Internal Calibration Target tables in the instrument articles for information about what exposure times to use.

Use the Target Acquisition sections of the Instrument Handbooks and STScI Web tools to estimate exposure times used for acquisition exposures.

Exposure times may be changed during scheduling by STScI in order to place exposures in observing windows defined by orbital constraints (Earth blockage, passage through the SAA, etc.) and to improve overall efficiency. Changes to exposure times will be such that the exposure time is not changed by more than about 20%; note that increases, as well as decreases, in exposure time are possible.

Target acquisition and peakup exposure times are not altered during scheduling.

ETC RUN #

Enter the ETC Run # in the ETC Request ID. Clicking on the icon next to this field will display that ETC Run in your web browser. APT will warn you if you do not supply this information for exposures using one of the sensitive detectors (such as the MAMAs).

Exposure-level Comments [Comments]

Information that cannot be made to conform to the required formats may be entered as a comment. Comments are not interpreted by the software, but are maintained in the database and do appear on printouts of the programs. Comments should be used sparingly, if at all. They are intended only for the small number of programs whose requirements cannot be met with standard and supported features. Please contact your Program Coordinator before entering comments that would affect the execution of an exposure.

Optional Parameters [Optional_Parameters]

The Operating Modes of the instruments frequently have parameters that may be adjusted. The default parameter values that have been defined for the various Instrument Configurations and Operating Modes can be overridden by entries in the Optional Parameters form. See the instrument articles in this document and the Instrument Handbooks for descriptions of the Optional Parameters.

If no values are changed in the Optional Parameters form, default values will be used.

Exposure-level Special Requirements [Special_Requirements]

A variety of exposure-level Special Requirements may be chosen; these requirements apply to individual exposures in a visit (see 6.2 Visit-level Special Requirements). These requirements will be interpreted by the computer software that is used to schedule the observations; therefore it is essential that the formats of the keyword values shown in 6.1 Conventions for Special Requirements are followed precisely. If none of the allowed Special Requirements appears to be sufficient, you can describe the requirements with a text explanation using the “Comments” keyword. You should contact your Program Coordinator prior to entering such a comment in your proposal.

Several of these Special Requirements require the use of limited resources or may impose serious constraints on the scheduling system (e.g., RT ANALYSIS, REQ UPLINK).  These Special Requirements should be used with care.

Exposure Containers: Exposure Sequences, Coordinated Parallels and Patterns

In previous versions of the software, when you wanted to create a set of exposures to be executed in a special way (i.e. a coordinated parallel, a pattern, or a non-interruptible sequence), you would specify exposures separately and then link them with exposure-level special requirements. In APT, the exposure-level special requirements listed below have been replaced with the use of exposure containers or "groups". Once an exposure container has been created in APT, you then place the related exposures in this container instead of using the special requirements to link them.

These special requirements (see 6.3 Exposure-level Special Requirements) that have been replaced by these exposure containers or groupings (in parenthesis) are:

•  Exposure Sequences Container (Type: Sequence) (replaces SEQuence <exposure-list> NON-INTerruptible):

The exposures placed in this container will be observed without gaps due to Earth occultation or SAA passages. See CREATING NON-INTERRUPTIBLE EXPOSURE SEQUENCES for the mechanics (i.e. a "how to") of making a SEQUENCE container.

•  Coordinated Parallel Container (replaces PARallel <parallel-exp-list> WITH <primary-exp-list>):

The exposures in this container using the “primary” SI will execute in parallel with a sequence of exposures using a “parallel” SI. The “primary” SI will be the SI used in the first exposure in this container. See Coordinated Parallel Containers for more information,  and  CREATING  COORDINATED  PARALLEL OBSERVATIONS for the mechanics (i.e. a "how to") of making a PARALLEL container.

•  Pattern Container (replaces PATTERN):

Each exposure placed in this container will be repeated at each point in a pattern of discrete pointing offsets from a target. The pattern # is assigned by APT. See Introduction to Patterns for more information, and CREATING AND USING PATTERNS for the mechanics (i.e. a "how to") of making a PATTERN container.

You can place containers within containers (e.g., a coordinated parallel container can be inside a pattern container).

Subexposures

In an Exposure Specification, each data sample collected is represented in APT by a separate entity called a subexposure. A subexposure tracks the orbit number (orbit_number) of the sample, as well as any override to the default duration (actual_duration). You need not supply these values.

Actual_Duration

Unless the user (or the adjust feature in the Orbit Planner) fills in this field, it will be blank and defaults used. For example, if the exposure is CR-SPLIT, the sum of the exposure times of the subexposures will be equal to the parent exposure’s exposure time. In all other cases the exposure time of each subexposure will be equal to the exposure time of the parent exposure.

Note, however, that if the actual_duration field is filled, this value overrides the default. So the total exposure time for an exposure will be equal to the sum of the actual_durations of the subexposures regardless of the original exposure time.

Orbit_Number

This determines which orbit the subexposure will be placed in. Generally, unless you need to control the orbit structure of the visit, this field can be left alone and will be filled in by the Orbit Planner.

Change Log