Commands That Use Setups

The scan and loop Commands

To handle setups, observing commands have been written which package together the usual collection of observing commands into objects that the user can easily chain together (along with their setups) to create their own unique observing scripts. The two fundamental observing commands that deal with setups are scan and loop.

The scan command groups together the standard observing programs and source checking into one concise setup driven package. The syntax of the scan command is:

  scan setup='setupList' [start=value] [stop=value]
where the start and stop keywords are optional (see below). The value assigned to the setup keyword may be one setup or a group of several setups. The next two sections will discuss how the scan command behaves for a single setup entry and then how scan handles multiple (or groups of) setups.

The steps scan takes for each setup

The actual logic of what steps the scan command takes is directly related to the contents of the setup. The order in which each step is taken and the required keyword(s) to proceed is shown in the list that follows. The contents of the setup control which of these steps will be performed but, in principle, each might be done. For example, to set up the correlator, fix the frequency, and tune the receivers, a setup could be constructed which has the necessary correlator and frequency keywords but lacks the source keyword. The task of observing would be omitted in this case. Alternatively, by omitting the freq and iffreq keywords from a series of setups, a user can skip the process of resetting the frequency and retuning before each and every observation.

How scan handles multiple setups

When scan is called, the one required argument is the value associated with the setup keyword. One of the powerful qualities of the scan command is that more than one setup can be passed as its argument. The value associated with this keyword is a (single) quoted string which may be either the name of a single setup or a group of setups which are separated by operators (and perhaps grouped). The operators and the grouping characters define which setups in the list will be executed and in which order. The logical operators are the two characters '|' and ',' and correspond to the operations OR and AND, respectively. Groups are multiple setups treated by scan as a single object and are identified by enclosing the desired setups between a matching pair of parenthesis.

If two or more objects (setups or groups) are separated by the OR character (|), then the first object is run through scan. If that object is successful, then none of the remaining OR'd objects will be run. If the first object fails, then the test if applied to the next object. This process continues until either an object is successful; the setup list is completely exhausted; or the AND character (,) is encountered.

When objects are separated by the AND character (,), every object in the AND list is run through scan. The precedence of the operators is always left to right so the logic of the user's operation may need to be explicitly identified by the use of parentheses. When an object is a grouping of setups, the success or failure of the object is based on the resulting logic of the entire grouping; not necessarily on any one setup.

To illustrate the use of these logical operators and how they apply to individual setups and groups, several examples follow. In each of these examples, it is assumed that the setups A, B, C, and D have already been defined.

Setup A is executed.
Setup A or setup B is executed; but not both. If the setup A could not be observed properly, then the setup B would be executed.
The same as the last case except that setup C is also executed.
Both setups A and B will be executed.
Setup A will be executed. After that, scan will attempt to execute setup B. If that succeeds, then setup C will be ignored; otherwise setup C will be executed.
All four setups are executed.
Both A and B will be run. If either of these setups is successful, then C will be skipped; otherwise, it will be executed. Setup D is always run.
Only one of the four setups would be executed. In this example, the parentheses have no impact.
Setup A is executed. If that succeeds, then the other three are ignored. If setup A does not succeed, then all three setups are run.

How scan knows when to start and stop

The scan command has two optional keyword arguments called start and stop. Both of these keywords take values with the hhmm time format . The start keyword indicates the earliest time that the scan command can execute. Beware of dead time! If the time identified by the start keyword is later than the current LST, then scan will wait until the start time is reached. This may be useful to insure that an observation of a source does not begin so early that the source has not yet risen. If the start keyword is not present, then the default is to begin processing the setup keyword right away. (Because a setup may also have the start keyword which might also delay processing of the setup, it is generally suggested that the start keyword be omitted from setups.)

The other optional keyword to scan is stop. This keyword value specifies how long the scan command has to execute all of the setups present as the value of the setup keyword. This stop time may be referred to as the scan length. Note that this stop time is different from the setup keyword stop in that the setup keyword defines the duration of one setup's observation (or task observation) while scan's keyword identifies how long scan has to finish working through the list of input setups. This optional keyword to scan will, in general, not need to be set by the user since it is set to the project stopping time if it is not present.

Since the scan steps through the setup keyword in a left-to-right fashion, this stop time represents how much time should be needed to execute (or observe) each of the setups. In the most simple case (for example: scan setup='A'), the stop argument would need to just be equivalent to the time needed to observe the one source. However, since the setup can actually request more than one observation (for example: scan setup='A,B,C'), the user needs to be careful when assigning this stop time. It should be reiterated that this time has nothing to do with the individual setup stop times; it is only used to specify how long the scan command has to work through the setup keyword list.

Hence, there are three conditions which determine when scan should stop and the earliest of these always dominates:

The loop command

The loop task combines multiple calls of scan to handle the common observing practice of alternating between sources and calibrators. The syntax for the loop command is:
  loop srcsetup='sourceList' calsetup='calList' [start=value] \
       [stop=value] [thresh=mins]
where the start, stop, and thresh keywords are optional. As with the scan command, if the start argument is not present, it defaults to now. Likewise, if the stop argument is not present, it defaults to the project stop time. The keyword stop can be used to terminate the loop command so that enough time remains for other scan or loop commands.

The optional keyword thresh specifies the minimum number of minutes that is considered acceptable to observe any object in the source setup list. There is only one value associated with the thresh keyword and it is entered in minutes. If this optional keyword is not present, the threshold will be set internally to the average time spent on the calibrator list (typically between 6 and 10 minutes).

The observing logic of the loop command is that it will call scan using the calsetup value (as scan's setup argument) followed by a call to scan using the srcsetup value (again, as the setup argument). These two calls will alternate finishing up with a final call to scan with the calsetup value.

The loop command will stop when the time specified by the optional keyword stop has been reached or the project stop time has been exceeded; whichever is earlier. The internal structure of loop will attempt to insure that a final call to the calsetup is the last scan call performed before the stop conditional is reached. This may cause the final scan call of the srcsetup to be truncated. The details of how the srcsetup time may be adjusted are explained below.

What happens at the end of the loop command is a function of how much time remains. Remember that loop always tries to save enough time to insure that the calibrator can be done at the end. This means that the last source observation will either be truncated or lengthened to account for the scrap time. Whether the source time is made shorter or longer depends on the value of the thresh parameter. The details are outlined in the following paragraph.

If the amount of time that remains prior to the invocation of a source observation greater than the sum of the average source integration time (Tsrc), twice the average calibrator integration time (Tcal), and the threshold time (Tthresh), then the source setup will be observed as normal. If the time remaining is less than (Tsrc + (2 * Tcal) + Tthresh) but greater than (Tsrc + Tcal), then the source setup will be run but will have its integration time increased so that it ends at the loop stop time minus the calibrator time (stop - Tcal). However,, if the time remaining is less than (Tsrc + Tcal) but greater than (Tthresh + Tcal), then the source setup will be executed but the integration time will be shorten to insure that it ends at (stop - Tcal). Finally, if the time remaining is less than (Tthresh + Tcal), then the final calibrator setup is executed and loop exits with about Tthresh minutes remaining until the scheduled stop of the loop command. Note: This last (pathetic) case will only be reached if the loop command is started with less than (Tthresh + Tcal) minutes remaining.

(up to Document Overview, back to An Introduction to Setups, on to Specifying Relative and Absolute Times)
James Morgan

Page last modified: .