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

\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 ATI FireGL X1 cards
and the NVIDIA family. It may not work with other 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: Python2.5, Scientific Python, Mingw, Numeric
    and the NetCDF library. Note that the scientific Python installation
    sometimes ends with an error message, although ANUGA still works.
    These packages are available from either:
    \begin{itemize} 
      \item The supplied ANUGA distribution folder: \code{pre_requisites$\backslash$2.5} .
        Install in order:
        \begin{enumerate}
          \item \code{python-2.5.msi}
          \item \code{Numeric-23.8.2.win32-py2.5.exe}
          \item \code{ScientificPython-2.7.8.win32-py2.5.exe}
          \item \code{MinGW-5.1.4.exe}
        \end{enumerate} and then unpack \code{netcdf-3.6.1-win32.zip} into \code{C:$\backslash$bin} as suggested below.
      \item The WEB. Install in order:
          \begin{enumerate}  
              \item \url{http://www.python.org/download/} and click on the \code{Python 2.5.x Windows installer} link to get
                \code{python-2.5.x.msi}. Execute this file to install Python 2.5.
              \item \url{http://sourcesup.cru.fr/frs/?group\%5Fid=180}. Download \code{Numeric-23.8.2.win32-py2.5.exe}
                and execute it to install Numeric Python.
              \item \url{http://sourcesup.cru.fr/frs/?group\%5Fid=180}. Download \code{ScientificPython-2.X.X.win32-py2.5.exe}
                and execute it to install Scientific Python.
              \item \url{http://sourceforge.net/project/showfiles.php?group\%5Fid=2435}. Click on the \code{Download} link for
                the \code{Automated MinGW Installer} package. Execute the file \code{MinGW-5.X.X.exe} to install the MinGW environment.
                Note that you will need a working internet connection to install WinGW.
              \item \url{http://www.unidata.ucar.edu/software/netcdf/binaries.html} and click on the 
                "\code{Windows DLL}" link in the NetCDF 3.6.1 section.  This will download the file \code{netcdf-3.6.1-win32.zip}.
                Unpack this in a folder that is available on the system path. 
                We suggest unpacking it into \code{C:$\backslash$bin}.
          \end{enumerate}   
    \end{itemize}   
  
  \item For Python 2.4, install: 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, under the folder \code{pre_requisites} .
        Install in order:
        \begin{enumerate}
          \item enthon-python2.4-1.0.0.exe
          \item ScientificPython-2.4.9.win32-py2.4.exe
        \end{enumerate}
        and then unpack \code{netcdf-3.6.1-beta1-win32dll.zip} into \code{C:$\backslash$bin} as suggested below.
      \item The WEB. Install in order:
      \begin{enumerate}  
        \item \url{http://code.enthought.com/projects/} and install the Enthought environment for Python 2.4.x.
        \item \url{http://sourceforge.net/project/showfiles.php?group\%5Fid=172848}. Click on the \code{Download} link for Scientific Python
          and download \code{ScientificPython-2.4.9.win32-py2.4.exe} which will install Scientific Python.
        \item \url{http://www.unidata.ucar.edu/software/netcdf/binaries.html} and click on the 
          "\code{Windows DLL}" link in the NetCDF 3.6.1 section.  This will download the file \code{netcdf-3.6.1-win32.zip}.
          Unpack this in a folder that is available on the system path. We suggest unpacking it into \code{C:$\backslash$bin} .
      \end{enumerate}   
    \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}
    For details on how to do this under windows please refer to Section \ref{sec:windowspath}.

  \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 running it in IDLE):
    \begin{verbatim}python compile_all.py\end{verbatim}

  \item In the ANUGA root directory, run the test suite (either from the commandline or by running it in IDLE):
    \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$\backslash$automated_validation_tests} in which you can run
    \begin{verbatim}python validate_all.py\end{verbatim}


  \item To install the ANUGA viewer:
    \begin{enumerate} 
      \item Unpack the distribution (\code{anuga_viewer_1.0.tgz}) into
        \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 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} 
    (discussed in the ANUGA user manual 
    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.
\end{enumerate}   


%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:$\backslash$Python24$\backslash$Lib$\backslash$site-packages})

In the ANUGA root directory (\code{C:$\backslash$Python24$\backslash$Lib$\backslash$site-packages$\backslash$anuga}), 
run the compilation script:
\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:
\begin{verbatim}
python test_all.py
\end{verbatim}
ANUGA has been succesfully installed if the tests pass as follows:
\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}


\chapter{Appendix}
\section{Setting the PATH on Windows}
\label{sec:windowspath}



\end{document}