OPT: Importing Scheduling Blocks

Note: due to a recent upgrade in Firefox (version 115.x), the functionality of uploading an SB as a text file has been broken. If you want to upload an SB as a text file, NRAO staff have determined that the following browsers and platforms will work: Safari (Mac), Chrome (Mac, Windows, Linux), Opera (Mac, Windows, Linux), and Microsoft Edge (Windows).

Scheduling Blocks and Scan Lists

First, note the differences between importing scan lists and importing complete scheduling blocks:

A text file representing a complete scheduling block (SB) defines not only the scan list, but also defines the variables needed for a scheduling block
Importing scheduling blocks will create a new SB entry in the active Program Block, whereas importing a scan list will add the scans to an active Scheduling Block directly after the active scan, or at the start if the active field is the SB name.

In this section we discuss the scheduling block preamble, and in the next we describe importing scan lists. Note that we are creating experimental scripts that take an ordered list of source names and produce a text file for import into the OPT. This should be helpful to create simple observing schedules. Please let the NRAO Science Helpdesk know if you are interested in trying this out.

Scheduling Block Preamble

A text file defining a scheduling block has to begin with the following case-sensitive content (boldface lines are mandatory):

VERSION;versionNumber;
SCHED-BLOCK;schedBlockName;schedulingType;iterationCount;date;timeOfDay;shadowLimit;. . .
. . .shadowCalcConfiguration;initTeleAz;initTeleEl;avoidSunrise?;avoidSunset?;. . .
. . .windApi;commentsToOperator;

The VERSION line is optional, but if present it must be the first data line and include an integer versionNumber in the second field between two semi-colons (;). The current maximum versionNumber is 6. If the line is omitted, versionNumber defaults to the latest version of the syntax. The documentation here is for the latest version.

The SCHED-BLOCK line distinguishes a complete scheduling block input text file from a scan list input text file. Only a single SCHED-BLOCK line is allowed in the file and has to precede any scan list lines (below). If it is not present the file will be interpreted as a scan list only file as described later. Apart from the data field identifier “SCHED-BLOCK”, this line includes 13 fields and exactly 14 semi-colons (;), including the last. Details and possible (predefined) values per field are described in the table below. Note that unless specified otherwise, the parsing of strings is case sensitive.

schedBlockName	Optional, single value (defaults to [New Scheduling Block]) Name to give to the scheduling block, free-format text.

schedulingType	Optional, single value (defaults to Dynamic), not case-sensitive Scheduling type, valid options are: Dynamic, Fixed.

iterationCount	Optional, single value (defaults to 1) Integer, maximum number of times to observe the scheduling block (Dynamic scheduling type only).

date	Mandatory single value for Fixed, optional multi-value for Dynamic scheduling type Fixed: an observing date, either in "yyyy-mm-dd" format for UTC or a five-digit integer that is interpreted as the VLA LST day (e.g., 2012-07-25 or 62859). The parser will bail out of creating the scheduling block if this date is not in the future. Dynamic: if provided, the earliest and latest UTC date and time that this scheduling block may be run; must be formatted as "yyyy-mm-dd hh:mm:ss, yyyy-mm-dd hh:mm:ss" where the ending date and hh:mm:ss parts are optional. If nothing is provided it defaults to the date that the OPT scheduling block is created for the early start, and a date far in the future for the latest start.

timeOfDay	Mandatory single value for Fixed, optional multi-value for Dynamic scheduling type Fixed: time of day in hh:mm:ss format at which the schedule must start. If the date is in yyyy-mm-dd format the time is interpreted as UTC but if the date is a five-digit integer (i.e., without thousand-separators) it will be interpreted as LST. Dynamic: a comma-separated list of LST start ranges where each range takes the form “hh:mm - hh:mm” where all whitespace is ignored. It defaults to “00:00-24:00” which is only sensible for a scheduling block with only circumpolar sources (Declination > 64 degrees). This implies that any dynamic scheduling block with a standard VLA flux calibrator needs a non-default LST start range.

shadowLimit	Optional, single value (defaults to 0.0) Numerical value in meters (0 to 25) for issuing shadowing warnings in the scheduling block report when an antenna is shadowed by another by this value or more.

