; ATMCA
;---------------------------------------------------------------
;! Determines delay/phase gradient from calibrator observations
;# Task Calibration
;----------------------------------------------------------------
;;  Copyright (C) 2004, 2008
;;  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
;-----------------------------------------------------------------------
ATMCA     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
ATMCA     Fits phase/delay slope to residual calibrator data
INNAME                             Input UV file name (name)
INCLASS                            Input UV file name (class)
INSEQ             0.0     9999.0   Input UV file name (seq. #)
INDISK                             Input UV file disk unit #
SNVER                              Input SN table version
                                   0 => last
GAINVER                            Input CL table to copy
                                   0=>high
APARM                              control parameters:
                                   1: Number of terms to fit
                                      1=>Fit 1-D gradient
                                      2=>Fit 2-D gradient
                                      3=>Fit 2-D grad+offset
                                      4=>like 3 + time slope
                                      5=>Fit gradient along
                                         elevation
                                      0 => 2
                                   2: Create corrected CL table?
                                      0 => not create
                                      1 => create
                                   3: Create residual SN table?
                                      0 => not create
                                      1 => create
                                   4: Use the reference
                                      calibrator (first at the
                                      list) when APARM(1)= 2
                                      0 => use
                                      1 => do not use
                                   5: Reference time (days) when
                                      the two-pi ambiguity is
                                      zero (OPTYPE='PHAS')
                                   6: Intermediate and output
                                      SN tables:
                                      0 => delete
                                      1 => not delete
SOURCES                            Sources to correct in the
                                   new CL table. ' '=>all
CALSOUR                            List of the calibrators
                                   used to find the solution.
                                   The first source MUST be the
                                   primary reference source.
STOKES                             Stokes type to process
SELBAND                            Bandwidth to select (kHz)
SELFREQ                            Frequency to select (MHz)
FREQID                             Freq. ID to select, 0=>all
BIF               0.0      100.0   Lowest IF number 0=>all
EIF               0.0      100.0   Highest IF number 0=>all
TIMERANG                           Time range to use. 0=>all
ANTENNAS                           Antennas to select. 0=>all
SUBARRAY          0.0     9999.0   Subarray; 0 => 1.
SOLINT                             Solution time interval,
                                   in min.  0=> 30min
OPTYPE                             What data to read from the
                                   SN table:
                                   'PHAS' => phase delay
                                   'MDEL' => multi band delay
                                   '    ' => 'PHAS'
OUTTEXT                            Table of fitted slopes
DOHIST                             >0 => put coefficients in
                                         history file.
BADDISK           0.0     9999.0   Disks to avoid for scratch
----------------------------------------------------------------
ATMCA
Task:  This task determines the phase or delay slope from the
       residual data of nearby calibrators to the main
       reference source, and applies the appropriate correction
       to all sources.
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.
  SNVER......Input SN table with the residual MBDELAY or PHASE
             for the calibrators.  0 => highest.
  GAINVER....Input CL table version which is corrected if
             APARM(2)=1. 0 => highest input table.  Output
             CL table is the next one after the highest
  APARM......control parameters (see explanation)
             1: Number of terms to solve for correction.
                1 => determine phase slope between main cal
                     and secondary calibrator, and project this
                     phase difference to the target.
                2 => determine the 2-D phase slope using the
                     main calibrator and at least two secondary
                     calibrators, and apply to the target.
                3 => also determine an offset phase.  Need at
                     least two secondary  calibrators
                4 => also determine a time rate of change.
                     Need at least three secondary calibrators
                5 => Fit gradient along elevation.
                0 => 2
             2: Create CL table?
                0 => do not create
                1 => create CL table with corrections
             3: Create output SN table of result for sources
                     in CALSOUR.
                0 => do not create
                1 => create.  Results can be displayed by SNPLT for
                              example
             4: Use the reference calibrator (first at the CALSOUR list)
                when APARM(1)= 2
                0 => use
                1 => do not use
                0 is recommended
             5: Time (in days) when the phase for all sources and
                baselines has no two pi ambiguity.
             6: When solving 2pi ambiguity, (OPTYPE = 'PHAS')
                the intermediate SN table with the solved phase is created.
                This table includes the solved phase (in degrees) at the
                column REAL, which can be plotted by SNPLT (OPTYPE='REAL').
                The output SN table has the same format.
                These two tables should be deleted under control of
                APARM(6), because they can not be used at the following
                calibration due to strange REAL (degrees) and IMAG=0.
                You can leave them but then still delete them later
                (having examined) using verb EXTDEST.
                0 => create
                1 => not create
  SOURCES....List of the sources to apply the found correction at CL
             table. ' ' = all
  CALSOUR....List of the calibrators used to find the solution.
             The first source MUST be the main phase reference
             source or target if strong.. The output SN table
             include correction for the sources given at CALSOUR (not SOURCE)
  STOKES.....The desired Stokes type of the output data:
             'R', 'L', '  '=> all available.
  SELBAN.....Bandwidth to select (kHz)
  SELFREQ....Frequency to select (MHz)
  FREQID.....Frequency ID to select. 0=>all
  BIF........First IF to process. 0=>all.
  EIF........Highest IF to process. 0=>all higher than BIF
  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. 0=>all
  ANTENNAS...A list of the antennas to be calibrated, plotted and
             corrected.  If any number is negative then all
             antennas listed are ignored.
             All 0 => use all antennas.
  SUBARRAY...The subarray to calibrate. Does only one at a time.
  SOLINT.....Time interval in min to find a solution.  This
             interval should must contain sufficient data to define
             a solution.  0=>30 min
  OPTYPE.....What data to read from the SN table:
             'PHAS' => phase delay
             'MDEL' => multi band delay
             '    ' => 'PHAS'
  OUTTEXT....Table of fitted delays and slopes for each solution
             intervals and antennas
             The values correspond to the desired
             corrections.
  DOHIST.....if DOHIST > 0, the gain coefficients are written
             into the history file.
  BADDISK....A list of disks on which scratch files are not to
             be placed.  This will not affect the output file.
----------------------------------------------------------------
ATMCA:  Task determines delay/phase gradients from calibrator
        observations, and applies the appropriate correction to
        the target sources.
Documenters: L.R. Kogan, E.B. Fomalont
Related Programs: DELZN, CLCAL, ELINT, SNPLT

                            PURPOSE

   Please read AIPSMEMO111 for detailed instructions of the use
of ATMCA.

tp://ftp.aoc.nrao.edu/pub/software/aips/TEXT/PUBL/AIPSMEM111.PS

   Most phase referencing observations nod between a reference
calibrator (0) and a target source (T).  Errors in the correlator
model (egs. troposphere and ionospheric refraction, antenna locations)
introduce systematic phase differences between the 0 and T direction
over each telescope, often with a time-scale of many minutes to hours
of time.  These errors decrease the dynamic range and astrometric
accuracy of VLBI observations.

    To a first approximation, this phase difference can be described
as a linear slope of anomalous delay over each of the telescopes
within a region of about five to ten degrees near 0 and T.  With
observations of additional calibrator(s), the effect of this phase
gradient can be decreased.

                         PARAMETERS FOR ATMCA

INNAME, INCLASS, INSEQ, INDISK:  The input data set

SNVER: The SN table which contains the antenna-based phases for of the
sources to be analyzed by ATMCA.  Source position offsets must have
been removed.

GAINVER: The CL table with the calibrations used to generate the SNVER
table.  A new CL table will be generated with the improved solution.

-------------------------------------------------------------------
APARM(1)  MAIN CONTROL OF ATMCA  (see AIPSMEMO111)

APARM(1)=1: Linear interpolation of phase of two calibrators to apply
to target.  The calibrators must be within 45 deg of colinear.

APARM(1)=2: Determine phase slope and orientation.  Three calibrators
in a reasonable two-dimensional distribution must be used.

APARM(1)=3: Phase/delay gradient and offset:  Needs at least four
calibrators

APARM(1)=4: The same as APARM(1)=3 but a gradient in time is added to
the list of found parameters.  Needs at least five calibrators.

APARM(1)=5: Assumes phase gradient is in the elevation direction.  Can
be used with two calibrators or one calibrator and a strong target.

------------------------------------------------------------------------
APARM(2):  Create new CL table.

    A new CL table containing the additional phase terms for all
designated sources in SOURCE, will be produced if APARM(2) = 1.

APARM(3): Create a new SN table which contains the residuals for
sources in CALSOUR after the correction is applied.  This SN table is
used to view the fitting result using SNPLT.  It is not meant to be
applied to a CL table using CLCAL.

SOURCES: List of sources to correct.  Often ' ' is the correct choice.
It should include all of the calibrators and targets.

CALSOUR: The first source MUST be the main reference source or the
target if it is used as the main reference source.  Other calibrator
sources are then added.  It is dangerous to use ' '.

SOLINT: The time interval for obtaining a solution.  The minimum time
must contain sufficient phase measurements to obtain a solution.  In
order to decrease the effects of short-term atmospheric phase
fluctuations, or phase noise of relatively weak calibrators, longer
SOLINT can be considered.


OUTTEXT:  The output file for the solutions.
