; TARS
;--------------------------------------------------------------------
;! Simulation of Faraday rotation synthesis (mainly task FARS)
;# TASK ANALYSIS POLARIZATION
;--------------------------------------------------------------------
;;  Copyright (C) 2009-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
;-----------------------------------------------------------------------
TARS      LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
TARS:  Faraday rotation synthesis on simulated input data
INFILE                             Input file of the U,Q
                                   dependence on frequency.
OUTFILE                            Output file of the depedence
                                   on RM.
                                   BLANK=>OUTFILE is not created
APARM                              Parameters for algorithm:
                                     1 number of pixels at
                                       half of the Fourier
                                       transform output
                                       The whole number is
                                         2*APARM(1)+1
                                     2 cell size in 1/m^2
                                       0 =>
                                       PI/(4*(Lmax^2-Lmin^2))
                                       Lmax,Lmin-max,min lambda
                                       at the data
                                     3 0 => regular output
                                       1 => output is RMTF
                                     4 0=> CLEANed Fourier
                                           transform
                                       1=> unCLEANed Fourier
                                           transform
                                     5 0=>original(shifted back)
                                          RE/IM are sent out
                                       1=>the shifted RE/IM are
                                           sent out
                                       2=>amplitude and phase of
                                          the data are sent out
                                     6 Number of rows to use in
                                       INFILE
                                       0=> all rows in INFILE
                                     7 0=> convolve the clean
                                       components
                                       1=> no convolve
                                     8 0=> use the Gaussian as
                                           the convolve function
                                       1=> use the Re of RMTF as
                                           the convolve function
                                     9 full width of Gaussian
                                       convolve function, at 0.5
                                       level, in 1/m^2
                                       0 => fit to real RMTF
                                    10 what send to output?
                                       0 => sum of CLEAN and
                                            residual
                                       1 => CLEAN result
                                       2 => residual
GAIN                               Gain in the CLEAN
NITER                              Maximum number of clean
                                   components
FLUX                               Minimum flux of clean
                                   component (Jy)
OPCODE                             'CMPL' - new method Clean
                                   else peak amplitude Clean
----------------------------------------------------------------
TARS
Type: Task

      The task is for testing the result of Faraday rotation Synthesis
      (FARS)

Adverbs:
  INFILE......User-supplied text file giving Q (second column) and U
              (third column) as a function of frequency (first
              column).  A weight may be given in the fourth column.
              These cards determine the frequecies that will be used
              and their weights.  Default values for Q and U are 0
              while the default weight is 1.

              Model components (up to 20) may be added to the data
              contained in the cards described above.   If the first
              symbol is "M", then the following 3 numbers give the
              parameters of a model component: RM, in 1/m^2; AMP, and
              Phase in degrees.  The models are computed and added to
              the data given in the main data cards --- if you want no
              data added to the model, specify Q and U as 0.0 in the
              data cards.

              If the first symbol in a row is a semicolon, the row is
              skipped and acts as a comment.  The format of columns in
              INFILE is free with any number of blank characters
              between columns.

              The following is example of an INFILE with 2 components
              in a model and 3 of the N rows of data

         ; Input file for TARS With the top rows for model.
         ; The model rows are started with symbol M
         ; and includes RM in 1/m^2,  AMP and PHASE in Degrees
         ;    RM, 1/m^2    AMP        Phase, deg
         M     -600         5             60
         M     -800         3              0
         ;  FREQ, Hz         Q               U        weight
          1266000000     -3.6542873      -2.3332453      0.9
          1276000000     -5.0204344      -1.8241444      1.0
          1286000000     -4.3795457       0.393933       0.7

  OUTFILE.....The result of calculation of Faraday rotation synthesis
              is written to this file consist of 4 columns
                 1. the row number;
                 2. RM in 1/m^2
                 3. Amplitude (or Real, depending on APARM(5))
                 4. Phase (or Imaginary, depending on APARM(5))
              ' ' => results are directed to the message file and
                     message display
  APARM.......Parameters: the same as in FARS
               APARM(1) number of pixels at half of the Fourier
                        transform output.  The whole number is
                        2*APARM(1)+1 with zero at the center.
                        The value of APARM(1) should be chosen in
                        accordance of expected range of the Faraday
                        rotation measures and value of CELL (APARM(2))
               APARM(2) cell size of the outputs, in 1/m^2.  The cell
                        is recomended to be less or around the default
                        value (pi)/4/(lambda^2max - lambda^2min)
               APARM(3) 0 => regular outputs
                        1 => outputs are RMTF
               APARM(4) 0=> CLEANed Fourier transform, using inputs:
                            NITER, FLUX, GAIN. The CLEAN uses the
                            shifed (at lambda^2) data but the cleaned
                            components correspond to the original lambda^2
                            RE is recorded to the first output
                            IM is recorded to the second output
                        1=> the uncleaned Fourier transform is recorded
                            RE is recorded to the first output
                            IM is recorded to the second output
               APARM(5) 0=>original  data (RE and IM) are used at the
                           Fourier transform
                        1=> the shifted (to the center) data (RE, IM)
                            are used at the Fourier transform.
                            This option allows better discrimination
                            of different features at the Fourier transform.
                        2=> amplitude and phase of the data are sent out.
               APARM(6) Number of rows to use in INFILE
                        0=> all rows in INFILE
                        If the first symbol at the infile row
                        .EQ. semicolumn, this row is skipped.
                        THIS SEICOLUMN CONCEPT CAN BE USED FOR SELECTION
                        THE ROWS!
               APARM(7) 0=> convolve the clean components
                        1 => no convolve; So just the set of the clean
                             components is sent to the output files
                        No convolution is forced if:
                             uncleaned Fourier is sent out (APARM(4)=1)
               APARM(8) 0=> use the Gaussian as the convolve function
                        1=> use the Re of RMTF as the convolve function
               APARM(9) full width of the Gaussian convolve function,
                        at the 0.5 level, in 1/m^2.   0 -> fit the
                        real part of the RMTF.
               APARM(10) What send to the output?
                         0 => sum of CLEAN and  residual
                         1 => CLEAN result
                         2 => residual
  GAIN........Gain in the CLEAN
  NITER.......Maximum number of clean components 0 => 1
  FLUX........Minimum Clean component (Jy)
                 The task can subtract the given number of complex
                 components. On each iteration, the maximum (and its
                 position) of the spectrum amplitude is determined.
                 The complex function RMTF is multiplied by the
                 complex value of the spectrum at the position of the
                 found amplitude maximum and by GAIN.
                 The found function(production) is put by its median
                 on the position of found amplitude maximum, and is
                 subtracted from the having evaluated spectrum. The
                 process of the subtraction is terminated having
                 achieved number of iterations NITER or the flux
                 FLUX.
  OPCODE......'CMPL' invokes a (slower) true complex Clean rather than
                     the one that looks for the peak in the
                     amplitude.
              other - standard peak in the amplitude Clean.
----------------------------------------------------------------







