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

Last change on this file since 5771 was 5771, checked in by rwilson, 16 years ago
  • Property svn:keywords set to LastChangedDate LastChangedRevision LastChangedBy HeadURL Id
File size: 12.0 KB
Line 
1\documentclass{manual}
2
3
4\title{ANUGA Installation Guide}
5
6\author{Ole Nielsen, Duncan Gray, Jane Sexton}
7
8% Please at least include a long-lived email address;
9% the rest is at your discretion.
10\authoraddress{Geoscience Australia \\
11  Email: \email{ole.nielsen@ga.gov.au}
12}
13
14%Draft date
15\date{\today}                   % update before release!
16                % Use an explicit date so that reformatting
17                % doesn't cause a new date to be used.  Setting
18                % the date to \today can be used during draft
19                % stages to make it easier to handle versions.
20
21               
22\input{version} % Get version info - this file may be modified by
23                % update_anuga_user_manual.py - if not a dummy
24                % will be used.
25                               
26
27\makeindex          % tell \index to actually write the .idx file
28%\makemodindex          % If this contains a lot of module sections.
29
30
31
32\begin{document}
33\maketitle
34
35
36
37% This makes the contents more accessible from the front page of the HTML.
38\ifhtml
39\chapter*{Front Matter\label{front}}
40\fi
41
42
43
44
45\chapter{Introduction}
46
47This document outlines the required software for installing the Anuga toolbox.
48All components are licensed as open source and readily available from the net.
49It is assumed that the reader is familiar with the Python programming language and the process of downloading, installing and unpacking files into directories.
50
51
52\section{System requirements}
53\label{sec:requirements}
54
55To run ANUGA you will need a Windows (2000 or XP) or a Linux PC with at
56least 512MB RAM. The viewer (Windows only) requires a graphics adapter that
57is OpenGL compatible. It has been tested with e.g. ATI FireGL X1
58and the NVIDIA family. It may not work with cards such as those from the
59Intel(R) 82915G Express Chipset Family.
60
61
62
63\section{Quick install (Windows only)}
64
65This section provides the quickest path to getting ANUGA up and running on a Windows machine.
66For Linux and for more details please refer to Section \ref{sec:prerequisites}.
67
68\begin{enumerate} 
69 
70  \item For Python 2.5, install Python pre-requisites: Python2.5,
71  Scientific Python, Mingw, Numeric
72  and the NetCDF library. Note that the scientific Python installation
73  sometimes ends with an error message, although ANUGA still works.
74  These packages are available from:
75  \begin{itemize} 
76    \item The supplied ANUGA distribution folder: \code{pre_requisites\textbackslash 2.5} .
77      Install in the order
78      \begin{verbatim} 
79python-2.5.msi
80Numeric-23.8.2.win32-py2.5.exe
81ScientificPython-2.7.8.win32-py2.5.exe
82MinGW-5.1.4.exe
83      \end{verbatim} 
84      and then unpack \code{netcdf-3.6.1-win32.zip} into \code{C:\\bin} as suggested below.
85    \item The WEB:
86        \begin{itemize} 
87            \item Python2.5: \url{http://www.python.org/download/}.
88            \item Numeric Python: (Numeric-23.8.2.win32-py2.5.exe) \url{http://sourcesup.cru.fr/frs/?group_id=180}
89            \item Scientific Python: (ScientificPython-2.X.X.win32-py2.5.exe) \url{http://sourcesup.cru.fr/frs/?group_id=180}
90            \item MinGW: (MinGW-5.X.X.exe) \url{http://sourceforge.net/project/showfiles.php?group_id=2435}
91            \item NETCDF: Go to \url{http://www.unidata.ucar.edu/software/netcdf/binaries.html} and click on the
92              \code{Windows DLL} link in the NetCDF 3.6.1 section.  This will download the file
93              \code{netcdf-3.6.1-win32.zip} .
94              Unpack this in a folder that is available on the system path.
95              We suggest unpacking it into \code{C:\textbackslash bin} .
96        \end{itemize}   
97  \end{itemize}   
98 
99 
100  \item For Python 2.4, install Python pre-requisites: The Enthought version of Python2.4,
101  Scientific Python
102  and the NetCDF library\footnote{Separate installation of Scientific
103  Python and NetCDF
104  will become unneccesary once Enthought sorts out netcdf support
105  (see \url{https://svn.enthought.com/enthought/ticket/917})}.
106  These are available from either
107  \begin{itemize} 
108    \item The supplied ANUGA distribution as under the folder pre_requisites
109    (Install in the order \code{enthon-python2.4-1.0.0.exe},
110    \code{ScientificPython-2.4.9.win32-py2.4.exe} and the unpack
111    \code{netcdf-3.6.1-beta1-win32dll.zip} into \code{C:\textbackslash bin} as
112    suggested below.
113    \item The WEB:
114    \begin{itemize} 
115      \item Enthought version of Python2.4:
116      \url{http://code.enthought.com/projects/}.
117      \item Scientific Python:\\
118       \url{http://sourceforge.net/project/showfiles.php?group_id=172848}
119      \item NETCDF: download the file netcdf-3.6.1-beta1-win32dll.zip from
120      \url{http://www.unidata.ucar.edu/software/netcdf/binaries.html} 
121      (\url{ftp://ftp.unidata.ucar.edu/pub/netcdf/contrib/win32/netcdf-3.6.1-beta1-win32dll.zip}).
122      Unpack this in a folder that is available on the system path.
123      We suggest unpacking it into
124      \begin{verbatim} 
125      C:\bin
126      \end{verbatim} 
127    \end{itemize}   
128  \end{itemize}   
129 
130  \item Add the following to the PATH environment variable
131    \begin{verbatim}
132      PATH=C:\Python24;C:\Python24\Enthought\MingW\bin;C:\bin
133    \end{verbatim}   %C:\Program Files\anuga_viewer;
134  \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.} 
135  in the python site-packages
136  directory \code{C:$\backslash$Python24$\backslash$Lib$\backslash$site-packages}. This is often done in Windows by
137  double clicking on the .tgz file and then 'browse to' the
138  destination directory.
139  \item In the ANUGA root directory (\code{C:$\backslash$Python24$\backslash$Lib$\backslash$site-packages$\backslash$anuga}),
140  run the compilation script (either from the commandline or by clicking on it):
141    {\small \begin{verbatim}
142        python compile_all.py
143    \end{verbatim}}
144  \item In the ANUGA root directory, run the test suite
145  (e.g. by opening it with IDLE and running the file):
146    {\small \begin{verbatim}
147        python test_all.py
148    \end{verbatim}}
149    ANUGA has been succesfully installed if the tests pass.
150  \item To verify that ANUGA succesfully reproduces a series of validation
151  examples, go
152  to the directory \code{anuga_validation\\automated_validation_tests} in
153  which you can run
154  {\small \begin{verbatim}
155      python validate_all.py
156  \end{verbatim}}   
157\end{enumerate}   
158
159
160
161
162To install the anuga\_viewer
163\begin{enumerate} 
164  \item Unpack the distribution (\code{anuga_viewer_1.0.tgz}) in
165    \begin{verbatim} 
166      C:\Program Files
167    \end{verbatim}
168  \item Double click on the test file
169    \begin{verbatim} 
170      C:\Program Files\anuga_viewer\cylinders.sww
171    \end{verbatim}       
172  \item and associate .sww files with the executable
173  \begin{verbatim} 
174    C:\Program Files\anuga_viewer\animate.exe
175  \end{verbatim}       
176\end{enumerate} 
177
178Try the demos provided in the ANUGA directory \code{anuga\_demos} 
179(also discussed in the ANUGA user manual available with the distribution
180and also at
181\url{http://datamining.anu.edu.au/\~ole/anuga/user_manual/anuga_user_manual.pdf})and view the resulting .sww files with the anuga\_viewer.
182
183%To run the ANUGA against the Okushiri Island wave tank validation dataset
184%(\url{http://www.cee.cornell.edu/longwave})
185%go to \code{anuga_validation}
186% into
187%any directory and run the scripts \code{create_okushiri.py},
188%\code{run_okushiri.py} and \code{compare_timeseries.py}.  See also the
189%\code{README.txt} file that comes with the validation scripts for more
190%details.
191
192
193\clearpage
194\section{Pre-requisites (software)}
195\label{sec:prerequisites}
196
197This and the following sections is for custom installations and
198installations using Linux.
199
200The ANUGA software core (shallow\_water, pmesh, least\_squares, ...) depends on the following software:
201\begin{itemize}
202  \item python 2.3 or later\footnote{Problems have been observed with
203  Python 2.5 and Numeric on 64 bit platforms. See
204  \url{https://datamining.anu.edu.au/anuga/ticket/221}} 
205  \url{http://www.python.org}
206  %\footnote{Note, the
207  %dll python2X.dll is needed to compile ANUGA, but is not always
208  %automatically added for versions 2.4 and above.  Install it into the
209  %python2X directory, if you need it.}. 
210  \item python-numeric for Linux.  It's called Numeric in Windows. 
211  %\item python-dev (Interestingly, numeric seems to be installed as
212  %well) for Linux.  This is not necessary for Windows.
213  \item python-scientific (to provide python-netcdf) for Linux.  It's
214    called ScientificPython in Windows.
215  \item NETCDF.  Extract the file netcdf.dll, and put in C://Windows//System32// (Windows XP) or C://WINNT//System32 (Windows NT or 2000).     
216  \item A C compiler such as gcc (from GNU in case of Linux and MinGW
217  in case of Windows)
218  %\item scons for automatically compiling the distribution.
219\end{itemize}
220
221Note: All of these can be installed in one go on Windows platforms by
222using the Enthought Python
223distribution available at \url{http://code.enthought.com/projects/}.
224
225\section{Recommended software}
226
227\begin{itemize}
228  \item psyco \url{http://psyco.sourceforge.net/index.html}: Speeds up anuga by about 30\%.
229  %\item visual python \url{http://vpython.org}
230  \item matplotlib (pylab) for quality 2d plotting (moving towards mandatory requirement and now part of Enthought.)
231  \item VTK \url{http://mayavi.sourceforge.net/dwnld/vtk/win32/} - also now part of Enthought.
232\end{itemize}
233
234
235
236\section{System configuration}
237
238
239The system path on Win32 architectures must contain the
240directories (this examples assumes the Enthought Python 2.4 distribution
241has been installed. Path names may vary depending on the
242exact configuration).
243\begin{verbatim}
244  PATH=C:\Python24;C:\Python24\Enthought\MingW\bin;C:\Program Files\anuga_viewer
245\end{verbatim}
246The path should be analoguous for Unix operating systems.
247
248If anuga is not installed in the python site-packages directory
249the root directory for all
250anuga/inundation modules must be on the pythonpath, e.g.\
251\begin{verbatim}
252PYTHONPATH=C:\anuga_core\source
253\end{verbatim}
254
255
256
257
258
259\section{Installation of source zip file}
260Get a source zip file, for example, anuga_source_3807.zip, and expand
261it in the python site-packages directory (\code{C:\\Python24\\Lib\\site-packages})
262
263In the ANUGA root directory (\code{C:\\Python24\\Lib\\site-packages\\anuga}),
264run the compilation script:
265{\small \begin{verbatim}
266  python compile_all.py
267\end{verbatim}}
268
269%or (in anuga_core)
270% scons install
271% scons -c #(clean)
272
273
274\subsection{Testing}
275
276In the ANUGA root directory, run the test suite:
277{\small \begin{verbatim}
278  python test_all.py
279\end{verbatim}}
280ANUGA has been succesfully installed if the tests pass as follows:
281
282{\tiny
283\begin{verbatim}
284  ...
285  test_data_manager.py
286  test_interpolate_sww.py
287  test_mesh.py
288  test_mesh_interface.py
289  test_triangmodule.py
290  test_triangmoduleII.py
291  test_advection.py
292............................................................................................................................................
293............................................................................................................................................
294............................................................................................................................................
295............................................................................................................................................
296.................................
297----------------------------------------------------------------------
298Ran 593 tests in 42.712s
299
300OK
301\end{verbatim} }
302
303
304
305%\section{Other stuff to be included}
306%
307%\begin{verbatim}
308%Install tortoise from downloads (ITs didn't integrate wih explorer).
309%In settings set proxy to proxy.agso.gov.au  8080
310%%
311%
312%Install swollen from latest distro (in subversion)
313%
314%
315%\end{verbatim}
316
317
318
319
320
321\end{document}
Note: See TracBrowser for help on using the repository browser.