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

\documentclass{manual}

\title{ANUGA Installation Guide}

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

\usepackage{graphicx}


% 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 procedure 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 PC (XP or Vista) 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{Installation}

Below are the install procedures for Windows XP, Windows Vista and Linux.

\subsection{Quick install - Windows XP}
\label{sec:winxp}

This procedure assumes that you do not have python installed on the target machine.
If you do have a python installed already then skip the installation of python as
long as you have version 2.3 or later installed.

\begin{enumerate}  
  \item Install the support software.
    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 Execute \code{python-2.5.msi} to install python.
          \item Execute \code{Numeric-23.8.2.win32-py2.5.exe} to install Numeric Python.
          \item Execute \code{ScientificPython-2.7.8.win32-py2.5.exe} to install Scientific Python.
          \item Execute \code{MinGW-5.1.4.exe} to install MinGW.
        \end{enumerate} and then unpack \code{netcdf-3.6.1-win32dll.zip} into a folder that is available on the system path.
        We suggest unpacking it into \code{C:$\backslash$bin}.
      \item The Internet. Install in order:
        \begin{enumerate}  
          \item \url{http://www.python.org/download/}. 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.
          \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}.  Download and execute the file \code{MinGW-5.X.X.exe} to install the MinGW environment.
            Note that you need a working internet connection to install WinGW.
          \item \url{http://www.unidata.ucar.edu/software/netcdf/binaries.html}. 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:\Python25;C:\MingW\bin;C:\bin\end{verbatim}
    For details on how to do this under Windows please refer to Appendix \ref{sec:setwindowspath}.

    Note that if you have another version of python installed, 2.4  say, you would replace any
    \code{Python25} above with \code{Python24}.
    A similar replacement should be made in all following steps wherever you see \code{Python25}.

  \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$Python25$\backslash$Lib$\backslash$site-packages}.
    This is often done in Windows by double clicking on the \code{.tgz} file and then 'browse to' the destination directory.

  \item In the ANUGA root directory (\code{C:$\backslash$Python25$\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 (\code{C:$\backslash$Python25$\backslash$Lib$\backslash$site-packages$\backslash$anuga}),
    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
    \linebreak
    \code{anuga_validation$\backslash$automated_validation_tests} under the ANUGA root directory where you can run:
    \begin{verbatim}python validate_all.py\end{verbatim}
    This may take some time.

  \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 \code{.sww} files with the executable:
      \begin{verbatim}C:\Program Files\anuga_viewer\animate.exe\end{verbatim}        
      For details on how to do this under Windows please refer to Appendix \ref{sec:assocanimatesww}.
    \end{enumerate} 

    Try the demonstrations provided in the ANUGA directory \code{anuga\_demos} 
    (discussed in the ANUGA user manual at 
    \url{http://datamining.anu.edu.au/\%7Eole/anuga/user\%5Fmanual/anuga\%5Fuser\%5Fmanual.pdf})
    and view the resulting \code{.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.

\subsection{Quick install - Windows Vista}
\label{sec:winvista}

There has been one reported instance of ANUGA being installed successfully on Windows Vista.
The following steps should be read in conjunction with the windows XP procedures above:

\begin{enumerate}  
  \item Install \code{python-2.5.msi}.
  \item Add the directory \code{C:$\backslash$Python25} to the \code{PATH} environment variable (appendix \ref{sec:setwindowspath}).
  \item Install \code{Numeric-23.8.2.win32-py2.5.exe} (as administrator).
  \item Install \code{ScientificPython-2.7.8.win32-py2.5.exe} (as administrator).
  \item Install \code{MinGW-5.1.4.exe} (as administrator). Use the default package selection.  Don't use old packages and let it make fresh downloads.
  \item Unpack \code{netcdf-3.6.1-beta1-win32dll.zip} into \code{C:$\backslash$bin}.
  \item Add the directory \code{C:$\backslash$bin} to the \code{PATH} environment variable (appendix \ref{sec:setwindowspath}).
  \item Install \code{pysco-1.6.win32-py2.5.exe} (as administrator).
  \item Install \code{matplotlib-0.91.2.win32-py2.5.exe} (as administrator).
  \item Install \code{numpy-1.1.0-win32-superpack-python2.5.exe} (as administrator).
  \item Check that the system variable \code{PATH} contains
        \code{C:$\backslash$Python2.5;C:$\backslash$Python25$\backslash$DLLs;C:$\backslash$bin;C:$\backslash$MinGW$\backslash$bin}
        (appendix \ref{sec:setwindowspath}).
  \item Now follow the Windows XP install steps from the ANUGA source code install step.
\end{enumerate}

Some of the installed packages above are optional and may not be required, but this is the reported working install we have received.

\subsection{Quick install - Linux}
\label{sec:linux}

The procedure to install onto a Linux platform is targetted at a Debian-like Linux, such as Ubuntu.
If you use another Linux the overall procedure should be followed, although the details will vary.

This steps below assume that you do not have python installed on the target machine.
If you do have a python installed already then skip the installation of python as
long as you have version 2.3 or later.

Note that even if you already have python installed you should still check if things like 
\code{python-dev} and \code{python-profiler} need to be installed.

\begin{itemize}
  \item Install support software (in order):
    \begin{enumerate}  
      \item Install python development environment, either through Synaptic or by:
        \begin{verbatim}sudo apt-get install python python-dev python-profiler\end{verbatim}
      \item Install Numeric Python, either through Synaptic or by:
        \begin{verbatim}sudo apt-get install python-numeric\end{verbatim}
      \item Install Scientific Python, either through Synaptic or by:
        \begin{verbatim}sudo apt-get install python-scientific\end{verbatim}
      \item Install NetCDF, either through Synaptic or by:
        \begin{verbatim}sudo apt-get install python-netcdf\end{verbatim}
      \item Install \code{gcc} and it's development environment if you don't have it, either through Synaptic or by:
        \begin{verbatim}sudo apt-get install gcc libc6-dev\end{verbatim}
        Ensure that \code{libc6-dev} is installed even if \code{gcc} is already installed.
    \end{enumerate}   
  \item Get the ANUGA source from \url{http://sourceforge.net/projects/anuga} (\code{anuga-1.0_5789.tgz} say),
    and expand it into the python site-packages directory \code{/usr/lib/python2.5/site-packages}.
    In the unpacked ANUGA directory \code{/usr/lib/python2.5/site-packages/anuga_core} run the command:
    \begin{verbatim}sudo python compile_all.py\end{verbatim}
\end{itemize}

\section{Optional but recommended software}
This software is not required to run the ANUGA toolbox, but it is recommended.
\begin{itemize}
  \item psyco. Speeds up ANUGA by about 30\%. Under Ubuntu install either through Synaptic or by:
    \begin{verbatim}sudo apt-get install python-psyco\end{verbatim}
    Under Windows install the file \code{psyco-1.6.win32-py25.exe}
    which you can find from the \url{http://psyco.sourceforge.net/download.html} page.
  \item matplotlib. For quality 2d plotting (moving towards mandatory requirement). Under Ubuntu install either through Synaptic or by:
    \begin{verbatim}sudo apt-get install python-matplotlib\end{verbatim}
    Under Windows install the file \code{matplotlib-0.98.3.win32-py2.5.exe}
    which you can find from the \url{http://sourceforge.net/projects/matplotlib} page.
  \item VTK. The Visualization Toolkit. Under Ubuntu install either through Synaptic or by:
    \begin{verbatim}sudo apt-get install python-vtk\end{verbatim}
    Under Windows install the file \code{vtk-5.2.0-win32.exe}
    from the \url{http://www.vtk.org/get-software.php} page.
\end{itemize}



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


\appendix
\chapter{Miscellaneous procedures}
\section{Setting the PATH on Windows}
\label{sec:setwindowspath}

The method of setting the PATH environment variable for Windows XP is shown here.
Setting the variable for Windows Vista should be similar.

\setlength\fboxsep{0pt}
\setlength\fboxrule{1.0pt}

First, open the Control Panel:
\begin{figure}[ht]
  \centerline{\fbox{\includegraphics[scale=0.75]{installgraphics/winsetpath1.png}}}
%  \caption{Run Control Panel from the Start menu}
  \label{fig:winsetpath1}
\end{figure}

Next, start the System applet:
\begin{figure}[ht]
  \centerline{\fbox{\includegraphics[scale=0.75]{installgraphics/winsetpath2.png}}}
%  \caption{Start the System applet}
  \label{fig:winsetpath2}
\end{figure}

\pagebreak

Select the \code{Advanced} tab in the System Properties window:
\begin{figure}[ht]
  \centerline{\includegraphics[scale=0.5]{installgraphics/winsetpath3.png}}
%  \caption{Select the Advanced tab}
  \label{fig:winsetpath3}
\end{figure}

%\pagebreak

Press the \code{Environment Variables} button in the \code{Advanced} tab:
\begin{figure}[ht]
  \centerline{\includegraphics[scale=0.5]{installgraphics/winsetpath4.png}}
%  \caption{Press the Environment Variables button}
  \label{fig:winsetpath4}
\end{figure}

\pagebreak

If the \code{PATH} variable is not defined in the top window, press the \code{New} button.
If \code{PATH} already exists, select the row with the \code{PATH} variable name in the top listbox
and press the \code{Edit} button next to the \code{New} button:
\begin{figure}[ht]
  \centerline{\includegraphics[scale=0.5]{installgraphics/winsetpath5.png}}
%  \caption{Press the New button}
  \label{fig:winsetpath5}
\end{figure}

%\pagebreak

You will be shown the editor window whichever button you pressed in the above step. If the \code{Variable name} box is empty
type in the name \code{PATH}.  In the \code{Variable value} box type the value you want the \code{PATH} variable to have.  If there
is already some text in the box, place your additional value at the front of the existing value, not forgetting to terminate your additional
string with the ';' character. The final value string must be a series of directory names seperated by ';' characters:
\begin{figure}[ht]
  \centerline{\includegraphics[scale=0.75]{installgraphics/winsetpath6.png}}
%  \caption{Modifying the PATH value}
  \label{fig:winsetpath6}
\end{figure}

When you are finished, press the \code{OK} button and exit from the applet.

\pagebreak

\section{Associating animate.exe with a .sww file}
\label{sec:assocanimatesww}

The method of associating \code{animate.exe} with a \code{.sww} file is shown here for Windows XP.
A similar process should work for Windows Vista.

Double left-click on any \code{.sww} file.  This brings up a dialog because Windows doesn't know how to open the file:
\begin{figure}[ht]
  \centerline{\fbox{\includegraphics[scale=0.5]{installgraphics/winassoc1.png}}}
%  \caption{Try to open the .sww file}
  \label{fig:winassoc1}
\end{figure}

Select the "\code{Select the program from a list}" radiobutton and press the \code{OK} button:
\begin{figure}[ht]
  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc2.png}}
%  \caption{Select the program from a list}
  \label{fig:winassoc2}
\end{figure}

\pagebreak

Press the \code{Browse...} button to find the \code{animate.exe} program:
\begin{figure}[ht]
  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc3.png}}
%  \caption{Find animate.exe program}
  \label{fig:winassoc3}
\end{figure}

Navigate to the \code{C:$\backslash$Program Files$\backslash$anuga_viewer} directory:
\begin{figure}[ht]
  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc4.png}}
%  \caption{Navigate into Program Files|anuga_viewer directory}
  \label{fig:winassoc4}
\end{figure}

\pagebreak

Select \code{animate.exe} and press the \code{Open} button:
\begin{figure}[ht]
  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc5.png}}
%  \caption{Select the animate.exe program press Open}
  \label{fig:winassoc5}
\end{figure}

Finally, press the \code{OK} button:
\begin{figure}[ht]
  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc6.png}}
%  \caption{Press the OK button}
  \label{fig:winassoc6}
\end{figure}


\end{document}