; M3TAR ;--------------------------------------------------------------- ;! translate Haystack MKIII VLBI format "A" TAR's into AIPS ;# TASK VLBI UV ;----------------------------------------------------------------------- ;; Copyright (C) 1997 ;; Associated Universities, Inc. Washington DC, USA. ;; ;; This program is free software; you can redistribute it and/or ;; modify it under the terms of the GNU General Public License as ;; published by the Free Software Foundation; either version 2 of ;; the License, or (at your option) any later version. ;; ;; This program is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; ;; You should have received a copy of the GNU General Public ;; License along with this program; if not, write to the Free ;; Software Foundation, Inc., 675 Massachusetts Ave, Cambridge, ;; MA 02139, USA. ;; ;; Correspondence concerning AIPS should be addressed as follows: ;; Internet email: aipsmail@nrao.edu. ;; Postal address: AIPS Project Office ;; National Radio Astronomy Observatory ;; 520 Edgemont Road ;; Charlottesville, VA 22903-2475 USA ;----------------------------------------------------------------------- M3TAR LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC M3TAR Task which reads Haystack MKIII VLBI format "A" TAR's INFILE Experiment info file name IN2FILE A-file name - see HELP INTAPE Tape drive number NFILES Number of TAR's to skip REFDATE Reference date. 'dd/mm/yy' TIMERANG Timerange selected SOURCES Source selection list DOUVCOMP -1.0 1.0 1 (T) => compressed data DOCONCAT -1.0 1.0 1 (T) => append data to old files (use with caution). OUTNAME Output UV file name (name) OUTCLASS Output UV file name (class) OUTSEQ -1.0 9999.0 Output UV file name (seq. #) OUTDISK 0.0 9.0 Output UV file disk unit #. APARM Control information (1) = CL table time increment (min). (2) = Maximum tape parity error rate (0=> 0.01) (3) = Maximum dropout rate accepted (0=> 0.5) (4) .ge. 1 => suppress FBS (5) = No of files to read from tape (0=> to EOT) (6) 0 => apply all error checks to data 1 => ignore CRCC errors 2 => ignore slip sync 3 => ignore both CRCC and slipped sync (7) > 0 = separate sidebands (8) > 0 = accept data with LO offset (9) = Print level (0..4) *** DEBUG *** (10) = 1=> dump headers 2=> dump header, data ---------------------------------------------------------------- M3TAR Task: This task reads MKIII VLBI data from Haystack "A" tapes, when they come as standard UNIX TAR's. An ASCII experiment file is read from disk to assign antenna numbers and obtain other information. Any type 52 (Haystack FRNGE output) records are written to an AIPS HF table (see EXPLAIN M3TAR). Adverbs: INFILE.....Name of ASCII experiment information file. Eg., disk$res:[username]STATIONS.DAT under VMS or MYVLB:STATIONS.DAT under UNIX IN2FILE....Name of ASCII file containing list of scans to be read from an 'A' tape. This file can be generated by hand, or using the task TFILE. If IN2FILE = ' ', all scans will be read from the tape. INTAPE.....Tape drive from which to read data. NFILES.....Number of Tape ARchives to skip on the tape. REFDATE....Reference date 'dd/mm/yy', ' ' => first found Better get it right!!! Data may not be in time order on the tape and the default reference date is the first date found. Data on days before the reference data will have negative times and will be rejected by the default TIMERANG as well as causing other troubles displaying the data. The reference day used should be one for which there is actual data or the antenna table will end up with incorrect data (a warning message is given in this case). TIMERANG...Range of UTC times to be read wrt REFDATE. 0=>all. If any part of a scan is selected then that whole scan is read. See EXPLAIN MK3IN for details. SOURCES....Sources to be included in or excluded from the output file. If the first character of any element is "-" then all named sources are excluded otherwise all named sources are included. Names should correspond to those used in the Mk3 experiment file. If all entries are blank then all sources are selected. DOUVCOMP...If true (DOUVCOMP >= 0) the output data is written in compressed format which can result in a substantial reduction in disk space needed but only calibration routines are likely to interprete this data. DOCONCAT...If true (>0) then data is to be appended to an existing file if possible. Possible output files can be selected by OUTNAME, OUTDISK and OUTSEQ. Use this option with CAUTION. OUTNAME....Output UV file name (name). Standard behavior with default 'MKIII DATA'. OUTCLASS...Output UV file name (class). Standard defaults. OUTSEQ.....Output UV file name (seq. #). 0 => highest unique. OUTDISK....Disk drive # of output UV file. 0 => highest disk with space for the file. APARM......Task control information. (1) = Time increment in CL table entries in min. 0 => 2 min. <0 => use PRT (near center) time only (2) = Maximum parity error rate on the MKIII data tapes for good data. 0=> 0.01 (3) = Maximum dropout rate on the MKIII data tapes for good data. 0=> 0.5 (4) .ge. 1 means do not make Fractional Bit Shift corrections. (5) = Number of file to read from tape 0=> to EOT. (6) = Data rejection criteria 0 => apply all MK3 error checks 1 => ignore CRCC errors in sync blocks 2 => ignore slipped sync errors (XS/YS) 3 => ignore both CRCC and slipped sync (7) If > 0 then separate sidebands into different IF. This may fail if it exceeds the max. number of IFs. (9) = Print level 0=> Source hdr per scan; 1=> include scan error summary and correlator model summary; 2 => list each correlator separately; 3 => print COREL file names; 4=> error summary per correlator module serial no. (10) = flag indicating a dump of the raw data is requested on Fortran unit 9. 0 => no dump 1 => header records only 2 => headers plus data (type 51 records) ---------------------------------------------------------------- M3TAR : Creates an AIPS uv data set from Haystack MKIII A TAR's. DOCUMENTOR : W. D. Cotton, NRAO/CV RELATED TASKS : TFILE PURPOSE M3TAR creates an AIPS uv data set from a Haystack MkIII "A tape" in the form of UNIX TAR. COMMENTS INFILE: A separate external file MUST be created by the user (and text editor) containing the names of stations used in the current VLB experiment. The station names are entered in quotes like this : STATIONS='NRAO','VLA','OVRO','FDVS','MPI','JDRLMKII', 'OSO25','CRIMEA' Note: no case conversion is done so the case should match the antenna name as given on the tape. When M3TAR starts up, it will list the stations it found in INFILE. The first time M3TAR is run on data from an experiment, antenna names 'ANY' may be used and any antennas found (up to the number of 'ANY's in STATIONS) will be accepted. If more data is to be read from other tapes then the STATIONS array must be filled in using the values in the AN table. The order of the antenna names in STATIONS defines the antenna numbers used inside the AIPS data base. To insure that a given antenna is always given the same number be sure to update the values in STATIONS after any execution of M3TAR in which a new antenna has been added as a result of an 'ANY' in the STATIONS list. The times in the data set can be either in UTC or IAT. To use IAT the correction from UTC to IAT (IAT-UTC) should be given as the parameter TIMEOFF as in: TIMEOFF=23.0 If no value of TIMEOFF (or 0.0) is given then the time system is assumed to be in UTC. The Stokes parameter range of the output file is set using the parameter: STOKES= subset of {'RR','LL','RL','LR'}. The default Stokes is 'LL'. If polarization sensitive data is to be read in this is indicated by the parameter DOPOL=1; if data are all of the same Stokes' type this is indicated by DOPOL=-1 (the default). The MKIII correlators usually indicate different polarizations by using frequency codes; as these codes are not entirely consistent they may be entered using FREQCODE as: FREQCODE='R','L','r',l' (where R=RR; L=LL; r=RL; l=LR). If DOPOL=1 the defaults are 'R','L','r' and 'l' else any frequency code is selected. The following are optional parameters in the experiment file, and will default to the values found for the first scan. NO_LAGS - Number of XC lags in output file (only correlation functions with this lag range will be translated; autocorrelation functions with half this range). NO_IF - Number of IF's in the output file. SIDEBAND - 'DOUBLE' => concatenate video converter USB, LSB to form one IF (default). Enter the delimiter character (/) at the end of the experiment information. The experiment definition may be followed by an optional list of antenna aliases. This comprises a line containing the keyword ALIASES and a delimeter character (/) followed by a list of paired strings. If the first string of any pair matches an antenna name in the input data then the antenna name will be replaced by the second string. This is done before matching the antenna names against the antenna list given in the experiment definition. Here is an example experiment definition file using aliases. STATIONS='TDRSE', 'USUDA', 'DSS43' / ALIASES / 'TDRS1' 'TDRSE' 'TDRS2' 'TDRSE' 'TDRS3' 'TDRSE' 'TDRS4' 'TDRSE' / In this experiment data from TDRSE was correlated using four different names. With the alias list given, M3TAR will recognize all four names as referring to the same telescope and will name this telescope TDRSE in the AIPS data file. Examples: INFILE='disk$res:[username]stations.dat' (VMS) INFILE='MYAREA:STATIONS.DAT' (Unix) where MYAREA is an environment variable set before starting AIPS: %setenv MYAREA /mnt/username. Note: All file names used on a Unix system must have only uppercase characters in the name. The abbreviations used in the error summary have the following meaning: Code Desc MOD Correlator module serial number (0 => module sum). CS Correlate suppress TS Tapes out of sync AP AP array overrun PP No PP update YS Y slipped sync. XS X slipped sync. CL No X clock or no Y clock. TM Unexpected tape time. CRCC CRCC error in remote station sync block, reference station sync block. XP X parity errors exceed parity error rate for good data. YP Y parity errors exceed parity error rate for good data. XD Fewer than allowed fraction of the nominal number of bits are correlated within the AP in the cos channel (set by maximum dropout rate). YD As for XD but applies to the sine channel correlation count (ignored for AC functions). MT Module termination status bad (ie operator reports error condition). 3A MKIIIA error condition. TOT Total number of module output records read. Each column indicates the percentage of module output records with the appropriate error condition. The field Nvis=nnn indicates the number of full correlation functions passed by M3TAR. The field Good=xx% indicates what percentage of correlation functions was passed. Multiband Observing A special problem occurs when data at different observing bands are observed simultaneously, e.g. S/X geodetic style observations. M3TAR will read all data and place them in the same file. For purposes of calibration and imaging these must be seperated into seperate files using UVCOP. FRNGE output The output of the Haystack baseline fringe fitting routine FRNGE is copied to the AIPS table of type HF. The labels of the column are the names of the entries in the Haystack documentation. The contents of this table with a description from Haystack documentation are given in the following: Col # Label Type(dim) Description 1 XY C*2 Baseline code, 1 char per antenna. 2 UTC TAG I(6) UTC time tag (YMDHMS) EPOCH for delay and rate . 3 VLB2 UTC I(6) UTC of FRNGE processing (YMDHMS) 4 ARCHIV I(4) ARCHIV 5 SAMPRATE I Sample rate in kbits/sec 6 FR/PP I no. frames per parameter period 7 PASS NO. I Pass number 8 NO. CHANELS I #U/L sideband pairs included in this processing (i.e. # of discrete LO frequencies) 9 NO. OF AP I(28) #Accumulation periods by sideband by channel 10 RECTRACK I(2,2,14) Track # table in order of: Station #, Refer/partn Sideband, Channel # 11 COREL VERSION NO. I COREL version # 12 UTCM TAG I(6) UTC time tag (YMDHMS) EPOCH for "central" EPOCH 13 LU OF PRINTOUT I LU of printout (for FRNGP) 14 REF. TAPE DRIVE NO. I Reference tape drive number 15 REM. TAPE DRIVE NO. I Remote tape drive number 16 SPECIAL OPTIONS I Special options NAME(211) 17 INTEGER PARM(250) I Integer value of PARAM(250) [=999 for special PCAL by AP] 18 CORELXTNT I(2,14) COREL extent# from which each track is taken. 19 CALBYFRQ I(3,2,14) Phase-cal amp, phase and freq by station and channel normalized as follows: AMP 0 to 10000(in voltage) -1=manual cal PHS -18000 to +18000 frq kHz 20 PROCUTC I(2,14) COREL processing UT (YDDD) by sideband and channel. 21 ERRORATE I(2,2,14) Tape error rate by station, sideband and channel encoded as: 1000*LOGT(error rate) (=-32000 if no errors) 22 INDEX I(2,14) COREL index #s by sideband and FRNGE CH# 23 FRNGE ERROR CODE I FRNGE error code 0=OK NE.0 Don't use 24 SBDOFFST FLAG I flag 1=this run had sideband fixup. 25 STAR ID C*8 Radio source name 26 BASELINE ANT1 C*8 First antenna name of baseline 27 BASELINE ANT2 C*8 Second antenna name of baseline 28 CORELFILE C*6 COREL correlation output file name 29 TAPEID ANT1 C*8 first raw-data tape ID label 30 TAPEID ANT2 C*8 second raw-data tape ID label 31 VLB2PRG C*6 FRNGE program version YYMMDD 32 RUN CODE C*8 Run code, e.g. "329-1300" 33 FRNGE QUALITY CODE C*1 FRNGE quality code 0=no good, 1=very poor, 9=very good, A=has FRNGE error code=1,B=2 etc. 34 FREQ. GROUP CODE C*2 Frequency group code 35 ORIG. COREL FILE NAME C*6 Original COREL file name 36 TAPE Q CODE C*6 Tape Q code 37 REF OCCUPATION CODE C*8 Ref station occupation code 38 REM OCCUPATION CODE C*8 Rem station occupation code 39 RFREQ D(14) LO frequencies (MHz) by channel 40 REF FREQ D RF freq (MHz) to which phase is referred 41 DEL OBSV D Observed group delay in microseconds equals single band delay if only one freq. processed. DELOBSV=T2-T1, T1=time of arrival at site 1 (reference site) as measured by the site clock at site 1, T2=time of signal arrival at site 2 as measured by site clock at site 2. The signal in question is the one which arrives at site 1 at a UTC time equal to that given as the UTC epoch. 42 RATOBSV D Observed delay rate (usec/sec) corrected for the phase cal rate. 43 NB DELAY D Narrow-band group-delay (usec) 44 DGPD D group delay ambig. (usec) 45 BTE0 D apriori clock (usec) 46 EPOCH0 D ref. st. clock epoch (usec) 47 DEL OBSVM D observed delay at central epoch 48 RAT OBSVM D observed delay rate at central epoch 49 DLY2 D phase delay at EPO+1 sec 50 DLY3 D phase delay at EPO-1 sec. 51 AMBYFRQ R(2,14) Amp and phase by channel 1=100% phase=-180 to 180 deg. residual to COREL and uncorrected for PCAL rate. 52 PHASECAL R(2) Phase cal rate by station (usec/sec) 53 DELRESID R Delay residual to COREL a priori. 54 DELSIGMA R Calculated delay error (usec) 55 RATRESID R Delay-rate residual to COREL a priori (usec/sec) corrected for phase cal rates. 56 RATSIGMA R Calculate delay-rate error (usec/sec) 57 COHERCOR R Coherent multi-freq correlation coefficient. (1=100% correlation) 58 TOTPHASE R Total observed fringe phase (deg) 59 UVF/ASEC R(2) Fringes per asec in N-S and E-W 60 STARELEV R(2) Calculated star elevations run reference time by station (deg). 61 AAMP FRNGE R amplitude from incoherent addition of frequency channels. 62 URVRSEC R(2) Rate derivatives mHz/sec arc 63 SRCHPAR R(6) Search parameters 64 DEPSBRES R Single band delay residual (usec) 65 SNR R Signal to noise ratio in sigma. 66 PROB R Probability of a false detection. 67 INCOH R Incoherent segmented fringe amp. in units of 10,000. 68 EARP R total phase refered to an epoch at time the signal reaches the center of the earth. 69 REARP R Residual phase corrected to earth centered epoch 70 START R Start time in seconds past hour 71 STOP R Stop time in seconds past hour 72 EPD R Epoch offset from center of run in sec. 73 DUR R Effective run duration in seconds. 74 DELSS R Single-band delay error in microsec. 75 QB R Ratio of min to max data accepted in % 76 DISCD R % data discarded 77 TOTPM R Total phase at central epoch