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

Last change on this file since 5768 was 5768, checked in by rwilson, 16 years ago

More testing (trying to get '\' printed *inline*!

  • Property svn:keywords set to LastChangedDate LastChangedRevision LastChangedBy HeadURL Id
File size: 11.9 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: the scientific Python installation
73  sometimes ends with an error message.  ANUGA still works though.
74  These packages are available from:
75  \begin{itemize} 
76    \item The supplied ANUGA distribution folder; \begin{verbatim}
77      pre_requisites\2.5
78    \end{verbatim} 
79    (Install in the order \code{python-2.5.msi},
80     \code{Numeric-23.8.2.win32-py2.5.exe},
81    \code{ScientificPython-2.7.8.win32-py2.5.exe},
82      \code{MinGW-5.1.4.exe} and then unpack
83    \code{netcdf-3.6.1-beta1-win32dll.zip} into \code{C:{\textbackslash}bin} as
84    suggested below.
85    \item The WEB:
86    \begin{itemize} 
87      \item Python2.5:
88      \url{http://www.python.org/download/}.
89      \item Numeric Python: (Numeric-23.8.2.win32-py2.5.exe)\\
90       \url{http://sourcesup.cru.fr/frs/?group_id=180}
91      \item Scientific Python: (ScientificPython-2.X.X.win32-py2.5.exe)\\
92       \url{http://sourcesup.cru.fr/frs/?group_id=180}
93      \item MinGW: (MinGW-5.X.X.exe)\\
94       \url{http://sourceforge.net/project/showfiles.php?group_id=2435}
95      \item NETCDF: download the file netcdf-3.6.1-beta1-win32dll.zip from
96      \url{http://www.unidata.ucar.edu/software/netcdf/binaries.html} 
97      .
98      Unpack this in a folder that is available on the system path.
99      We suggest unpacking it into \begin{verbatim}C:\bin\end{verbatim} 
100    \end{itemize}   
101  \end{itemize}   
102 
103 
104  \item For Python 2.4,  install Python pre-requisites: The Enthought version of Python2.4,
105  Scientific Python
106  and the NetCDF library\footnote{Separate installation of Scientific
107  Python and NetCDF
108  will become unneccesary once Enthought sorts out netcdf support
109  (see \url{https://svn.enthought.com/enthought/ticket/917})}.
110  These are available from either
111  \begin{itemize} 
112    \item The supplied ANUGA distribution as under the folder pre_requisites
113    (Install in the order \code{enthon-python2.4-1.0.0.exe},
114    \code{ScientificPython-2.4.9.win32-py2.4.exe} and the unpack
115    \code{netcdf-3.6.1-beta1-win32dll.zip} into \code{C:\\bin} as
116    suggested below.
117    \item The WEB:
118    \begin{itemize} 
119      \item Enthought version of Python2.4:
120      \url{http://code.enthought.com/projects/}.
121      \item Scientific Python:\\
122       \url{http://sourceforge.net/project/showfiles.php?group_id=172848}
123      \item NETCDF: download the file netcdf-3.6.1-beta1-win32dll.zip from
124      \url{http://www.unidata.ucar.edu/software/netcdf/binaries.html} 
125      (\url{ftp://ftp.unidata.ucar.edu/pub/netcdf/contrib/win32/netcdf-3.6.1-beta1-win32dll.zip}).
126      Unpack this in a folder that is available on the system path.
127      We suggest unpacking it into
128      \begin{verbatim} 
129      C:\bin
130      \end{verbatim} 
131    \end{itemize}   
132  \end{itemize}   
133 
134  \item Add the following to the PATH environment variable
135    \begin{verbatim}
136      PATH=C:\Python24;C:\Python24\Enthought\MingW\bin;C:\bin
137    \end{verbatim}   %C:\Program Files\anuga_viewer;
138  \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.} 
139  in the python site-packages
140  directory \code{C:$\backslash$Python24$\backslash$Lib$\backslash$site-packages}. This is often done in Windows by
141  double clicking on the .tgz file and then 'browse to' the
142  destination directory.
143  \item In the ANUGA root directory (\code{C:$\backslash$Python24$\backslash$Lib$\backslash$site-packages$\backslash$anuga}),
144  run the compilation script (either from the commandline or by clicking on it):
145    {\small \begin{verbatim}
146        python compile_all.py
147    \end{verbatim}}
148  \item In the ANUGA root directory, run the test suite
149  (e.g. by opening it with IDLE and running the file):
150    {\small \begin{verbatim}
151        python test_all.py
152    \end{verbatim}}
153    ANUGA has been succesfully installed if the tests pass.
154  \item To verify that ANUGA succesfully reproduces a series of validation
155  examples, go
156  to the directory \code{anuga_validation\\automated_validation_tests} in
157  which you can run
158  {\small \begin{verbatim}
159      python validate_all.py
160  \end{verbatim}}   
161\end{enumerate}   
162
163
164
165
166To install the anuga\_viewer
167\begin{enumerate} 
168  \item Unpack the distribution (\code{anuga_viewer_1.0.tgz}) in
169    \begin{verbatim} 
170      C:\Program Files
171    \end{verbatim}
172  \item Double click on the test file
173    \begin{verbatim} 
174      C:\Program Files\anuga_viewer\cylinders.sww
175    \end{verbatim}       
176  \item and associate .sww files with the executable
177  \begin{verbatim} 
178    C:\Program Files\anuga_viewer\animate.exe
179  \end{verbatim}       
180\end{enumerate} 
181
182Try the demos provided in the ANUGA directory \code{anuga\_demos} 
183(also discussed in the ANUGA user manual available with the distribution
184and also at
185\url{http://datamining.anu.edu.au/\~ole/anuga/user_manual/anuga_user_manual.pdf})and view the resulting .sww files with the anuga\_viewer.
186
187%To run the ANUGA against the Okushiri Island wave tank validation dataset
188%(\url{http://www.cee.cornell.edu/longwave})
189%go to \code{anuga_validation}
190% into
191%any directory and run the scripts \code{create_okushiri.py},
192%\code{run_okushiri.py} and \code{compare_timeseries.py}.  See also the
193%\code{README.txt} file that comes with the validation scripts for more
194%details.
195
196
197\clearpage
198\section{Pre-requisites (software)}
199\label{sec:prerequisites}
200
201This and the following sections is for custom installations and
202installations using Linux.
203
204The ANUGA software core (shallow\_water, pmesh, least\_squares, ...) depends on the following software:
205\begin{itemize}
206  \item python 2.3 or later\footnote{Problems have been observed with
207  Python 2.5 and Numeric on 64 bit platforms. See
208  \url{https://datamining.anu.edu.au/anuga/ticket/221}} 
209  \url{http://www.python.org}
210  %\footnote{Note, the
211  %dll python2X.dll is needed to compile ANUGA, but is not always
212  %automatically added for versions 2.4 and above.  Install it into the
213  %python2X directory, if you need it.}. 
214  \item python-numeric for Linux.  It's called Numeric in Windows. 
215  %\item python-dev (Interestingly, numeric seems to be installed as
216  %well) for Linux.  This is not necessary for Windows.
217  \item python-scientific (to provide python-netcdf) for Linux.  It's
218    called ScientificPython in Windows.
219  \item NETCDF.  Extract the file netcdf.dll, and put in C://Windows//System32// (Windows XP) or C://WINNT//System32 (Windows NT or 2000).     
220  \item A C compiler such as gcc (from GNU in case of Linux and MinGW
221  in case of Windows)
222  %\item scons for automatically compiling the distribution.
223\end{itemize}
224
225Note: All of these can be installed in one go on Windows platforms by
226using the Enthought Python
227distribution available at \url{http://code.enthought.com/projects/}.
228
229\section{Recommended software}
230
231\begin{itemize}
232  \item psyco \url{http://psyco.sourceforge.net/index.html}: Speeds up anuga by about 30\%.
233  %\item visual python \url{http://vpython.org}
234  \item matplotlib (pylab) for quality 2d plotting (moving towards mandatory requirement and now part of Enthought.)
235  \item VTK \url{http://mayavi.sourceforge.net/dwnld/vtk/win32/} - also now part of Enthought.
236\end{itemize}
237
238
239
240\section{System configuration}
241
242
243The system path on Win32 architectures must contain the
244directories (this examples assumes the Enthought Python 2.4 distribution
245has been installed. Path names may vary depending on the
246exact configuration).
247\begin{verbatim}
248  PATH=C:\Python24;C:\Python24\Enthought\MingW\bin;C:\Program Files\anuga_viewer
249\end{verbatim}
250The path should be analoguous for Unix operating systems.
251
252If anuga is not installed in the python site-packages directory
253the root directory for all
254anuga/inundation modules must be on the pythonpath, e.g.\
255\begin{verbatim}
256PYTHONPATH=C:\anuga_core\source
257\end{verbatim}
258
259
260
261
262
263\section{Installation of source zip file}
264Get a source zip file, for example, anuga_source_3807.zip, and expand
265it in the python site-packages directory (\code{C:\\Python24\\Lib\\site-packages})
266
267In the ANUGA root directory (\code{C:\\Python24\\Lib\\site-packages\\anuga}),
268run the compilation script:
269{\small \begin{verbatim}
270  python compile_all.py
271\end{verbatim}}
272
273%or (in anuga_core)
274% scons install
275% scons -c #(clean)
276
277
278\subsection{Testing}
279
280In the ANUGA root directory, run the test suite:
281{\small \begin{verbatim}
282  python test_all.py
283\end{verbatim}}
284ANUGA has been succesfully installed if the tests pass as follows:
285
286{\tiny
287\begin{verbatim}
288  ...
289  test_data_manager.py
290  test_interpolate_sww.py
291  test_mesh.py
292  test_mesh_interface.py
293  test_triangmodule.py
294  test_triangmoduleII.py
295  test_advection.py
296............................................................................................................................................
297............................................................................................................................................
298............................................................................................................................................
299............................................................................................................................................
300.................................
301----------------------------------------------------------------------
302Ran 593 tests in 42.712s
303
304OK
305\end{verbatim} }
306
307
308
309%\section{Other stuff to be included}
310%
311%\begin{verbatim}
312%Install tortoise from downloads (ITs didn't integrate wih explorer).
313%In settings set proxy to proxy.agso.gov.au  8080
314%%
315%
316%Install swollen from latest distro (in subversion)
317%
318%
319%\end{verbatim}
320
321
322
323
324
325\end{document}
Note: See TracBrowser for help on using the repository browser.