; VLBAKRGP
;---------------------------------------------------------------
;! Fringe fit phase referenced data and apply calibration
;# PROCEDURE VLBI UTILITY CALIBRATION
;-----------------------------------------------------------------------
;;  Copyright (C) 1995-2001; 2006
;;  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
;-----------------------------------------------------------------------
VLBAKRGP  LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
VLBAKRGP: Procedure to fringe fit and calibrate phase ref. data
                                   Input uv data.
INNAME                                UV file name (name)
INCLASS                               UV file name (class)
INSEQ              0.0      9999.0    UV file name (seq. #)
INDISK             0.0         9.0    UV file disk drive #
CALSOUR                            Source list to fringe fit
                                   NO DEFAULT
TIMERANG                           Time range to use.
BCHAN             0.0     2048.0   Lowest channel number 0=>all
                                   FOR SPEC. LINE EXP. ONLY
ECHAN             0.0     2048.0   Highest channel number
                                   FOR SPEC. LINE EXP. ONLY
GAINUSE                            CL table to apply.
REFANT                             Reference antenna
SUBARRAY                           Subarray               0=>all
SEARCH            0.0     1000.0   Prioritized reference antenna
                                   list - supplements REFANT
SOLINT                             Solution interval (min)
                                   0 => 10 min
OPCODE                             'ZDEL' => zero delays
                                        for more, See HELP KRING
                                   FOR SPEC. LINE EXP. ONLY
CPARM                              for strong sources, it is
                                   only necessary to set
                                   CPARM(1) and CPARM(8).
                                   1 min. int. time (sec) 0 => 2
                                   8 <=0 rereference solutions
                                     this should be 1 for
                                     polarization experiments.
                                   for rest see HELP VLBAKRGP
SOURCES                            Source list to calibrate: Any
                                   sources in the SOURCE list
                                   that are not in the CALSOUR
                                   list will be phase referenced
                                   to the FIRST source in the
                                   CALSOUR list.
INTERPOL                           Interpolation function:
                                   '2PT','SIMP','AMBG','CUBE',
                                   'SELF'
BADDISK            0.0        15.0 Disk no. not to use for
                                      scratch files.
----------------------------------------------------------------
VLBAKRGP
Type: Procedure
Use:  This procedure does antenna based fringe fitting for phase
      referencing experiments using KRING and then applies those
      corrections using CLCAL.  For more information on KRING and
      CLCAL see their respective HELP/EXPLAIN files.
      Type RUN VLBAUTIL to make the VLBAKRGP procedure
      available.
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.
  CALSOUR....List of sources for which calibration constants are to be
             determined.  The default is not permitted nor are '-'
             sources, as you must select a phase reference source.  The
             FIRST source in the list is the phase reference source and
             will be used to phase reference any sources in the SOURCES
             list that are NOT in the CALSOUR list.
  TIMERANG...Time range of the data to be used. In order: Start day,
             hour, min. sec, end day, hour, min. sec. Days relative to
             reference date.
  BCHAN......First channel to use. 0=>all.  If this is not a spectral
             line experiment, leave as default.
  ECHAN......Highest channel to use. 0=>all higher than BCHAN; If this
             is not a spectral line experiment, leave as default.
  GAINUSE....(multisource) version number of the CL table to apply to
             the data.   0 => highest.
  REFANT.....The desired reference antenna for phases.  Note that
             the desired refant is not required to be the primary search
             antenna.  You should choose the REFANT to be an antenna
             that is present during most of the observation.
  SUBARRAY...Subarray number to use. 0=>all.
  SEARCH.....List of prioritized reference antennas to be used for
             fringe searching during the FFT stage.  KRING constructs
             an internal search list to determine the order in which to
             perform the FFTs.  This search list is constructed by first
             copying the elements of SEARCH.  Finally, all remaining
             antennas antennas are appended to the search list in
             numerical order.  You can limit the search to only the
             specified elements of the SEARCH list by setting CPARM(6).
             Only baselines where at least one antenna appears in the
             search list will be searched for fringes.
             You should explicitly order the antennas in terms of decreasing
             sensitivity if at all possible.
  SOLINT.....The solution interval.  Note that this is only a
             recommended solution interval.  The actual solution interval
             used by KRING will be changed in order to divide each scan
             evenly into an integral number of data chunks.
             SOLINT is in minutes; the default value (SOLINT=0) is 10
             minutes.  SOLINT values larger than 10 are reset to 10 minutes
             unless CPARM(9)>0.  NB: If SOLINT > 0.75*Scan, SOLINT = Scan.
  OPCODE.....Solution masking to be performed _after_ fringe-fitting
             ' '  no masking
             'ZPHS'  zero phases in output SN table
             'ZRAT'  zero rates in output SN table
             'ZDEL'  zero delays in output SN table
             If CPARM(8)>0, OPCODE is forced = ' '.
             If this is not a spectral line experiment leave this
             as the default.
  CPARM......CPARM(1) and CPARM(8) are the only CPARMs that it is essential
             to set, for strong sources the rest can be left as default.
  CPARM(1)...The minimum integration time of the data (sec);
             0 => 2 'VLBA' seconds
               It is important to get this number right to within 20 %.
               E.g., if you've averaged up 1 second data to 10 seconds,
               setting this to 10 is okay so long as there are only a
               very few points with shorter than 10 second integration
               times.  If you set this to 1 second, you will regret it.
  CPARM(2)...The delay window FW to search (nsec) centered on 0 delay.
             <= 0 => full Nyquist range.
             [Use SOLMOD to turn off the delay search.]
  CPARM(3)...The rate window FW to search (mHz) centered on 0 rate.
             <= 0 => full Nyquist range.
             [Use SOLMOD to turn off the rate search.]
  CPARM(4)...The minimum allowed signal-to-noise ratio.  <0 => 3
             The SNR calculation is described in AIPS Memo 101.
             [You might consider setting this to 5.]
  CPARM(5)...Number of baseline combinations to use in the initial,
             FFT fringe-search (1-3).  Larger values increase the
             point source sensitivity but reduce the sensitivity to
             extended sources when an accurate model is not available.
             0=>3.
             [Solutions formed using combinations of baselines are
              marked with a plus for singly indirect combinations and
              with two pluses for doubly indirect combinations.]
  CPARM(6)...If CPARM(6)=1, only baselines to those antennas on the
             SEARCH list are searched during the FFT stage.  Otherwise,
             other baselines are eventually searched until either fringes
             have been found to each antenna, or no baselines remain to
             be searched.
  CPARM(7)...If >0, RR and LL data are averaged together and only a
             single solution is determined for both polarizations.  This
             is useful when reducing polarization data.
  CPARM(8)...If <= 0 then the phase, rate and delays will be
             re-referenced to a common antenna.  CPARM(8)=1 is only
             desirable for VLBI polarization data. Using this option also
             forces OPCODE = ' '.
  CPARM(9)...If SOLINT>10 is desired, you must set CPARM(9)>0 .  This
             is necessary to prevent accidentally requesting more memory
             than your computer can deliver and locking up computer.
  CPARM(10)..Try Hard Option.  If CPARM(10)>=0, When KRING is ready to
             do the initial FFT-based fringe search, it will first try
             to initialize residual fringe-fit delay and rate solns for
             each antenna using an average of all good solutions found
             in the SN table.  Only those antennas for which acceptable
             solutions are not found will then be FFTd to find fringes.
             This does not preclude the final Least Squares refinement.
             [20 Oct 1999, it has been reported that CPARM(10) is broken -
              it may trash the solutions - dont try it unless you have
              the time to re-run KRING if need-be.]
  SOURCES....Sources to calibrate.  If this is left blank then all
             the sources are calibrated at once using the INTERPOL
             (i.e. CLCAL is only run once) and phase referenced to the
             FIRST source in the CALSOUR list.  If sources are listed
             then CLCAL is run once for each source using the
             interpolation method stated in INTERPOL.  Any sources
             that are in the SOURCE list but not in the CALSOUR list
             will be phase referenced to the FIRST source in the
             CALSOUR list.
  INTERPOL...The type of interpolation to be applied to the SN table:

             '    ' = linear vector interpolation with no SN smoothing.
             '2PT ' = linear vector interpolation with no SN smoothing.
             'SELF' = Use only SN solution from same source which
                      is closest in time.
             'SIMP' = Simple linear phase connection between SN phase
                      entries, assumes phase difference less than 180
                      degrees.
             'AMBG' = Linear phase connection using rates to resolve
                      phase ambiguities.
             'CUBE' = As AMBG but fit third order polynomial to phases
                      and rates.
  BADDISK....A list of disk numbers to be avoided when creating scratch
             files.
----------------------------------------------------------------
VLBAKRGP:           Procedure to perform antenna based fringe fitting
                    for phase referenced data using KRING and then apply
                    these corrections using CLCAL.
Documenter:         Amy Mioduszewski
Related Programs:   VLBAUTIL, KRING, CLCAL, VLBAKRNG, VLBAFRGP

This should be done after solving for the instrumental phase
corrections (VLBAPCOR) and before applying all the calibration
and averaging (SPLIT/SPLAT).  After VLBAKRGP is run it is ESSENTIAL
to check the solutions in POSSM setting GAINUSE to the CL table
output by VLBAKRGP.  VLBAKRGP will produce the highest SN and
CL table.  For details on KRING and CLCAL see their HELP/EXPLAIN
files.

It should be noted that this procedure will do the same thing as
VLBAKRNG if all SOURCES are in the CALSOUR list.  In order to have
the target source phase referenced it must be missing from the CALSOUR
list and in the SOURCES list or, alternatively, the SOURCES list must be
left blank.  The first option caused the sources listed in SOURCES but
missing from CALSOUR to be phase referenced to CALSOUR(1), while the
second caused ALL the sources to be phase referenced to CALSOUR(1).

VLBAKRGP assumes:

1. there is only one FREQID

2. that all IFs should be calibrated

3. that all antennas should be calibrated

4. that the entire uv range should be calibrated

5. that the highest FG table is the one that should be applied

6. that this is a multisource file

Steps in VLBAKRGP:

1. Runs KRING, which will do antenna based fringe fits.  This
   will produce the highest SN table.

2. Runs CLCAL, with OPCODE 'CALI', SNVER output SN table from
   KRING; GAINVER input GAINUSE and GAINUSE = highest CL table +1.
   Output should be highest CL table.  If SOURCES is blank then
   CLCAL is run only once and phase referenced to CALSOUR(1).  If
   SOURCES is not blank then CLCAL is run for each source in
   SOURCES.  If the source in SOURCES is in the CALSOUR list then
   it is referenced to itself, if not it is phase referenced to
   CALSOUR(1).

After VLBAKRGP is run and the solutions are checked in POSSM, SPLIT
or SPLAT should be run with GAINUSE set to the CL output from VLBAKRGP
and DOCAL=2.
