; UVMOD
;---------------------------------------------------------------
;! Modify UV database by adding a model or models
;# TASK UV ANALYSIS MODELING
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1997, 2001
;;  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
;-----------------------------------------------------------------------
UVMOD     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
UVMOD     Task which inserts a model into uv data
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 #
OUTNAME                            Output UV file name (name)
OUTCLASS                           Output UV file name (class)
OUTSEQ           -1.0     9999.0   Output UV file name (seq. #)
OUTDISK           0.0        9.0   Output UV file disk unit #
NGAUSS            0.0        4.0   Number of sources
CTYPE             0.0        5.0   Component type: 0 point, 1
                                   Gaussian, others see help
GMAX                               Peak value of sources
GPOS                               (X,Y) position in asec
GWIDTH                             (Major,Minor,PA) in
                                   asec,asec,deg
ZEROSP                             Zero spacing flux for (1) I,
                                   (2) Q, (3) U and (4) V in Jy.
FLUX                               Noise level in Jy/Weight.
FACTOR                             Multiplication factor.
QUAL                               If >0 then weights are
                                   reset to a value of 1.
----------------------------------------------------------------
UVMOD
Type: Task
Use: Modification of existing UV data by the addition of models.
Adverbs:
   INNAME.....Input image name (name).       Standard defaults.
   INCLASS....Input image name (class).      Standard defaults.
   INSEQ......Input image name (seq. #).     0 => highest.
   INDISK.....Disk drive # of input image.   0 => any.
   OUTNAME....Output image name (name).      Standard defaults.
   OUTCLASS...Output image name (class).     Standard defaults.
   OUTSEQ.....Output image name (seq. #).    0 => highest unique
   OUTDISK....Disk drive number of output image.  0 =>
              highest number with sufficient space.
   NGAUSS.....Number of sources 1 - 4.
   CTYPE......Type of each source: 1 Gaussian, 2 solid disk, 3 solid
              rectangle, 4 optically thin sphere, 5 exponential
              otherwise point.
   GMAX.......I polarization max of each source
   GPOS.......Offset value of the X,Y centroid of the sources in
              arcsec. Positive values mean increasing R.A. and DEC.
              These are offsets in the tangent plane and are applied
              with the W term taken into account (as of 1997-04-16).
   GWIDTH.....Model major and minor axis in arcsec and PA in degrees.
              Full width or full width to half maximum (GAUS).
   ZEROSP.....Zero spacing flux of (2) Q, (3) U and (4) V in Jy used
              with the first source only.
   FLUX.......Noise level to be added (in Jy. per Weight).
   FACTOR.....Factor by which original data are multiplied before they
              are added to the model.  If FACTOR = 0 then only the model
              will be left.
   QUAL.......If QUAL > 0 then all Weights will be set to a
              value of 1 in the output file.
----------------------------------------------------------------
UVMOD: Task which modifies UVDATA by scaling the existing data,
       and adding a specified model (See also IMMOD).
DOCUMENTATION: Eric R. Nelson NRAO/VLA/UNM
DATE OF DOCUMENTATION: 14 JUNE 1983
RELATED PROGRAMS: IMMOD, UVMAP, APCLN, COMB

                  PURPOSE

     UVMOD modifies an already existing UV data file by the addition of
one of several model types.  The original data may be scaled by a
multiplicative factor, including negative values and zero, before they
are added to the model.  Random noise may also be added to the UV data.
The program could be useful in investigating the affects of CLEAN on a
specific geometry, or for removing models from data, i.e. planetary
disks.

     The five available models to choose from are 1) point source, 2)
Gaussian, 3) solid disk  4) solid rectangle, and 5) optically thin sphere..
These models are first Fourier transformed and then added to the UV
data.  The resulting functions are:

          1) Point -> A constant visibility amplitude is added to the
                      data.  The GWIDTH adverbs have no affect on this
                      model.

          2) Gaussian -> The function EXP(-3.559707*R**2) is added to
                      the UV data.  The function R is given by:
                         R = Sqrt(UU**2 + VV**2) where
                         UU = BMAJ*(V*COS(BPA)+U*SIN(BPA))
                         VV = BMIN*(U*COS(BPA)-V*SIN(BPA))

          3) Disk ->  The function J1(R)/R is added to the UV data,
                      where J1 is the Bessel function of order 1 and R
                      is the same as above.

          4) Rectangle -> The function SINC(UU)*SINC(VV) is added to
                      the UV data, where SINC(X) = SIN(X)/X.  UU and
                      VV are defined as above for the Gaussian.

          5) Sphere -> The function (SIN(A)/A - COS(A)) / (A*A) is
                      added to the UV data where
                         A = BMAJ * Sqrt (U*U + V*V)
                         A = max (A, 2 pi / 100)
                      The GWIDTH adverbs have no affect on this model.

          6) Exponential -> 'EXPD'
                      The function 2 Pi / (1 + a * a * R * R) ** 3/2
                      is added to the UV data where R is defined in 2
                      above and a is Pi/ln(2).

Note that all functions are scaled by the total flux and a complex
vector representing the phase of the model before being added to the
scaled input visibility data.

BMAJ, BMIN, BPA :

     In this discussion, BMAJ = GWIDTH(1,i) for the i'th component,
BMIN = GWIDTH(2,i) for the i'th component, and BPA = GWIDTH(3,i) for
the i'th component,  The dimensions of the resulting functions are
determined by BMAJ, BMIN and BPA (position angle).  For the Gaussian
the first two values are the FWHM of the two axis.  For the Disk and
the Rectangle, the first two values are the absolute dimensions of the
two available axis.  If BMAJ and BMIN are both zero then all the
models reduce to the point model.

ZEROSP:

     This adverb, array indices 2-4, allows you to add polarization to
the first model component only.

FACTOR :

     The FACTOR term allows one to add a scaled version of the
original data to the model.  FACTOR is simply multiplied by the
original data which is then added to the model.  If FACTOR = 0, then
only the model will remain in the final UV data base.
