; IMAGRPRM
;---------------------------------------------------------------
;! Specifes enhancement parameters for OOP-based imaging
;# ADVERB IMAGING OOP
;-----------------------------------------------------------------------
;;  Copyright (C) 2002-2003, 2008-2009
;;  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
;-----------------------------------------------------------------------
IMAGRPRM  LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
----------------------------------------------------------------
IMAGRPRM
Type: Adverb  (array(20))
Use:  To specify correction and other "enhancement" parameters to
      IMAGR .  See EXPLAIN IMAGR for further discussion.

IMAGRPRM(1) If > 0 then make frequency dependent primary beam
     corrections assuming an antenna diameter of IMAGRPRM(1) meters.
     Can change with TELL which only makes sense if you are going to
     repeat the subtraction with a filtered set of components (see
     IMAGRPRM(8)).  Note that VLA and ATCA arrays (TELESCOPE header
     parameter) use the default primary beam parameters defined
     elsewhere in AIPS, while other antennas actually use IMAGRPRM(1)
     as the diameter of a "standard" telescope.  Usage affected by
     FQTOL adverb as well.

        (2) Visibility amplitudes will be corrected to the average
     frequency assuming a spectral index of IMAGRPRM(2).  Note: the
     typical optically thin synchrotron spectral index is about -0.7.

        (3) If > 0, then the u,v and w terms are scaled by IMAGRPRM(3)
     before imaging.

        (4) If > 0, then SDI Clean will be used when the fractionof
     residual pixels in the Clean boxes stronger than half the maximum
     residual exceeds IMAGRPRM(4).  <= 0 -> never use or allow SDI
     Clean.  Can change with TELL. If SDI Clean is enabled, the output
     CC files will have been merged.

        (5) If > 0 then scaling of residuals is requested and

        (6) Half-width in x of box to determine the dirty beam area
     (default = 5)

        (7) Half-width in y of box to determine the dirty beam area
     (default = 5)  Can change (5)-(7) with TELL.

        (8) If non-zero, select only those Clean components having >
     ABS(IMAGRPRM(8)) Jy within a radius of IMAGRPRM(9) cells of the
     component.  If IMAGRPRM(8) < 0, the abs value of the flux near
     the component is used.  This is an optional filter to remove weak
     isolated components which can cause a significant bias.  Can
     change with TELL but only if it was non-zero to begin with.  A
     copy of the input data has to be made for this option and it is
     only made if IMAGRPRM(8) is non-zero.  If this option is
     selected, the output CC files will have been merged.  Note that
     IMAGRPRM(8) should always be <= 0 for images of Q, U, and V
     Stokes parameters since negative brightnesses are valid.
     Filtering is done on restarts, when requested from the TV, on
     certain Cleaning failures, on normal completion (after which the
     task resumes Cleaning until the completion points such as NITER
     and FLUX are reached a second time) and on final exit.  If
     ALLOKAY >= 2, the filter is not applied on the restart.  If the
     filtering option was selected at the start (IMAGRPRM(8) non
     zero), it may be turned off by setting IMAGRPRM(8) exactly 0 and
     running TELL.  To delete all negative regions, set IMAGRPRM(8) to
     a tiny positive number.

        (9) abs (IMAGRPRM(9)) is the radius in cells for the area in
     which fluxes are computed.  If IMAGRPRM(9) < 0, the Clean will
     restart following the "final" filtering on the assumption that
     the filter will have changed things enough that the residual will
     be > FLUX for example.  abs (IMAGRPRM(9)) < 1.1 => 3.1.
     Can change with TELL.

       (10) = multiplier of max image size to set beam size.  Values
     of 2, 1, 0.5, and 0.25 are allowed.  0 => 2.  Smaller beam images
     are a bit faster, but less accurate in the early Clean cycles.
     The largest beam image used is 2048 on a side except when
     IMAGRPRM(1) > 0.75.  When IMAGRPRM(10) is 1, the limit is 4096
     and when IMAGRPRM(10) > 1.5, the beam is twice the image size
     limited by 32768.

     Multi-scale experimental controls are based on
            BeamRatio = (field beam area) / (min beam area)
     See below for more discussion.

       (11) Multi-scale experimental control: select which field
     to Clean using peak fluxes (in Jy/beam) weighted by
     1 / (BeamRatio)**IMAGRPRM(11).  This is the most important
     multi-scale control.  Set it so that all scales have about an
     equal chance of being selected.

       (12) Multi-scale experimental control: decrement the value
     of IMAGRPRM(11) used above by IMAGRPRM(12) each time an non-point
     resolution field is Cleaned until it is 0.

       (13) Multi-scale experimental control: use gain =
     GAIN * [ {1/BeamRatio} ** IMAGRPRM(13) ]

       (14,15) Multi-scale experimental control: use
     factor = FACTOR + IMAGRPRM(14) * [ 1 - {BeamRatio} ** IMAGRPRM(15) ]

       (16) Multi-scale experimental control: use maxpixel
     = MAXPIXEL + IMAGRPRM(16) * (BeamRatio)

       (17) 1 => use a spectral-index image represented inIN3NAME,
    IN3CLASS, IN3SEQ, IN3DISK below to correct the Clean component
    model for each channel.  IN4NAME et al will also be used as a
    curvature image iff IN3NAME are specified.  IMAGRPRM(17)-0.5 is
    used as a radius in pixels over which the spectral index image is
    averaged.  When it is small (0 < IMAGRPRM(17) <~ 1), the spectral
    index is interpolated rather than averaged.  See FQTOL below as
    well.  When doing spectral index, the primary beam correction
    (IMAGRPRM(1)) costs very little extra.

       (18) In OVERLAP>=2 mode, when imaging multiple fields, IMAGR
    grid and FFT multiple fields in an attempt to determine the next
    one to Clean.  Multiple fields are done to reduce I/O in this
    search which may otherwise have to re-read the work file several
    times to find the next field to Clean.  The limit on the number of
    fields done depends on the maximum size of the AP, the size of the
    images, etc - trying to guess when I/O will be expensive in time.
    Sometimes, IMAGR will make more images than are needed at a
    subsequent excess cost.  To limit the number of fields imaged at
    any one try, set IMAGRPRM(18) to the maximum number you want to
    allow.

       (19) In OVERLAP>= 2 mode, when Cleaning a field with a small
    bright source, it is possible to Clean too deeply.  Then weak
    lumps due to sidelobes of strong sources in other fields are
    treated as sources in the present field.  By the time the present
    field is Cleaned again, these errors become very apparent.  This
    parameter is used to limit the weakest source Cleaned in this
    major cycle to IMAGRPRM(19) times the strongest source in this
    cycle.  The default is the sum of the maximum sidelobe outside a
    radius of 5 pixels and the maximum sidelobe outside a radius of
    MINPATCH pixels.

       (20) In OVERLAP >= 2 mode, the objective function of the
    selected field after it is re-imaged is compared to the objective
    function of the second best field (without re-imaging).  If the
    second best now appears better than the selected field by a
    factor greater than IMAGRPRM(20), then the task will try another
    field. 0 = 1.005.  (Values < 1 are converted to 1/IMAGRPRM(20)
    and, finally, values > 5 => 1.005.)

