; ELINT
;---------------------------------------------------------------
;! Determines and removes gain dependence on elevation
;# Task Calibration
;-----------------------------------------------------------------------
;;  Copyright (C) 1995-1997, 1999-2003, 2006, 2012
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
ELINT     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
ELINT     Determines and removes gain dependence on elevation
INNAME                             Input UV file name (name)
INCLASS                            Input UV file name (class)
INSEQ             0.0     9999.0   Input UV file name (seq. #)
INDISK                             Input UV file disk unit #
INVERS            0.0     9999.0   Input SN table version
                                   0 => high
GAINVER                            Input CL table to copy to
                                   CL=high+1 and then correct
                                   0=>high
SOURCES                            Source list ' '=>all.
CALSOUR                            Calib. list. Do not use ' '
QUAL            -10.0              Calibrator qualifier -1=>all
CALCODE                            Calibrator code '    '=>all
STOKES                             Stokes type to process
SELBAND                            Bandwidth to select (kHz)
SELFREQ                            Frequency to select (MHz)
FREQID                             Freq. ID to select, 0=>all
BIF               0.0      100.0   Lowest IF number 0=>all
EIF               0.0      100.0   Highest IF number 0=>all
TIMERANG                           Time range to use. 0=>all
ANTENNAS                           Antennas to correct. 0=>all
SUBARRAY          0.0     9999.0   Subarray; 0 => 1.
NPLOTS                             Number of plots per page
                                     0=>5, -1=> Don't make plots
XINC              0.0     5000.0   Plot every XINC'th point
OPTYPE                             '   ' OR 'AMPL' => gain fit
                                        without opacity
                                   'AMPT' => fit both gain and
                                        opacity (see HELP)
OPCODE                             Fit type: '    ' => 'POLZ'
                                   'POLE' Ampl. vs. Elevation
                                   'POLZ' Ampl. vs. zenith dist.
                                   'PWR ' Power vs. zenith dist.
                                   'PWRN' Power vs. zenith dist.
                                          normalized.
PRTLEV                             0=> no printout.
                                   1   => print coefficients
                                   2   => print coefficients
                                          and their errors
                                          and rms of residual
                                          see help.
                                   >10 => see help
DOHIST                             >0 => put coefficients in
                                         history file.
DOTV             -1.0       1.0    > 0 Do plot on the TV, else
                                   make a plot file
GRCHAN            0.0       8.0    Graphics channel 0 => 1.
BADDISK           0.0     9999.0   Disks to aviod for scratch
----------------------------------------------------------------
ELINT
Task:  Determines and removes gain dependence on elevation
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.
  INVERS.....Input SN table version number. 0 => high.
  GAINVER....Input CL table version. If GAINVER is equal zero or
             greater than the total number of the CL tables
             then GAINVER is equal to the last existing CL table.
             The input CL table version (GAINVER) is copied to
             the output CL table version=(high+1), and then
             the output CL table is corrected.
  SOURCES....list of sources to process.
             ' ' = all; a "-" before any source name
             means ALL listed sources will be skipped.
  CALSOUR....list of calibrators to use.
             Do not use ' '; a "-" before any calibrator name
             means ALL listed calibrators will be skipped.
             CALSOUR(1) is the flux density standard source.
  QUAL.......Only calibrators with a source qualifier number in the SU
             table matching QUAL will be used if QUAL is not -1.
  CALCODE....Calibrators may be selected on the basis of the calibrator
             code:
                  '    ' => any calibrator code selected
                  '*   ' => any non blank code (cal. only)
                  '-CAL' => blank codes only (no calibrators)
                  anything else = calibrator code to select.
             NB: The CALCODE test is applied in addition to the other
             tests, i.e. CALSOUR and QUAL, in the selection of sources
             for which to determine solutions.
  STOKES.....The desired Stokes type of the output data:
             'R', 'L', '  '=> all available.
  SELBAN.....Bandwidth to select (kHz)
  SELFREQ....Frequency to select (MHz)
  FREQID.....Freq. ID to select. 0=>all
  BIF........First IF to process. 0=>all.
  EIF........Highest IF to process. 0=>all higher than BIF
  TIMERANG...Time range of the data to be used. In order:
             Start day, hour, min. sec, end day, hour, min. sec.
             Days relative to reference date. 0=>all
  ANTENNAS...A list of the antennas to be calibrated.  If any
             number is negative then all antennas listed are
             ignored.  All 0 => use all antennas.
  SUBARRAY...The subarray to calibrate. Does only one at a time.
  NPLOTS.....Number of gain plots per page; 0=>5.
             If NPLOTS < 0, then no plots are made.
  XINC.......Plot every XINC'th point
  OPTYPE.....Data to be fitted: 'AMP ', '    ', 'AMPL'=  ampl.
             without opacity fit, 'AMPT' = ampl.+opacity fit.
	     'AMPT' is experimental and not recommended for use.
  OPCODE.....Fit type:
             'POLE':  G = G0 + G1*ELEV + G2*ELEV*ELEV,
                      ELEV in degrees
             'POLZ':  G = G0 + G1*ZA + G2*ZA*ZA,
                      ZA in degrees
	     'PWR ':  G = G0 + G1*ZA + G2*ZA*ZA,
                      ZA in degrees
		      In this type of solution, the 'data'
		      are taken as 1 over the raw data squared.
	     'PWRN':  as 'PWR ', but coefficients are
		      normalized before being printed/put in
		      history file.
             '    ' => 'POLZ'
  PRTLEV.....0 => Don't print the coefficients.
             1 => print the coefficients for each antenna,
                  IF and Stokes.
             2 => print coefficients and their errors and
                  rms of residual for each antenna, IF and Stokes.
	     If a second digit is included (e.g. '21' or '11'),
	       the coefficients are written in the form:
		G = Gm + G2*(ZA - Zm)^2; Gm = min. correction,
                Zm = angle of min. correction (= max gain).
  DOHIST.....if DOHIST > 0, the gain coefficients are written
	     into the history file.
  DOTV.......> 0 Do plot on the TV, else make a plot file
  GRCHAN.....Graphics channel 0 => 1.
  BADDISK....A list of disks on which scratch files are not to
             be placed.  This will not affect the output file.
----------------------------------------------------------------
ELINT:  Task to apply corrections to an CL table as a function
	of elevation or zenith distance.
Documentors: L.R. Kogan, B. Butler, R. Perley
Related Programs: CLCAL, SNPLT

                            PURPOSE

The widely used task CLCAL provides for the interpolation of antenna
gains measured on calibrators to the target sources.  The
interpolation is carried out as a function of time. If the elevation
difference between calibrator and target sources is large, (either due
to a large physical or time separation), significant errors can
result, especially at high frequencies where there is a strong
dependence of antenna gain on elevation.  The task ELINT will both
solve for the gain dependence on elevation, and will implement the
required corrections into an CL table.  In addition, ELINT will solve
for the flux densities of the calibrators used, assuming the flux
density of the first calibrator is known.
   The input data is an SN table obtained as a result of preliminary
calibration using a set of selected calibrators. The task fits a given
type of fitting function to these data.  This functional form is then
used to interpolate gain values for all sources. The fitting is done
independently for each antenna, each IF, and each polarization
(Stokes).
   The simplest mode of operation is to determine the gain dependence
using only a single calibrator whose elevation range matches or
exceeds that of the target sources.
   In many situations however, the elevation range covered by a single
calibrator is not sufficient, while that of all, or many calibrators,
is.  In this case, ELINT can solve for *both* the elevation gain
dependence, and the flux density ratios between the calibrators,
assuming the first-named calibrator is the flux density reference. It
then determines the corrected flux densities of the calibrators.
ELINT does *not* enter these new values into the SU table, however.
   The result of fitting can be displayed on the TV or recorded in a
plot file.  The average (for all selected antennas, IF's, and Stokes)
found voltage factors, (MEANFACTOR), original flux densities of
selected calibrators (FLUXOLD) and corrected flux densities of the
calibrators (FLUXNEW) are printed at display.  The determined
correction of the antennas' gain vs. elevation is written in an output
CL table for all selected target sources.
   The program fits a third order polynomial to the data.  The type of
fit is controlled by the OPCODE adverb: 'POLE' fits the amplitude
vs. elevation, 'POLZ' (the default) fits the amplitude vs. zenith
distance, 'PWR ' fits the power (1/amplitude*amplitude) vs. zenith
distance, while 'PWRN' normalizes these coefficients to maximum unity
gain.  At this time (Dec '96) only amplitude data are fitted -- others
are planned in the future.  The purpose of OPCODEs 'PWR ' and 'PWRN'
is to permit measurement of the power gain dependence, instead of
voltage gain correction.
   For testing purposes, we have implemented an OPTYPE command to
additionally fit for the opacity (following a law of the form
exp(-tau/cos z)) as well as the polynomial form described above.  This
is turned on by setting OPTYPE to 'AMPT'.  Use of this option is not
recommended -- it could only be useful in situations of high optical
depth (such as at the upper end of Q-band, or a soaking wet day at
K-band).  OPTYPE = 'AMPL', or ' ' is the normal mode.

   ELINT should be run as the initial step in calibration.  A
normal calibration sequence, using ELINT, would be:
   1) Do an opacity correction if you know the atmospheric opacity at
      the time (e.g., via use of the TIPPER function).  To do this,
      copy CL table 1 to table 2 (via TACOP), then run CLCOR, with
      OPCODE = 'OPAC', CLCORPRM(1) = zenith opacity in nepers.
      This step is optional, as ELINT can solve for the entire
      elevation dependence (both opacity and antenna dependent gain)
      but helps in certain cases.
   2) Run CALIB on one, or many calibrators.  If step 1 was
      done, make sure to set DOCALIB = 1;GAINUSE = 2.
   3) Run ELINT to determine the elevation gain.  If one
      calibrator alone covers the range of elevation, use just
      that one.  If many are required, use them all.  Put
      'SOURCES' equal to all your objects, both targets and
      calibrators (or leave blank).  CALSOUR(1) is your flux density
      standard.  ELINT will estimate the gain dependendence on elevation
      fitting the second order polynom to the input SN table data for
      each antenna and apply the corrections for the list of the sources
      to the output CL table.
      Examine the plots of the fits to convince yourself of their
      validity.
   4) Continue with normal calibration, using CALIB, GETJY,
      CLCAL, etc.  Be sure to apply the calibration when running
      CALIB!

	IMPORTANT!  If your phase stability is poor (phases changing
by near a radian within the calibrator scans) and the calibrators' SNR
is not high (this is a common combination), you should calibrate out
the phase gradients within each calibrator scan before solving for the
antenna gains.  To do this, generate a new default CL table with a
time interval as short as the timescale for significant phase changes
(this can be as short as 3 seconds -- in which case your visibility
integration time had better be as short !), and run CALIB, with
SOLMODE = 'P'.  Then CLCAL this with INTERPOL = 'SIMP' (for all
sources, including the calibrators) to remove these phase changes.
Then proceed as described above, with all CL tables incremented by one
(since CL#2 now contains the needed phase changes).
