; UVMAP
;---------------------------------------------------------------
;! makes images from calibrated UV data.
;# Task AP Imaging
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1999, 2019
;;  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
;-----------------------------------------------------------------------
UVMAP     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
UVMAP:  Task which makes a map from UV data on disk
INNAME                             Input UV data (name)
INCLASS                            Input UV data (class)
INSEQ                              Input UV data (seq. #)
INDISK                             Input UV data disk drive #
CHANNEL          0.0     3000.0    Freq. channel (0 for cont.)
NMAPS            0.0         8.    # freq chan. to map (max=8)
OUTNAME                            Output image name (name)
OUTDISK                            Output image disk drive #
OUTSEQ          -1.0    32000.0    Output seq. no.
STOKES                             Stokes parameters (see HELP)
                                   Use 'LINE' for spectral line
IMSIZE         32.       4096.     Image size (X,Y) is pixels
CELLSIZE      1.E-12               (X,Y) size of grid in asec
SHIFT                              (X,Y) image shift in asec
UVTAPER         0.                 (U,V) gaussian taper
                                     units are kilolambda
UVRANGE         0.                 Min & max baseline (klambda)
UVWTFN                             UV dist. weight function
                                     blank => uniform
UVBOX           0.        128.     Additional rows and columns
                                   used in weighting. Use 0.
DOGRIDCR       -1.          1.     Correction for gridding?
DOTV           -1.          1.     Use TV?  > 0 -> yes.
ZEROSP                             0-spacing fluxes and weights
XTYPE           0.         10.     Conv. function type in x
                                     default spheroidal
YTYPE           0.         10.     Conv. function type in y
                                     default spheroidal
XPARM                              Conv. function parms for x
YPARM                              Conv. function parms for y
GUARD          -1.          0.9    x,y guard band fractional
                                   radius
BADDISK                            Disk drive #'s to avoid
----------------------------------------------------------------
UVMAP
Type:  Task
Use:   Fourier Transform UV data from a disk file to make
       catalogued images.  Several images can be made with one
       execution.  Now writes REAL format output images.
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.
  CHANNEL....Frequency channel to map (1 relative)
             Use 0 for (pseudo)continuum data.
  NMAPS......Number of frequency channels to map.  0 => 1.
             Maximum = 8.
  OUTNAME....Output image name (name).      Standard defaults.
  OUTDISK....The disk drive # of output images.  0 => highest
             with space (note: I and Beam go on same disk,
             Q and U go on same disk but may not be same on 0)
             Note:  OUTCLASS='XYYY'
             where X=Stokes, YYY=IM001 or BM001
  OUTSEQ.....Output sequence number. 0 => highest unique.
  STOKES.....Make images with these STOKES parameters
             blank =>I,B            'I'   =>I,B (B=beam)
             'IQU' =>I,Q,U,B        'IV'  =>I,V,B
             'IQUV'=>I,Q,U,V,B      'RL'  =>R,L,B
             'LINE'=> Spectral line I polarization
             'RLIN'=> Spectral line right circular poln.
             'LLIN'=> Spectral line left circular poln.
  IMSIZE.....(X,Y) image size in pixels.
             Must be a power of 2 on each side from 32X32
             to 4096X2048
  CELLSIZE...(X,Y) pixel separation in asec.
  SHIFT......(X,Y) shift of map center from phase center in asec.  Map
             center = Phase center + shift. If X>0 & Y>0, source shifts
             to south-west (down & right).  Units are arc sec at the
             initial coordinate in RA and Dec (if unrotated).
  UVTAPER....(U,V) gaussian taper (kilolambda) at 30% level
  UVRANGE....(Minimum,Maximum) baseline (kilolambda) in map.
  UVWTFN.....Weighting function of (u-v) place.
             blank=>Uniform; 'NA'=>Natural
  UVBOX......(U,V) box size for smoothing.  See HELP UVBOX
  DOGRIDCR...Apply gridding correction in maps? > 0 => yes.
  DOTV.......Display UV coverage on the TV?  > 0 => yes.
  ZEROSP.....Zero-spacing value of I,Q,U,V,Weight or
             R,L,-,-,Weight.
  XTYPE......Convolution function type in X-direction
             1=Pillbox, 2=exponential, 3=Sinc, 4=Exp*Sinc,
             5=Spheroidal, 6=exp*BESSJ1(x)/x.
              <= 0 or > 5  -> 5.
  YTYPE.....Convolution function type in Y-direction
  XPARM.....Array containing parameters for XTYPE.
            See HELP UVnTYPE when n=convolution type.
            If STOKES='RL' or 'L' and XPARM(9) = 1.0, then
            the Lmap is made with freq = catfreq + XPARM(10)
            where units are Hz (for pseudo-cont line data).
  YPARM.....Array containing parameters for YTYPE.
  GUARD.....Fraction of the x and y radius for which uv samples
            are not allowed.  < 0 => just enough to avoid
            mathematical errors in the convolution.
            0 => 0.3 * SQRT(taper weight at 0.3 from edge).
  BADDISK...Disk drive #'s to avoid for scratch files
----------------------------------------------------------------
UVMAP:  Task which makes a map from UV data on disk using AP
DOCUMENTOR: T.J.Cornwell NRAO/VLA
RELATED PROGRAMS: UVLOD,UVSRT,APCLN,IMAGR,CALIB

                          PURPOSE

     UVMAP makes dirty maps and beams from (u,v) data using a
Fast Fourier Transform (FFT).  The data must be in the 'XY'
sorted order produced by UVSRT so that gridding requires minimum
core storage.  The data are then convolved onto the regularly
spaced grid which is used for the Fourier transform.  Maps of
several Stokes parameters, and a beam, can be made with one
execution.
     A fairly complete description of the functions performed by
UVMAP is given in Lecture 2 of the Proceedings of the NRAO-VLA
Workshop on Synthesis Mapping.  Observers who are unfamiliar
with interferometry are recommended to study this volume.

                         COMMENTS

CHANNEL, NMAPS:
     Use 0.  These keywords will be used with real spectral line
data bases.

OUTDISK :
     If OUTDISK = 0, the map and beam will be put on the same
disk.  The Q and U maps may be put on another disk.  It is best
to specify OUTDISK.

IMSIZE,CELLSIZE :
     For effective CLEANing of the maps, the number of pixels
per beam should be such that the pixel value immediately north
or east of the beam center is no less than about 50% of the
peak.  In the gridded data (shown on the TV if DOTV=1) the
furthest point from the corner should be no more than 1/4 of the
full gridsize.  However, if tapering is used, the outlying (u,v)
points may not have any significant weight in the map.
Furthermore, the CLEAN algorithm in APCLN will only CLEAN
correctly a quarter of the map so that the dirty map size should
be at least twice the size of the area to be CLEANed.
     The map should also be made large enough that no strong
confusing sources are aliased by the FFT.  Aliased sources or
aliased sidelobes will not CLEAN properly and will limit the
fluctuation level on your final map.
     UVMAP will make maps which have a power of two pixels on
a side; between 32 and 4096 on the X-axis and between 32 and
2048 on the Y-axis.

STOKES :
     When only the Stokes parameter I is requested, all parallel
hand data are used.  When multiple Stokes parameter maps are
made only the records which contain all necessary correlators
are included and hence only one dirty beam is necessary.  When
CLEANing be careful not to mix up dirty beams made with Stokes I
and with other Stokes combinations.
     If you do not expect your source to show significant
circular polarization, as is normally the case with galactic
and extragalactic continuum sources, making a V map can be a
useful diagnostic for calibration problems, correlator offsets,
etc.  The V map should be a pure noise map close to the
theoretical sensitivity if your data base is well calibrated
and edited.

UVWTFN :
     The default uniform weighting option gives higher
resolution than natural weighting.  However, uniform weighting
gives a signal to noise ratio that is about 30% lower.  Natural
weighting is therefore preferable for detection experiments.
With uniform weighting the dirty beam size decreases slightly
with larger maps, other parameters remaining unchanged.

ZEROSP :
     To improve CLEANing of extended sources, the zero-spacing
flux should be included in UVMAP.  The weight assigned should
normally be in the range 10-100 but you may need to experiment,
as the optimal value depends on your (u,v) coverage.  Inclusion
of the zero-spacing flux will allow CLEAN to interpolate into
the inner region of the (u,v) plane more accurately, provided
that this flux does not exceed the average visibility at the
short spacing by too much.  You must also CLEAN deeply to derive
the full benefit of this (see the EXPLAIN file for APCLN).
     Jacqueline van Gorkom claims that the only proper weight
for the zero spacing flux density is the number of cells
missing in the center of the uv plane as long as the zero
spacing flux density doesn't greatly exceed the amount
observed on the shortest baselines.

UVBOX :
     Using UVBOX not equal to zero should, to some extent,
suppress sidelobes due to unusual fluctuations in the u,v plane
sampling such as occurs at the end of a long track, or in
snapshots.

XTYPE,YTYPE :
     The default convolution function Spheroidal (5) is now
recommended for nearly all maps. This replaces the  default
function EXP*SINC (4) used prior to the 83jul15 version.

SPECTRAL LINE :
     When making spectral line map from pseudo-continuum data
the user may want to correct for the frequency difference
between the channels stored in the R and L IF slots. At the
moment this information is not stored in the header and so must
be inserted by hand. To do this set XPARM(9) to 1.0 and set
XPARM(10) to the channel spacing in HERTZ.

EXECUTION TIMES :
     Typical execution times for running UVMAP in an otherwise
empty VAX 11/780 with FPS120B array processor are :

           Time in minutes
    4.0 * (D/500,000) **1.0                          Get data
    1.8 * (D/500,000) **0.5  * (M/1024) **0.3       Grid data
    2.0 * (M/1024)    **2.1                            Do FFT
    2.0 * (M/1024)    **2.0                        Write maps
where M is the map size and D is the number of visibility
points.  Generally two maps (map and beam) are made with each
execution.

DISK SPACE :
     The amount of disk space allocated for the following maps
is :
               256 x 256       256 blocks
               512 x 512      1024 blocks
              1024 x1024      4096 blocks
              2048 x2048     16384 blocks

                       REFERENCES

    Proceedings of the NRAO-VLA Workshop on Synthesis Mapping
1982, ed. A.R.Thompson and L.R.D'Addario.
