; UVLOD
;---------------------------------------------------------------
;! Read export or FITS data from a tape or disk
;# TASK UV TAPE FITS
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1998-1999, 2003, 2007-2008
;;  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
;-----------------------------------------------------------------------
UVLOD     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
UVLOD:  Task which copies Export or FITS tape UV data to disk
DOALL            -1.0       1.0    > 0 => all sources in file
OBJECT                             Source name (blank => any)
QUAL             -1.0     999.0    Source qualifier (-1 => any)
BAND                               Frequency band ('L','C',...)
                                      blank => any
BCOUNT            0.0    1000.0    Sequential source number to
                                   begin the loading
NCOUNT            0.0    1000.0    Number of sources to check
                                   and perhaps load. 0 means 10.
INTAPE            0.0       9.0    Tape drive # (0 => 1)
NFILES        -9999.0    9999.0    # of files to advance on tape
DATAIN                             Disk file name (FITS ONLY)
DOUVCOMP         -1.0       1.0    >=0 => compressed data (FITS)
DOCONCAT         -1.0       1.0    > 0 => concatenate all UV
                                   data selected in one file.
OUTNAME                            Output UV file name (name)
                                     blank => OBJECT
OUTCLASS                           Output UV file name (class)
                                     blank => UVDATA
OUTSEQ           -1.0    9999.0    Output UV file name (seq #)
                                     -1 => tape seq # (FITS)
                                      0 => high unique
OUTDISK           0.0       9.0    Output disk drive #
NPOINTS           0.0              Max # 1000's of visibilities
          Adverbs DOALL, OBJECT, QUAL, BAND, BCOUNT, NCOUNT,
          and NPOINTS apply only to Export format data files.
NPIECE            0.0      90.0    Maximum uv table piece number
                                   to be loaded
ERROR            -1.0       3.0    >= 2 -> do not use AIPS
                                   history in the FITS file
----------------------------------------------------------------
UVLOD
Type:  Task
Use:   To copy a UV data base from an Export or FITS tape to a
       catalogued file.  Export tapes are likely to be left within the
       data file unless DOCONCAT is true and BCOUNT + NCOUNT encompasses
       the last source in the file.  In that case and the case of FITS
       format, the tape is left following the End-of-File mark of the
       specified file.
       UVLOD (and PRTTP, IMLOD, FITLD, TPHEAD) now understand and
       interpret the standard world coordinate system keywords CDi_j
       and PCi_j.  They are used if possible and problems reported.
Adverbs:
  DOALL......> 0 => load all sources matching adverbs OBJECT, QUAL, and
                    BAND in the tape file.
             < 0 => load only first match.  (Not for FITS)
  OBJECT.....The source name.  Blank => any name ok.  Standard
             "wild-card" conventions are supported.
  QUAL.......The source name qualifier.  -1 => all quals
  BAND.......Frequency band.  blank => any.  Not used for FITS
  BCOUNT.....Load sources beginning with sequence number BCOUNT (see
             PRTTP listing of tape).
  NCOUNT.....Check and perhaps load only NCOUNT consecutive sources from
             the tape.
             0 => 10   (DOALL > 0),
             0 => 100  (DOALL <= 0).
  INTAPE.....Tape drive #.   0 => 1
  DATAIN.....48-character name of the disk file from which to read a
             FITS file.  It must be in the form
                  <logical>:<file name>
             or
                  <node>::<logical>:<file name>
             where <node> is the remote computer name, <logical> is the
             environment variable (logical name) for the disk area in
             which the file named <file name> is stored.  <node> is
             usually omitted when the file is local to the current
             computer.  For multi-piece FITS uv-table files (see NPIECE
             below and task FITAB), it is the base name without the
             appended sequence number or the full name of the starting
             piece.  (If the file DATAIN does not exist, the task looks
             for DATAIN with a "1" appended.)
  NFILES.....# of files to skip on tape before reading data.
             0 => no tape movement at all.
  DOUVCOMP...If true (DOUVCOMP >= 0) the output data is written in
             compressed format which can result in a substantial
             reduction in disk space needed.  Some loss of spectral
             dynamic range and differences in weights between IFs and
             spectral channels within a record are lost.
             Only used for FITS files of the random-groups type (e.g.
             written by FITTP).  Binary tables have the compression
             selected by the compression state of the table (e.g.
             FITAB).
  DOCONCAT...> 0 = True = concatenate all selected data into a single uv
             data file.  Ignored if DOALL > 0.  Does not apply to older
             UV fits files, but does apply to FITS uv-table files
             produced by FITAB.
  OUTNAME....Output UV file name (name).  Standard behavior with default
             = (in order) OBJECT and source-name.qual for Export data.
             Default = (in order) tape value, OBJECT, source name, and
             'NONE' for FITS.
  OUTCLASS...Output UV file name (class).  Standard behavior with
             default = 'UVDATA' for Export and (in order) tape value and
             'UVDATA' for FITS.
  OUTSEQ.....Output UV file name (seq #).  0 => highest unique.
             < 0 => use tape value if present (FITS only).
  OUTDISK....Output UV file disk drive #. 0 => highest with space for
             the file.
  NPOINTS....Read and store a maximum of NPOINTS*1000 UV points
             per source. (Not used for FITS)  0 => 50.
  NPIECE.....Maximum piece number to read in a multi-piece uv-table FITS
             data set.  0 => maximum in the data.
  ERROR......>= 2 => do not parse AIPS history cards found in the FITS
             header.  Do not use this option until you have tried UVLOD
             without it.  If you get mysterious errors (usually error 4
             which implies premature end of file), then try UVLOD with
             ERROR set to 2.  For a period of time, data sets written
             out with FITAB, read back in, and then written out with
             FITTP could have so many AIPS history records in their
             header as to cause UVLOD to read the data wrongly.
----------------------------------------------------------------
UVLOD:  Task to load UV data from tape to disk.
RELATED PROGRAMS: FITTP, FITAB, UVEXP, EXIND, PRTTP, MOUNT, DISMOUNT

                            PURPOSE

     UVLOD loads UV data from a magnetic tape to disk.  The UV data may
be written either in FITS format or in Export format.  Tapes with FITS
format can be generated from AIPS using the task FITTP (random groups
type) or FITAB (uv-tables).  Tapes with Export format are generated from
the AIPS task UVEXP or from the DEC-10 using EXPVIS. The FITS format is
recommended since no information is lost due to arbitrary restrictions
in the format.  Normally the u-v data set has been calibrated already,
as initial data calibration is not generally performed in AIPS.
However, self-calibration and some forms of editing of the data set are
often performed within AIPS once the data set has been loaded.  Some of
the adverbs are used only for Export format and are ignored with FITS
format data.
     FITS format files can be read from a disk file on one of the AIPS
disks.  This uses the adverb DATAIN.

                        GENERAL COMMENTS

     The tape must be properly mounted and the correct density
specified.  This is most easily done using the MOUNT command in AIPS.
When through reading the tape and no other tape processing is
anticipated, use DISMOUNT to free the tape drive for other users.

OUTDISK:
     Make sure there is enough space for the source data on the
specified OUTDISK (see below).  This is especially important if many
large data bases will be written onto the disk.


                    COMMENTS FOR FITS FILES

Most of the adverbs are ignored for FITS files.  DOALL, OBJECT, QUAL,
BAND, BCOUNT, NCOUNT, and NPOINTS have no interest for FITS files of
either the random groups (FITTP) or table form (FITAB found only in
15APR99 and later).

NPIECE:
     Maximum piece number in a multi-piece (multi-file) uv-table FITS
data set to be read.  0 => maximum in the data.  These files are written
by FITAB in 15APR99 and later AIPS.  If the first piece to be read is
noit the first piece written, position the tape, or set DATAIN, to the
first file to be read.

DOCONCAT:
      If multiple pieces of uv-table files are being read, they will
automatically go into the same output disk file.  If you wish this disk
file to be a pre-existing disk file, give DOCONCAT > 0 and specify the
output file name.  Defaults NAME and CLASS will work, but it is
recommended that you set OUTSEQ.  If OUTSEQ=0 or DOCONCAT<= 0, a new
file will be created.  DOCONCAT does not apply to the random-groups form
of uv FITS files.


                    COMMENTS FOR EXPORT FILES

DOALL:
     If DOALL is TRUE (> 0.0), UVLOD will load all sources matching the
OBJECT, QUAL, and BAND adverbs in the range from BCOUNT through
BCOUNT+NCOUNT-1.  Each selected source will be put in a separate
catalogued disk file.  The initial value is FALSE (<= 0), in which case
only the first source or sources (depending on DOCONCAT) matching these
adverbs will be loaded.

BCOUNT:
     The PRTTP and EXIND tasks give a sequential listing of all sources
on the Export tape.  This adverb specifies the first source within a
file that is considered for loading onto disk.

NCOUNT:
     For Export tapes, this adverb specifies the total number of sources
which will be considered for loading on disk

DOCONCAT:
     This adverb is considered only if DOALL is false (<= 0).  If
DOCONCAT is true (> 0), UVLOD will concatenate the data for all sources
selected via the OBJECT, BAND, QUAL, BCOUNT, and NCOUNT adverbs.  This
concatenation may be desirable for certain types of data (e.g. position
tracking of planets, frequency tracking of spectral lines).  UVLOD does
not modify phases and the like for different source positions in the
concatenated sources.  However, it does convert the baselines from time
units to wavelengths at the frequency given on the tape for the
particular source.  This is exactly what is desired for
frequency-tracked data.
     For a tape file containing a large number of sources from which
only one source is desired, it is a good idea to set DOALL false and
DOCONCAT false (<= 0).  Otherwise, UVLOD will read through the entire
tape file (to BCOUNT+NCOUNT sources) before ending, even if the desired
source has long since been loaded to disk.  This will waste both CPU and
user interactive time.

NPOINTS:
     This adverb specifies the maximum number of UV points which will be
transferred to disk from an Export tape (not used for FITS-style tapes).
The value of NPOINTS is 1000 times the number of points to be
transferred, and should also be set at the lowest multiple of 1000
higher than the number of points to be loaded to disk (e.g., NPOINTS=17
for a data set containing 16,201 visibility records).  The number of
visibility records can be found by running EXIND or on a log of the
EXPVIS program executed at the VLA.
     There is a 20% leeway in NPOINTS.  If you set NPOINTS=17, the UVLOD
will read upto 20,400 uv points before terminating. A warning message is
given if more data are found.


INTERACTION WITH OTHER PROGRAMS:
     PRTTP will print out the contents of an entire tape including
Export uv files, IBM map files, and all kinds of FITS files.
FITTP and FITAB (15APR99 and later) are different means of using AIPS to
write UV data from disk to tape (e.g., after self-calibration); this
data can later be reloaded from both formats using UVLOD.  In general,
the data are not in 'XY' sorted order after being loaded via UVLOD, so
UVSRT may need to be run to sort the data properly for some imaging
tasks.

EXECUTION TIMES:
     The execution time depends on the location on the tape of
the desired data.  If the user starts reading from the
beginning of the tape, required CPU time may be only 10 seconds
for data near the beginning of the tape and several minutes for
data close to the end of the tape, with a roughly linear
relation in between (i.e., most of the CPU time for a data set
not at the beginning of the tape is spent reading through the
tape to find the desired data set).
     In an otherwise empty VAX 11-780 it takes about 5.5 min
to load 500,000 visibility points (all four polarizations)

DISK SPACE:
     The size of a data set loaded via UVLOD is linearly
proportional to the number of UV records in the data.  The
ratio of disk blocks to visibility records is roughly 1:7, so a
data set containing 50,000 visibility records will occupy
approximately 7,000 blocks of disk space.  Be sure there is
enough space on OUTDISK to hold the data.