The MS Clean is an experimental algorithm and has been provided with a
number of "knobs" to adjust its behavior.  All the knobs use the ratio
of the current beam area (BMAJ(field)*BMIN(field)) to the minimum beam
area (R).  These knobs are:

    1. Show some preference to select higher resolution images (lower
       R) for the next image to Clean.  Otherwise a strong point with
       some extended emission will be over Cleaned at low resolution,
       forcing higher resolutions to correct many pixels:
          IMAGRPRM(11) select which field to Clean using peak fluxes
          (in Jy/beam) weighted by 1 / R**IMAGRPRM(11).

    2. Reduce this preference to zero as one Cleans more and more of
       the R > 1 fields:
          IMAGRPRM(12) decrement the initial value of IMAGRPRM(11)
          used above by IMAGRPRM(12) each time an R > 1 scale
          field is Cleaned until it is 0.

    3. The lower resolution fields may easily over Clean creating zero
       net flux from a mix of negative and positive areas.  These then
       have to be corrected with numerous high resolution Clean
       steps.  To use a lower loop gain for lower resolution:
          IMAGRPRM(13) use gain = GAIN / R ** IMAGRPRM(13)

    4. To avoid over Cleaning with lower resolution, one may also
       Clean each major cycle less deeply with the FACTOR parameter.
       To control FACTOR:
          IMAGRPRM(14,15) use
             factor = FACTOR + IMAGRPRM(14) * (1 - R ** IMAGRPRM(15))

Multi-scale experimental control limits:
    0 <= IMAGRPRM(11) <= 1.0    not changed by TELL     Try 0.5
    0 <= IMAGRPRM(12) <= 0.1    changed by TELL         Try 0.03
    0 <= IMAGRPRM(13) <= 1.0    changed by TELL         Try 0.5
    0 <= IMAGRPRM(14) <= 1.0    changed by TELL         Try 0.1
    0 <= IMAGRPRM(15) <= 1.0    changed by TELL         Try 0.5
Note that IMAGRPRM(11-15) = 0 causes each Clean to be done on the
field with the highest Jy/point-source-beam with the same GAIN and
FACTOR.

IMAGRPRM(11) is important, (12)-(16) can be left 0.0 usually.

Tasks:
    IMAGR.....Wide-field and/or wide-frequency Cleaning / imaging
              task.
----------------------------------------------------------------
