; FXPOL
;---------------------------------------------------------------
;! Corrects VLBA polarization assignments
;# Task UV VLBI
;-----------------------------------------------------------------------
;;  Copyright (C) 2000, 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
;-----------------------------------------------------------------------
FXPOL     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
FXPOL     Task to fix mislabelled VLBA polarizations and IFs
INNAME                             Input UV file name (name)
INCLASS                            Input UV file name (class)
INSEQ             0.0     9999.0   Input UV file name (seq. no.)
INDISK            0.0        9.0   Input UV file disk number
OUTNAME                            Output UV file name (name)
OUTCLASS                           Output UV file name (class)
OUTSEQ            0.0     9999.0   Output UV file name (seq no.)
OUTDISK           0.0        9.0   Output UV file disk number
BANDPOL                            Polarization specification
                                   (see help)
FQTOL                              Frequency tolerance for IF
                                   comparisons in kHz
----------------------------------------------------------------
FXPOL
Task:  The VLBA erroneously labels dual polarization experiments
       as having only one polarization and occasionally
       mislabels single polarization experiments. FXPOL allows
       the polarizations and IFs to be correctly labelled
       provided that no cross-polarization correlations are
       present.
Adverbs:
  INNAME.....Input UV file name (name).      Standard defaults.
  INCLASS....Input UV file name (class).     Standard defaults.
  INSEQ......Input UV file name (seq. no.).  0 => highest.
  INDISK.....Disk no. 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. no.). 0 => highest.
  OUTDISK....Disk no. of output UV file.     0 => any.
  BANDPOL....A string specifying the polarization of each IF.
             The simplest form is a string of Rs and Ls. See
             HELP BANDPOL for the complete set of rules.
                    '       ' => alternating RR and LL to the
                                 maximum number of IFs allowed.
  FQTOL......Frequency tolerance used when checking whether
             a pair input IFs should be assigned to the same
             output IF. Given in kHz.     < 1.0 kHz => 10.0 kHz.
----------------------------------------------------------------
FXPOL: Corrects VLBA polarization assignments
Documentor: Chris Flatters
Related Programs: FITLD

The VLBA correlator does not preserve polarization information
unless it is operating in full polarization mode. This results
in polarizations not being labelled correctly when both RR and
LL polarizations are observed without RL and LR. Each VLBA
correlator band is loaded into AIPS as a seperate IF and is
assigned the same polarization.

FXPOL takes a data set from the VLBA correlator and produces a
new data set that has the correct IF and polarization
assignments. Unfortunately, there is no reliable way to
determine the polarization of each IF from the input data set
and you must specify the polarization assigments using the
BANDPOL adverb.

Most VLBA setups assign odd-numbered bands to RCP and even-
numbered bands to LCP. In this case BANDPOL should be set to
'*(RL)   ' (the default) and FXPOL will generate a new data set
that is of equal size to the input data set but has two
polarizations and half the number of IFs. This case normally
applies if LISTR shows pairs of IFs with the same frequency and
QHEADER shows one pixel on the STOKES axis with coordinate value
RR but there may be exceptions to this rule when non-VLBA
antennas are used.

Most Mk3 and Mk4 VLBI setups reverse the polarizations and
assign odd-numbered bands to LCP and even-numbered bands to RCP.
In this case BANDPOL should be set to '*(LR)   ' and the output
data set will again be of equal size to the input data with two
polarizations and half the number of IFs. This case normally
applies if LISTR shows pairs of IFs with the same frequency and
QHEADER shows one pixel on the STOKES axis with coordinate value
LL but there may be exceptions to this rule when non-VLBA
antennas are used.

The vast majority of dual-polarization experiments fall into
these two categories but more complicated setups are possible.
For example,  combined 50cm and 90cm observations will often
assign 6 IFs to a single polarization in the 50cm band and 2 IFs
to different polarizations in the 90cm band. FXPOL can deal with
these cases but finding the correct setting for BANDPOL may be
complicated because

1 - the VLBA correlator does not necessarily preserve
    the order of the bands (although each band-pair,
    1-2, 3-4, etc., will be kept together), and

2 - FITLD will sort the bands into ascending order of
    frequency while preserving the relative ordering
    of bands that have the same reference frequency.

In most cases you will be able to determine the appropriate
setting for BANDPOL from your observing set-up but there may be
cases where you will need to gain access to the records of the
correlation to find out how the IFs in the AIPS file correspond
to the bands in your original observing set-up.

In general, the output files for the more complicated
polarization configurations will be larger than the input files.
In the worst possible case, the output file will be larger than
the input file by a factor of 2.

FXPOL will transfer the following tables to the output file,
correcting them for the new IF/polarization structure as
necessary.

AN - antenna
CL - calibration
CQ - decorrelation information
CT - CALC model
FG - flags
FQ - frequency
GC - gain curves
IM - interferometer model
MC - CALC model components
NX - index
OB - orbital parameters
PC - phase cal
SU - sources
TY - system temperature
VT - tape statistics
WX - weather

All other tables will be deleted to avoid potential confusion.

RESTRICTIONS

1 - FXPOL will not operate on files that already contain more
    than one polarization.

2 - FXPOL will not operate on files that have no IF axis nor on
    files that have no STOKES axis.

3 - FXPOL will not operate on files containing more than one
    frequency ID unless the same mapping from input IFs to
    output IFs can be applied to every frequency ID.

4 - FXPOL will do a limited amount of checking to ensure that
    no two output IFs have the same frequency and polarization.
    It will only check neighbouring IFs so FXPOL will not
    catch a case where, for example,  three IFs at the same
    frequency are assigned RCP, LCP, RCP in that order.

----------------------------------------------------------------
