source: anuga_core/documentation/user_manual/anuga_installation_guide.tex @ 4638

\documentclass{manual}


\title{ANUGA Installation Guide}

\author{Ole Nielsen, Duncan Gray, Jane Sexton}

% Please at least include a long-lived email address;
% the rest is at your discretion.
\authoraddress{Geoscience Australia \\
  Email: \email{ole.nielsen@ga.gov.au}
}

%Draft date
\date{\today}                   % update before release!
                % Use an explicit date so that reformatting
                % doesn't cause a new date to be used.  Setting
                % the date to \today can be used during draft
                % stages to make it easier to handle versions.

\release{1.0}           % release version; this is used to define the
                % \version macro

\makeindex          % tell \index to actually write the .idx file
%\makemodindex          % If this contains a lot of module sections.



\begin{document}
\maketitle



% This makes the contents more accessible from the front page of the HTML.
\ifhtml
\chapter*{Front Matter\label{front}}
\fi




\chapter{Introduction}

This document outlines the required software for installing the Anuga toolbox.
All components are licensed as open source and readily available from the net.
It is assumed that the reader is familiar with the Python programming language and the process of downloading, installing and unpacking files into directories.


\section{System requirements}
\label{sec:requirements}

To run ANUGA you will need a Windows (2000 or XP) or a Linux PC with at 
least 512MB RAM. The viewer (Windows only) requires a graphics adapter that
is OpenGL compatible. It has been tested with e.g. ATI FireGL X1 
and the NVIDIA family. It may not work with cards such as those from the 
Intel(R) 82915G Express Chipset Family.



\section{Quick install (Windows only)}

This section provides the quickest path to getting ANUGA up and running on a Windows machine. 
For Linux and for more details please refer to Section \ref{sec:prerequisites}.

