; SWPOL
;---------------------------------------------------------------
;! Swap polarizations in a UV data base
;# Task UV POLARIZATION
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2000, 2013-2014
;;  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
;-----------------------------------------------------------------------
SWPOL     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
SWPOL     Task which swaps polarizations in a UV data base
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 #
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 #.
ANTENNAS                           Antennas to swap
SUBARRAY          0.0       99.0   Selected subarray
DOCALIB                            Swap calibration info?
DOTABLE          -1.0        1.0   >= 0 > swap SY, TY, CD tables
FQCENTER                           >= 0 -> center frequency axis
----------------------------------------------------------------
SWPOL
Task:  This task swaps polarization data streams in a UV data
       file. This allows data sets in which the polarization
       streams have been mislabelled to be corrected.
       Polarization streams may be mislabelled in VLA data if
       the transfer switch is set incorrectly or in VLBI data if
       the the normal/alternative IF switch is set to the wrong
       position at one or more telescopes.

       Calibration data in CL and SN tables may updated to
       reflect the altered polarization streams at the discretion
       of the user.

       SWPOL will handle both linear and circular polarizations
       but not a mixture of the two. SWPOL requires both both
       parallel hands (RR and LL or XX and YY) to be present and
       if any cross-hand (RL, LR, XY or YX) is present its
       conjugate cross-hand musty also be present.

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.
  OUTNAME....Output UV file name (name).     Standard defaults.
  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 with
             space for the file.
  ANTENNAS...Antennas for which polarizations are to be swapped.  If
             all entries are zero then polarizations are swapped for
             the whole array. If any entry is negative then all
             antennae *except* those listed are swapped.
  SUBARRAY...Subarray to process.            0 => subarray 1
  DOCALIB....If > 0 then swap calibration information for selected
             antennas in CL and SN tables
  DOTABLE....>= 0 -> swap polarizations in monitor tables (SY, TY, and
             CD) only.  < 0 -> no table swap.
  FQCENTER...>= 0 => Change frequency axis reference pixel to
                     Nchan / 2 + 1
             else => do not change reference pixel
----------------------------------------------------------------
SWPOL: Task to swap polarizations on one or more antennae
Documentor: C. Flatters, NRAO-AOC (preliminary version)
Related tasks: Most other UV tasks.

SWPOL is intended to correct UV data sets in which the
polarization data streams have been mislabelled at one or more
telescopes. It handles either linear (X and Y are swapped for
designated antennae) or circular polarization (R and L are
swapped for designated antennae). In order to allow
polarizations to be swapped for arbitrary subsets of telescopes
there are a number of restrictions on the form of the input
data. Principally, the polarization combinations in the data
must correspond to one of the following sets: (RR, LL),
(XX, YY), (RR, LL, RL, LR) or (XX, YY, XY, YX).

Some examples of the use of SWPOL to correct common errors are
given below.

Example 1: The transfer switch is set incorrectly at the VLA.
           This leads to the labels for right and left circular
           polarization being applied to the wrong channel for
           the whole array. In this case set up the input and
           output file specifications and set the ANTENNAS array
           to all zeros.

Example 2: One telescope in a VLBI experiment has set the
           normal/alt switch to the wrong position. This leads
           to RCP and LCP being recorded on the wrong tracks at
           that station; the diagnostic is wildly different
           amplitudes (commonly differing by a factor of 10) in
           the two parallel hands on baselines including that
           antenna. The solution is to find the number of the
           bad antenna using the 'MATX' output of LISTR, or using
           PRTAN if you already know the name of the telescope,
           and to set antennas using 'ANTENNAS = t, 0', where t
           is the antenna number of the bad telescope. DOCALIB
           should be set to true (> 0) to preserve phase-cals.

DIAGNOSTIC MESSAGES

The following messages indicate that the input data is not in a
form that SWPOL can handle.

SWINIT: COMPLEX AXIS MUST BE AXIS ONE
    This should not occur. If it does many other AIPS tasks will
    also fail on your data.

SWINIT: MUST BE EITHER 2 OR 4 POLARIZATIONS PRESENT
    Self-explanatory.

SWINIT: POLARIZATIONS INCOMPLETE OR MIXED
    The data contains a mixture of linear and circular
    polarizations or has a fragmentary set of polarizations (for
    example one parallel hand and one cross hand).
