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

\documentclass{manual}


\title{ANUGA Installation Guide}

\author{Howard Silcock, 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.


\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
    \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 \url{ftp://ftp.unidata.ucar.edu/pub/netcdf/contrib/win32/netcdf-3.6.1-beta1-win32dll.zip}
    \end{itemize}   
  \end{itemize}   
  
  \item Add the following to the PATH environment variable
    \begin{verbatim}
      PATH=C:\Python24;C:\Python24\Enthought\MingW\bin;C:\Program Files\anuga_viewer
    \end{verbatim} 
  \item Unpack the ANUGA source code (\code{anuga-1.0_xxxx.tgz}) 
  in the python site-packages 
  directory \code{C:\\Python24\\Lib\\site-packages}
  \item In the ANUGA root directory (\code{C:\\Python24\\Lib\\site-packages\\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:
    {\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 Associate .sww files with the executable
  \begin{verbatim} 
    C:\Program Files\anuga_viewer\animate.exe
  \end{verbatim}        
  \item Double click on the test file 
    \begin{verbatim} 
      C:\Program Files\anuga_viewer\cylinders.sww
    \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/index.cfm?page=benchmark&problem=2})
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}
\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:


\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}
  %\item visual python \url{http://vpython.org}
  \item matplotlib (pylab) for quality 2d plotting (moving towards mandatory requirement)
  \item VTK \url{http://mayavi.sourceforge.net/dwnld/vtk/win32/}
\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}