OPT: Importing Scan Lists into SBs

Note: due to a recent upgrade in Firefox (version 115.x), the functionality of uploading Scan lists as a text file has been broken. If you want to upload Scan lists 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).

Scan Lists

Recall from the previous section that scan lists can only be uploaded into an existing scheduling block in the OPT; it will not create a new scheduling block. Before uploading make sure to select API/wind conditions that match your observing requirements. The following scan syntax is a description of the latest version (see previous section). To define a scan list, the standard case-sensitive(!) text file content must start with (boldface lines are mandatory):

VERSION; 6;
SRC-CAT;sourceCatalogNames;
HDWR-CAT;hardwareCatalogNames;

These catalog lines must be included before any scan line described below, and currently also before the SCHEDBLOCK line described in the previous section (where it also says that specifying the version is optional). The following table contains a more extensive description:

Type of Line	Field	Description
SRC-CAT	sourceCatalogNames	Mandatory, multi-value Comma-separated list of names of source catalogs in order of priority, highest priority first. Source names below must be pre-defined with source properties in at least one of the included catalogs, where the first match will be the one that defines the source in this scan. In practice, one would list the personal source catalogs containing sources for this scheduling block and end with the standard VLA calibrator catalog if the calibrators to be used were not copied to the personal catalog.

HDWR-CAT	hardwareCatalogNames	Mandatory, multi-value Comma-separated list of names of resource catalogs in order of priority, highest priority first. Resource names below must be pre-defined with resource properties in at least one of the included catalogs, where the first match will be the one that defines the resource in this scan. In practice, one would list the personal resource catalogs containing resources for this scheduling block and end with the standard NRAO Defaults (note the upper-case D in Defaults) catalog for continuum and pointing setups.

Text files with scan lists can be imported into the OPT if they use the following syntax. Every line containing any scan information in the file must define a separate scan as one of the following options:

STD;scanName;sourceName;resourceName;timeType;time;antennaWrap;applyRefPtg?;applyPhase?;. . .
. . .recordOnMark6?;allowOverTop?;use10HzNoise?;pulsarRecording;VDIFrecording;scanIntents;comments;
PTG;scanName;sourceName;resourceName;timeType;time;antennaWrap;applyRefPtg?;applyPhase?;. . .
. . .recordOnMark6?;allowOverTop?;use10HzNoise;comments;
TIP;scanName;azimuth;resourceName;timeType;time;antennaWrap;tippingOrder;comments;
OTFM;scanName;sourceName(beg);sourceName(end);resourceName;timeType;time;numSteps;numIntPs;. . .
. . .RAdirection;antennaWrap;applyRefPtg?;applyPhase?;recordOnMark6?;allowOverTop?;use10HzNoise;comments;
SOL;scanName;sourceName;resourceName;timeType;time;antennaWrap;applyRefPtg?;applyPhase?;. . .
. . .recordOnMark6?;allowOverTop?;use10HzNoise?;pulsarRecording;VDIFrecording;scanIntents;solarHwCfg;comments;

Standard, Pointing, On-the-fly Mosaicking, and Solar Mode Scans

Standard observing mode, or STD-scans, require 15 additional fields (in the numbered order below) and 16 semi-colons (;), including the last. Pointing mode scans, or PTG-scans, necessary only for observations at the higher frequencies (Ku, K, Ka, Q), have 12 additional fields and 13 semi-colons, including the last. Similarly, Tipping mode scans, or TIP-scans, are described with 8 additional fields and 9 semi-colons including the last. On-the-fly Mosaicking (OTFM, introduced in version 3) scans are defined with 16 additional fields and 17 semi-colons. These modes were complemented (in version 4) by Solar mode scans, or SOL-scans, and require 16 additional fields and 17 semi-colons (which fields aren't exactly the same as for OTFM). The following table contains a more extensive description of the fields for STD, PTG, OTFM or SOL lines (other scans further below):

Order				Field	Description
STD	PTG	OTFM	SOL
1	1	1	1	scanName	Optional, single value (defaults to the source name (below) or [New Scan]) The name to be given to the scan.

2	2	2, 3	2	sourceName	Mandatory, single value A source name with its properties (such as sky coordinates) must pre-exist in one of the source catalogs included in the list in sourceCatalogNames in the SRC-CAT line. If you use an alias (B1950, NGC, 3C, Messier name, etc.) as source name instead of the standard 10-digit J2000 calibrator or target name in your scheduling block, please make sure to include this source name with the J2000 coordinates in one of your listed source catalogs. Note that for OTFM-scans (introduced in version 3), both a beginning and end source position name must be entered in two different columns. Also be alerted that calibrators in the VLA catalog use capital letters (J#, and 3C# for the standard flux density calibrators) in their designation.

3	3	4	3	resourceName	Mandatory, single value A resource name with its properties (such as receiver observing band, etc.) must pre-exist in one of the resource catalogs included in the list in hardwareCatalogNames in the HDWR-CAT line. The special term prev (not case-sensitive) can be used to indicate that there is no resource change from the previous scan, though this term is not allowed in loops.

4	4	5	4	timeType	Optional, single value (defaults to Duration LST), not case-sensitive The timing method used for the scan. Valid options with their 3-letter abbreviations are: Duration (LST) or DUR, On-Source (LST) or SRC, Stop Time (LST) or END, Duration (UT) or UTD, On-Source (UT) or UTS, Stop Time (UT) or UTE.

5	5	6	5	time	Mandatory, single value Time measure for the scan, typically a scan length in the form of hh:mm:ss.s or αhβmγs, but for stop times an absolute hh:mm:ss.s time of (LST or UT) day. Note that 01:02 is interpreted as 1h 2m, and that 01:2.0 is interpreted as 1m 2.0s so it is safest to use the full h:m:s format with two colons (:) or explicitly write it as 1m 2.0s (with or without spaces) if that is what is meant. A pointing scan needs at least 2m30s on-source time, after slewing.

-	-	7	-	numSteps (OTFM-scan only)	Mandatory, single value (introduced in version 3) The number of steps, number of phase centers along a strip or stripe. See the OTFM mode description on the special modes page.

-	-	8	-	numIntPs (OTFM-scan only)	Mandatory, single value (introduced in version 3) The number of integrations per step, per phase center. See the OTFM mode description on the special modes page.

-	-	9	-	RAdirection (OTFM-scan only)	Mandatory, single character (introduced in version 3) For any two points in the sky there is a shortest path between them in RA as well as a path to go the other way and take the long slew in RA (there is only one way allowed in Dec, the shortest way). Using the character '0' (zero) will select the shortest path between the starting point (2nd parameter) and the end point (3rd parameter). To explicitly fix the motion in RA, use a plus or a minus sign to observe in increasing RA direction ('+') or in decreasing RA direction ('-'), respectively. Valid values: +, -, 0 (zero)

6	6	10	6	antennaWrap	Optional, single value (defaults to No Preference), not case-sensitive Specified antenna azimuth wrap for the scan. Valid values: R, CW, Clockwise, No Preference, L, CCW, Counterclockwise

7	7	11	7	applyRefPtg?	Mandatory, single value, not case-sensitive Should this scan use previously determined reference (antenna) pointing offsets? Needs a preceding PTGscan to be effective. Valid values: Y, N

8	8	12	8	applyPhase?	Optional and only for phased VLA observations, single value (defaults to N), not case-sensitive Should this scan use previously determined delay and phase (autophasing) solutions? Needs a preceding STD-scan with DetAutoPh intent (see below) to be effective, and usually not used. Valid values: Y, N

9	9	13	9	recordOnMark6?	Optional and only for phased VLA VLBI observations, single value (defaults to N), not case-sensitive Does this scan need recording for correlation with other antennas? Do not use unless you know what this means and you really need it. Valid values: Y, N

10	10	14	10	allowOverTop?	Optional, single value (defaults to N), not case-sensitive Allow the antennas to tip to the other side of the zenith, to Az+180? Do not use unless you know what this means and you really need it. Valid values: Y, N

11	11	15	11	use10HzNoise?	Optional, single value (defaults to Y), not case-sensitive (introduced in version 5) Use the noise diodes for calibration. When observing pulsars this will mimic a 10Hz pulsar so pulsar observers (only) would want to switch it off. Valid values: Y, N

12	-	-	12	pulsarRecording	Optional, single value (defaults to N), not case-sensitive (introduced in version 6) Use for pulsar-mode observations using a resource specified as such. Do not use unless you know what this means and you really need it. Valid values: Y, N

13	-	-	13	VDIFrecording	Optional, single value (defaults to N), not case-sensitive (introduced in version 6) Use for eLWA observations, cross correlating VLA+LWA (not for VLBI - see recordOnMark6). Do not use unless you know what this means and you really need it. Valid values: Y, N

14	-	-	14	scanIntents (STD-scan only)	Mandatory, multi-value, not case-sensitive All intents for each scan should be listed. The full list of intents, including all intents for operations, is collected in the documentation mentioned above. The most useful valid options for normal observing: ObsTgt observe the target, usually not combined with any other intent CalGain calibrate phase and amplitude gains together, in particular for standard calibration loops on the target source CalFlux determine the absolute flux density scale calibration, typical on the handful of standard VLA flux calibrator sources CalBP bandpass calibration on a strong continuum source SetAtnGain setup attenuator and requantizer gain levels for the antennas CalDelay delay calibration if the bandpass calibration scans are not suitable for delay calibration, or to explicitly name a scan for this purpose CalPolAng source with a known polarization angle for calibration of the absolute polarization angle in polarized target sources CalPolLeak calibration scans to resolve the differences and cross-contamination between the two orthogonally measured polarizations Note that the separate scan definition for a pointing scan or OTF only differs from a standard scan because the scan intent is fixed for those scans; pointing scans may indeed also be phased up and recorded for VLBI correlation.

-	-	-	15	solarHwCfg (SOL-scan only)	Optional, single integer value (defaults to 1) (introduced in version 4) Use no specific attenuation hardware (0), use the low-noise (1) or high-noise (2) internal cal to set the attenuators for the quiet and active Sun, respectively. In the future the L-band reverse coupling setup (3) may be available too. Valid values: 0, 1, 2 (and maybe 3)

15	12	16	16	comments	Optional, single value Any comments for personal use such as reminders or purpose, free-format text.

Note that in principle only a single one of STD/PTG/TIP/OTFM/SOL scans in the scan list is required, but it does not make sense to not have any STD-scan in a normal observation scheduling block (as any science data calibration scan will be an STD scan).

Tipping Mode Scans

Please note that tipping scans are currently prohibited. Until further notice, there is no suggested path in CASA or AIPS to apply tipping scan solutions to the data. This documentation is for those who want to take the tipping data anyway during their observations. If you have questions about setting up TIP-scans please consult the NRAO Science Helpdesk.

Tipping mode scans will need a scan length of at least 1 minute and 50 seconds to perform the tip and to derive a useful measurement. Slew from the previous source to the anticipated azimuth needs to be added to the scan length and is not straightforward to estimate for a dynamic schedule; use the longest slew during any of your LST start times (which may need some experimenting with the assumed LST start of the SB in the Reports tab).

The following table contains the fields expected on a TIP line.

Order	Field	Description
1	scanName	Optional, single value The name to be given to the scan.

2	azimuth	Mandatory, single value Numerical value in degrees azimuth at which a tipping scan should be performed. Valid range: −85.0° to +445.0°.

3	resourceName	Mandatory, single value A resource name with its properties (such as receiver observing band, etc.) must pre-exist in one of the resource catalogs included in the list in hardwareCatalogNames in the HDWR-CAT line. The special term prev (not case-sensitive) can be used to indicate that there is no resource change from the previous scan, though this term is not allowed in loops.

4	timeType	Optional, single value (defaults to Duration LST), not case-sensitive The timing method used for the scan. Valid options with their 3-letter abbreviations: Duration (LST) or DUR, On-Source (LST) or SRC, Stop Time (LST) or END, Duration (UT) or UTD, On-Source (UT) or UTS, Stop Time (UT) or UTE.

5	time	Mandatory, single value Time measure for the scan as in all other scans. Note that for a tipping scan the on-source time should be at least 1m50s.

6	antennaWrap	Optional, single value (defaults to No Preference), not case-sensitive Specified antenna azimuth wrap for the scan. Valid values: R, CW, Clockwise, No Preference, L, CCW, Counterclockwise

7	tippingOrder	Mandatory, single value, not case-sensitive Elevation movement while performing the tipping scan. Valid values: Up or Low To High, Down or High To Low in elevation (underscores may be omitted). Scan length will be fixed to 5 minutes.

8	comments	Optional, single value Any comments for personal use such as reminders or purpose, free-format text.

Scan Loops

Loops of scans can be defined (with 4 additional fields and 5 semi-colons) and nested without limitation, and every LOOP-START line must have a corresponding LOOP-END (with no other fields and a single semi-colon). The uppermost unpaired LOOP-END is taken to end the lowermost unpaired LOOP-START.

LOOP-START;loopName;iterationCount;bracketed?;comments;
  [some STD-scans and/or PTG-scans, TIP-scans, nested loops, etc.]
LOOP-END;

The following table describes fields expected on a LOOP-START line:

Order	Field	Description
1	loopName	Optional, single value (defaults to [New Loop]) Name of the loop, e.g., to remind oneself of the content when collapsed in the scheduling block tree.

2	iterationCount	Mandatory, single value Integer number, maximum number of times to observe the loop of scans at this point in the schedule.

3	bracketed?	Optional, single value (defaults to N), not case-sensitive Specifies whether the loop is a bracketed loop, i.e., whether the first scan of the loop is repeated at the very end of all loop iterations. Valid values: Y, N

4	comments	Optional, single value Any comments for personal use such as reminders or purpose, free-format text.

Subarrays

Up to three subarrays can be generated using the syntax below; it is a kludge from the normal loop and thus a bit more clumsy (with 5 additional fields and 6 semi-colons). Subarrays cannot be nested, but loops in subarrays can. Every SUBARRAY-LOOP-START line must have a corresponding SUBARRAY-LOOP-END (with no other fields and a single semi-colon). The uppermost unpaired SUBARRAY-LOOP-END is taken to end the lowermost unpaired SUBARRAY-LOOP-START. Note that the number of pads in a 3-subarray observation cannot be 9+9+9; the closest possible subarray distribution is 8+9+10 antennas.

SUBARRAY-LOOP-START;subarrayName;1;N;;ListOfPads;
  [some STD-scans and/or PTG-scans, TIP-scans, nested loops, etc.]
SUBARRAY-LOOP-END;

The following table describes fields expected on a SUBARRAY-LOOP-START line:

Order	Field	Description
1	subarrayName	Optional, single value (defaults to [New Subarray]) Name of the subarray, e.g., to remind oneself of the subarray goal when collapsed in the scheduling block tree.

2	[unused]	Mandatory, 1 Loop-implementation left-over: must be a "1" as in the maximum number of times to observe the subarray.

3	[unused]	Optional, single value (defaults to N), not case-sensitive Loop-implementation left-over: should be a "N" as in not to repeat the first scan and bracket the loop.

4	[unused]	Optional, single value Loop-implementation left-over:Any comments for personal use, free-format text.

5	listOfPads	Mandatory, comma-separated list of pads List of antennas used in the subarray, with pads named in relative order on each (N,E,W) arm as counted from the center. That is, here E09 is (always) the furthest antenna (with the longest baselines) on the east arm for example, regardless whether it is D-array (absolute pad name E09) or A-array (absolute pad name E72) configuration, Similarly W01 is the antenna closest to the center on the west arm: i.e., pad W01/W02/W04 in D/C/B-array or pad W08 in A-array, Example (note that "pads" don't need to be listed in sequence) [for subarray #1] N03,N02,W09,E04,E05,W06,N01,W08,W07 [for subarray #2] N05,N04,N09,E02,W02,W04,E06,E09

Holography

For completeness the following defines the holograpy line. This mode should not be used in general but is listed here as documentation for operations. Note that in the OPT there is a way to define the antenna wrap which is missing in the definition here, and that there is no implementation of rotating the grid yet (in this text line, nor in the OPT itself, only in the observing script). The UT scan duration and scan intent are automatically generated in the interface from this text line input.

HOLO;scanName;sourceName;resourceName;maxTime(h);refAnts;dwellTime(s);initDir(AZ/EL);. . . 
. . .numbPtsAz;numbPtsEl;offsAz;offsEl;oversampAz;oversampEl;initDirAz;initDirEl;. . .
. . .calIntRow;calDur(s);ptgResource;ptgIntRow;ptgDur(s);comments;

Importing a Scan List

To ingest a text file with a scan list, navigate to the OPT and activate (click) the scheduling block or a scan in the scheduling block in/after which the new scans should be placed. Any lines relating to the scheduling block preamble will be ignored at this stage. Select from the menu FILE - IMPORT SCANS. After providing a file name to import, scans will be appended directly after the activated field, i.e., at the beginning of a scheduling block if the scheduling block is active, or after the activated scan. The imported scans can be moved around with the the general copy/paste method of the OPT web application.

Examples

Following are some very simple (version 4) examples for 8-bit correlator modes; for 3-bit modes additional setup scans are needed and may be recommended for 8-bit as well. An example of an OTFM scheduling block is given in the OPT manual, OTFM section.

Example of a scan list with two (8-bit) low-frequency science resources (thus no pointing) starting with target observing and ending with flux calibration scans at the end of the observation:


# Start with defining which pre-defined source and resource catalogs to use
SRC-CAT; My Sources, VLA;
HDWR-CAT; My Resources, NRAO Defaults;
#
# Two one-minute 8-bit frequency setup scans, CW wrap, no cal.intents
STD; setupDummy1; J1404+6551; L full width; dur; 0:01:0.0; CW;n; ; ; ; ; SetAtnGain,;dummyL ;
STD; setupDummy2; J1404+6551; my S band; DUR; 0:01:0.0; CW;N; ; ; ; ; SetAtnGain;dummyS;
#
# Account for slew and wrap, may take ten mins minus above, alternate flux calibrator
LOOP-START; finish 10min startup loop; 2; N; ;
  STD; ; J1404+6551; my S band; ; 0:2:0; CW; N;;; ; ; CalGain;;
  STD; ; J1404+6551; L full width; ; 0:2:0; CW; N;;; ; ; CalGain;;
LOOP-END;
#
# Target observing loop; save on some slewing time
LOOP-START; target+cal both freqs; 15; N; ;
  LOOP-START;19min scan; 2; ;keep scans under 10min by repeating it;
    STD; ; source1atL; L full width; ; 0:09:30.0;; N;;;; ; ObsTgt,,; ;
  LOOP-END;
  STD;; source2atS; my S band; ; 0:07:30.0;; n;;;; ; ObsTgt,,; ;
  STD; calS; J1404+6551; my S band ; ; 0:2:0; ; n; ;;; ; CalGain; ;
  STD; calL; J1404+6551; L full width; ; 0:2:0; ; N; ;;; ; CalGain,;;
LOOP-END;
#
<etc>
#
# Slew to the flux calibrator, needs some extra time on first scan, deal with wrap issues
STD ; L FXBP ; J1331+3030 ; L full width; ; 0:07:20 ; CW; N; ; ; ; ; CalBP, CalFlux ; ;
STD ; S FXBP ; J1331+3030 ; my S band ; ; 0:2:0 ; CW; N; ; ; ; ; CalBP, CalFlux ; ;

Example of the start of a scan list with two (8-bit) high-frequency science resources, pointing and flux calibration at the start of the observation:


# Start with defining which pre-defined source and resource catalogs to use
SRC-CAT; My project sources, VLA;
HDWR-CAT; HIGHFreqCat, NRAO Defaults;
#
# Two one-minute 8-bit frequency setup scans, CCW wrap, no cal.intents
STD; setup–Q; J0137+3309; Q wide band; dur; 0:01:0.0; CCW;n;; ; ;;SetAtnGain,;dum setup;
STD; setup–A; J0137+3309; special ka band; dur; 0:01:0.0; CCW;N;;; ;; SetAtnGain;dum;
#
# Account for slew, add time for pointing, may take twelve mins minus above
PTG; pointing ; J0137+3309 ; Primary X band pointing; ; 0:10:0 ; CCW; N; ; ; ;; ;
#
# Standard calibration, note the “Y” to apply pointing solutions
STD ; Q FXBP ; J0137+3309 ; Q wide band; ; 0:1:30 ; ; y; ; ;; ; CalBP, CalFlux ; ;
STD ; A FXBP ; J0137+3309 ; special ka band; ; 0:1:30 ; ; Y; ; ; ;; CalBP, CalFlux ; ;
#
# Slew to calibrator, need to do a new pointing scan (should have >2:30 on source for all start LST)
PTG; pointing ; TargPTG ; Primary X band pointing; ; 0:6:20 ; ; N; ; ;; ; ;
# 
# Bracketed loop in first frequency, switch on reference pointing
LOOP-START; qloop; 17; y; ;
  STD; ; TargCAL ; Q wide band; ; 0:1:0; ; Y;;; ; ;calgain; ;
  STD; ; myTarget; Q wide band; ; 0:2:30; ; y;;; ;; obstgt;;
LOOP-END;
#
# New pointing scan (should have >2:30 on source for all start LST)
PTG; pointing ; TargPTG ; Primary X band pointing; ; 0:2:50 ; ; N; ;; ; ; ;
#
# Non-bracketed loop to account for extra time to slew from pointing
STD; ; TargCAL ;special ka band;;0:1:20;;y;;;;;calgain;;
LOOP-START; Ka-loop; 13; n; ;
  STD;;myTarget;special ka band;;0:2:30;;Y;;;;;obstgt;;
  STD;;TargCAL ;special ka band;;0:1:00;;y;;;;;calgain;;
LOOP-END;
#
<etc>