% Chapter 1 of the AIPS Cookbook
\input COOK82.MAC
\input psfig
\def\doFIG{T}
\def\titlea{15-Jul-1994}
\def\chapt{1}
\tsect{1. INTRODUCTION}

\subsectt{1.1. The NRAO \AIPS\ Project --- A Summary}
\pd

    The NRAO Astronomical Image Processing System (\AIPS) is a
software package for interactive (and, optionally, batch) calibration
and editing of radio interferometric data and for the calibration,
construction, display and analysis of astronomical images made from
those data using Fourier synthesis methods.  Design and development of
the package began in Charlottesville, Virginia in 1978.  It presently
consists of over 800,000 lines of code, 80,000 lines of on-line
documentation, and 400,000 lines of other documentation.  It contains
over 300 distinct applications ``tasks,'' representing approximately
50 man-years of effort since 1978.  The \AIPS\ group in Charlottesville
and Socorro has five full-time scientist/programmers, and several
other computing and scientific staff with partial responsibility to
the \AIPS\ effort.  The group is responsible for the code design and
maintenance, for documentation aimed at users and programmers, and for
exporting the code to about 200 non-NRAO sites that have requested
copies of \hbox{\AIPS}.  It currently offers \AIPS\ installation kits
for a variety of UNIX systems, with updates available semi-annually.

    In 1983, when \AIPS\ was selected as the primary data reduction
package for the Very Long Baseline Array (VLBA), the scope of the \AIPS\
effort was expanded to embrace all stages of radio interferometric
calibration, both continuum and spectral line.  The \AIPS\ package
contains a full suite of calibration and editing functions for both
VLA and VLBI data, including interactive and batch methods for editing
visibility data.  For VLBI, it reads data in MkII, MkIII and VLBA
formats, performs global fringe-fitting by two alternative methods,
offers special phase-referencing and polarization calibration, and
performs geometric corrections, in addition to the standard
calibrations done for connected-element interferometers.  The
calibration methods for both domains encourage the use of realistic
models for the calibration sources and iterated models using
self-calibration for the program sources.

    \AIPS\ has been the principal tool for display and analysis of both
two- and three-dimensional radio images (\ie\ continuum ``maps'' and
spectral-line ``cubes'') from the NRAO's Very Large Array (VLA) since
early in 1981.  It has also provided the main route for
self-calibration and imaging of VLA continuum and spectral-line data.
It contains facilities for display and editing of data in the
aperture, or u-v, plane; for image construction by Fourier inversion;
for deconvolution of the point source response by Clean and by maximum
entropy methods; for image combination, filtering, and parameter
estimation; and for a wide variety of TV and graphical displays.  It
records all user-generated operations and parameters that affect the
quality of the derived images, as ``history'' files that are appended
to the data sets and can be exported with them from \AIPS\ in the
IAU-standard FITS (Flexible Image Transport System) format.  \AIPS\
implements a simple command language which is used to run ``tasks''
(\ie\ separate programs) and to interact with text, graphics and image
displays.  A batch mode is also available.  The package contains nearly
3.8 Mbytes of ``help'' text that provides on-line documentation for
users.  There is also a suite of printed manuals for users and for
programmers wishing to code their own applications ``tasks'' within
\hbox{AIPS}.

    An important aspect of \AIPS\ is its portability.  It has been
