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

Last change on this file since 5510 was 5510, checked in by ole, 14 years ago

Added What's new document and updated other documentation slightly.

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