shadowCalcConfiguration	Optional, single value (defaults to the first array configuration in the Program Block) The array configuration for which the above shadowing calculation is performed. Valid values: A, B, C, D and Any (case-sensitive!). "Any" implies calculations for the worst case, i.e., "D". When provided, the array configuration has to match one of the array configurations in the program block or it will revert to the default value. The hybrid configurations (e.g., BnA) are also allowed but not in use anymore.

initTeleAz	Optional, single value (defaults to 225) Assumed antenna pointing direction in degrees Azimuth at the start of the observation, used to calculate slewing time to the first source. Valid range: −85.0 to +445.0, where an Azimuth of 180° points toward the south

initTeleEl	Optional, single value (defaults to 35) Assumed antenna pointing direction in degrees Elevation at the start of the observation, used to calculate slewing time to the first source. Valid range: +8.0 to +90.0, where an Elevation of 90° points toward the Zenith and where the lower Elevation limit is 8.0°. (Note, the hard EL limit of the VLA antennas is 8.0°, therefore we recommend avoiding ELs less than 10.0°.)

avoidSunrise?	Optional, single value (defaults to N), not case-sensitive; leave blank for Fixed Should this scheduling block avoid observing at sunrise, i.e., should this scheduling block not overlap in time between 10 minutes before and 60 minutes after the actual sunrise time? Valid values: Y, N. This field must be left blank for Fixed time scheduling blocks.

avoidSunset?	Optional, single value (defaults to N), not case-sensitive; leave blank for Fixed Should this scheduling block avoid observing at sunset, i.e., should this scheduling block not overlap in time between 10 minutes before and 60 minutes after the actual sunset time? Valid values: Y, N. This field must be left blank for Fixed time scheduling blocks.

windApi	Mandatory for Dynamic scheduling type, single or dual value; leave blank for Fixed The maximum allowable wind speed and atmospheric phase fluctuations that are allowed to start observing this scheduling block. Valid entries are either the (case-sensitive!) character designations per observing band (Q, Ka, K, Ku, X, C, S, L or Any - for sub-GHz use Any), which provide pre-defined wind and API limits, or a direct numerical entry for both wind speed (in m/s) and API rms phase (in degrees) as a dual-valued entry. The format for the latter is “w=#,p=#” (w and p in lower case) with # an appropriate non-negative numerical value (wind < 18 m/s, rms phase < 180 deg). Whitespace and reverse order are allowed as long as both variables with values are explicitly specified. This field must be left blank for Fixed time scheduling blocks.

commentsToOperator	Optional, single value Comments to the operator, free-format text

To ingest a text file with a scheduling block, navigate to the OPT and activate (click) the program block or a scheduling block in the program block in which the new scheduling block should be placed. Select from the menu FILE → IMPORT SCHEDULING BLOCK. After providing a file name to import, a new scheduling block with the default name [New Scheduling Block] will be created if no predefined name is given in the first field of the SCHED-BLOCK line. Note that if FILE → IMPORT SCHEDULING BLOCK is grayed out, the wrong item in the project tree is selected (e.g., a scan).

Scheduling Block Preamble Examples

Version line and fixed-date observing specified in VLA LST day and time:

VERSION; 4;
SCHED-BLOCK; Orion Neb; Fixed; ; 72987; 13:45:30; ; ; ; ; ; ; ; Coord w/ HST;

Dynamic observing, with repeat, multiple LST start ranges, shadow calculations and weather settings for X band, and avoid sunset and sunrise with a comment to run with 20 antennas or more.

SCHED-BLOCK;Orion;Dynamic;3;2012-08-11;09:30-13:00,18:00-00:30;0;;180;45;y;y;X;>=20 antennas;

Absolute minimum specifies mandatory wind and API for Dynamic blocks with the receiver letter code only (but then one would be wise to edit the scheduling block name, etc., directly in the OPT).

SCHED-BLOCK;;;;;;;;;;;;Ka;;

Absolute minimum for a Fixed scheduling block includes a fixed starting time (here in LST) at the VLA.

SCHED-BLOCK; ; Fixed ; ; 72859 ; 08:45 ;;;;;;;;;