designed to run, with minimal modifications, in a wide variety of
computing environments.  This has been accomplished by the use of
generic FORTRAN wherever possible and by the isolation of
system-dependent code into well-defined groups of routines.  \AIPS\
tries to present as nearly the same interface to the user as possible
when implemented in different computer architectures and under
different operating systems.  The NRAO has sought this level of
hardware and operating system independence in \AIPS\ for two main
reasons.  The first is to ensure a growth path by allowing \AIPS\ to
exploit computer manufacturers' advances in hardware and in compiler
technology relatively quickly, without major recoding.  (\AIPS\ was
developed in ModComp and Vax/VMS environments with Floating Point
Systems array processors, but was migrated to vector pipeline machines
in 1985.  Its portability allowed it to take prompt advantage of the
new generation of vector and vector/parallel optimizing compilers
offered in 1986 by manufacturers such as Convex and Alliant.  It was
extended in simple ways in 1992 to take full advantage of the current,
highly-networked workstation environment).  The second is to service
the needs of NRAO users in their home institutes, where available
hardware and operating systems may differ substantially from NRAO's.
By doing this, the NRAO supports data reduction at its users' own
locations, where they can work without the deadlines and other
constraints implicit in a brief visit to an NRAO telescope site.  The
exportability of \AIPS\ is now well exploited in the astronomical
community; the package is known to have been installed at some time on
a large number of different computers, and is currently in active use
for astronomical research at more than 140\footnote{$^1$}{``The 1990
\AIPS\ Site Survey'', \AIPS\ Memo No.~70, Alan Bridle and Joanne
Nance, April 1991} sites worldwide.  \AIPS\ has been run on Cray and
Fujitsu supercomputers, on Convex and Alliant ``mini-supercomputers,''
on the full variety of Vaxen and MicroVaxen, and on a wide range of
UNIX workstations including Apollo, Data General, Hewlett Packard,
IBM, MassComp, Nord, Silicon Graphics, Stellar and SUN products.  It
is available for use on 80386 and 80486 personal computers under the
public-domain Linux operating system.  In late $1990^1$, the total
computer power used for \AIPS\ was the equivalent of about 6.5 Cray X-MP
processors running full-time.

    Similarly, a wide range of digital TV devices and printer/plotters
has been supported through AIPS's ``virtual device interfaces''.
Support for such peripherals is contained in well-isolated subroutines
coded and distributed by the \AIPS\ group or by \AIPS\ users elsewhere.
Television-like interactive display in now provided directly on
workstations using an \AIPS\ television emulator and X-Windows.  Hardware
TV devices are no longer common, but those used at \AIPS\ sites have
included IIS Model 70 and 75, IVAS, AED, Apollo, Aydin, Comtal,
DeAnza, Graphica, Graphics Strategies, Grinnell, Image Analytics,
Jupiter, Lexidata, Ramtek, RCI Trapix, Sigma ARGS, Vaxstation/GPX and
Vicom.   Printer/plotters include Versatec, QMS/Talaris, Apple,
Benson, CalComp, Canon, Digital Equipment, Facom, Hewlett-Packard,
Imagen, C.Itoh, Printek, Printronix and Zeta products.  Generic and
color encapsulated PostScript is produced by \AIPS\ for a wide variety
of printers and film recorders.  The standard interactive graphics
interface in \AIPS\ is the Tektronix 4012, now normally emulated on
workstations using an \AIPS\ program and X-Windows.

    The principal users of \AIPS\ are VLA, VLBA, and VLBI Network
observers.  A survey of \AIPS\ sites carried out in late $1990^1$
showed that 61\%\ of all \AIPS\ data processing worldwide was devoted to
VLA data reduction.  Outside the NRAO, \AIPS\ is extensively used for
other astronomical imaging applications, however.  56\%\ of all \AIPS\
processing done outside the U.S. involved data from instruments other
than the \hbox{VLA}.  The astronomical applications of \AIPS\ that do
not involve radio interferometry include the display and analysis of
line and continuum data from large single-dish radio surveys, and the
processing of image data at infrared, visible, ultraviolet and X-ray
wavelengths.  About 7\%\ of all \AIPS\ processing involved astronomical
data at these shorter wavelengths, with 7\%\ of the computers in the
survey using \AIPS\ more for such work than for radio and {\it another}
7\%\ of the computers using \AIPS\ exclusively for non-radio work.

    Some \AIPS\ use occurs outside observational astronomy, \eg\ in
visualization of numerical simulations of fluid processes, and in
medical imaging.  The distinctive features of \AIPS\ that have attracted
users from outside the community of radio interferometrists are its
ability to handle many relevant coordinate geometries precisely, its
emphasis on display and analysis of the data in complementary Fourier
domains, the NRAO's support for exporting the package to different
computer architectures, and its extensive documentation.

