Building a Scheduling File in SCHED

The major calibration strategies were covered in a previous chapter. Here, the details for applying those strategies in a SCHED .key file are presented.

Some General Points

The easiest way to create a SCHED .key file to start with an example .key file or a .key file that has successfully been run previously. The SCHED release contains many example .key files in the “examples” directory. Some of them are out-of-date and will not be useful to many observers.

The filename for the .key file should be the project name (e.g., BL267) plus the letter corresponding to which observation in the project it is (A=1, B=2, C=3, etc.). For example, the .key file for the fifth observation under project code BL267 would be named “bl267e.key”.

SCHED will not execute any line in a .key file that is preceded by a “!” (i.e., this is the comment symbol).

Observers are encouraged to consult the SCHED User Manual for many more details and tips. Additionally, observers can always contact the VLBA staff via the NRAO helpdesk if they have any questions or encountered any problems.

Sections of a .key File

At the very top of a .key file, users may enter notes for themselves and the VLBA Data Analysts. This is done using the “!” symbol.

The sections can be in any order, with the exception that the “Scans” section must be the last section. It is often useful to have the Preferred Dynamic Constraints and Cover Information sections near the top so the VLBA Data Analysts and schedulers can see them easily.

Preferred Dynamic Constraints

This section is not included in many of the example .key files, but it is very helpful to the Data Analysts and schedulers for determining the best time to schedule an observation. An example of the Preferred Dynamic Constraints section is available from an online template and a downloadable text file. It is also possible to copy this section from the vips11.key example file in the “examples” directory of SCHED.

At the very least, this section should identify which antennas are essential to the observation (many users require both MK and SC in order to get the maximum angular resolution), how many antennas are required, and what weather constraints should be used for scheduling. If a specific observing cadence is desired (e.g., one observation every 30 +/- 3 days), it should be stated in this section as well. Specifying both MK and SC as required antennas will reduce the chances of an observation being interrupted by a Daily UT1-UTC observation.

All constraints provided in this section should be consistent with those that were specified in the proposal. An observer who submits a .key file with tighter constraints than specified in the proposal may be asked to change the schedule to be more in line with the proposal, or the VLBA Schedulers may edit the .key file themselves and inform the observers of the changes.

Cover Information

This section should have the contact information for the PI and observer for the project. It can also contain notes to the Analysts, schedulers, and operators.

The expcode should be set to match the filename of the .key file. This should be the project code plus the letter corresponding to the observation number (1=A, 2=B, 3=C, etc.). For example, if the project code is BL267 and the .key file is for the fifth observation under that project, the user should set

expcode = bl267e

After running SCHED on the .key file, it will produce control and summary files based on the expcode, NOT the filename. For example, if a schedule is named bl267d.key but has expcode=bl276a, SCHED will produce a summary file named bl267a.sum. If the Program Control keyword “overwrit” is set, SCHED will overwrite any pre-existing files with the same names, so it is important to remember to change the expcode for every new observation.

Correlator Information

This section describes how the observation will be correlated once the data arrives at the NRAO Pete V. Domenici Science Operations Center (DSOC) in Socorro, NM.

Most VLBA observations will have CORREL = ‘Socorro’, which means the observation will be correlated using the DiFX correlator at the DSOC.

Observers can set the correlator average time, number of spectral channels per data channel, the correlator weighting function, and several other parameters in this section of the .key file. See the Correlator Information section of the Schedule File chapter in the SCHED User Manual.

Spectral Zooming

The Correlator Information section of the keyin file is where observers inform VLBA staff about their choices for zooming in on particular regions of the observed frequency range. Observers should specify their zoom options using the corenote entries. In the following example, the first correlation pass is for continuum, and the second pass zooms in on the HI line.

