; CONFI
;---------------------------------------------------------------
;! Optimize array configuration by minimum side lobes
;# Task Calibration
;-----------------------------------------------------------------------
;;  Copyright (C) 1998, 2000-2003
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
CONFI     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
CONFI     Optimize array configuration by minimum side lobes
INNAME                             UV file name.
INCLASS                            Input UV file name (class)
INSEQ             0.0     9999.0   Input UV file name (seq. #)
INDISK                             Input UV file disk unit #
                                   The UV file is needed
                                   only to attach PL table
INFILE                             Filename of the data
                                   of initial configuration.
                                   Blank => the initial
                                   configuration is calculated
IN2FILE                            Filename of the topography
                                   mask.
                                   Include character sequence
                                   'FITS' in the file name
                                   if the IN2FILE is in
                                   FITS format.
                                   Used also as fixed positions
                                   of the two  and three circle
                                   configurations (see HELP)
CELL                               Size of the cell at mask,
                                   meters (x, y); 0 => 10m
XPARM                              BLC and TRC of selected part
                                   of the mask relatively
                                   the initial mask
                                   1. X of the  bottom left
                                      corner of the mask,
                                      in meters
                                   2. Y of the  bottom left
                                      corner of the mask,
                                      in meters
                                   3. X of the  top right
                                      corner of the mask,
                                      in meters
                                   4. Y of the  top right
                                      corner of the mask,
                                      in meters
                                   5. ALPHA the degree to
                                      (1/DIST) at the
                                      dependence of the gain
                                      on the distance
                                      ALPHA > 0 (see explain
                                      on APARM(2))
                                      0 => 1
OUTFILE                            Filename of the final
                                   configuration
                                   '' => no record a file
NPLOTS                             Number of plots of beam's
                                   pattern at the page.
                                   0 => 20.
DOTV             -1.0       1.0    > 0 Do plot on the TV, else
                                   make a plot file
APARM                              1. Number of iterations.
                                      0 => 1
                                   2. gain in the iterat. loop
                                      0 => 0.001
                                      <0 => GAIN = ABS(APARM(2)*
                                            (1/DIST)**ALPHA
                                      ALPHA=XPARM(5) > 0
                                   3. Number of elements at the
                                      array. 0 => 64
                                   4. Outer radius of optimizat.
                                      circle at the sky
                                      in main lobe size; 0=>20
                                   5. Step of the beam calculat.
                                      in main lobe size 0 => 0.2
                                   6. 0 => display configuration
                                      1 => not display it;
                                   7. Size of the array in km
                                   8. 0 => The configuration had
                                           been shifted
                                      1 => The configuration had
                                           not been shifted
                                   9. Inner radius of optimizat.
                                      circle at the sky
                                      in main lobe size;
                                   10.Sector of optimization
                                      in degrees. < 180 deg.
                                      0 => 180 deg.
BPARM                              1. 0 => beam maximum is found
                                        as maximum over 8
                                        surrounding pixels
                                      1 => beam maximum is found
                                        as maximum outside of
                                        RADMIN=APARM(9)
                                   2. Total number of plots of
                                      the beam pattern; 0 => 20
                                   3. 0 => auto scale beam plots
                                      otherwise: Min = 0
                                                 Max = BPARM(3)
                                   4. X-shift of configuration
                                      relatively BLC of mask, m
                                   5. Y-shift of configuration
                                      relatively BLC of mask, m
                                   6. Turn of configuration
                                      clockwise, degrees
                                   7. Number of steps in topogr.
                                      fitting, X, 0 => 50
                                   8. Number of steps in topogr.
                                      fitting, Y, 0 => 50
                                   9. Number of steps in topogr.
                                      fitting, Rotation,
                                      0 => 360/STEP
                                  10. Step in topography
                                      fitting of rot., degrees
                                      0 => 5
                                      see explain of BPARM(4-10)

CPARM                              Data to prepare the output
                                   file at UVCON format
                                   1. 0 => CONFI format
                                      1 => UVCON format
                                   The following CPARMs used
                                   only  if CPARM(1) = 1
                                   2. The site geodetic
                                      latitude, degrees
                                   3. The site geodetic
                                      longitude, degrees
                                   4. Antenna diameter, meters
                                      0 => 12
                                   5. Ant. efficiency, 0 => 0.5
                                   6. Antenna system temperature
                                      0 => 50K
                                   7. Number of levels of
                                      digitizer; 0 => 2 level
                                   8. 0 => no beam correction
                                           by the primary beam
                                      1 => yes beam correction
                                           by the primary beam
                                           The diameter of the
                                           antenna should be
                                           given at CPARM(4)
                                   9. The site height above
                                      the geoid, in meters
DPARM                              1. Initial configuration:
                                      0 => homogeneous
                                           circular array
                                      2 => two circles
                                      3 => three circles
                                      4 => hexagon tile
                                   2. Number of fixed antennas
                                   3. Constraints:
                                      0 => no constraint
                                      1 => constraint of topogr.
                                      2 => constraint of 2 circ.
                                      3 => constraint of donuts.
                                      4 => constraint topography
                                           and donuts
                                      5 => constraint topography
                                           and 2 circus
                                   4. 0 => input configuration
                                           is normalized to 1
                                      1 => input configuration
                                           is in meters
                                   5. 0 => Yes side lobes optim.
                                           No topography fit
                                      1 => No side lobes optim.
                                           Yes topography fit.
                                      2 => Yes side lobes optim.
                                           Yes topography fit.
                                           number of steps at
                                           fitting to topography
                                           BPARM(7,8,9) are
                                           forced to 1
                                   6. Output file mode:
                                      0 =>  normalized
                                      1 =>  in meters
                                   7. Minimum distance between
                                      elements, meters
                                   8. Inner radius of donut, in
                                      the outer diameter parts.
                                      radius of the 2nd circle
                                      if DPARM(1) =2, or 3.
                                      >0 => the circle is
                                      concentric
                                      <0 => the circle is inside
                                      tangent to the outer
                                      circle.
                                   9. radius of the third
                                      (innerest) circle
                                  10. number of additional
                                      elements at the outer
                                      circle. see explain.
----------------------------------------------------------------
CONFI
Type:   Task
Use:    This task optimizes the array configuration minimizing side lobes
Adverbs:
  INNAME.....Input UV file name (name).      Standard defaults.
  INCLASS....Input UV file name (class).     Standard defaults.
  INSEQ......Input UV file name (seq. #).    0 => highest.
  INDISK.....Disk drive # of input UV file.  0 => any.
             The input UV file actually does not participate
             in the calculating process. It is used only if DOTV<0
             as a file to attach the plot file. It is  a good idea
             to use the task TASAV to create the UV file with only
             one visibility.
  INFILE.....The name of a file where the initial array configuration
             is stored.
             X and Y of the array elements are given in decimal form.
             Twenty characters field is reserved for X and Y.
             Maximum 9(10) characters are given for the data part before
             decimal point and maximum nine character are given for
             the data part after decimal point (F20.9).
             For example:
             1234567890.123456789 -123456789.123456789
                -23.65             123.74
              2345789.564327          12345.896
             The file has not to have empty lines.
             If INFILE = '', then initial configuration is calculated
             as a homogeneous configuration on the circumference;
             as a configuration on the circumference with progressively
             increasing of the spacing;
             as a homogeneous configuration on the two circumferences; or
             as a homogeneous configuration on the three circumference;
             The calculated configuration is selected under control of
             DPARM(2).
  IN2FILE....Filename of the mask - restricted positions
             If the IN2FILE includes character sequence 'FITS' then
                the IN2FILE is interpreted as FITS format file
             else the file is interpreted as ASCII format file:
                Three columns at the file:
                1. Pixel number at X;
                2. Pixel number at Y;
                Y changes faster than X (Scan by Y for each new X)
                3. IND, restricted (IND=1) or not restricted (IND=0);
                Position of the given pixel in meters is determined
                by the two dimensional array CELL
                X, Y, IND should be located at one line and
                       given at the free format
                                    ^^^^^^^^^^^
             If topography constraint are not used (DPARM(5)=0) then
             this file is used  as positions of fixed elements
             at the outer circle when two and three circle configurations
             are used (DPARM(1)=2 or =3). INFILE is not used in this case.
             The position of the fixed elements at the outer circle are taken
             from IN2FILE (in meters). FORMAT is 2F20.9
             The rest positions in the outer circle and inner circles
             fill evenly the spaces between the fixed elements at the
             outer circle and in the inner circles.
             This is useful when the inner circle of A-configuration
             is the outer circle of B-configuration and so on.
             Then the pads of the A-configuration's inner circle
             can be used as part of the B-configuration's outer
             circle. So during optimization of B-configuration's
             these positions should be fixed.
             Positions of the fixed elements should be given in
             normalized form. If the bigger configuration is given in
             meters it has to be normalized:
                 Run CONFI with the following parameters to provide
                 the normalization: INFILE - the bigger configuration
                 in meters. APARM(7) diameter of the inner circle
                 of the bigger configuration (or that the same
                 the outer circle of the smaller configuration).
                 DPARM(4) = 1.
                 APARM(1) = 1. OUTFILE - the bigger configuration
                 in normalized form.
             Now extract the outer circle from the found configuration.
             It is the fixed part of the smaller configuration's
             optimization. Use it with DPARM(4) = 0.

             If you want to have fixed element in general case including
             topography, you have to:
                1. Use INFILE as input configuration.
                2. Consider the first DPARM(2) lines of INFILE
                   as the fixed antennas.
                3. Use IN2FILE as the topography mask if you want
                   to include the topography constraint (DPARM(5).NE.0)
  CELL.......Size of the cell at mask in X and Y, meters; 0 => 10 meter.
  XPARM......BLC and TRC of the selected portion of the mask relatively
             the initial mask
             1. X of the  bottom left corner of the mask, in meters
             2. Y of the  bottom left corner of the mask, in meters
             3. X of the  top right corner of the mask, in meters
             4. Y of the  top right corner of the mask, in meters
             5. ALPHA the degree to (1/DIST) at the dependence of
                the gain on the distance of the beam maximum from
                the beam center.
                ALPHA > 0 (see explain on APARM(2))
                0 => 1
  OUTFILE....Filename of the final configuration. The configuration
             corresponding to the lowest found side lobes is
             recorded to the file. The format of the file is
             identical with the format of the INFILE.
             So the OUTFILE can be used as INFILE for the following
             optimization
             Blank => no record to a file
  NPLOTS.....Number of plots of the beam pattern at the page.  0 => 20.

  DOTV.......> 0 Do plot on the TV, else make a plot file
  APARM .... 1. Number of iterations. 0 => 1
             2. gain in the iteration loop 0 => 0.001
                The required gain depends on the DIST - distance of the
                found beam maximum from the beam center.
                The more distance the less gain.
                Using negative APARM(2) you can introduce this dependence
                GAIN = ABS(APARM(2)) * (1/DIST)**ALPHA
                ALPHA=XPARM(5) > 0
                GAIN = ABS(APARM(2)) for DIST=1 for any ALPHA
                The recomended ALPHA is between 0.5 and 1.0
             3. Number of elements at the array
                Used if INFILE = BLANK.  0 => 64
             4. Radius of optimization circle at the sky, measured
                in main lobe size; 0=>20
             5. Step of the beam measured in main lobe size. 0 => 0.2
             6. 0 => display configuration; 1 => not display
             7. Size of the array in km; 0 => 1
             8. 0 => The configuration had been shifted.
                The shifted configuration is created during
                fitting in topography.
                1 => The configuration had not been shifted.
                APARM(8) does not have a sense if configuration
                is given in the normalized form.
             9. Inner radius of optimization circle at the sky
                in main lobe size; Practically this option is
                never used. So put APARM(9)=0!!!.
            10. Sector of optimization in degrees. < 180 deg.
                0 => 180 deg.
BPARM        1. 0 => beam maximum is found as maximum over 8
                     surrounding pixels.
                1 => beam maximum is found as maximum outside of
                     RADMIN=APARM(9)
             2. Total number of plots of the beam pattern. 0 => 20
                Each plot represents one cross section of the two
                dimensional beam at the range (-APARM(4), +APARM(4)).
                The maximum total number is APARM(4) / APARM(6).
                BPARM(2) allows to plot only some part of the all
                available cross sections of the two dimensional beam.
             3. 0 => auto scale of the beam pattern plots
                otherwise: Min = 0;  Max = BPARM(3)
             4. X-shift of configuration relatively BLC of mask, m
             5. Y-shift of configuration relatively BLC of mask, m
             6. Turn of configuration clockwise, degrees
             7. Number of steps in topography fitting, X, 0 => 50
             8. Number of steps in topography fitting, Y, 0 => 50
             9. Number of steps in topography fitting, Rotation,
                0 => 360/STEP
             !!!!! BPARM(7,8,9) are used onlyduring initial search
                   of the configuration to fit it to the topography
                   Use BPARM(7,8,9)=1 when you optimize the
                   configuration with topography constrain.
            10. Step in topography fitting of rot., degrees 0 => 5
                Step's value in X and Y is determined by CELL

                Look below the explanation of BPARM(4-10)

CPARM      Data to prepare the output file at UVCON format

            1. 0 => CONFI format;  1 => UVCON format.
               The following CPARMs used only if CPARM(1) = 1
            2. The site geodetic latitude in degrees
            3. The site geodetic longitude in degrees
            4. Antenna diameter, meters; 0 => 12
            5. Antenna efficiency; 0 => 0.5
            6. Antenna system temperature; 0 => 50K
            7. Number of levels of digitizer; 0 => 2 level
            8. make the beam correction by the primary beam?
               0 => no
               1 => yes
               The diameter of the antenna should be given at CPARM(4)
            9. The site height above the geoid, in meters
DPARM        1. Initial configuration:
                0  => The elements are distributed homogeneously
                      on the  circumference
                2  => The elements are distributed homogeneously
                      on two circumferences.
                      The radius of the outer circumference is 0.5;
                      The radius of the inner circumference is DPARM(8);
                      The number of elements on the circumferences
                      is proportional its radius.
                      See DPARM(10) for difference.
                3  => The elements are distributed homogeneously
                         on three circumferences.
                      The radius of the outer circumference is 0.5;
                      The radius of the intermediate circumference
                         is DPARM(8);
                      The radius of the inner circumference is DPARM(9);
                      The number of elements on the circumferences
                      is proportional its radius.
                      See DPARM(10) for difference.
                4  => hexagon tile. The number of the array antennas
                      given at APARM(3) should be equal:
                      7,19,37,61..= 3*NC^2 + 3*NC + 1; NC = 1,2,3...
             2. The first DPARM(2) antennas are fixed duaring optimization
             3. 0 => no constraint of the elements location
                In the case of a constraint initial configuration has
                to satisfy to the constrains: the elements should be
                in good topography points or inside the donuts...
                1 => constraint of topography
                2 => constraint of  two circles.	
                3 => constraint of donuts. The initial configuration
                     is automatically two circles also (DPARM(1) =2)
                4 => constraint both topography and donuts
                5 => constraint both topography and 2 circus
             4. 0 => input configuration is normalized to 1
                1 => input configuration is in meters
             5. 0 => Yes side lobes optimization. No topography fit.
                1 => No side lobes optimization. Yes topography fit.
                2 => Yes side lobes optimization. Yes topography fit.
                     In this case number of steps at the searching
                     of configuration fitting to topography are
                     forced to 1
             6. 0 => record normalized configuration in output file
                1 => record  configuration in meters.
             7. Minimum allowed distance between elements, meters.
                Initial configuration should satisfy the given minimum
                spacing. It is not simple in the case of some antennas
                being fixed. The routine OUTER provides insertion
                of the rest antennas in the outer circle. It inserts
                number of element between the neighbor fixed elements
                proportional to the relevant arc length. Such an algorithm
                does not follow the minimum spacing condition. Of course,
                it is simple to satisfy the minimum spacing condition
                using the step .GE. the given spacing. But in this case
                it can happen that all inserted elements will appear at
                the only interval what is not good. For small size array
                the routine outer add one element to the interval
                where the minimum spacing allows. If still there is a
                problem of minimum spacing, then it is necessary to
                diminish number of fixed elements and number of elements
                at the outer circle (DPARM(10)). It is useful to plot the
                initial configuration with very small spacing (DPARM(7)=1,
                APARM(1)=1)
             8. Inner radius of the donuts, in parts of the outer diameter
                If DPARM(1)=2 or 3, it is the radius of the second
                circle, starting from the outer circle.
                >0 => the circle is concentric;
                <0 => the circle is inside tangent to the outer circle.
             9. Radius of the third (most inner) circle, if DPARM(1)=3
            10. number of additional elements at the outer circle.
                Used if DPARM(1) = 2,3
                Useful for D MMA's configuration.
                It can be both positive or negative.
                The number of elements in the circumferences are
                calculated proportional to its radius.
                Then the number in the outer circumference is
                increased by DPARM(10);
                For the three circle configuration (DPARM(1)=3)
                    the number of elements in the intermediate
                    circumference is  decreased by (DPARM(10) + 1), and
                    the additional element is added at the center.
                For the two circle configuration (DPARM(1)=2)
                    the number of elements in the inner circumference
                    is decreased by DPARM(10)
--------------------------------------------------------------------
CONFI:  Optimizes the array configuration minimizing side lobes.
Documenters: L.R. Kogan

The task finds the array configuration which has the minimum worst
side lobes at the given circular area at the sky.
The initial configuration is taken from the file 'INFILE'. The data in
the file is arranged as two columns (2F20.10) for X and Y. They
can be normalized to unit maximum baseline or given in meters.
It is anticipated by DPARM(4).
The number of the array elements is determined by the reading
end of file. That is why the empty lines are not allowed in the file.
If INFILE = '', then initial configuration is calculated
     as a homogeneous configuration on the circumference;
     as a configuration on the circumference with progressively
        increasing of the spacing;
     as a homogeneous configuration on the two circumferences; or
     as a homogeneous configuration on the three circumference;
        The calculated configuration is selected under control of
        DPARM(2).
The last iteration is not necessary is the best one. That is why
the best configuration is stored and recorded to the output file
'OUTFILE' in normalized form (DPARM(6)=0) or in meters (DPARM(6) = 1).

If you want to plot(display) the found best configuration and relevant
beam's crossections, you need repeating the task with one iteration
(APARM(1)=1) and INFILE selected as the output file in the previous
iteration process.

The configuration is plotted (displayed) by "diamonds" and the relevant
UV coverage by dots.

The process of finding the configuration is an iterative process.
At each iteration the position and value of the worst side lobe in the
given sky area is found.  Then a small correction of each element position
is provided to minimize the value of the worst side lobe.
Side lobes' value both before and after optimization for each iteration
are printed for each iteration.
The worst side lobe for the given iteration will be suppressed,
but you'll see another side lobe at different position, which is definitely
bigger than minimized value of the previous iteration. Usually the value
of the new worst side lobe is less than this value of the previous iteration.
But sometimes it is not true especially if you select the gain (APARM(2))
two big.
The value and the direction of the correction is calculated in accordance
of the theory (L. Kogan, MMA memo # 171 ). The value is determined by the
product of the calculated shift and the gain (APARM(2)).
The value of the gain should be found empirically but has to be rather small.
If it is two small the task run too long. If it is too big the found new
worst side lobes will jump from iteration to iteration and convergence can
be missed. The compromise should be found empirically. For example if
the array elements number = 36, 0.0001 < APARM(2) < 0.01.

           		FITTING TO THE TOPOGRAPHY.

First of all the topography file IN2FILE should exist. The file have to
have the three columns:

             1. Pixel number at X;  I4
             2. Pixel number at Y;  I5
             3. Restricted (0) or not restricted (1);  I4
                The spacing between near pixels is determined
                by the two dimensional array CELL in meters.

The fitting consists of the three stage:

STAGE 1. Shifting and rotation of the configuration having found
         without constraints.

It is clear that the side lobes property in the given circular area
does not change if the configuration is shifted or rotated.
The initial guess for the shifting/rotation is determined by BPARM(4-6).
Steps in shifting is determined by CELL(2). Step in rotation is BPARM(10).
Number of steps in the searching is BPARM(7-9).
APARM(7) = the array's size.

You need to fix DPARM(3)=1; DPARM(5)=1 to invoke this option.

Use as INFILE the configuration found in a optimization without constraints.
The task provides the output file which includes X,Y coordinates
of the best fitted configuration.

If you are lucky to fit all elements of the array the following message
will be added at the top of the file:
"Configuration fitted topography is found"

If not, the number of unfitted elements and their coordinates will be added
at the top of the file.

The plot of the topography together with the best fitted configuration
is provided also.

To go to the stage #2, edit the output file shifting manually the unfitted
element to the nearest good topography place; do not forget to remove the
top messages.

Now having had the configuration which fits the configuration and
reasonably differ from the original optimized configuration you are
ready to optimize the configuration with the topography constraints.

STAGE #2 Optimization with the topography constraint.

Use as INFILE the edited OUTFILE found in stage #1.
BPARM(3), BPARM(4) should be equaled to the the found shifts.
BPARM(5) = 0. APARM(7) = the array's size. (the same as in stage #1)
DPARM(3) = 1; DPARM(5) = 2.
The greeting message:
"Configuration fitted topography is found" is appearing at the beginning,
because you started with the fitted configuration.
The process of the optimization and outputs will be identical to the
optimization under other constraints.

Stage #3. Check the result.

Use the OUTFILE of the stage #2 as INFILE.
DPARM(3) = 1; DPARM(5) = 1.
BPARM(3), BPARM(4) should be equaled to the the found shifts.
BPARM(5) = 0. APARM(7) = the array's size. (the same as in stage #2).
The task provides the plot of the topography with the found fitted and
optimized configuration.

All questions send to Leonid Kogan: lkogan@aoc.nrao.edu









