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

Last change on this file since 5342 was 5342, checked in by duncan, 15 years ago

How to for Python 2.5

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