; PCCOR
;---------------------------------------------------------------
;! Corrects phases using  PCAL tones data from PC table
;# Task UV VLBI CALIBRATION
;-----------------------------------------------------------------------
;;  Copyright (C) 1995-1999
;;  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
;-----------------------------------------------------------------------
PCCOR     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
PCCOR     Corrects phases using  PCAL tones data from PC table
INNAME                             Input UV file name (name)
INCLASS                            Input UV file name (class)
INSEQ             0.0     9999.0   Input UV file name (seq. #)
INDISK            0.0        9.0   Input UV file disk unit #
TIMERANG                           Timerange of a calibrator
                                    1-4 = start day,hr,min,sec
                                    5-8 = end   day,hr,min,sec
                                   Has to be specified!!!
SNVER             -1.0   46655.0   Output SN table, 0=>new table
INVER             -1.0   46655.0   Input  PC table, 0=>last one
REFANT             0.0      20.0   Ref. antenna, 0=>the first
SUBARRAY           0.0    9999.0   Subarray;  0 => all.
FREQID                             Freq. ID to select; 0 => 1.
CALSOUR                            Calibrator source name;
                                   blank => any
CUTOFF                             Cable correction:
                                   1 => switch off
                                   0 => switch on
BIF               0.0      100.0   Lowest IF number 0=>1
EIF               0.0      100.0   Highest IF number 0=>NIF
                                   Use BIF=EIF=0 except for
                                   special cases (see help)
DELCORR           0.0      1.0     1 => zero MBDELY.
                                   Use zero always except for
                                   special cases (see help)
----------------------------------------------------------------
PCCOR
Type: Task
Use:  PCCOR corrects for instrumental phase and delay offsets using
      pulse-calibration data already loaded in the PC table.
Adverbs:
  INNAME.....Input UV file name (name).      Standard defaults.
  INCLASS....Input UV file name (class).     Standard defaults.
  INSEQ......Input UV file name (seq. #).    0 => highest.
  INDISK.....Disk drive # of input UV file.  0 => any.
  TIMERANG...Time range of the calibrator to be used. In order:
             Start day, hour, min. sec,
             End day, hour, min. sec. Days relative to
             reference date.
  SNVER......Desired output SN table.
             0 means create a new SN table.
  INVER......Input PC table. 0 means the last one in the data.
  REFANT.....Reference antenna, 0 => the first in the antenna list
  SUBARRAY...The subarray to use. 0 => all
  FREQID.....Frequency identifier to select (you may determine
             which is applicable from the OPTYPE='SCAN' listing
             produced by LISTR). Process each freq. id. separately.
  CALSOUR....Calibrator source name
  CUTOFF.....Cable correction: 1 => switch off; 0 => switch on
             This option was requested by geodesy people. Use zero
             if you do not have a special idea.
  BIF........Start IF number to use. 0 => 1
  EIF........End IF number to use. 0 => Max available IF in the data
             Selection of IFs is required if two bands are observed
             simultaneously. For example X/S observations typically
             used in astrometry/geodesy. In this case PCCOR should run
             twice selecting IFs for the each band.
             The two SN (SN1, SN2) tables will be created with REAL=1,
             IMAG=0 for unused IFs.
             CLCAL should be applied twice to combine the two SN table
             in one CL table.
             Use the following CLCAL adverbs for the two passes:
             Pass 1: SNVER=SN1, GAINVER= CL1, GAINUSE=CLTEM,
                     SN1 is PCCOR output SN table of the first IF group.
                     CL1 is input CL table usually with REAL=1 IMAG=0
                     CLTEM is the output CL table of the first pass.
             Pass 2: SNVER=SN2, GAINVER= CLTEM, GAINUSE=CLOUT,
                     SN2 is PCCOR output SN table of the second IF
                     group.
                     CLOUT is the output CL table of the both pass.
             Use BIF=0 EIF=0 in all other cases!!

DELCORR......If DELCORR=1, MBDELY is equal zero in the output SN table.
             table.
             Multi band delay (MBDELY) of the output CL table will
             include the sum of the two SN tables MBDELYs. So it does
             not correspond to the either first IFs or second IFs.
             If you want to have MBDELY for one of the two IFs, you need
             to zero MBDELY in the relevant SN table. The zeroing of
             MBDELY can be done under control of DELCOR.
             The column MBDELY of a CL table is not used in the
             calibration procedure but used in the astrometry/geodesy
             projects to restore the total delay.
-----------------------------------------------------------------------
PCCOR: Corrects instrumental phase and delay offsets using
       pulse-calibration information in the PC table.
Documenter:  L.R. Kogan
RELATED PROGRAMS: FITLD, FRING, PCLOD

                          METHOD

Pulse-calibration tones are injected into the VLBA receivers and, in
conjunction with the cable calibration system, can be used to measure
and track instrumental variations in delay and phase between separate
baseband converters. If the pulses are separated by 1 microsecond in
time then the corresponding tones are separated by 1 MHz in frequency.
The measured phases of the tones allow the connection of the phase
across the all IFs. The phase difference between two tones in the same
IF allows to estimate  the instrumental single-band delay for that IF.
The measurement of single band instrumental delay is however subject
to ambiguity due to the 2pi*N ambiguity in measured phase.  The
visibilities of a calibrator are used to resolve this ambiguity.  The
ambiguity is solved in for each polarization, IF and antenna relative to
the reference antenna.  The adverbs, TIMERANG, CALSOUR and FREQID select
both UV and PC table calibrator data.

The phase ambiguity, as measured for the calibrator scan, is used to
correct the entire experiment. Each pulse-calibration (PC) table entry
is read, corrected for the ambiguity, and an SN table record is
written containing single- and multi-band instrumental phase and delay
corrections for each IF and polarization. The application of this SN
table, using CLCAL, eliminates instrumental phase and delay offsets
between individual IF's.  Further details of how the pulse-calibration
data may be applied are contained in VLBA Scientific Memo. #8,
by Craig Walker.


                          COMMENTS

Two tones per IF are used by PCCOR to find the instrumental delay.
It is not necesarry to have more than two tones per IF for this
purpose. If more than two tones exist, the most left and the most
right ones are selected.
Each FREQID must be processed separately.
The selection criteria TIMERANG, FREQID, SUBARRAY are used only for
the calibrator during ambiguity solve.
Having resolved the ambiguity the task converts each PC
table's row to a SN table row.  The calibrator has to be observed at all
antennas during the selected time range, or some antennas will not be
corrected. The calibrator visibilities are averaged (vector) during the
time range. The time range of the calibrator scan should be large enough
to provide a good SNR but small enough to insure that the fringe rate
does not decorrelate the signal. A reasonable compromise is around one
minute.

If there is no a time interval included all antennas, then some antennas
are not corrected. The relevant rows at the SN table has REAL = 1; IMAG
= 0.  PCCOR can be repeated with another time interval and/or calibrator
to provide correction of the antennas which have not been corrected.
Use parameters ANTENNA in CLCAL to correct the missing antennas.

Some antennas (VLA for example) do not have pulse cals at all.  The
output SN table does not have a row for such antennas.  To avoid the
complete loosing of such antennas use CLCAL with OPCODE = 'CALP'. The
option 'CALP' is identical to 'CALI' except that uncalibrated data is
passed through instead of being discarded.
