; APVC
;---------------------------------------------------------------
;! Deconvolves images with van Cittert algorithm
;# Task Imaging AP
;-----------------------------------------------------------------------
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
APVC      LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
APVC :  Task which deconvolves by a generalized van Cittert iter
                                   Dirty image
INNAME                                Image name (name)
INCLASS                               Image name (class)
INSEQ              0.0      9999.0    Image name (seq. #)
INDISK             0.0         4.0    Image disk drive #
                                   Beam image
IN2NAME                               Image name (name)
IN2CLASS                              Image name (class)
IN2SEQ             0.0      9999.0    Image name (seq. #)
IN2DISK            0.0         4.0    Image disk drive #
                                   Deconvolved image
OUTNAME                               Image name (name)
OUTCLASS                              Image name (class)
OUTSEQ             0.0      9999.0    Image name (seq. #)
OUTDISK            0.0         4.0    Image disk drive #

DOTV              -1.0         1.0 TV display of residuals?
NBOXES             0.0        10.0 Number of boxes
BOX                0.0      4096.0 Four coordinates for each box
GAIN               0.0             VC loop gain, try 0.5
NITER              0.0     32767.0 Maximum # of iterations
PHAT              -1.0      1000.0 Stabilized smooth param.
                                   Try 0 to 0.05
OPCODE                             Iteration type. Try 'TL','WT'
                                   'VC','PC' or 'ST'. Prefix
                                   with '+' for positivity
                                   constraint.
APARM                              Use varies according to
                                   algorithm. See explain.
BADDISK           -1.0      1000.0 Disks to avoid for scratch.
----------------------------------------------------------------
APVC
Type: Task
Use: APVC deconvolves the dirty beam from the dirty map thus
producing a map with the units of brightness (Jy/pixel).
Conversion to other units e.g. KELVIN can be done with
AXDEFINE. APVC  may be restarted if further improvement is
desired. This program is slow but should be comparable to
APCLN if the map contains many picture elements. The task
CONVL may be used to convolve the map to the resolution
produced by a CLEAN program.

     This is a rather experimental and ad hoc task, but in some
limiting cases it reduces to the standard CLEAN algorithm
(though it would be impractically slow) and to the classical
van Cittert iteration.

Adverbs:

   INNAME,INCLASS,INSEQ,INDISK.......Specification of the dirty
map. Standard defaults apply.

   IN2NAME,IN2CLASS,IN2SEQ,IN2DISK...Specification of the dirty
beam. Defaults will depend on dirty map spec.

   OUTNAME,OUTCLASS,OUTSEQ,OUTDISK...Specification of the output
deconvolved map, in units of Jy/pixel. Standard defaults, with
the output class being 'xVC', 'x' being I,Q,V,U,L or R,
depending on the polarization of the dirty map. The algorithm
can be restarted by putting the FULL specification of the
partially deconvolved map into OUTNAME, etc. In this case, the
output will overwrite the partially deconvolved image.

   DOTV..............................Display each iterration on
the TV channel 1. If true, you may stop the iterating with TV
button D after each VC map is displayed. Default is no display.

   NBOXES............................The number of rectangular
boxes, as with APCLN. The VC image is non-zero only within these
boes. Default is 1.

   BOX...............................A 4x10 array with the BLC
and TRC of each box. 0 implies use one box only, which is the
inner quarter of the map.

   NITER.............................Number of iterations to
perform.  Default is 20 (usually 15-30 is adequate).

   GAIN..............................Loop gain. The loop gain
is scaled by the volume of the main lobe of the dirty beam, and
consequently quite high gains apply (typically 0.2-5). Default
is 0.5.

   PHAT..............................Cornwells smooth
stabalizing parameter. Use 0 to 0.1. Default is 0.

   OPCODE............................This dictates the actual
iteration scheme used. Default is 'VC'. Possible values are:
 'VC'  Van Cittert iteration.
 'TL'  Cornwells Tunnel iteration.
 'ST'  Steers CLEAN-like iteration.
 'WT'  "Weighted" iteration. See EXPLAIN.
 'PC'  "Percent" iteration. See EXPLAIN.
Additionally each of the above can be prefixed by a '+'
(e.g. '+VC') which enforces a positivity contraint on the
estimate.

   APARM.............................A hotch-potch of
extra parameters which dicate the actual iteration scheme.
Sensible defaults apply. See EXPLAIN.

   BADDISK...........................Bad disks to avoid.

---------------------------------------------------------------

Schemes:
========

     The van Cittert iteration consists of the 2 steps:
 1) Estimate a correction to add to the current map
estimate, by multiplying the residuals by some weight.
In the classical van Cittert algorithm this weight is
a constant, where as in CLEAN the weight is zero everywhere
except at the peak of the residuals.
 2) Add the step to the current estimate, and subtract the
estimate, convolved with the dirty beam, from the residuals.

Though it is a simple algorithm, it works well (if slowly) for
cases where the dirty beam is positive semi-definite (as it is
in astronomy). The basic idea is that the dirty map is a pretty
good estimate of the deconvolved map.

The different iterations vary only in the weight to apply to
each residual in determining the correction step.
Assuming that EST is the map estimate, RES is the residuals, and
nppbeam is, roughly, the volume of the central lobe of the dirty
beam, then the correction step is given by:

             gain/nppbeam*RES*WT

and WT is:

1. Tunnel Algorithm
     WT = (offset+EST**2/(EST**2+(resrms/nppbeam)**2))

2. Van Cittert Algorithm
     WT = 1

3. Steer ('ST')
     WT = 0     if RES < resmax*trim
        = 1     otherwise

(NOTE If trim is 1, then Steer degenerates to a slow CLEAN)

4. Percent ('PC')
     WT = (alpha + (1-alpha)*(RES/resmax)**2)*
            (RES**2/(RES**2+epsi*resrms**2)

5. Weight ('WT')
     WT = alpha*(RES/resmax)**2+(1-alpha)*(EST/estmax)


If the positivity constraint is being applied, then the
correction step is clipped to ensure that the resulting
estimate remains positive.

Iteration Parameters:
====================
Extra parameters required by each scheme (e.g. alpha, epsi,
offset, etc) are given in APARM. Their order and defaults are
given below. Defaults are taken in the entered parameter is less
than of equal to zero.

  Variable  Entered       Scheme    Default   Typical

  Nppbeam   APARM(1)       all      Varies     30-50
  Alpha     APARM(2)      WT,PC      0.5        0-1
  Offset    APARM(2)      TL         0          0-0.1
  Trim      APARM(2)      ST         0.8        0.4-1
  Epsi      APARM(3)      PC         4          2-10

Determining Nppbeam:
====================

The Nppbeam parameter (number of points per beam) is a rough
estimate of the "gain" of the beam, and this will vary according
to the algorithm used and the type of structure in the map (i.e.
extended or point-like). The peak of the transform of the
beam will be correct when observing a particular sinusoid.
Though this estimate is strictly to ensure that ALL (even
pathological) cases converge, in practice it is far too
conservative. A smaller value is more appropriate.
If observing noise, then the rms of the transform of the beam is
roughly the gain factor, but this is probably too small an
estimate, especially when there is extended structure. When
observing point sources, and using the Steer algorithm, a value
slightly bigger than 1 is appropriate, whereas when observing
structure about the same size as the beam, then the volume of
the main lobe is a good estimate. This is approximately given
by 1.1331*FWHM*FWHM/CELLSIZE**2.
    If this parameter is allowed to default, then APVC will
calculate the peak and rms of the transformed beam, and take
Nppbeam as the geometrical mean of these. Typically when
the u-v plane is well sampled, the peak of the transformed
beam will be 100-200 and the rms about 5-10, giving a Nppbeam
of the order of 30-40.
---------------------------------------------------------------
