\chapter{Introduction}
\label{cha:introduction}

\begin{quote}
   This chapter introduces the numarray Python extension and outlines the rest
   of the document.
\end{quote}

Numarray is a set of extensions to the Python programming language which allows
Python programmers to efficiently manipulate large sets of objects organized in
grid-like fashion. These sets of objects are called arrays, and they can have
any number of dimensions. One-dimensional arrays are similar to standard Python
sequences, and two-dimensional arrays are similar to matrices from linear
algebra. Note that one-dimensional arrays are also different from any other
Python sequence, and that two-dimensional matrices are also different from the
matrices of linear algebra. One significant difference is that numarray objects
must contain elements of homogeneous type, while standard Python sequences can
contain elements of mixed type. Two-dimensional arrays differ from matrices
primarily in the way multiplication is performed; 2-D arrays are multiplied
element-by-element.

This is a reimplementation of the earlier Numeric module (aka numpy). For the
most part, the syntax of numarray is identical to that of Numeric, although
there are significant differences. The differences are primarily in new
features. For Python 2.2 and later, the syntax is completely backwards
compatible. See the High-Level Overview (chapter \ref{cha:high-level-overview})
for incompatibilities for earlier versions of Python. The reasons for rewriting
Numeric and a comparison between Numeric and numarray are also described in
chapter \ref{cha:high-level-overview}. Portions of the present document are
almost word-for-word identical to the Numeric manual. It has been updated to
reflect the syntax and behavior of numarray, and there is a new section
(~\ref{sec:diff-numarray-numpy}) on differences between Numeric and numarray.

Why are these extensions needed? The core reason is a very prosaic one:
manipulating a set of a million numbers in Python with the
standard data structures such as lists, tuples or classes is much too slow and
uses too much space. A more subtle
reason for these extensions, however, is that the kinds of operations that
programmers typically want to do on arrays, while sometimes very complex, can
often be decomposed into a set of fairly standard operations. This
decomposition has been similarly developed in many array languages. In some
ways, numarray is simply the application of this experience to the Python
language.  Thus many of the operations described in numarray work the way they
do because experience has shown that way to be a good one, in a variety of
contexts. The languages which were used to guide the development of numarray
include the infamous APL family of languages, Basis, MATLAB, FORTRAN, S and S+,
and others.  This heritage will be obvious to users of numarray who already
have experience with these other languages.  This manual, however, does not
assume any such background, and all that is expected of the reader is a
reasonable working knowledge of the standard Python language.

This document is the ``official'' documentation for numarray. It is both a
tutorial and the most authoritative source of information about numarray with
the exception of the source code. The tutorial material will walk you through a
set of manipulations of simple, small arrays of numbers. This choice was made
because:
\begin{itemize}
\item A concrete data set makes explaining the behavior of some functions much
   easier to motivate than simply talking about abstract operations on abstract
   data sets.
\item Every reader will have at least an intuition as to the meaning of the
   data and organization of image files.  \remark{These ``image files'' are not
      mentioned anywhere before, and not really used later...?}
\end{itemize}
All users of numarray, whether interested in image processing or not, are
encouraged to follow the tutorial with a working numarray installed,
testing the examples, and more importantly, transferring the
understanding gained by working on arrays to their specific domain. The best
way to learn is by doing --- the aim of this tutorial is to guide you along
this "doing."

This manual contains:
\begin{description}
\item[Installing numarray] Chapter \ref{cha:installation} provides information
   on testing Python, numarray, and compiling and installing numarray if
   necessary.
\item[High-Level Overview] Chapter \ref{cha:high-level-overview} gives a
   high-level overview of the components of the numarray system as a whole.
\item[Array Basics] Chapter \ref{cha:array-basics} provides a detailed
   step-by-step introduction to the most important aspect of numarray, the
   multidimensional array objects.
\item[Ufuncs] Chapter \ref{cha:ufuncs} provides information on universal
   functions, the mathematical functions which operate on arrays and other
   sequences elementwise.
\item[Pseudo Indices] Chapter \ref{cha:pseudo-indices} covers syntax for some
   special indexing operators.
\item[Array Functions] Chapter \ref{cha:array-functions} is a catalog of each
   of the utility functions which allow easy algorithmic processing of arrays.
\item[Array Methods] Chapter \ref{cha:array-methods} discusses the methods of
   array objects.
\item[Array Attributes] Chapter \ref{cha:array-attributes} presents the
   attributes of array objects.
\item[Character Array] Chapter \ref{cha:character-array} describes the
  \code{numarray.strings} module that provides support for arrays of fixed
  length strings.