As well as producing user- and programmer-oriented manuals for AIPS,
the group publishes a newsletter that is sent to over 775 \AIPS\ users
outside the NRAO soon after each semi-annual ``release'' of new \AIPS\
code.  There is also a mechanism whereby users can report software
bugs or suggestions to the \AIPS\ programmers and receive written
responses to them; this provides a formal route for user feedback to
the \AIPS\ programmers and for the programmers to document difficult
points directly to individual users.  Much of the \AIPS\ documentation
is now available to the ``World-Wide Web'' so that it may be examined
over the Internet (start with ``URL'' {\tt
http://info.cv.nrao.edu/aips/aips-home.html}).  The NRAO knows of over
230 \AIPS\ ``tasks,'' or programs, that have been coded within the
package outside, and not distributed by, the observatory.

    The \AIPS\ group has developed a package of benchmarking and
certification tests that process standard data sets through the dozen
most critical stages of interferometric data reduction, and compare
the results with those obtained on the NRAO's own computers.  This
``DDT'' package is used to verify the correctness of the results
produced by \AIPS\ installations at new user sites or on new types of
computer, as well as to obtain comparative timing information for
different computer architectures and configurations.  It has been
extensively used as a benchmarking package to guide computer
procurements at the NRAO and elsewhere.  Two other packages, ``VLAC''
and ``VLAL'', are less widely used to verify the continued correctness
of calibration and spectral-line reductions.

     In 1992, the NRAO joined a consortium of institutions seeking to
replace all of the functionality of \AIPS\ using modern coding
techniques and languages.  The ``{\tt aips++}'' project is expected to
provide the main software platform supporting radio-astronomical data
processing in the latter half of the 1990's.  Future development of
the original (``Classic'') \AIPS\ will therefore be limited mostly to
calibration of VLBI data, general code maintenance with minor
enhancements, and improvements in the user documentation.

    Further information on \AIPS\ can be obtained by writing by
electronic mail to {\tt aipsmail@nrao.edu} or by paper mail to the
AIPS Group, National Radio Astronomy Observatory, Edgemont Road,
Charlottesville, VA 22903-2475, U.S.A.

\subsect{1.2.  The \COOKBOOK}
\pd

     This \COOKBOOK\ is intended to help beginning users of the NRAO
{\af A}stronomical {\af I\/}mage {\af P\/}rocessing {\af S}ystem (\AIPS)
by providing a recipe approach to the most basic \AIPS\ operations.
While it illustrates some aspects of \AIPS, it does not pretend to be
complete.  However, it does include detailed instructions for running
many important items of \AIPS\ software.  With these as a model, the
user should be able to run other \AIPS\ software aided by the
{\tt EXPLAIN}, {\tt HELP} and {\tt INPUTS} files and the complete
index of software given in Chapter 13 of the \hbox{\COOKBOOK}.  In this
edition, some of the chapter have matured into something more like a
users' manual, than a beginners' cookbook.  These sections provide an
overview of a few less basic, but nonetheless interesting, programs
which often seem to be forgotten even by experienced \AIPS\ users.  To
assist the beginning and infrequent user, two appendices have been
added to provide outlines of continuum and spectral-line calibration
procedures, primarily geared to users of the \hbox{VLA}.

     \AIPS\ software is changing and growing continually.  This seventh
edition of the \COOKBOOK\ describes the 15 January 1994 release of \AIPS,
frequently referred to as {\tt 15JAN94}, while some chapters have
information from even later releases. Much has changed in \AIPS\
software since the previous ({\tt 15JUL90}) edition of the
\hbox{\COOKBOOK}.  The chapter on the \AIPS\ calibration package for
continuum, spectral-line, solar and VLBI data (Chapter 4) was revised
with the assistance of Rick Perley and Alan Bridle.  The index of
current \AIPS\ tasks (Chapter 13) has been updated and reflects the
extensive improvement and expansion of \AIPS\ software and of our
cability to do the indexing.  The chapters on imaging and improving
images were merged as were the chapters on interactive and
hard-copy displays.  These mergers reflect in part the mergers of
these operations.  The chapter on spectral-line imaging (Chapter 8)
has been revised with the assistance of Elias Brinks.  Phil Diamond
and John Conway have rewritten the chapter on VLBI calibration and
imaging (Chapter 9).  Appendix~Z contains instructions and advice
peculiar to the individual \AIPS\ sites of the \hbox{NRAO}.  This has
been revised extensively to reflect the migration of much of the data
reduction at NRAO sites away from VAXes and Convex computers to Sun
and IBM workstations.

     This edition still contains the helpful glossary of astronomical and
computing terms written by Fred Schwab.  Suggestions for additions to
the \COOKBOOK\ and reports of any inadequacies or errors in it should
be made to the \AIPS\ group in Charlottesville ({\tt aipsmail@nrao.edu}).

     As a result of typesetting, the \COOKBOOK\ does not exist in a
form which can be listed intelligibly on ordinary line printers.
Copies may be obtained by writing to the NRAO Computer Division in
Charlottesville or at the \hbox{VLA}.  A faster method is to use your
own copying machine.  \AIPS\ sites which have a PostScript printer may
also have files on disk from which up-to-date copies of the \COOKBOOK\
may be printed.  Consult your local \AIPS\ Manager for details on how
to do this.  Much of the \AIPS\ documentation, including the
\COOKBOOK, is now available to the ``World-Wide Web'' so that it may
be examined and retrieved over the Internet (start with ``URL'' {\tt
http://info.cv.nrao.edu/aips/aips-home.html}).

     This edition of the \COOKBOOK\ is issued in a ring-binder format
with a chapter-nased page numbering system.  This allows us to update
individual chapters without altering the pagination of others and to
make each chapter available individually over the Internet.

     Additional written documentation on \AIPS\ is available in
several forms.  A programmers' reference manual called {\it Going
AIPS} is available in two volumes.  This was revised completely for
the {\tt 15APR90} release due to the upgrading of the \AIPS\ code to
FORTRAN-77 and to reflect the extensive additions and improvements to
the software.  Unfortunately, it has not been revised since.  The
first volume is intended for applications programmers, while the
second volume is needed by programmers developing \AIPS\ for new
peripheral devices or computers.  Printed copies of {\it Going AIPS}
may be obtained by writing to the NRAO Computer Division in
Charlottesville.

     \AIPS\ provides run-time documentation in the form of {\tt HELP}
and {\tt EXPLAIN} files which may be viewed at the terminal or
printed. (See \Sec 3.8 for explicit instructions.)  Should these not
suffice, consult your local \AIPS\ Manager and then, if needed, call
the \AIPS\ programmers in Charlottesville.  Although individual \AIPS\
programs have often been written, and are best understood, by a single
programmer, the \AIPS\ group as a whole assumes responsibility for all
released software.  Anyone in the group will attempt to help you or,
at least, to identify another member of the group better able to help
you.

     Finally, users are encouraged to recommend new and better
analysis and display tools and to help debug the existing software by
entering ``Gripes'' (see \Sec 10.3).  Please note that examples of
bugs that are documented by printouts of inputs, message logs, {\it
etc.\/} are most useful to the programmers.  Also note that written
bug reports are {\it much} more effective than verbal reports.
A ``Gripes'' database has been constructed to improve ``gripe''
response times and to aid the programmers in reviewing outstanding
complaints and suggestions.

\subsect{1.3.  Organization of the \COOKBOOK}

\subsubsectt{1.3.1.  Contents}


     Chapter~2 of the \COOKBOOK\ describes in general terms how to get
started in \AIPS\ --- signing up, logging in, mounting tapes, {\it
etc.\/}  Appendix~Z gives details of these operations specific to
NRAO's \AIPS\ sites.  Your local \AIPS\ Manager may be able to provide
a version of this appendix appropriate to your system.  Chapter~3
introduces the basic \AIPS\ utilities.  Chapter~4 leads you through
the basics of reading in and calibrating your \uv\ data.  Chapter~5
explains the basic operations required to make and improve images.
Appendices A and B provide a simpler recipe-like approach to
calibration and imaging which beginning users may wish to try.
Chapters 6 and 7 introduce the basic \AIPS\ tools for making
interactive and hard-copy displays of images and other data and for
analyzing them.  Chapter~8 contains hints and further \AIPS\ tools of
particular interest, but not restricted, to spectral-line users and
other observers who have images of more than 2 dimensions.  Similarly,
Chapter~9 is aimed primarily at users of VLB interferometers.
Chapter~10 deals with exiting from \AIPS\ and tidying up your disk
areas to be polite to the other users.  Chapter~11 suggests some cures
for common hang-ups and miscellaneous ``disasters'' which seem to
afflict \AIPS\ users.  No such list can be made comprehensive or
sufficiently general to cover all the computer systems now running
\hbox{\AIPS}.  You will need to consult with your local \AIPS\ Manager
or other users if you encounter an unlisted problem.

     Chapter~12 is intended for the ``mature'' \AIPS\ user who wishes
to learn about data formats, procedures, {\tt RUN} files, and various
subtleties of {\tt AIPS} syntax.  We recommend that you read this
after becoming familiar with the operations described in Chapters 3
through 7.  Chapter~13 contains lists of all available routines broken
down by categories.  Appendix G presents Fred Schwab's Glossary of
radio astronomy data processing terminology.  Appendix~Y gives some
useful recipes for estimating disk files sizes and for saving data and
images on tape.

\subsubsect{1.3.2.  Minimum match}

     In this \COOKBOOK, we use the minimum-matching capability of
\AIPS\ to abbreviate the instructions needed to run the programs.
This speeds up your activity at the terminal while working in
\hbox{\AIPS}.  However, the full names of some of the {\tt AIPS}
instructions may be easier to learn and to remember.  They are given
in Chapter 13.

\subsubsect{1.3.3.  Fonts and what they signify}

    Throughout this \COOKBOOK, {\us RESPONSES TO BE TYPED BY THE USER
APPEAR IN THE PRESENT \hbox{FONT}}.  Prompts provided by the operating
or \AIPS\ systems are left-justified on the same line, \eg\ system
prompts \dol\ on VAXes or {\tt \%} on UNIX systems , {\tt AIPS} prompt
\hbox{{\tt >}}.  {\tt THIS IS THE FONT USED FOR SAMPLE OUTPUTS FROM
THE COMPUTER} and for program names such as \hbox{{\tt PRTUV}}.  A
lower-case italic font, {\it such as this}, is used for numeric and
character parameter values which must be supplied by the user.  The
symbol {\tt AIPS} refers to the program which you will use to
communicate with the computer.  The symbol \AIPS\ refers to the full
system, made up of the {\tt AIPS} program, numerous other programs
which may be run from {\tt AIPS}, and the hardware configuration.  The
symbol \CR\ means ``hit the {\us RETURN} key on the terminal.''

The symbol \Sec\ means Section and refers to the various chapters and
sub-chapters of this \hbox{\COOKBOOK}.

\subsect{1.4.  General structure of \AIPS}

The diagram on the next page is an attempt to show the general
structure of the \AIPS\ software package.  You may wish to refer to it
as you read the remaining chapters.  Input to \AIPS\ is either
interactive or batch via the main {\tt AIPS} program.  It uses the
{\ss POPS\/} language processor and symbol table to set ``adverb''
values and cause application ``verbs'' to be executed.  Chief among
these, the verb {\tt GO} causes independent programs called ``tasks''
to run.  Sequences of commands may be run in batch by {\tt SUBMIT}ting
them to a batch ``checker'' and running them using the batch version
of \hbox{{\tt AIPS}}.  All programs access and modify disk data files,
and interactive ones may access tapes and TV- and Tektronix-like
display devices.

\vfill\eject
\if T\doFIG
   \centerline{\psfig{figure=FIG/AM61.FIG.1,height=8.3in}}
\else
   \vbox to 8.3in{\vfill\omit\vfill}
\fi
\vfill\eject

\end
