; UVSIM
;---------------------------------------------------------------
;! Generate sample UV coverage given a user defined array layout
;# TASK ANALYSIS UV
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1996, 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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
UVSIM     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
UVSIM     Task to generate specimen u-v coverage.
INFILE                             Input data file name (name)
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 #.
APARM                              (1) observing freq. (Hz)
                                   (2) observing wavlength (m)
                                   (3)-(4) array Bx (m)
                                   (5)-(6) array By (m)
                                   (7)-(8) array Bz (m)
----------------------------------------------------------------
UVSIM
Task:
Adverbs:
  INFILE.....Name of the user-supplied file defining the array
             configuration (number of antennas, their locations,
             etc.)
  OUTNAME....Output UV file name (name).    Standard behavior
             with default 'UV DATA FILE'.
  OUTCLASS...Output UV file name (class).   Standard defaults.
  OUTSEQ.....Output UV file name (seq. #).  0 => highest unique.
  OUTDISK....Disk drive # of output UV file. 0 => highest disk
             with space for the file.
  APARM......User specified array.
             APARM(1): Nominal observing frequency (Hz).
             APARM(2): Nominal observing wavelength (meters).
             (A wavelength of 1 mm is assumed if neither
             APARM(1) nor APARM(2) is positive.)
             APARM(3)+(4) array Bx, meters
             APARM(5)+(6) array By, meters
             APARM(7)+(8) array Bz, meters
             Here X is in the direction of the intersection of the
             meridian of the reference location (long=0 for earth
             centered) and the equator; Y is 90 deg. EAST along the
             equator from X; Z is in the direction of the N. pole.
             Note that:
                BX = APARM(3) + APARM(4)
                BY = APARM(5) + APARM(6)
                BZ = APARM(7) + APARM(8)
             The addition of two parameters allows the coordinates
             to be specified with more precision than a single adverb
             allows; on a 32-bit machines adverb values are only
             accurate to 7 significant digits.
         NOTE: Setting Bx, By and Bz is required for accurate IAT
             times in the resultant UV dataset.  This may or may not be
             important, depending on what the data is used for. E.g.
             UVFIX WILL NOT WORK correctly on this data unless Bx, By
             and Bz are set.
         NOTE2: If Bx, By, Bz are set then the site latituted is
             calculated (normally input using the INFILE) using
             these numbers, since it is assumed that this will be
             more accurate.
----------------------------------------------------------------
UVSIM:
DOCUMENTOR: W. D. Cotton and F. R. Schwab, A. J. Mioduszewski, NRAO
RELATED PROGRAMS: Most AIPS tasks

                          PURPOSE

     This task is used to generate specimen u-v coverage for
an interferometric array, given an array configuration
specified by the user.  This task runs interactively, prompting
the user for such information as the source declination,
hour-angle coverage, integration time, minimum allowable
elevation angle, etc.  The output is a standard AIPS u-v data
file, with all visibilities set equal to unity.

     The "data" produced by UVSIM corresponds to a 1 Jy point
source at the phase center, observed on 1 Jan. 2000 and in 2000
coordinates. To simulate observations of an extended source, the
output of this task may be used as the input to the AIPS task
UVMOD or UVSUB.  FOR THE TIME STAMPS TO BE CORRECT THE SITE
Bx, By and Bx MUST BE SET.  IF THIS IS NOT DONE THEN PROGRAMS
THAT RECALCULATE THE U, V, W WILL NOT WORK CORRECTLY (e.g
UVFIX).

               SPECIFYING THE ARRAY CONFIGURATION

     The information defining the array configuration is read by
UVSIM from an auxiliary input file, supplied by the user.  This
is a free-format text file.  One must list, in the following
order:
  1)  The number of antennas,
  2)  The site latitude, in degrees (so that elevation angles
      may be computed), if Bx, By, and Bz are set then this
      number is recalulated.
  3)  A multiplicative conversion factor specifying how the
      antenna coordinates, listed next by the user, can be
      converted into units of meters; and a second
      multiplicative conversion factor specifying how the listed
      antenna diameters can be converted into units of meters,
  4)  The x-, y-, and z-coordinates of the first antenna (in a
      right-handed system) and the diameter of the first
      antenna, followed by the same information for the other
      antennas of the array. The origin of the coordinate system
      is at the center of the array. The z-axis points to the
      North Celestial Pole, the y-axis runs east-west, and the
      x-axis runs perpendicular to both pointing at the celestial
      equator.

Here is a sample file for a six-element array (the antenna
coordinates of this array are the coordinates, in units of
nanoseconds light-travel-time, of the innermost elements of two
arms of the VLA, in D-configuration).  The antenna diameters are
given here in units of meters, so the second conversion factor
is set to unity.  Antenna diameters are required by UVSIM in
order to permit computation of geometric blockage of array
elements (i.e., shadowing).

6
34.07874917
.2997924562 1
2.350 0 1.590 25
-100.220 -15.980 152.410 25
-174.850 -27.630 262.290 25
151.290 23.190 -218.530 25
49.330 -124.060 -67.540 25
96.580 -248.700 -137.120 25

This numeric information can instead be given in E-format (e.g.,
2.997925E-1, etc.) or in mixed E- and F-format.

     One must supply the name of the input file via the AIPS
adverb INFILE.  Examples:
         INFILE='disk$res:[fschwab.sim]test.ant'  (VMS)
         INFILE='myarea:test.ant'                 (Unix)
            where MYAREA is an environment variable set before
            starting AIPS:
            %setenv MYAREA /mnt/fschwab/sim


                       ADVERBS REQUIRED

     UVSIM records, in its output file, the (u,v,w) coordinates
corresponding to some nominal frequency, or wavelength, of
observation.  The default choice of the program (for example,
when APARM(1)=APARM(2)=0) is to set the nominal observing
wavelength to 1 mm.  Otherwise, if APARM(1) is positive, it uses
a frequency of APARM(1) Hz.  If APARM(2) is positive, but
APARM(1) is not, then the program uses a nominal wavelength of
APARM(2) meters.  (More simply stated: if you don't like the
default choice of 1 mm, then specify either your choice of
frequency or your choice of wavelength in APARM(1) or APARM(2),
respectively.)

     No other AIPS adverbs are used by UVSIM, apart from those
that specify the input and output files.


                         RUNNING THE PROGRAM

     To run the program one just types appropriate responses to
the questions that the program prints on the terminal screen.
The user is prompted for the following information:
   1)  The source declination,
   2)  The hour-angle coverage,
   3)  Minimum allowable elevation angle,
   4)  Integration time,
   5)  Maximum allowable fractional blockage of one antenna by
       another.
The responses can be typed in free format, either E- or F-, and
with or without decimal points.  The numbers, when more than one
is required, should be separated by blanks.
(E.g.,  6   6.0   -12  12.0   3e5   3.0E5).


                           LIMITATIONS

    At present, the program is mainly applicable only to compact
array configurations - as opposed, say, to VLBI arrays.  It
assumes, for example, that the elevation angles of all array
elements are identical.  However, it is expected that minor
embellishments will be added to UVSIM, removing such
restrictions as the need arises.