\item[Record Array] Chapter \ref{cha:record-array} describes the
   \code{numarray.records} module that supports arrays of fixed length records
   of string or numerical data.
\item[Object Array] Chapter \ref{cha:object-array} describes the
   \code{numarray.objects} module that supports arrays of Python objects.
\item[C extension API] Chapter \ref{cha:C-API} describes the C-APIs provided
   for \module{numarray} based extension modules.
\item[Convolution] Chapter \ref{cha:convolve} describes the
   \module{numarray.convolve} module for computing one-D and two-D convolutions
   and correlations of \class{numarray} objects.
\item[Fast-Fourier-Transform] Chapter \ref{cha:fft} describes the
   \module{numarray.fft} module for computing Fast-Fourier-Transforms
   (FFT) and Inverse FFTs over \class{numarray} objects in one- or
   two-dimensional manner.  Ported from Numeric.
\item[Linear Algebra] Chapter \ref{cha:linear-algebra} describes the
   \module{numarray.linear_algebra} module which provides a simple
   interface to some commonly used linear algebra routines; 
   \program{LAPACK}.   Ported from Numeric.
\item[Masked Arrays] Chapter \ref{cha:masked-arrays} describes the
   \module{numarray.ma} module which supports Masked Arrays: arrays which
   potentially have missing or invalid elements.  Ported from Numeric.
\item[Random Numbers] Chapter \ref{cha:random-array} describes the
   \module{numarray.random_array} module which supports generation of arrays of
   random numbers.  Ported from Numeric.
\item[Multidimentional image analysis functions] Chapter \ref{cha:ndimage}
   describes the \module{numarray.ndimage} module which provides
   functions for multidimensional image analysis such as filtering,
   morphology or interpolation.
\item[Glossary] Appendix \ref{cha:glossary} gives a glossary of terms.
\end{description}


\section{Where to get information and code}

Numarray and its documentation are available at SourceForge
(\ulink{sourceforge.net}{http://sourceforge.net}; SourceForge addresses can
also be abbreviated as \ulink{sf.net}{http://sf.net}). The main web site is:
\url{http://numpy.sourceforge.net}. Downloads, bug reports, a patch facility,
and releases are at the main project page, reachable from the above site or
directly at: \url{http://sourceforge.net/projects/numpy} (see Numarray under
"Latest File Releases").  The Python web site is \url{http://www.python.org}.
For up-to-date status on compatible modules available for numarray, please 
check \url{http://www.stsci.edu/resources/software_hardware/numarray/}.

NOTE: because numarray shares the numpy Source Forge project with Numeric and
Numeric3, there are dedicated Source Forge ``Trackers'' for numarray, .e.g.
``Numarray Bugs'' rather than just ``Bugs''.  When submitting bug reports,
patches, or requests, please look for the numarray version of the tracker under
the top level menu item ``Tracker'', nominally here:
\url{http://sourceforge.net/tracker/?group_id=1369}.

\section{Acknowledgments}

Numerical Python was the outgrowth of a long collaborative design process
carried out by the Matrix SIG of the Python Software Activity (PSA). Jim
Hugunin, while a graduate student at MIT, wrote most of the code and initial
documentation. When Jim joined CNRI and began working on JPython, he didn't
have the time to maintain Numerical Python so Paul Dubois at LLNL agreed to
become the maintainer of Numerical Python. David Ascher, working as a
consultant to LLNL, wrote most of the Numerical Python version of this
document, incorporating contributions from Konrad Hinsen and Travis Oliphant,
both of whom are major contributors to Numerical Python.  The reimplementation
of Numeric as numarray was done primarily by Perry Greenfield, Todd Miller, and
Rick White, with some assistance from J.C. Hsu and Paul Barrett. Although
numarray is almost a completely new implementation, it owes a great deal to the
ideas, interface and behavior expressed in the Numeric implementation. It is
not an overstatement to say that the existence of Numeric made the
implementation of numarray far, far easier that it would otherwise have been.
Since the source for the original Numeric module was moved to SourceForge, the
numarray user community has become a significant part of the process.
Numeric/numarray illustrates the power of the open source software concept.
Please send comments and corrections to this manual to
\ulink{perry@stsci.edu}{mailto:perry@stsci.edu}, or to Perry Greenfield, 3700
San Martin Dr, Baltimore, MD 21218, U.S.A.




%% Local Variables:
%% mode: LaTeX
%% mode: auto-fill
%% fill-column: 79
%% indent-tabs-mode: nil
%% ispell-dictionary: "american"
%% reftex-fref-is-default: nil
%% TeX-auto-save: t
%% TeX-command-default: "pdfeLaTeX"
%% TeX-master: "numarray"
%% TeX-parse-self: t
%% End: