%-----------------------------------------------------------------------
%;  Copyright (C) 1995, 1997-1998, 2000-2001, 2003-2004, 2007, 2009-2010
%;  Copyright (C) 2012-2014, 2016, 2018, 2020, 2022, 2024-2025
%;  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
%-----------------------------------------------------------------------
% Chapter 1 of the AIPS Cookbook
\chapts{Introduction}{intro}

\renewcommand{\titlea}{31-DEC-2025 (revised 16-July-2025)}
\renewcommand{\Rheading}{\AIPS\ \cookbook:~\titlea\hfill}
\renewcommand{\Lheading}{\hfill \AIPS\ \cookbook:~\titlea}
\markboth{\Lheading}{\Rheading}

\sects{The NRAO \AIPS\ Project --- A Summary}

    The NRAO Astronomical Image Processing System (\AIPS\Iodx{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 1,775,000 lines of code, 236,000 lines
of on-line documentation, and 496,000 lines of other
documentation.\footnote{Counted on 16-July-2025 and omitting the
GNU copyrights, PostScript and PDF files, and obsolete areas.}  It
contains over 633 distinct applications ``tasks,'' representing very
approximately 90 man-years of effort since 1978.  The \AIPS\ group,
now solely in Socorro, has one full-time scientist/programmer, and a
few other scientific staff with some low-level 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 hundreds \footnote{The {\tt 15JAN96} release
alone was shipped to 225 sites and installed on well over 800
computers.  The {\tt 15APR99} release was shipped to 344 non-NRAO
sites.  In 2009, more than 2400 different IP addresses installed or
updated copies of \AIPS\@.  In 2019, this number had dropped to 1155.}
of non-NRAO sites that have requested copies of \AIPS\@.  It currently
offers \AIPS\ installation kits for a variety of UNIX systems (Linux
and Mac OS/X), with updates available annually.\footnote{The {\tt TST}
version, currently {\tt 31DEC24}, will be available continuously. It
remains under development and sites may update their copies at will.
Binary versions are available for Linux (32- and 64-bit) and Max OS/X
(Intel and ARM) and text versions for these and other operating systems.}

    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 (FITS
IDI) 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 \indx{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 11.4 Mbytes of ``help'' text that provides on-line
documentation for users.  There is also a suite of printed manuals
(available on-line) for users and for programmers wishing to code
their own applications ``tasks'' within \AIPS\@.

    An important aspect of \AIPS\ is its \indx{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 re-coding.  \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 way more than 140\footnote{``The
\indx{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 and laptops including Apollo,
Data General, Hewlett Packard, IBM, MassComp, Nord, Silicon Graphics,
Stellar and SUN products.  It is available for use on personal
computers under the public-domain Linux operating system and, since
2003, On MacIntosh OS/X computers.  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 \Iodx{AIPS}\AIPS\ group or by \AIPS\
users elsewhere.  Television-like interactive display is now provided
directly on workstations using an \AIPS\ \indx{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.  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 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 semi-annually that is sent to
subscribing libraries and is available on the Web.  There is also a
mechanism whereby users can report software bugs or suggestions to the
\AIPS\ programmers and receive written responses from 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 ``\indx{World-Wide Web}'' so that it may be examined over the
Internet (start with ``\indx{URL}'' {\tt https://info.aips.nrao.edu/}).
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 \Iodx{AIPS}\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. The ``Y2K'' 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 \indx{aips++}}'' project, now
named ``{\tt \indx{casa}},'' is expected to provide the main software
platform supporting radio-astronomical data processing sometime in the
future.  Further 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 daip@nrao.edu} or by paper mail to the AIPS
Group, National Radio Astronomy Observatory, P. O. Box O, Socorro, NM,
87801-0387, U.S.A.

\sects{The \COOKBOOK}

     This \Iodx{COOKBOOK}\COOKBOOK\ is intended to help beginning
users of the NRAO {$\cal A$}stronomical {$\cal I\/$}mage {$\cal
P\/$}rocessing {$\cal 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
\Rchap{list} of the \COOKBOOK\@.  In this edition, some of the
chapters 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, appendices have been added to provide outlines of
continuum, spectral-line, and high-frequency calibration procedures,
primarily geared to users of the VLA, and a simplified outline of VLBA
data reduction.   A guide to reduction of data from the historic VLA
appears in Appendix O\@.  To assist in finding information in this now
large document, an index has been added.

     \AIPS\ software is changing and growing continually.  This
edition of the \COOKBOOK\ describes the {\tt 31DEC24} (aka ``\AIPS\
for the Ages (Aged), version 25'') release of \AIPS.  Some chapters
have information only from earlier releases.  When something only
applies to fairly recent versions of \AIPS, a comment to that effect
is made.  Features remain in later releases even if the particular
comment does not say as much.  There were many changes in \AIPS\
software between the seventh ({\tt 15JAN94}) and the sixth ({\tt
15JUL90}) edition of the \COOKBOOK\@.  The chapter on the \AIPS\
calibration package for continuum, spectral-line, solar and VLBI data
(\Rchap{cal}) was revised in 2018 to describe calibration and editing
of the Expanded VLA\@.  Material applying to the old VLA was moved to
Appendix O (old).  The list of current \AIPS\ tasks (\Rchap{list}) has
been updated and reflects the extensive improvement and expansion of
\AIPS\ software.  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 (\Rchap{line}) has been revised with
the assistance of Elias Brinks.  Phil Diamond, John Conway, Athol
Kemball, and Ketan Desai have rewritten the chapter on VLBI
calibration and imaging (\Rchap{vlbi}).  \Rappen{sys} contains
instructions and advice peculiar to the individual \AIPS\ sites of the
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 Linux workstations.  The ninth edition has an
Index which is current and updates concerning editing, calibration,
imaging and single-dish processing in the {\tt 15APR98} and later
versions of \AIPS\@.  This edition still contains, essentially
unchanged, the helpful glossary of astronomical and computing terms
written by Fred Schwab.

Paper copies of recent editions of the \COOKBOOK\ are no longer
available from NRAO\@.  However, much of the \AIPS\ documentation,
including the  \COOKBOOK, is now available on the ``World-Wide Web''
so that it may be examined and retrieved over the Internet (start with
``URL'' {\tt https://www.aips.nrao.edu}).  This edition of the
\Iodx{COOKBOOK}\COOKBOOK\ is issued in a ring-binder format with a
chapter-based 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.  The
documentation is also included with every copy of \AIPS\ shipped.

     Additional written documentation on \AIPS\ is available in
several forms.  A programmers' reference manual called {\it
\indx{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 but it continues to be quite useful.  The first volume is
intended for applications programmers, while the second volume is
needed by programmers developing \AIPS\ for new peripheral devices or
computers.  {\it Going AIPS\/} may be obtained from the \AIPS\ web
site.

     \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{help} for explicit instructions.)  Should these not
suffice, consult your local \AIPS\ Manager and then, if needed, e-mail
the \AIPS\ programmer at {\tt daip@nrao.edu}.  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{gripe}).  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.
E-mail to {\tt daip@nrao.edu} reaches everyone in the group.

\sects{Organization of the \COOKBOOK}

\subsections{Contents}

     \Rchap{start} of the \COOKBOOK\ describes in general terms how to
get started in \AIPS\ --- signing up, logging in, mounting tapes, {\it
etc.\/}  \Rappen{sys} 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.  \Rchap{basic}
introduces the basic \AIPS\ utilities.  \Rchap{cal} leads you through
the basics of reading in and calibrating your modern VLA \uv\ data.
\Rchap{image} explains the basic operations required to make and
improve images.  Appendices~\ref{appen:cont}, \ref{appen:line}, and
\ref{appen:VLBAeasy} provide simpler recipe-like approaches to
calibration and imaging which beginning users may wish to try.
\Rchap{plot} introduces the basic \AIPS\ tools for making interactive
and hard-copy displays of images and other data and \Rchap{anal}
describes tools for analyzing them.  \Rchap{line} and \Rappen{line}
contain 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.  \Rappen{Olderdata} is designed for users of
the historic VLA archive and for older VLBI formats.  Similarly,
\Rchap{vlbi} and \Rappen{VLBAeasy} are aimed primarily at users of VLB
interferometers.  \Rchap{sd} deals with single-dish data reduction
with \AIPS\@.  \Rchap{exit} describes how to help the \AIPS\
programmers, to backup your data, and to exit from \AIPS\@.  It also
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 \AIPS\@.  You will need to consult with your local
\AIPS\ Manager or other users if you encounter an unlisted problem.

     \Rchap{pops} 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.  \Rchap{list} contains lists of all available routines
broken down by categories.  Appendix~G presents Fred Schwab's Glossary
of radio astronomy data processing terminology.  \Rappen{size} gives
some useful recipes for estimating disk files sizes and for saving
data and images on tape.  \Rappen{VLAtasks} contains information
about tasks used to maintain the VLA, including holography of dish
surfaces.  Appendix~I contains the index.
%\eject

\subsections{Minimum match}

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

\subsections{Fonts and what they signify}

    Throughout this \COOKBOOK, {\us RESPONSES TO BE TYPED BY THE USER
APPEAR IN THE PRESENT 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 {\tt PRTUV}\@.  A
lower-case italic \indx{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} or {\us Enter} key on the
terminal.''

The symbol \Schar\ means Section and refers to the various chapters and
sub-chapters of this \COOKBOOK\@.  Except in the values assigned to
character string variables, \AIPS\ is case insensitive.  We use
upper-case letters in this \COOKBOOK\ to differentiate \AIPS\ symbols
from ordinary words visually.  This usage also allows us to generate
html and pdf capable versions of the \COOKBOOK\ from the basic \TEX\
files automatically.

\sects{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
\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 {\tt AIPS}\@.  All programs access and modify disk data files, and
interactive ones may access tapes and TV- and Tektronix-like display
devices.\iodx{structure of \AIPS}

\vfill\eject
\begin{figure}
%\resizebox{!}{8.5in}{\gname{am61}}
\resizebox{!}{8.5in}{\gbb{498,673}{am61}}
\caption{Basic \AIPS\ flow diagram}
\label{fig:aipsflow}
\end{figure}
