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

\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.

                
\input{version} % Get version info - this file may be modified by
                % update_anuga_user_manual.py - if not a dummy 
                % will be used.
                                

\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 For Python 2.5, install Python pre-requisites: Python2.5, 
  Scientific Python, Mingw, Numeric
  and the NetCDF library. Note: the scientific Python installation
  sometimes ends with an error message.  ANUGA still works though.
  These packages are available from:
  \begin{itemize} 
    \item The supplied ANUGA distribution folder; \begin{verbatim}
      pre_requisites\2.5
    \end{verbatim} 
    (Install in the order \code{python-2.5.msi}, 
     \code{Numeric-23.8.2.win32-py2.5.exe},
    \code{ScientificPython-2.7.8.win32-py2.5.exe},
      \code{MinGW-5.1.4.exe} and then unpack 
    \code{netcdf-3.6.1-beta1-win32dll.zip} into \code{C:\\\\bin} as 
    suggested below.
    \item The WEB:
    \begin{itemize}  
      \item Python2.5: 
      \url{http://www.python.org/download/}.
      \item Numeric Python: (Numeric-23.8.2.win32-py2.5.exe)\\
       \url{http://sourcesup.cru.fr/frs/?group\_id=180}
      \item Scientific Python: (ScientificPython-2.X.X.win32-py2.5.exe)\\
       \url{http://sourcesup.cru.fr/frs/?group_id=180}
      \item MinGW: (MinGW-5.X.X.exe)\\
       \url{http://sourceforge.net/project/showfiles.php?group_id=2435}
      \item NETCDF: download the file netcdf-3.6.1-beta1-win32dll.zip from 
      \url{http://www.unidata.ucar.edu/software/netcdf/binaries.html} 
      . 
      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 For Python 2.4,  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/projects/}.
      \item Scientific Python:\\
       \url{http://sourceforge.net/project/showfiles.php?group_id=172848}
      \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})\footnote{Internet explorer has the habit of renaming the .tgz files to .gz - the remedy is to rename them back or use another browser such as Firefox.} 
  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 '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):
    {\small \begin{verbatim}
        python test_all.py
    \end{verbatim}}
    ANUGA has been succesfully installed if the tests pass.
  \item To verify that ANUGA succesfully reproduces a series of validation 
  examples, go
  to the directory \code{anuga_validation\\automated_validation_tests} in 
  which you can run
  {\small \begin{verbatim}
      python validate_all.py
  \end{verbatim}}    
\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 directory \code{anuga\_demos} 
(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 run the ANUGA against the Okushiri Island wave tank validation dataset
%(\url{http://www.cee.cornell.edu/longwave})
%go to \code{anuga_validation}
% 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\footnote{Problems have been observed with 
  Python 2.5 and Numeric on 64 bit platforms. See 
  \url{https://datamining.anu.edu.au/anuga/ticket/221}} 
  \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/projects/}.

\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}