MAKECCR Program MAKECCR is used to generate Correlator Control Records (CCR) for control of the JPL/Caltech Block II VLBI Processor. At present, the program only supports multi-telescope MkII-format experiments. The "blocks" are written in the Forth language, and they can be created using the following procedure: 1. Use a text editor on the VAX to generate a script for the processing run, as described below. 2. Run program MAKECCR to generate Forth blocks (CCR) from the script. 3. Use the BEDIT editor on the VAX (if necessary) to modify the Forth blocks generated by MAKECCR, or to make a line-printer listing. 4. Copy the blocks to the disk area VLB_CCR (system logical name) on MicroVax SCALAR used by the Correlator. To run the program MAKECCR use the command MAKECCR (defined in VLB:LOGIN.COM): $ MAKECCR The program asks for 1. Input experiment file: type the name of the file containing your script, e.g., P35.EXP. Note that the default directory is VLB_CCR and the default file type is EXP. 2. Name for output CCR file: type the name of a new file to receive the Forth blocks, e.g., P35.BLK. Default is derived from the input experiment file name. 3. Name for listing file: type the name of a new file to receive a listing of the blocks, e.g., P35.LIS. Default is derived from the input experiment file name. The listing may be useful, but is not normally printed out. 4. Name for Correlator log file: type the name of a new file to receive a log of the blocks, in a form convenient for the Operator. Default is derived from the input experiment file name. The log file is normally printed on the Printronix printer on SCALAR. The following is an example of a script file for MAKECCR. Note the following conventions: anything following an exclamation mark, up to the end of the line, is a comment, ignored by MAKECCR; blank lines are MAKECCR Page 2 also ignored. Lowercase letters are allowed, and are translated to uppercase where necessary. The file is divided into four sections, which are identified by labels $EXPERIMENT, $STATIONS, $SOURCES, and $SCANS. The $EXPERIMENT section must be placed first, but the other three can be in any order. Note: no space is allowed after the $-sign. $EXPERIMENT TITLE = "Test experiment - based on BS3G" UT1UTC = 0.1657 ! From IERS Bulletin YEAR = 1992 ! Year of observation NOSPLIT ! No split of scans across UT hour ! NFREQ = 8416.99 ! Nominal LO frequency in MHz (DC edge of band) ! SIDEBAND = USB ! upper sideband (or LSB for lower sideband) ! NFREQ and SIDEBAND commented out: see FSWITCH ! DFREQ ! Parameter DFREQ is no longer valid; use SIDEBAND EXNAME = "BS3TEST" ! Experiment identification for PCR files EXTIME = 228.130000 ! Epoch of clock offsets (ddd.hhmmss) AUTOLOAD ! Keep tapes synced between consecutive scans SCANSIZE = 20 ! Typical scan length (minutes, default 60) NRACKS = 4 ! Use all four hardware racks FSWITCH ! Specify LO and sideband in $SCANS, not here / $STATIONS ! STNAME X Y Z [ CLOCK CLOCKRATE LO FOFF ZTROP ] BONN 4033941.1 -486985.2 4900543.1 0.0 ONSA 3370960.6 -711467.7 5349665.2 5.1 BOLOGNA 4461371.7 -919595.8 4449559.6 8.0 0.103 DUMMY 0.1 0.2 0.3 ! Dummy station - unused HSTK 1492406.7 4457267.3 4296882.1 -3.0 NRAO 882881.9 4924483.7 3944131.2 -1.5 VLBA_FD -1324007.4 5332182.8 3231962.9 2.3 VLBA_LA -1449750.5 4975299.4 3709124.4 0.0 VLBA_KP -1995675.0 5037335.0 3357320.0 2957.0 VLBA_PT -1640951.8 5014816.9 3575412.3 2.7 VLBA_NL -130874.0 4762317.0 4226862.0 -4.2 VLBA_OV -2409153.0 4478571.0 3838618.0 1.1 VLA -1600808.5 5042223.3 3554701.9 -10.2 ! VLA (Pad E8 = AE1) DUMMY 0.1 0.2 0.3 DUMMY 0.1 0.2 0.3 DUMMY 0.1 0.2 0.3 $SOURCES ! Source RA (1950) Dec (1950) 0735+178 073514.126 +174909.30 ! VLA cal 13-Feb-85 C 1 1 2 0 0851+202 085157.253 +201758.44 ! VLA cal 13-Feb-85 C 2 2 2 0 3C273 122633.248 +021943.29 ! VLA cal 13-Feb-85 B 5 5 5 3 $SCANS ! Source Day UT [] [ ] Comments 0851+202 228 2340 2400 8416.99 ! scan cannot cross day boundary 0735+178 229 0000 0010 8416.99 0851+202 229 0010 0030 8416.99 3C273 1 2 3 4 ! Europe on 3C273 0735+178 229 0030 0050 4990.99 0735+178 229 0050 0110 4990.00 ! NOSPLIT - scan crosses UT hour. 0851+202 229 0110 0130 -1662.99 ! 18cm non-standard (lsb) 0851+202 229 0130 0200 8416.99 MAKECCR Page 3 Notes on individual parameters: $EXPERIMENT section: The parameters in this section are supplied in the standard free-format (KEYIN) parameter assignment used by the other VLBI programs. Thus a slash (/) is needed at the end of the $EXPERIMENT section (but not the other sections). The following parameters must be specified: TITLE - a label to be written at the head of each block, in quotation marks (up to 56 characters). YEAR - the year of the observations, e.g., 1986. UT1UTC - UT1 minus UTC, in seconds; usually obtained from the IERS circulars kept in a red binder in the Correlator room. This info is also available online. EXNAME - a name of up to 15 characters to uniquely identify the experiment. Used in naming the Correlator output (PCR) files; recommend 8 characters or less. NFREQ and SIDEBAND - Nominal local oscillator frequency, in MHz to the nearest Hz, and (net) sideband (= USB or LSB). If frequencies switch between scans, DO NOT enter NFREQ or SIDEBAND here - these are specified in the $SCANS section. The following parameters are optional: FSWITCH (no value) - enables frequency switching between scans. When set, DO NOT specify NFREQ or SIDEBAND here - these are set in $SCANS. PASSNUM = n - enables every scan in a multi-pass experiment to have a unique scan number, which is useful for keeping track of the scans in B2FITS. The largest allowed pass number is 99, and the default is 0. Scan numbers are made from PASSNUM, day number, and scan stop time, thus: 'SCAN# ppdddhhmm'. MAKECCR also forms a unique name for the PCR file, which is opened when a scan is loaded: 'PCROPEN " exname_ppddd_hhmm"'. EXTIME = ddd.hhmmss - reference epoch for clock offsets. Actual clock offset used is the given clock offset, plus accumulated drift (see $STATIONS) between EXTIME and nominal scan start time. NOSPLIT - scan start and stop times in the $SCANS section are taken literally. Otherwise, scans are split across UT hour boundaries. AUTOLOAD - use only for experiments with a large number of short (say 15 min or less) consecutive scans. Correlator keeps tapes running while next scan is loaded. Applies to all scans in $SCANS section, but may be cancelled at any time by typing 'MANULOAD' at the 'user' keyboard. MAKECCR Page 4 SCANSIZE = n - typical scan length in minutes. This sets the disk file allocation reserved by the Correlator. Intended for use with AUTOLOAD - values less than default of 60 reduce 'dead' time while system loads next scan. INTEG = n - Correlator accumulation time, in seconds, maximum 10 s. Default is the minimum, 2 s, the recommended value. SECONDS - scan times in the $SCANS section must include seconds (hhmmss); default is (hhmm) format. NRACKS = n - set number of Correlator hardware racks in use (2, 3, or 4, default 3). Up to 4 cassettes may be correlated with 2 racks, 9 with 3 racks, and 16 with the full 4-rack system; select according to experiment size. BADRACK = n - rack number to ignore (valid only with NRACKS = 4: configures the remaining 3 racks). Useful to avoid some hardware problems. NLAGS = 7 or 8, default 7. Mask off the top lag of every channel to make the delay function symmetric about the central lag. This is required for accurate correction for lag function truncation in AIPS program SPLIT. $STATIONS section: Specify EXACTLY 16 telescopes, using one line for each. Each line corresponds to a 'logical station' in the MkII Interface, in ascending order. Use 'DUMMY' for unused Interface logical stations: program B2FITS, which reads Correlator output, ignores data to stations labelled in this way. Details of how to assign telescopes to logical stations may be found in the Block II documentation (see also the 'TRK29 table' below). The items on each line are: Station name (STNAME) up to 16 characters; avoid using spaces. Geocentric coordinates (XYZ) in meters (three values, to nearest 0.1m). Clock offset (CLOCK) in microsec (UTC minus station clock). Sign convention is opposite to those of Haystack and Bonn. Clock drift rate (DRIFTRATE) in microsec/day (reference epoch is EXTIME specified in $EXPERIMENT section). Sign convention same as for CLOCK. Local oscillator frequency (LO) in MHz (to nearest Hz). Local oscillator offset (FOFF) in Hz (to nearest mHz). Zenith troposphere delay (ZTROP) in meters. MAKECCR Page 5 A self-consistent set of XYZ coordinates for most commonly-used VLBI stations may be found in VLBHELP:MAKEBLOCK.STN (logical name VLBSTATIONS). This file is in the format required for station positions, and a text editor may be used to include the relevant lines from this file in preparing the script. All the coordinates should be sufficiently accurate for experiments up to at least 10650 MHz. Only the station name and XYZ are mandatory: the clock offset, clock-rate, and frequency offset default to 0, troposphere to 2.0 m. LO is used to correct for an incorrect LO frequency at a station, and should be set with care; it defaults to the value of NFREQ set in the $EXPERIMENT section, and, for a given station, supersedes the value specified there. For NRACKS = 2, some lines in the list must be duplicated to obtain all baseline combinations (see TRK29 table); e.g. an experiment with four telescopes (A, B, C, and D) may be listed in $STATIONS in order ('*' denotes DUMMY telescope): A, B, *, *, A, C, B, C, A, D, B, D, C, D, *, *. For NRACKS = 3, logical stations are normally assigned to telescopes in the following order: 1, 3, 5, 7, 9, 11, 13, 15, 2. Experiments with more than 9 telescopes require more 'passes', or else NRACKS = 4; multiple passes are not recommended. For NRACKS = 4, and no bad hardware channels, assignments to stations may be made in any combination. $SOURCES section: One line for each source. The items on each line are source name (up to 12 characters; no spaces allowed), 1950 RA (hhmmss.sss), 1950 Dec (ddmmss.ss). Note: no spaces or colons between hours, minutes, and seconds. For negative declinations, enter '-ddmmss.ss'. $SCANS section: Each line contains a source name (which must match one in the $SOURCES list), day number, UT start (hhmm) and UT stop (hhmm). Start and stop time must be on the same day, and must be specified only to the nearest minute, unless SECONDS was specified in $EXPERIMENT (hhmmss). Use '2400' for a stop time on a day boundary. MAKECCR will split the input into scans starting and stopping on the hour, unless NOSPLIT is specified ($EXPERIMENT section). Recommendation: use the conventional (nominal scheduled) scan start and stop times - actual times on-source are unnecessary. Frequency switching between scans: If FSWITCH is set in $EXPERIMENT, then each scan line takes an additional (mandatory) argument which is the local oscillator frequency in MHz, specified (if necessary) to the nearest Hz. Upper sideband is MAKECCR Page 6 denoted by positive values, lower sideband by negative values. If the scans are split across the UT hour, both scans will have the same LO frequency and sideband. Not all combinations of frequency switching between scans, subnetworking, and stations with differing LOs can be handled by MAKECCR. The following restrictions apply. (1) All stations must use the same LO and sideband, as specified in $SCANS. LO cannot be specified in $STATIONS if FSWITCH is set. (2) A constant FOFF is allowed in $STATIONS but a warning is issued: FOFF applies to all frequencies a station observes at. (3) To reset FOFF, or ZTROP in $STATIONS, set LO = 0.0. (4) If a subnetwork is in use, it must use the same LO and sideband as the main network, in any given scan. By using the BEDIT editor on the output CCR file from MAKECCR several of these can be overcome in principle; however, this is recommended for experts only! For instance, to change the LO by 10 kHz for (e.g.) the seventh station in $STATIONS, edit into the relevant scan block 'SITE 7 NOMINAL_LO 4990.98'. Sub-networked telescope array: For sub-networks, additional entries on the scan line in $SCANS are needed. Sub-networks can be specified for a single scan, or group of scans, and may be different sets of telescopes in each scan. The additional entries (following the stop time, or new LO frequency, as appropriate) are: name of sub-network source (must be in $SOURCES), and a list of 'logical station' numbers in the sub-network (see $STATIONS). Further subnetworks are possible, but these must be added to the CCR file using the BEDIT editor, after running MAKECCR. Note the restrictions on the station list: (1) it must contain an even number of entries between 2 and 8; (2) the entries must be paired as consecutive odd then even numbers, i.e., (2n-1, 2n) where n = integer; (3) entries must be in ascending order and may not repeat. **Warning** MAKECCR assumes the full 4-rack, 28-channel system is operational, when assigning delay models (DMOs) to channels (every channel is assigned to either the primary or sub-network source). When a sub-system is specified (either NRACKS = 2 or 3, or NRACKS = 4 and BADRACK = n), the program does NOT check the numerous combinations to see whether the DMO assignments are correct. A valid configuration is almost always possible, but the user must check the 'TRK29 table' to ensure that all required station pairs are correctly configured. Incorrect assignments will not halt the Correlator, but cause fringes to be lost. Multiple passes: A separate run of MAKECCR is required for experiments which require more than one pass (e.g., experiments with more than 9 telescopes, with NRACKS = 3) Details of the logical assignments needed for multiple passes may be found in the Block II documentation. Use of multiple passes is strongly discouraged, unless there are more than 16 stations, when it is unavoidable. **WARNING** - all parameters in common between scans MUST be identical, otherwise unrecoverable non-closing errors will MAKECCR Page 7 be introduced. TRK29 table: logical station to channel assignments --------------------------------------------------- Channel MkIII rack Channel MkIII rack number number number number (1) (2) (3) (4) (1) (2) (3) (4) 1 1 2 3 4 15 9 10 3 4 2 9 10 11 12 16 1 2 15 16 3 1 2 5 6 17 5 6 9 10 4 1 2 13 14 18 15 16 3 4 5 5 6 3 4 19 7 8 9 10 6 13 14 3 4 20 5 6 15 16 7 1 2 7 8 21 1 2 11 12 8 5 6 13 14 22 7 8 15 16 9 7 8 3 4 23 11 12 3 4 10 7 8 13 14 24 9 10 15 16 11 5 6 7 8 25 5 6 11 12 12 9 10 13 14 26 11 12 15 16 13 1 2 9 10 27 7 8 11 12 14 11 12 13 14 28 13 14 15 16 Program History: Version 1.0: 1986 Oct 15 - new program (S.C. Unwin). Version 1.1: 1986 Dec 21 - change layout. Version 1.2: 1987 Feb 14 - better scan names; minor bugs fixed; add SDFREQ parameter; improve documentation. Version 1.3: 1987 Jun 26 - new output format; remove SDFREQ, add NFREQ; check EXTIME/DRIFTRATE. Version 2.1: 1987 Jul 2 - add operator log file (T.D. Rogstad). Version 2.2: 1988 Mar 17 - add AUTOLOAD and SCANSIZE; add useful operator messages; more syntax checking. Version 2.3: 1988 May 16 - add NRACKS, BADRACKS; re-order blocks. Version 2.4: 1988 Aug 10 - allow sub-networks in $SCANS. Version 2.5: 1989 Jan 24 - add NLAGS, SECONDS; change log file layout. Version 2.6: 1989 Jun 14 - flag unused DSOs for subnetworks. Version 3.1: 1991 Sep 16 - replace PMO/DMO etc. with Level II commands Version 3.3: 1992 Oct 24 - withdraw DFREQ; new parameter SIDEBAND. Allow frequency to change between scans.