; FARAD
;---------------------------------------------------------------
;! add ionospheric Faraday rotation to CL table
;# Task Calibration Polarization VLA
;-----------------------------------------------------------------------
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
FARAD     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
FARAD     Task to add ionospheric Faraday rotation to CL table
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 #
INFILE                             Ionosonde data file.
SOURCES                            Source list ' '=>all.
TIMERANG                           Time range to use.
ANTENNAS                           Antennas to correct.
SUBARRAY          0.0     9999.0   Subarray; 0 => 1.
GAINVER           0.0     9999.0   CL table version to update
OPCODE                             Operation code.
                                     'TEC ' => use TEC data
                                     'F0F2' => use f0F2 data
                                     'MOD ' => use Chiu model
                                     '    ' => use model
BPARM                              Model parameters:
                                     1 = altitude of F2 layer
                                     2 = R1 sunspot number
----------------------------------------------------------------
FARAD
Task:  This task estimates the ionospheric Faraday rotation
       measure and adds it to a CL table.
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.
  INFILE.....Name of file containing ionospheric data.
  SOURCES....list of sources to process.
             '*' = all; a "-" before a source name
             means all except ANY source named.
  TIMERANG...Time range of the data to be used. In order:
             Start day, hour, min. sec,
             end day, hour, min. sec. Days relative to ref.
             date.
  ANTENNAS...A list of the antennas to be modified.  If any
             number is negative then all antennas listed  are
             NOT to be modified.  All 0 => use all.
  SUBARRAY...The subarray to modify. Do only one at a time.
  GAINVER....The CL table version number which is to be updated.
             NOTE: There is NO default value.
  OPCODE.....Operation code (see also EXPLAIN FARAD):
             'TEC ' => use TEC data. INFILE should be the name
                       of a file containing TEC data in the
                       format distributed by the Boulder
                       station. Uses BPARM(1) or BPARM(2).
             'F0F2' => use critical frequency data (f0F2). Note
                       that the second character is a zero. Not
                       yet implemented.
             'MOD ' => use Chiu model. Uses BPARM(2) and may
                       use BPARM(1).
             The default is to use the Chiu model.
  BPARM......Model parameters:
             BPARM(1)  Altitude of F2 layer (km).
                       0 => calculate using Chiu model.
             BPARM(2)  Mean monthly Zurich sunspot number (R1).
----------------------------------------------------------------
FARAD:  Task to calculate line-of-sight, free-electron density
        and Faraday rotation measure of the ionosphere and to
        enter these in a calibration (CL) table.
Documentor: C. Flatters
Related Programs: CALIB, PCAL, SPLIT, TABCOP, TABED

This task estimates the Faraday rotation measure of the ion-
osphere and enters it in a CL table. If polarization calibra-
tion is requested, later AIPS calibration tasks will use this
estimate to remove the phase difference between right and
left circular polarization introduced by ionospheric Faraday
rotation. Note that although phase calibration eliminates
differences in ionospheric Faraday rotation between antennae
from the calibrated data it introduces these differences into
the polarization leakage terms (which are calculated by PCAL);
it is therefore necessary to know the ionospheric Faraday
rotation for every antenna in the array if polarization leakage
terms are to be properly calibrated.

    FARAD makes a number of simplifying assumptions about the
form and behaviour of the ionosphere. These are described in the
following sections. If you have not used FARAD before you should
read these sections to familiarize yourself with its limitations.

APPROXIMATIONS

IONOS calculates the free-electron column density from the
zenith column density of free electrons, usually referred
to as the total electron content (or TEC) of the ionosphere,
assuming that the ionosphere is approximated by a thin sheet;
the adverb OPTYPE selects the means used to derive the TEC.
Since the F2 layer of the ionosphere dominates the total
electron content and since the distribution of free electrons
in the F2 layer is normally strongly peaked the thin sheet
approximation is usually valid. It may, however, break down
for the daytime ionosphere when solar activity is high (near
solar maximum). Given the free-electron column density the
rotation measure is calculated assuming an offset dipole
model for the Earth's magnetic field.

    The F2 layer is assumed to be at a constant height for
the duration of the observations. The assumed height may be
entered directly as BPARM(1) or you may force FARAD to
calculate it using the Chiu model (see below) by setting
BPARM(1) to zero. The height of the F2 layer is normally
between 300 and 400 km, depending on solar activity. The
diurnal variation in altitude is negligable (of the order of
1% or less) but there is some variation with magnetic longitude
and if observing a source away from the zenith you may be
looking through the ionosphere at a significantly different
magnetic longitude. However, at most latitudes the following
approximation will become invalid long before the assumption
of constant height.

    FARAD calculates (or reads) the TEC for a single reference
