\chapter{Installing numarray}
\label{cha:installation}

\begin{quote}
   This chapter explains how to install and test numarray, from either the
   source distribution or from the binary distribution.
\end{quote}

Before we start with the actual tutorial, we will describe the steps needed for
you to be able to follow along the examples step by step. These steps include
installing and testing Python, the numarray extensions, and some tools and
sample files used in the examples of this tutorial.


\section{Testing the Python installation}

The first step is to install Python if you haven't already. Python is available
from the Python project page at \url{http://sourceforge.net/projects/python}.
Click on the link corresponding to your platform, and follow the instructions
described there. Unlike earlier versions of numarray, version 0.7 and later
require Python version 2.2.2 at a minimum.  When installed, starting Python by
typing python at the shell or double-clicking on the Python interpreter should
give a prompt such as:
\begin{verbatim}
Python 2.3 (#2, Aug 22 2003, 13:47:10) [C] on sunos5
Type "help", "copyright", "credits" or "license" for more information.
\end{verbatim}
If you have problems getting this part to work, consider contacting a local
support person or emailing
\ulink{python-help@python.org}{mailto:python-help@python.org} for help. If
neither solution works, consider posting on the
\ulink{comp.lang.python}{news:comp.lang.python} newsgroup (details on the
newsgroup/mailing list are available at
\url{http://www.python.org/psa/MailingLists.html\#clp}).


\section{Testing the Numarray Python Extension Installation}

The standard Python distribution does not come, as of this writing, with the
numarray Python extensions installed, but your system administrator may have
installed them already. To find out if your Python interpreter has numarray
installed, type \samp{import numarray} at the Python prompt. You'll see one of
two behaviors (throughout this document user input and python interpreter
output will be emphasized as shown in the block below):
\begin{verbatim}
>>> import numarray
Traceback (innermost last):
File "<stdin>", line 1, in ?
ImportError: No module named numarray
\end{verbatim}
indicating that you don't have numarray installed, or:
\begin{verbatim}
>>> import numarray
>>> numarray.__version__
'0.6'
\end{verbatim}
indicating that you do. If you do, you can skip the next section
and go ahead to section \ref{sec:at-sourceforge}.  If you don't, you have to
get and install the numarray extensions as described in section
\ref{sec:installing-numarray}.

\section{Installing numarray}
\label{sec:installing-numarray}

The release facility at SourceForge is accessed through the project page,
\url{http://sourceforge.net/projects/numpy}.  Click on the "Numarray" release
and you will be presented with a list of the available files. The files whose
names end in ".tar.gz" are source code releases. The other files are binaries
for a given platform (if any are available).

It is possible to get the latest sources directly from our CVS repository using
the facilities described at SourceForge. Note that while every effort is made
to ensure that the repository is always ``good'', direct use of the repository
is subject to more errors than using a standard release.


\subsection{Installing on Unix, Linux, and Mac OSX}
\label{sec:installing-unix}

The source distribution should be uncompressed and unpacked as follows (for
example):
\begin{verbatim}
gunzip numarray-0.6.tar.gz
tar xf numarray-0.6.tar
\end{verbatim}
Follow the instructions in the top-level directory for compilation and
installation. Note that there are options you must consider before beginning.
Installation is usually as simple as:
\begin{verbatim}
python setup.py install
\end{verbatim}
or:
\begin{verbatim}
python setupall.py install
\end{verbatim}
if you want to install all additional packages, which include
\module{\mbox{numarray.convolve}}, \module{\mbox{numarray.fft}},
\module{\mbox{numarray.linear_algebra}}, and
\module{\mbox{numarray.random_array}}.

See numarray-X.XX/Doc/INSTALL.txt for the latest details (X.XX is the version 
number).

\paragraph*{Important Tip} \label{sec:tip:from-numarray-import} Just like all
Python modules and packages, the numarray module can be invoked using either
the \samp{import numarray} form, or the \samp{from numarray import ...} form.
Because most of the functions we'll talk about are in the numarray module, in
this document, all of the code samples will assume that they have been preceded
by a statement:
\begin{verbatim}
>>> from numarray import *
\end{verbatim}
Note the lowercase name in \module{\numarray} as opposed to \module{\numpy}.


\subsection{Installing on Windows}
\label{sec:installing-windows}

To install numarray, you need to be in an account with Administrator
privileges.  As a general rule, always remove (or hide) any old version of
numarray before installing the next version.

We have tested Numarrray on several Win-32 platforms including:
   
\begin{itemize}
\item Windows-XP-Pro-x86 ( MSVC-6.0) 
\item Windows-NT-x86 (MSVC-6.0) 
\item Windows-98-x86 (MSVC-6.0)
\end{itemize}

\subsubsection{Installation from source}

\begin{enumerate}
\item Unpack the distribution: (NOTE: You may have to download an "unzipping"
   utility)
\begin{verbatim}
C:\> unzip numarray.zip 
C:\> cd numarray
\end{verbatim}
\item Build it using the distutils defaults:
\begin{verbatim}
C:\numarray> python setup.py install
\end{verbatim}
   This installs numarray in \texttt{C:\textbackslash{}pythonXX} where XX is the version
   number of your python installation, e.g. 20, 21, etc.
\end{enumerate}


\subsubsection{Installation from self-installing executable}

\begin{enumerate}
\item Click on the executable's icon to run the installer.
\item Click "next" several times.  I have not experimented with customizing the
   installation directory and don't recommend changing any of the installation
   defaults.  If you do and have problems, let us know.
\item Assuming everything else goes smoothly, click "finish".
\end{enumerate}


\subsubsection{Testing your Installation}

Once you have installed numarray, test it with:
\begin{verbatim}
C:\numarray> python
Python 2.2.2 (#18, Dec 30 2002, 02:26:03) [MSC 32 bit (Intel)] on win32
Type "copyright", "credits" or "license" for more information.
>>> import numarray.testall as testall
>>> testall.test()
numeric:  (0, 1115)
records:  (0, 48)
strings:  (0, 166)
objects:  (0, 72)
memmap:  (0, 75)
\end{verbatim}
Each line in the above output indicates that 0 of X tests failed.  X grows
steadily with each release, so the numbers shown above may not be current.


\subsubsection{Installation on Cygwin}

For an installation of numarray for python running on Cygwin, see section
\ref{sec:installing-unix}.



\section{At the SourceForge...}
\label{sec:at-sourceforge}

The SourceForge project page for numarray is at
\url{http://sourceforge.net/projects/numpy}. On this project page you will find
links to:
\begin{description}
\item[The Numpy Discussion List] You can subscribe to a discussion list about
   numarray using the project page at SourceForge. The list is a good place to
   ask questions and get help. Send mail to
   numpy-discussion@lists.sourceforge.net.  Note that there is no
   numarray-discussion group, we share the list created by the numeric community.

\item[The Web Site] Click on "home page" to get to the Numarray Home Page,
   which has links to documentation and other resources, including tools for
   connecting numarray to Fortran.
\item[Bugs and Patches] Bug tracking and patch-management facilities is
   provided on the SourceForge project page.
\item[CVS Repository] You can get the latest and greatest (albeit less tested
   and trustworthy) version of numarray directly from our CVS repository.
\item[FTP Site] The FTP Site contains this documentation in several formats,
   plus maybe some other goodies we have lying around.
\end{description}



%% 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: