; FRCAL
;---------------------------------------------------------------
;! Faraday rotation self calibration task
;# Task AP OOP calibration
;-----------------------------------------------------------------------
;;  Copyright (C) 1995
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
FRCAL     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
FRCAL: Faraday rotation self calibration task
INNAME                             Input UV data (name)
INCLASS                            Input UV data (class)
INSEQ                              Input UV data (seq. #)
INDISK                             Input UV data disk drive #
IN2NAME                            Model Image file name
IN2CLASS                           Model Image file class
IN2SEQ                             Model Image file seq
IN2DISK                            Model Image file disk
IN2VER                             Model Image CC version number
NITER                              Number of CC comps. to use.
PMODEL                             Source polarization model.
OUTNAME                            Output uvdata name (name)
OUTCLASS                           Output uv data class.
OUTDISK                            Output uvdata disk drive #
OUTSEQ          -1.0     9999.0    Output seq. no.
                                   Solution control adverbs:
SOLINT                             Solution interval (min)
APARM                              General parameters
                                      1=min. no. antennas
                                      2=min. SNR
                                      3=min. ratio
                                      4=max. ratio
                                      5 >1=> avg. IF
                                      6 >1=> divide only
                                      7 >1=> tell solutions
                                      8 >1=> input divided
ANTWT                              Ant. weights (0=>1.0)
UVRANGE                            Range of uv distance for full
                                   weight.  0 => all.
WTUV                               Weight outside UVRANGE 0=0.
BADDISK           -1.0      1000.0 Disks to avoid for scratch.
----------------------------------------------------------------
FRCAL
Type:  Task
 Use:  Determines ionospheric Faraday rotation corrections for a
       data set by comparison with a polarized model.
       Corrections are written into an SN table attached to the
       input uv data and a corrected uvdata set is written.
Adverbs:
  INNAME.....Input UV data file (name).       Standard defaults.
  INCLASS....Input UV data file (class).      Standard defaults.
  INSEQ......Input UV data file (seq. #).     0 => highest.
  INDISK.....Input UV data file disk drive #. 0 => any.
  IN2NAME....Cleaned map name (name).      Standard defaults.
  IN2CLASS...Cleaned map name (class).     Standard defaults.
             Class names are assumed to be of the form '?xxxxx'
             where ? is Q and U.
  IN2SEQ.....Cleaned map name (seq. #).    0 -> highest.
  IN2DISK....Disk drive # of cleaned map.  0 => any.
  INVERS.....CC file version #.  0=> highest numbered version
  NITER......# CLEAN comps. to use for model. 0 => all.
  PMODEL.....A single component model to be used instead of a
             CLEAN components model; if abs (PMODEL(2 or 3) > 0
             then use of this model is requested.
                PMODEL(1) = I flux density (Jy)
                PMODEL(2) = Q flux density (Jy)
                PMODEL(3) = U flux density (Jy)
                PMODEL(4) = V flux density (Jy)
                PMODEL(5) = X offset in sky (arcsec)
                PMODEL(6) = Y offset in sky (arcsec)
             NOTE: PMODEL takes precedence over an IN2NAME
             model.
  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
               disk number with space
The following control how the solutions are done, if you don't
understand what a parameter means leave it 0 and you will
probably get what you want.
  SOLINT.....The solution interval (min.) 0 = data integration.
  APARM......General control parameters.
  APARM(1)...Minimum number of antennas allowed for a solution.
             0 => 4
  APARM(2)...The minimum allowed signal-to-noise ratio.
             0 => 5
  APARM(3)...Minimum magnitude of the ration of the data to the
             model to be used. 0 = 0.75
  APARM(4)...Maximum magnitude of the ration of the data to the
             model. 0 = 1.5
  APARM(5)...If > 0 then average solution in IF.
  APARM(6)...If > 0 then return the data divided by the model.
  APARM(7)...If > 0 then tell about solutions.
  APARM(8)...If > 0 then the input data has already been divided
             by the model and only solutions will be determined.
  ANTWT......Antenna weights.  These are additional weights
             to be applied to the data before doing the
             solutions, one per antenna.  Use PRTAN to
             determine which antenna corresponds to each
             antenna number.
             0 => 1.0
  UVRANGE....The range of uv distance from the origin in
             kilowavelengths over  which the data will have
             full weight; outside of this annulus in the uv
             plane the data will be down weighted by a factor
             of WTUV.  0 => all.
  WTUV.......The weighting factor for data outside of the uv
             range defined by UVRANGE.
  BADDISK...This array contains the numbers of disks on which
            it is desired that scratch files not be located.
            BADDISK has no effect on input and output data.
----------------------------------------------------------------
FRCAL:  Faraday rotation self calibration task.
Documentor:  W. D. Cotton, NRAO
Related Programs: PCAL, FARAD

   Linearly polarized signals undergo a rotation of the
orientation of the electric vectors as they propagate through a
magnetized plasma; an effect know as Faraday rotation.  The
ionosphere can introduce substantial, time and source variable
Faraday rotation into the signals from radio sources.  The
magnitude of the effect is determined by the integral of the
electron density times the component of the magnetic field along
the line of sight.  This effect can therefore vary strongly with
observing geometry as well as electron density.  Faraday
rotation increases rapidly with decreasing frequency and
increasing solar activity.

   Task FARAD attempts to make a correction for ionospheric
Faraday rotation based on external models or measurments of the
ionospheric electron density.  However, when this effect is
significant this correction may be inadequate.  Task FRCAL uses
a polarized model of the source along with the observations to
estimate and remove the effects of ionospheric Faraday rotation.
As the model of the polarized emission will be corrupted by the
Faraday rotation multiple iterations of imaging - Faraday self
calibration may be needed.  In addition, the polarization
calibration may be adversely affected by variable Faraday
rotation and the instrumental polarization (task PCAL) may need
to be included in the Faraday rotation self calibration loop for
the polarization calibrator.

   The total intensity calibrations should have adjusted all the
parallel hand phases to the same reference antenna so that the
residual Faraday rotation effect is the right-left phase
difference at the reference antenna. A single right-left phase
difference is needed at any given time.

   The results of FRCAL are 1) an SN table attached to the
input uvdata and 2) a corrected set of uv data.  The corrections
in the SN table can, in principle, be applied to another source
although this will only work if the two sources involved are
near by on the sky and can be assumed to have the same Faraday
rotation properties.

   FRCAL first divides the observed RL and LR correlations by
the Fourier transform of the polarized model to remove the
effects of source structure.  The result will be all (1,0) for a
perfect model and no Faraday rotation.  The phase of the divided
RL and LR data will be rotated in opposite directions by Faraday
rotation.  In each solution interval the estimate of the Faraday
rotation is determined from the weighted average of the phase of
the divided RL data and the conjugate of the divided LR data.
Half of this phase is added to the R gain phases in the SN table
to all antennas in that solution interval and half is subtracted
from the L gain phases.  When applied to the visibility data
this will have no effect of parallel hand (RR and LL) data but
will remove the estimate of the Faraday rotation from the cross
(RL, LR) hand data.

   Note: this procedure will only work if the parallel hand data
is already fully calibrated and only the time variable
right-left phase difference remains to be determined.  Also any
prior R-L offset calibration will be lost.