position and applies it to the selected antennae assuming that
the TEC is a function of local mean time and does not depend
on geographic latitude. This approximation is only valid over
small distances and only antennae within a few degrees of the
reference point in latitude and longitude should be selected.
For OPTYPE = 'TEC' and OPTYPE = 'F0F2' the reference point is,
of course, the position at which the measurements were taken;
for OPTYPE = 'MOD' the reference point is the latitude and
longitude of the first selected antenna.

OPTYPE = 'TEC'

As TEC measurements (usually derived from measuring the
Faraday rotation of a signal from a geostationary satellite)
gives FARAD exactly what it needs, this is the preferred
method of running FARAD. INFILE should be a file containing
hourly TEC measurements in the format used by the Boulder
monitoring station (described below). Other monitoring stations
may also use this format.

TEC data from Boulder, which is used to calibrate VLA
polarization data, is distributed with AIPS. The input files
may be found in the directory AIPSIONS and follow the naming
convention TECB.yy, where yy is the last two digits of the year.
TEC indicates that the files contain TEC data, B indicates
Boulder. To access the TEC data for 1989, for example, use
INFILE = 'AIPSIONS:TECB.89'.

OPTYPE = 'F0F2' (NOT YET AVAILABLE)

The most commonly available information on the electron content
of the ionosphere is the critical frequency of the F2 layer
(f0F2). Many ionospheric monitoring stations distribute hourly
values of f0F2 in a standard format. The f0F2 values give the
peak density of the F2 layer, which can be converted to a TEC
provided that the profile of the F2 layer is known. FARAD
calculates an equivalent thickness assuming a Chapman profile
for the F2 layer; since Chapman profiles depend only on the
altitude of the peak (which is assumed constant) the equivalent
thickness is only calculated once. Note that the F2 layer may
not be described by a simple Chapman profile in the daytime
close to solar maximum.

OPTYPE = 'MOD'

If there is no ionospheric data available OPTYPE = 'MOD'
calculates the TEC using an empirical model due to Y. T.
Chiu (J. At. Terr. Phys. 37:1563, 1975). The model is
simplified somewhat by assuming a constant altitude and
slab thickness for the F2 layer (as for OPCODE = 'F0F2
above). The only input to this model is the mean monthly
Zurich sunspot number (R1), which is used as an indicator
of solar activity. The Chiu model does not therefore
reproduce day-to-day variations in the ionosphere (note
that use of daily values of R1 appears to exaggerate
day-to-day variations).

    The Chiu model is claimed to be accurate to within 20%,
but appears to fall apart badly for the daytime ionosphere
near solar maximum.

    This model is only the default since it requires no
external data. If ionospheric measurements exist for your
data, you should use them; the Chiu model should only be
used as a last resort!

THE BOULDER TEC FORMAT

TEC data from Boulder, Colorado is made available in the
form of a text file. All records in the file are 79 or 80
characters in length (the 80th character is stripped from
downloadable files). The file begins with a single header
record followed by an unlimited number of data records.

    The header record contains the following fields (optional
items are marked with an asterisk)

    Column         Description
    ======         ===========
    01             identifier for the type of data (7 for TEC)
    02             blank
    03-20          station name
    21-30 *        satellite name
    31-34 *        satellite East longitude
    35-40 *        beacon frequency
    41-45 *        latitude of SIP (420 km altitude)
    46-50 *        East longitude of SIP (420 km altitude)
    51-60 *        East longitude of time zone used for data
    61-70 *        Conversion factor (units of ambiguity) in
                     units of electrons per meter squared per
                     unitpf ambiguity (eg. pi radians) times
                     10 to the -15th
    71-80 *        Method of data reduction
                     FR:  Faraday rotation
                     GD:  group delay
                     DCP: differential carrier phase

    Each data record contains the following fields:

    Column         Description
    ======         ===========
    01-02          range and type of data
                     11: hourly values for 00-11 hours
                     12: hourly values for 12-23 hours
                     21: median data for 00-11 hours
                     22: median data for 12-23 hours
    03-05          station computer code (eg. 840 for Boulder)
    06-07          year - 1900
    08-09          month number
    10-11          day of month for hourly data; otherwise 40
                     for medians or 50 for median count
    12-13          characteristic (70 for TEC data)
    14-73          data (twelve fields of five characters each)
    74-76          latitude of SIP (degrees)
    76-79          East longitude of SIP (degrees)
    80             time
                     U: UT
                     L: local time

If column 80 is not present FARAD will assume that times are in UT.

    Each five-character data field has the following structure

    Character      Description
    1-3            TEC in units of 10 to the 15th (no decimal
                     point)
    4              blank
    5              data qualifier
                     C: no data
                     M: add 1000 to data
                     N: add 2000 to data