\begin{enumerate}  
 
  \item Install Python pre-requisites: The Enthought version of Python2.4, Scientific Python 
  and the NetCDF library\footnote{Separate installation of Scientific Python and NetCDF 
  will become unneccesary once Enthought sorts out netcdf support 
  (see \url{https://svn.enthought.com/enthought/ticket/917})}. These are available from either 
  \begin{itemize} 
    \item The supplied ANUGA distribution as under the folder pre_requisites (Install in the order \code{enthon-python2.4-1.0.0.exe}, 
    \code{ScientificPython-2.4.9.win32-py2.4.exe} and the unpack \code{netcdf-3.6.1-beta1-win32dll.zip} into \code{C:\bin} as suggested below.
    \item The WEB:
    \begin{itemize}  
      \item Enthought version of Python2.4: \url{http://code.enthought.com/enthon/}.
      \item Scientific Python:\\
       \url{http://sourcesup.cru.fr/frs/download.php/745/ScientificPython-2.4.9.win32-py2.4.exe}
      \item NETCDF: download the file netcdf-3.6.1-beta1-win32dll.zip from 
      \url{http://www.unidata.ucar.edu/software/netcdf/binaries.html} (\url{ftp://ftp.unidata.ucar.edu/pub/netcdf/contrib/win32/netcdf-3.6.1-beta1-win32dll.zip}). Unpack this in a folder that is available on the system path. We suggest unpacking it into 
      \begin{verbatim} 
      C:\bin
      \end{verbatim}  
    \end{itemize}   
  \end{itemize}   
  
  \item Add the following to the PATH environment variable
    \begin{verbatim}
      PATH=C:\Python24;C:\Python24\Enthought\MingW\bin;C:\bin
    \end{verbatim}   %C:\Program Files\anuga_viewer;
  \item Unpack the ANUGA source code (\code{anuga-1.0_xxxx.tgz}) 
  in the python site-packages 
  directory \code{C:$\backslash$Python24$\backslash$Lib$\backslash$site-packages}. This is often done in Windows by 
  double clicking on the tgz file and then select 'browse to' the destination directory.
  \item In the ANUGA root directory (\code{C:$\backslash$Python24$\backslash$Lib$\backslash$site-packages$\backslash$anuga}), 
  run the compilation script (either from the commandline or by clicking on it):
    {\small \begin{verbatim}
        python compile_all.py
    \end{verbatim}}
  \item In the ANUGA root directory, run the test suite (e.g. by opening it with IDLE 
  and running the file)\footnote{If run on the commandline, this test suite will cause an error that has to do 
  with the atexit.py functionality of the logger. As long as all tests pass OK, you can safely ignore that error.}:
    {\small \begin{verbatim}
        python test_all.py
    \end{verbatim}}
    ANUGA has been succesfully installed if the tests pass.
\end{enumerate}   

To install the anuga\_viewer
\begin{enumerate} 
  \item Unpack the distribution (\code{anuga_viewer_1.0.tgz}) in 
    \begin{verbatim} 
      C:\Program Files
    \end{verbatim}
  \item Double click on the test file
    \begin{verbatim} 
      C:\Program Files\anuga_viewer\cylinders.sww
    \end{verbatim}        
  \item and associate .sww files with the executable
  \begin{verbatim} 
    C:\Program Files\anuga_viewer\animate.exe
  \end{verbatim}        
\end{enumerate} 

Try the demos provided in the ANUGA root directory 
(also discussed in the ANUGA user manual available with the distribution and also at 
\url{http://datamining.anu.edu.au/~ole/anuga/user_manual/anuga_user_manual.pdf}) and 
view the resulting sww files with the anuga\_viewer.

To verify that the installed version of ANUGA validates satisfactorily
against the Okushiri Island wave tank validation dataset
(\url{http://www.cee.cornell.edu/longwave})
unpack the distribution (\code{anuga_validation_1.0_xxxx.tgz}) into
any directory and run the scripts \code{create_okushiri.py},
\code{run_okushiri.py} and \code{compare_timeseries.py}.  See also the
\code{README.txt} file that comes with the validation scripts for more
details.


\clearpage
\section{Pre-requisites (software)}
\label{sec:prerequisites}

This and the following sections is for custom installations and 
installations using Linux.

The ANUGA software core (shallow\_water, pmesh, least\_squares, ...) depends on the following software:
\begin{itemize}
  \item python 2.3 or later \url{http://www.python.org}/footnote{Note, the
  dll python2X.dll is needed to compile ANUGA, but is not always
  automatically added for versions 2.4 and above.  Install it into the
  python2X directory, if you need it.}.  
  \item python-numeric for Linux.  It's called Numeric in Windows.  
  %\item python-dev (Interestingly, numeric seems to be installed as
  %well) for Linux.  This is not necessary for Windows.
  \item python-scientific (to provide python-netcdf) for Linux.  It's
    called ScientificPython in Windows.
  \item NETCDF.  Extract the file netcdf.dll, and put in C://Windows//System32// (Windows XP) or C://WINNT//System32 (Windows NT or 2000).     
  \item A C compiler such as gcc (from GNU in case of Linux and MinGW
  in case of Windows)
  %\item scons for automatically compiling the distribution.
\end{itemize}

Note: All of these can be installed in one go on Windows platforms by using the Enthought Python 
distribution available at \url{http://code.enthought.com/enthon/}.

\section{Recommended software}

\begin{itemize}
  \item psyco \url{http://psyco.sourceforge.net/index.html}: Speeds up anuga by about 30\%.
  %\item visual python \url{http://vpython.org}
  \item matplotlib (pylab) for quality 2d plotting (moving towards mandatory requirement and now part of Enthought.)
  \item VTK \url{http://mayavi.sourceforge.net/dwnld/vtk/win32/} - also now part of Enthought.
\end{itemize}



\section{System configuration}


The system path on Win32 architectures must contain the directories (this examples assumes the 
Enthought Python 2.4 distribution has been installed. Path names may vary depending on the 
exact configuration).
\begin{verbatim}
  PATH=C:\Python24;C:\Python24\Enthought\MingW\bin;C:\Program Files\anuga_viewer
\end{verbatim}
The path should be analoguous for Unix operating systems.

If anuga is not installed in the python site-packages directory the root directory for all 
anuga/inundation modules must be on the pythonpath, e.g.\
\begin{verbatim}
PYTHONPATH=C:\anuga_core\source
\end{verbatim}





\section{Installation of source zip file}
Get a source zip file, for example, anuga_source_3807.zip, and expand
it in the python site-packages directory (\code{C:\\Python24\\Lib\\site-packages})

In the ANUGA root directory (\code{C:\\Python24\\Lib\\site-packages\\anuga}), 
run the compilation script:
{\small \begin{verbatim}
  python compile_all.py
\end{verbatim}}

%or (in anuga_core)
% scons install 
% scons -c #(clean)


\subsection{Testing}

In the ANUGA root directory, run the test suite:
{\small \begin{verbatim}
  python test_all.py
\end{verbatim}}
ANUGA has been succesfully installed if the tests pass as follows:

{\tiny
\begin{verbatim}
  ...
  test_data_manager.py
  test_interpolate_sww.py
  test_mesh.py
  test_mesh_interface.py
  test_triangmodule.py
  test_triangmoduleII.py
  test_advection.py
............................................................................................................................................
............................................................................................................................................
............................................................................................................................................
............................................................................................................................................
.................................
----------------------------------------------------------------------
Ran 593 tests in 42.712s

OK
\end{verbatim} }



%\section{Other stuff to be included}
%
%\begin{verbatim}
%Install tortoise from downloads (ITs didn't integrate wih explorer).
%In settings set proxy to proxy.agso.gov.au  8080
%%
%
%Install swollen from latest distro (in subversion)
%
%
%\end{verbatim}





\end{document}