correl = Socorro
coravg = 2
corchan = 256
cornant = 10
corpol = on
corwtfn = uniform
corsrcs = standard
cortape = FTP
corship1 = 'G. Observer'
corship2 = '123 Example St’
corship3 = 'Beverly Hills, CA 90210'
cornote1 = 'First correlation pass: 256 channels for all IFs.'
cornote2 = 'Second correlation pass: 32000 channels for IF-pair 1 (of 2) for the HI line.'
cornote3 = 'Output line data from channel 23001 to 25000 in zoom band mode (4 MHz total; covers the frequency range 1349-1353 MHz).'

The second correlation pass will deliver a 4 MHz chunk of data spanning the frequency range of 1349 - 1353 MHz, which is at 75% of the first 64 MHz IF pair. The 64 MHz IF itself will require 32000 channels to deliver 2 kHz channel spacing. The spectral region of interest (the 4 MHz) will be between channels 23001-25000 of the 32000 channels.

Program Control

This section allows the user to set up certain controls for their observation. Some options here are overwriting preexisting files (overwrit), starting the disks syncing before the first scan (prestart), and setting the minimum gap between entries (minpause).

Setting the sumitem variable will determine what information is included in the summary (.sum) file once SCHED is run on the .key file.

Standard Source and Station Catalogs

In this section, observers select which file to use for the source names and coordinate, and the antenna locations for their observation. The Catalogs section of the Schedule File chapter in the SCHED user manual lists all of the catalogs and other external input observers can use in this section of the .key file.

In Line Source Catalogs

Observers can define sources to be observed using custom coordinates. This is where the science targets are defined. It is often useful to define all of the target sources in one place rather than throughout the Scans section. At minimum, all sources should include the source name, RA, Dec, and the equinox used for the coordinates (usually “J2000”).

NOTE: If observers will be using AIPS to calibrate their data, it will be very useful to define source names using all capital letters.

Setup Information

In this section, observers define their observing setups. Many example setups are provided with the SCHED release in the “setups” directory. For more details on creating setups, see Linford & Brisken (2020).

Example setups for the new 4096 Mbps observing mode are included at the end of this chapter. Any observers who require assistance designing their setups are encouraged to contact the NRAO helpdesk and a member of the VLBA staff will contact them.

Initial Scan Information

The schedule must specify a start date and time. For dynamically scheduled projects, this will be a placeholder. The VLBA schedulers will update the the .key file with the appropriate date and time when the project is preparing to observe.

Optimization Information

SCHED can determine scan orders to optimize a schedule for many parameters. Usually, this section is only useful for projects observing many targets across a large range of RA. See the vips11.key file for an example optimizing for hour angle selection.

NOTE: The optimization controls are still labeled as “experimental features” and the output files should be inspected carefully to ensure they create schedules appropriate for a given observation.

The Scans

This must be the last section in the .key file. It is in this section that observers define the scans on the various sources. Unless optimization is being used, the scans will be executed in the order listed.

The first entry in The Scans section should be the list of stations to be used. The list can contain up to 30 stations. For most observers, this will be the ten standard VLBA stations and will look like:

stations = VLBA_SC, VLBA_HN, VLBA_NL, VLBA_FD, VLBA_LA,
           VLBA_PT, VLBA_KP, VLBA_OV, VLBA_BR, VLBA_MK

Other stations can be found in the stations.dat, stations_RDBE.dat, and stations_VLA.dat files located in the “catalogs” directory included in the SCHED release.

The list of stations can be changed before any scan. Each scan without a new list of stations will default to the previous list that was provided (i.e., observers using a single set of stations only need to define the list once before the first scan).

Each scan requires a frequency setup to be associated with it. Observers can switch frequency setups as often as necessary. However, changing the frequency will usually involve rotating the sub-reflector on the telescopes. This takes between 5 and 20 seconds, depending on the bands. When switching bands, it is usually prudent to include gaps in the schedule to give the telescopes time to switch receivers.

Scans can be defined similar to loops in computer programming using the “group” and “rep” commands. For example, to observe a phase reference source and a science target 10 times each in an alternating patter (e.g., phase ref, science target, phase ref, science target, …) with each scan lasting 2 minutes, an observer would enter:

group=2 rep=10
source=‘PHASEREF’ dwell=2:00 /
source=’SCIENCETARGET’ dwell=2:00 /

Observers have two options for defining the scan times: dwell and dur. Dwell means the scan time starts once the antennas get on source and lasts for the specified time. Dur (short for duration) means that the scan time starts immediately following the previous scan and will include the time it takes to slew to the next source. If observers want to have exactly a certain amount of time on source, it is recommended to use dwell. If observers want the total observation time to be set regardless of differences in slew times, it is recommended to use dur.

Observers can also use the "preempt" keyword to ensure that a scan or group of scans is not interrupted by a Daily UT1 observation. Setting preempt = 'NO' will ensure that all available antennas are used for a scan. For more information on using "preempt", see the Daily UT1-UTC page and the egdelzn.key example keyin file.

Running Sched

Once the .key file is complete, observers should run SCHED to ensure that everything is entered correctly and that all scans are scheduled properly.

To run SCHED on a .key file, enter:

sched < file.key

SCHED will produce several messages as it prepares the file. Once complete, if there are no errors, it will create several control files and a summary file. Observers should inspect the summary file to determine the total observing time, the total time on source for each source, and to see that the scans are scheduled properly.

If observers encounter any issues or have any questions while creating their schedules, they can contact the NRAO helpdesk and a member of the VLBA staff will provide assistance.

Phased VLA Special Considerations

Autophasing in SCHED

It will probably take about a minute to autophase. Every scan with the VLA in it must have a "vlamode". There are three modes that will be use most often:

1. vlamode = ' ', used when the VLA is not determining nor applying the autophase. E.g., dummy scans, pointing scans.
2. vlamode='va', determine autophase.
3. vlamode='vx', apply the autophase determined in the last vlamode='va' scan.

Reference Pointing for the VLA in SCHED

See the high frequency observing strategy guide for details on how to and when to reference pointing at the VLA. In SCHED the command "vlapeak" controls determining and applying pointing at the VLA, there are two modes used most often:

1. vlapeak= 'determine', determine reference pointing solution.

2. vlapeak='apply', apply last reference pointing solution.

Frequency Setups

Frequency setups compatible with VLBA PFB and DDC (4- and 8-channel) observing systems are available for the VLA. For more information see the table of phased array modes. The VLA's LO system is much more flexible than the VLBA's DDC system. See the RDBE section of the VLBA OSS for a description of the DDC/PFB. When putting together a frequency setup for a VLBA+VLA observation, start with the VLBA setup and just copy most of that setup for the VLA. The VLA setup should be correct in the channel (subband in VLA speak) width, edge frequencies, net sideband, IF channels and FE (front end specifications), but the details of the LO do not matter. Possible major differences between the VLA and the VLBA:

1. The VLA is always dual polarization, even in shared risk modes.

2. The VLA is always net upper side band (netside in SCHED).

3. The IF channels (ifchan in SCHED) on the VLA are always A, C, B, D

4. The Front End (FE) must be specified. This tells the telescope which receiver to use.

Examples of VLBA+VLA setups and scans are below.

Example VLBA+VLA Setups and Schedules

The SCHED User Manual has many example schedules, in particular see jvla.key and any DDC examples which will help you set up the VLBA DDC. Following are a few examples of frequency setups and sequences of phasing up and pointing.

Note that users do not need to fully understand the details of tuning the VLA. Simply using the same sideband, netside, firstlo, and bbsyn entries as the VLBA setup will suffice. The VLBA Schedulers will use a script to convert the SCHED setup to the appropriate VLA resource file.

Another important aspect of adding the VLA to VLBA observations is that observers must schedule a VLA dummy scan for each frequency setup (including pointing setups). The dummy scan(s) must be at leat 90 seconds in length, have vlamode='', and should be scheduled before any other scans. See the "Scans" examples below.

The VLBA antennas will begin to slew to the first target prior to the first scan, but the VLA antennas will not. If the VLA antennas need to unwrap at the begining of the observation, it may take up to 10 minutes for he VLA antennas to get on source. The VLBA Data Analysts will check that the VLA wrap is appropriate for the observation prior to scheduling the observations.

VLBA+VLA Frequency Setup Example #1: 8 GHz

setinit = rdbe_ddc_8540_dual.set /
! top section is for the VLBA DDC
dbe = rdbe_ddc
sideband = U
netside = U
bits = 2
bbfilt = 128
nchan = 4
pol = dual
firstlo = 7900.0
bbsyn=640., 640., 768., 768.
station = vlba
/
! bottom section is for the VLA
sideband = U
netside = U
pcal = off
ifchan = A, C, B, D
fe(1)='4cm' fe(2)='4cm' fe(3)='4cm' fe(4)='4cm'
firstlo = 7900.0
bbsyn=640., 640., 768., 768.
dbe = widar
station = vla27
/
endset /

 

VLBA+VLA Frequency Setup Example #2: 22 GHz

setinit = rdbe-128-k.set /
! Again, top section for the VLBA DDC
dbe = rdbe_ddc
sideband = U
netside = U
bits = 2
pcal = off
bbfilt = 128
nchan = 4
pol = dual
firstlo = 21300.00
bbsyn = 512.0,512.0, 640., 640.
station = vlba
/
! bottom part for the VLA
pcal = off
nchan = 4
sideband = U
netside = U
bbfilt = 128.0
ifchan = A, C, B, D
fe(1)='1cm' fe(2)='1cm' fe(3)='1cm fe(4)='1cm'
firstlo = 21300.00
bbsyn = 512.0,512.0, 640., 640.
dbe = widar
station = vla27
/
endset /

 

Scans example #1: Simple phasing up including Flux density scale calibrator scan

norecord
setup=rdbe_ddc_8540_dual.set
stations = VLA27
!! dummy scan for VLA
source='3C273' dur = 90 vlamode='' /

!! now observe with everybody
record
stations = VLBA_BR, VLBA_OV, VLBA_KP, VLBA_FD,
VLBA_PT, VLBA_LA, VLBA_NL, VLBA_HN, VLA27
!! Phase up with vlamode='va'
source='3C273' dur = 1:00 gap = 0 vlamode='va' /

!! Apply phased with vlamode='vx'
!! VLA scans cannot be longer than 10 minutes
!! D array so only need to phase up every ~20 minutes
source='M87' dur = 10:00 gap = 0 vlamode='vx' /
source='M87' dur = 10:00 gap = 0 vlamode='vx' /

!! Phase and apply loop
group=3 repeat=5
source='3C273' dur = 1:00 gap = 0 vlamode='va' /
source='M87' dur = 10:00 gap = 0 vlamode='vx' /
source='M87' dur = 10:00 gap = 0 vlamode='vx' /

!! Now lets look at a VLA flux density scale calibrator
source='3C286' dur = 7:00 gap = 0 vlamode='' /

 

Scans example #2: Pointing and Phasing the VLA at beginning of schedule

start=22:00:00
stations= VLA27
norecord

!! Dummy scans for the VLA, 90 seconds for each setup (yes
!! even for pointing setups).
setup = rdbe-128-x.set !x-band pointing dummy scan for the vla
source='0234+285' dur = 1:30 vlamode='' /
setup = rdbe-128-k.set ! k-band dummy scan for the vla
source='0234+285' dur = 1:30 vlamode='' /

!! Point at the VLA, the pointing scan is so long because
!! this is the start of the experiment and the VLA might
!! have to slew a long time to get to the pointing source.
!! Later in the schedule when you have to point again and
!! you know the slew times, you can usually make this shorter
!! The VLA needs 2.5 minutes on-source to point
setup = rdbe-128-x.set ! vla pointing setup
source = '0234+285' dur = 10:00 vlamode = '' vlapeak = 'determine' /

!! While the VLA points, VLBA will start observing.
setup = rdbe-128-k.set
stations=VLBA_HN,VLBA_NL,VLBA_FD,VLBA_PT,VLBA_KP,
VLBA_OV,VLBA_BR,VLBA_MK,VLBA_LA,VLBA_SC
nopeak
start = 22:00:00
source='J0437+24' dwell=12:00 record /

!! VLA is back from pointing, now start phasing
stations=VLBA_HN,VLBA_NL,VLBA_FD,VLBA_PT,VLBA_KP,
VLBA_OV,VLBA_BR,VLBA_MK,VLBA_LA,VLBA_SC,VLA27

!! Scan to phase up the VLA with vlamode='va', 70 seconds
!! are used to account for slewing. The VLBA is included
!! in this scan because it is better not to force subarrays
!! unless absolutely necessary. VLA pointing is applied with
!! vlapeak='apply'. The VLBA does not need to point at 22GHz.
source = '0234+285' dur = 1:10 gap=0 vlamode = 'va' vlapeak='apply' /

!! Scan to apply phases to the VLA with vlamode='vx'.
source = '0234+285' dur = 3:30 gap=0 vlamode = 'vx' vlapeak='apply' /

 

Using a Single VLA Antenna (Y1)

Building a .key file to use the VLBA plus a single VLA antenna (Y1) is very similar to the case for adding the full phased VLA. However, observers should be aware of the following differences:

• No phasing can be done with Y1, so there is no need to "phase up" the antenna.

• No pointing scans can be performed with Y1. VLA pointing scans are done as an interferometer, so attempting a pointing scan with a single antenna will not work.

• VLBA+Y1 .key files must set vlamode='' for the first scan.

• The VLA station should be set to “vla1”.

Just as for VLBA+VLA27 observations, VLBA+Y1 schedules must include a VLA dummy scan for each frequency to be used.  These dummy scans must be at least 90 seconds in length. While the VLBA antennas will begin slewing to the first target prior to the first scan, the VLA antenna will not. If the VLA antenna needs to unwrap at the begining of the observation, it may take up to 10 minutes to get on source. See y1ex.key for a rough example of how to build a VLBA+Y1 scheduling file. Observers can always get assistance with building their own scheduling files via the helpdesk.

setinit = rdbe_ddc_2cmy1_dual4.set /
! top section is for the VLBA DDC
dbe = rdbe_ddc
sideband = U
netside = U
bits = 2
bbfilt = 128
nchan = 8
pol = dual
firstlo = 14400.0
bbsyn=512., 512., 640., 640., 768., 768., 896., 896.
station = vlba
/
! bottom section is for the VLA
sideband = U
netside = U
pcal = off
ifchan = A, C, B, D, A, C, B, D
fe(1)='2cm' fe(2)='2cm' fe(3)='2cm' fe(4)='2cm'
firstlo = 14400.0
bbsyn=512., 512., 640., 640., 768., 768., 896., 896.
dbe = widar
station = vla1
/
endset /

 

Example 4096 Mbps Setups

The following 4096 Mbps setups have been tested and shown to work on the VLBA. 

6cm Receiver

!4 Gbps C-band, standard
setini = 4gb_ddc.6cm /
nchan = 8
bbfilt = 128.0
pol = dual
bits = 2
dbe = rdbe_ddc
netside = L
freqref = 4612.0
freqoff = 128.0, 128.0, 256.0, 256.0, 384.0, 384.0, 512.0, 512.0 /
endset /

!4 Gbps C-band, split between 4.5 and 6.7 GHz
setini = 4gb_ddc.6cm_split /
nchan = 8
bbfilt = 128.0
pol = dual
bits = 2
dbe = rdbe_ddc
netside = U
freqref = 0
firstlo = 3900, 3900, 3900, 3900, 5900, 5900, 5900, 5900
freqoff = 4412, 4412, 4540, 4540, 6540, 6540, 6668, 6668 /
endset /

4cm Receiver

!4 Gbps X-band, standard
setini = 4gb_ddc.4cm /
nchan=8
bbfilt= 128.0
pol=dual
bits=2
freqref = 8112.25
dbe = rdbe_ddc
sideband = U
netside = U
freqoff = 0.0, 0.0, 128.0, 128.0, 256.0, 256.0, 384.0, 384.0 /
endset /

2cm Receiver

!4 Gbps Ku-band, standard
setini = 4gb_ddc.2cm /
nchan=8
bbfilt= 128.0
pol=dual
bits=2
freqref = 15039.75
dbe = rdbe_ddc
sideband = L
netside = L
freqoff = 0.0, 0.0, 128.0, 128.0, 256.0, 256.0, 384.0, 384.0 /
endset /

1cm Receiver

!4 Gbps K-band, standard
setini = 4gb_ddc.1cm /
nchan=8
bbfilt= 128.0
pol=dual
bits=2
freqref = 23312.0
dbe = rdbe_ddc
sideband = U
netside = U
freqoff = 0.0, 0.0, 128.0, 128.0, 256.0, 256.0, 384.0, 384.0 /
endset /

7mm Receiver

!4 Gbps Q-band, standard
setini = 4gb_ddc.7mm /
nchan=8
bbfilt= 128.0
pol=dual
bits=2
freqref = 42912.75
dbe = rdbe_ddc
sideband = U
netside = U
freqoff = 0.0, 0.0, 128.0, 128.0, 256.0, 256.0, 384.0, 384.0 /
endset/

3mm receiver

!4 Gbps W-band, standard
setinit = 4gb_ddc.3mm /
nchan=8
bbfilt=128.0 
pol=dual   
bits = 2      
samprate = 256
freqref = 85500.0
dbe=rdbe_ddc
firstlo =85500,85500,85500,85500,85500,85500,85500,85500
pol     =RCP,LCP,RCP,LCP,RCP,LCP,RCP,LCP
bbc     =  1,  2,  3,  4,  5,  6,  7,  8
netside =  U,  U,  U,  U,  U,  U,  U,  U
ifchan  =  B,  D,  B,  D,  B,  D,  B,  D
freqoff  = 512,512,640,640,768,768,896,896
/

Additional Example setups

For more information on tuning the VLBA, see Linford & Brisken (2020).

Two data channels spanning 1476-1484 MHz and 1512-1520 MHz

!20cm, two 8 MHz channels
setini = ddc_2_8_20cm /
dbe = rdbe_ddc
nchan = 4
pol = dual
bbfilt = 8
firstlo = 2100
freqref = 0
netside = U
freqoff = 1476, 1476, 1512, 1512 /
endset /

Two data channels spanning 21879-21901 MHz and 21922-21937 MHz

!1cm, two 32 MHz channels
setini = ddc_2_31_1cm
dbe = rdbe_ddc
nchan = 4
pol = dual
bbfilt = 32
firstlo = 21200
freqref = 0
netside = U
freqoff = 21876, 21876, 21914, 21914 /
endset /

Continuous coverage 13cm receiver using the PFB

NOTE: This setup extends below and above the RFI filters on the 13cm receivers, which restrict the useful frequency range to 2200 - 2400 MHz.

!13cm, 2048 Mbps, PFB
setini = pfb_8_32_13cm
dbe = rdbe_pfb
nchan = 16
pol = dual
bbfilt = 32
firstlo = 3100
freqref = 0
sideband = L
netside = U
freqoff = 2188, 2188, 2220, 2220,
          2252, 2252, 2284, 2284,
          2316, 2316, 2348, 2348,
          2380, 2380, 2412, 2412 /
endset /

Alternating frequency channels at 20cm using the PFB

!20cm, 2048 Mbps, PFB
setini = pfb_8_32_20cm_alt
dbe = rdbe_pfb
nchan = 16
pol = dual
bbfilt = 32
firstlo = 2400
freqref = 0
netside = U
freqoff = 1392, 1392, 1456, 1456,
          1520, 1520, 1584, 1584,
          1648, 1648, 1712, 1712,
          1776, 1776, 1840, 1840 /
endset /