; LOCIT
;---------------------------------------------------------------
;! fits antenna locations from SN-table data
;# Task UV Calibration
;-----------------------------------------------------------------------
;;  Copyright (C) 2002, 2004-2005, 2007, 2009
;;  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
;-----------------------------------------------------------------------
LOCIT     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
LOCIT:  Task to fit antenna locations from SN table data
USERID                             User number - ignored
INNAME                             UV data (name).
INCLASS                            UV data (class).
INSEQ             0.0    9999.0    UV data (seq. #).  0 => high
INDISK                             Disk unit #.       0 => any
INVER            -1.0     255.0    SN table version
SOURCES                            Source list
TIMERANG                           Time range to list
SELBAND                            Bandwidth to select (kHz)
SELFREQ                            Frequency to select (MHz)
FREQID                             Freq. ID to select.
                                   None selected => 1.
BIF               0.0      100.0   Lowest IF number 0=1
EIF               0.0      100.0   Highest IF number
STOKES                             Stokes to use
ANTENNAS                           Antennas to fit
SUBARRAY          0.0     1000.0   Subarray, 0=>1
REFANT            0.0       90.0   Reference antenna
DPARM                              Controls
                                   (1) > 0 => difference method
                                   (2) > 0 => omit K term
                                   (3,4) Elevation range (deg)
                                   (5,6) HA range (deg)
                                   (7,8) Dec range (deg)
                                   (9) > 0 Difference 2 IFs
                                   (10) > 0 solve for slope
PRTLEV            0.0        3.0   Print level - 0 normal
OUTPRINT
                                   Output text file base name
BPARM                              (1) antennas/plot page
                                   (2) > 0 -> plot R-L
                                   (3) Phase plot min
                                   (4) Phase plot max
                                   (5) Scale plotted points
                                   (6) Point type
                                   (7) Line type
                                   (8) Degree of crowding
DOTV             -1.0        1.0   > 0 -> plot to TV
GRCHAN            0.0        7.0   Graphics channel to use
BADDISK                            Disk to avoid for scratch.
----------------------------------------------------------------
LOCIT
Type:  Task
Use:   Fits the phases of an SN table for antenna locations.
       Optionally prints and plots the results.
Adverbs:
  USERID.....User number. Ignored
  INNAME.....UV file name (name).       Standard defaults.
  INCLASS....UV file name (class).      Standard defaults.
  INSEQ......UV file name (seq. #).     0 => highest.
  INDISK.....Disk unit #.               0 => any.
  INVER......SN table version number 0=highest.
  SOURCES....List of sources to be listed. '  '=> all; if any starts
             with a '-' then all except ANY source named.
  TIMERANG...Time range of the data to be listed. In order:
             Start day, hour, min. sec, End day, hour, min. sec
             Days relative to reference date.
  SELBAND....Bandwidth of data to be selected. If more than
             one IF is present SELBAND is the width of the
             first IF required. Units = kHz, 0=> all
  SELFREQ....Frequency of data to be selected. If more than
             one IF is present SELFREQ is the frequency of the
             first IF required. Units = MHz, 0=> all
  FREQID.....Frequency identifier to select (you may determine
             which is applicable from the OPTYPE='SCAN' listing
             produced by LOCIT. If either SELBAND or SELFREQ
             are set, their values overide that of FREQID.
             However, setting SELBAND and SELFREQ may result in
             an ambiguity.  In that case the task will request
             that you use FREQID.  If neither SELBAND, SELFREQ
             nor FREQID are specified then the first FQ id in
             the FQ table (usually 1) will be used.
  BIF........Lowest IF to use.
             **************************************************
             NOTE to VLA users: IF=1 corresponds to the VLA
             AC ifpairs and IF=2 corresponds to the BD ifpairs.
             **************************************************
  EIF........Highest IF to list. 0 => Highest
  STOKES.....'RR' or 'R' use only right hand
             'LL' or 'L' use only left hand, else use both if present.
  ANTENNAS...A list of the antennas to fit.  If any number is negative
             then all antennas listed are NOT desired and all others
             are.  All 0 => fit all except REFANT.
  SUBARRAY...Subarray number to list. 0=>1.
  REFANT.....Antenna that is asumed to be fixed --- all fits are
             relative to this antenna.  Note that you may use no
             reference antenna if you wish - effectively saying that
             the reference antenna phases are all zero which they will
             be if the same REFANT was used in CALIB.  The difference
             method has no use for a REFANT.
  DPARM......Control parameters:
             (1) > 0 => use the method in which consecutive
                 observations are differenced.
             (2) > 0 => do not do the K term
             (3,4) Limit to elevation range (min,max) 0 -> all
                  (degrees)
             (5,6) Limit to hour angle range (min,max) 0 -> all
                  (degrees)
             (7,8) Limit to declination range (min,max) 0 -> all
                  (degrees)
             (9) > 0 => use the method in which IF 2 is differenced
                 with IF 1.  This is useful if the antenna locations
                 are poorly known since it depends on the small
                 frequency difference between the two IFs rather than
                 the larger absolute frequency of the IFs.  Note that
                 this halves the number of data points and makes the
                 errors much larger, but is essential if the antenna
                 locations are so poorly known that multiple phase
                 wraps occur.
             (10) > 0 => solve for a linear slope in phase with time.
                 Otherwise assume that the phase is roughly constant
                 after the antenna locations are corrected.
  PRTLEV.....Print level used for debugging problems.  0 normal.
  OUTPRINT...Disk text file name to use for output text files
  BPARM......(1) Number of antennas plotted per page.  0 -> no plots.
             (2) > 0 -> plot R-L rather than R and L separately
                (STOKES must not be 'RR' or 'LL')
             (3) Fixed plot range minimum in degrees (see below).
             (4) Fixed plot maximum in degrees.
                 If BPARM(4) > BPARM(3) do a fixed scale plot from
                 BPARM(3) to BPARM(4), discarding any points outside
                 the range.  If BPARM(4) < BPARM(3), do a fixed scale
                 plot from BPARM(4) to BPARM(3) except that, if there
                 are data outside this range for a particular plot,
                 allow that plot to self-scale to the larger range.
                 If BPARM(4) = BPARM(3), self-scale all plots.
             (5) Plot points scaled by BPARM(5) 0 -> 1
             (6) Point plot symbol:
                 1: Plus sign             12: Five pointed star
                 2: Cross (X)             13: Star of David
                 3: Circle                14: Seven-pointed star
                 4: Box                   15: Eight-pointed star
                 5: Triangle              16: Nine-pointed star
                 6: Diamond               17: Ten-pointed star
                 7: Pentagon              18: 11-pointed star
                 8: Hexagon               19: 12-pointed star
                 9: Septagon              20: 13-pointed star
                 10: Octagon              21: 14-pointed star
                 11: Nine-gon             22: Plus with gap
                                          23: Vertical line
                                          24: Cross (X) with gap
             (7) Do with connected lines: 0 no line, 1 direct
                 connection, 2 steps, -1 no points, connected line,
                 -2 no points, stepped line
             (8) = 1 -> plot polarizations together
                 = 2 -> plot IFs and polarizations together
  DOTV.......> 0 => make the plot(s) on the TV, else make plot files.
  GRCHAN.....Graphics channel to use when DOTV > 0.  0 -> 1.
  BADDISK....Disk numbers to avoid for scratch files.  Scratch
             files may be created by the sorting routines if
             calibration or flagging is applied.
----------------------------------------------------------------
The data to be used for LOCIT needs to be taken for the purpose of
fitting antenna locations.  Point-source calibrators all over the sky
must be observed one after another, preferably with large shifts in
hour angle and declination between scans.  The choice of REFANT is
significant and a single station should be used at all times, even
though its antenna number will change occasionally.

The DPARM(1) = 1 method implements an old Cal Tech algorithm in which
the antenna/atmosphere phase was assumed not to change between
adjacent scans.  The antenna phases of adjacent scans are differenced
as are the derivatives of phase wrt antenna location at the two scans.
The phase slope with time and the average phase offset are not
determined since they are assumed zero in this method.  The method
does limit the systematic wanderings of phase but seems to produce
somewhat noisier solutions for well-behaved antennas for some unknown
reason.
----------------------------------------------------------------

