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

Last change on this file since 7299 was 7299, checked in by rwilson, 15 years ago

Updated guide for new numpy release.

  • Property svn:keywords set to LastChangedDate LastChangedRevision LastChangedBy HeadURL Id
File size: 17.5 KB
Line 
1\documentclass{manual}
2
3\title{ANUGA Installation Guide}
4
5\author{Ole Nielsen, Duncan Gray, Jane Sexton}
6
7\usepackage{graphicx}
8
9
10% Please at least include a long-lived email address;
11% the rest is at your discretion.
12\authoraddress{Geoscience Australia \\
13  Email: \email{ole.nielsen@ga.gov.au}
14}
15
16%Draft date
17\date{\today}                   % update before release!
18                % Use an explicit date so that reformatting
19                % doesn't cause a new date to be used.  Setting
20                % the date to \today can be used during draft
21                % stages to make it easier to handle versions.
22
23               
24\input{version} % Get version info - this file may be modified by
25                % update_anuga_user_manual.py - if not a dummy
26                % will be used.
27                               
28
29\makeindex          % tell \index to actually write the .idx file
30%\makemodindex          % If this contains a lot of module sections.
31
32
33
34\begin{document}
35\maketitle
36
37
38
39% This makes the contents more accessible from the front page of the HTML.
40\ifhtml
41\chapter*{Front Matter\label{front}}
42\fi
43
44
45
46
47\chapter{Introduction}
48
49This document outlines the procedure for installing the Anuga toolbox.
50All components are licensed as open source and readily available from the net.
51It is assumed that the reader is familiar with the Python programming language
52and the process of downloading, installing and unpacking files into directories.
53
54
55\section{System requirements}
56\label{sec:requirements}
57
58To run ANUGA you will need a Windows PC (XP or Vista) or a Linux PC with at
59least 512MB RAM.  As ANUGA is a memory-intensive numerical system, more memory is better than less.
60
61The viewer (Windows only) requires a graphics adapter that
62is OpenGL compatible. It has been tested with ATI FireGL X1 cards
63and the NVIDIA family. It may not work with other cards such as those from the
64Intel(R) 82915G Express chipset family.
65
66The instructions below are written for the numpy version of ANUGA.  ANUGA changed from
67relying on the Numeric package to the numpy package early in July, 2009.  If you have a Numeric ANUGA,
68you should refer to the installation instructions for that version.  The last Numeric version of
69ANUGA had a build number of 7163.
70
71Where the text below refers to a specific package file such as \code{python-2.5.msi} you will find that
72file in a download area linked through the \emph{numpy_support_software} link on the page
73\url{https://datamining.anu.edu.au/anuga/wiki/NumpyInstall}.
74
75
76\section{Installation}
77
78Below are the install procedures for Windows XP, Windows Vista (both 32 bit) and Linux (32 and 64 bit).
79
80\subsection{Quick install - Windows XP (32 bit)}
81\label{sec:winxp}
82
83This procedure assumes that you do not have python installed on the target machine.
84If you do have a python installed already then skip the installation of python as
85long as you have version 2.5 or later installed.
86
87\begin{itemize} 
88  \item Install the support software, in order.
89    \begin{enumerate}
90      \item Execute \code{python-2.5.4.msi} to install python.
91
92      \item Install MinGW from \code{MinGW-5.1.4.exe}.  Install components:
93        \begin{enumerate}
94          \item MinGW base tools
95          \item g++ compiler
96          \item MinGW Make
97        \end{enumerate}
98        Note that you will need an internet connection for the above install.
99
100      \item Execute \code{numpy-1.3.0-win32-superpack-python2.5.exe} to install numpy.
101
102      \item Execute \code{netCDF_binary_4.0.exe} to install NetCDF.
103
104      \item Execute \code{ScientificPython-2.9.0.win32-py2.5.exe} to install Scientific Python.
105 
106      \item Execute \code{matplotlib-0.98.5.2.win32-py2.5.exe} to install matplotlib.
107    \end{enumerate}
108 
109  \item Add the following to the end of the PATH environment variable:
110    \begin{verbatim};C:\Python25;C:\MingW\bin;C:\netcdf4\bin\end{verbatim}
111    For details on how to do this under Windows please refer to Appendix \ref{sec:setwindowspath}.
112\end{itemize} 
113
114\subsubsection{ANUGA Installation}
115\label{sec:ANUGA}
116
117\begin{itemize} 
118  \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 -
119                                                                          the remedy is to rename them back or use another browser such as Firefox.} 
120    in the python site-packages directory \code{C:$\backslash$Python25$\backslash$Lib$\backslash$site-packages}.
121    This is often done in Windows by double clicking on the \code{.tgz} file and then 'browse to' the destination directory.
122
123  \item In the ANUGA root directory (\code{C:$\backslash$Python25$\backslash$Lib$\backslash$site-packages$\backslash$anuga}),
124    run the compilation script (either from the commandline or by running it in IDLE):
125    \begin{verbatim}python compile_all.py\end{verbatim}
126
127  \item In the ANUGA root directory (\code{C:$\backslash$Python25$\backslash$Lib$\backslash$site-packages$\backslash$anuga}),
128    run the test suite (either from the commandline or by running it in IDLE):
129    \begin{verbatim}python test_all.py\end{verbatim} ANUGA has been succesfully installed if the tests pass.
130
131  \item To verify that ANUGA succesfully reproduces a series of validation examples, go
132    to the directory
133    \linebreak
134    \code{anuga_validation$\backslash$automated_validation_tests} under the ANUGA root directory where you can run:
135    \begin{verbatim}python validate_all.py\end{verbatim}
136    This may take some time.
137
138  \item To install the ANUGA viewer:
139    \begin{enumerate} 
140      \item Unpack the distribution (\code{anuga_viewer_1.0.tgz}) into:
141        \begin{verbatim}C:\Program Files\end{verbatim}
142
143      \item Double click on the test file:
144        \begin{verbatim}C:\Program Files\anuga_viewer\cylinders.sww\end{verbatim}
145
146      \item Associate \code{.sww} files with the executable:
147      \begin{verbatim}C:\Program Files\anuga_viewer\animate.exe\end{verbatim}       
148      For details on how to do this under Windows please refer to Appendix \ref{sec:assocanimatesww}.
149    \end{enumerate} 
150
151    Try the demonstrations provided in the ANUGA directory \code{anuga\_demos} 
152    (discussed in the ANUGA user manual at
153    \url{http://datamining.anu.edu.au/\%7Eole/anuga/user\%5Fmanual/anuga\%5Fuser\%5Fmanual.pdf})
154    and view the resulting \code{.sww} files with the ANUGA viewer.
155\end{itemize}   
156
157
158%To run the ANUGA against the Okushiri Island wave tank validation dataset
159%(\url{http://www.cee.cornell.edu/longwave})
160%go to \code{anuga_validation}
161% into
162%any directory and run the scripts \code{create_okushiri.py},
163%\code{run_okushiri.py} and \code{compare_timeseries.py}.  See also the
164%\code{README.txt} file that comes with the validation scripts for more
165%details.
166
167\subsection{Quick install - Windows Vista}
168\label{sec:winvista}
169
170The installation of the suuport software and the ANUGA software should be the same as for Windows XP above.
171The installation and use of ANUGA under Windows Vista has not been heavily tested.  Feedback on any aspect
172of using ANUGA under Vista is welcomed.
173
174\subsection{Quick install - Linux}
175\label{sec:linux}
176
177The procedure to install onto a Linux platform is targetted at a Debian-like Linux, such as Ubuntu.
178If you use another Linux the overall procedure should be followed, although the details will vary.
179
180The steps below assume that you do not have python installed on the target machine.
181If you do have a python installed already then skip the installation of python as
182long as you have version 2.5 or later.
183
184Note that even if you already have python installed you should still check if things like
185\code{python-dev} and \code{python-profiler} need to be installed.
186
187\subsubsection{Support Software - Linux 32 bit}
188\label{sec:linux32bit}
189
190Install support software (in order):
191\begin{enumerate} 
192  \item Install the python development environment, either through Synaptic or by:
193    \begin{verbatim}sudo apt-get install python python-dev python-profiler\end{verbatim}
194    If you already have python 2.5 or later installed, don't include \code{python} above.
195
196  \item Install g++, either through Synaptic or by:
197    \begin{verbatim}sudo apt-get install g++\end{verbatim}
198
199  \item Install the numpy package, either through Synaptic or by:
200    \begin{verbatim}sudo apt-get install python-numpy\end{verbatim}
201
202  \item Install the NetCDF package from the .tar.gz file:
203    \begin{verbatim}tar xzf netcdf.tar.gz
204cd netcdf-4.0.1
205./configure
206make check
207sudo make install
208cd\end{verbatim}
209
210  \item Install the ScientificPython package from the .tar.gz file:
211    \begin{verbatim}tar xzf ScientificPython-2.9.0.tar.gz
212cd ScientificPython-2.9.0
213python setup.py build --numpy
214sudo python setup.py install
215cd\end{verbatim}
216
217  \item Install matplotlib, either through Synaptic or by:
218    \begin{verbatim}sudo apt-get install python-matplotlib\end{verbatim}
219\end{enumerate}   
220
221\subsubsection{Support Software - Linux 64 bit}
222\label{sec:linux64bit}
223
224Install support software (in order):
225\begin{enumerate} 
226  \item Install the python development environment, either through Synaptic or by:
227    \begin{verbatim}sudo apt-get install python python-dev python-profiler\end{verbatim}
228    If you already have python 2.5 or later installed, don't include \code{python} above.
229
230  \item Install g++, either through Synaptic or by:
231    \begin{verbatim}sudo apt-get install g++\end{verbatim}
232
233  \item Define a CFLAGS value:
234    \begin{verbatim}export CFLAGS=-fPIC\end{verbatim}
235
236  \item Install the numpy package, either through Synaptic or by:
237    \begin{verbatim}sudo apt-get install python-numpy\end{verbatim}
238
239  \item Install the NetCDF package from the .tar.gz file:
240    \begin{verbatim}tar xzf netcdf.tar.gz
241cd netcdf-4.0.1
242./configure
243make check
244sudo make install
245cd\end{verbatim}
246
247  \item Install the ScientificPython package from the .tar.gz file:
248    \begin{verbatim}tar xzf ScientificPython-2.9.0.tar.gz
249cd ScientificPython-2.9.0
250python setup.py build --numpy
251sudo python setup.py install
252cd\end{verbatim}
253
254  \item Install matplotlib, either through Synaptic or by:
255    \begin{verbatim}sudo apt-get install python-matplotlib\end{verbatim}
256\end{enumerate}   
257
258\subsubsection{ANUGA Installation - 32 or 64 bit}
259\label{sec:ANUGA32-64bit}
260
261\begin{enumerate} 
262  \item Get the ANUGA source from \url{http://sourceforge.net/projects/anuga} (\code{anuga-1.0_5789.tgz} say),
263    and expand it into the python site-packages directory \code{/usr/lib/python2.5/site-packages}.
264    In the unpacked ANUGA directory \code{/usr/lib/python2.5/site-packages/anuga} run the command:
265    \begin{verbatim}sudo python compile_all.py\end{verbatim}
266
267  \item In the ANUGA root directory (\code{/usr/lib/python2.5/site-packages/anuga})
268    run the test suite:
269    \begin{verbatim}python test_all.py\end{verbatim} ANUGA has been succesfully installed if the tests pass.
270
271  \item To verify that ANUGA succesfully reproduces a series of validation examples, go
272    to the directory
273    \linebreak
274    \code{/usr/lib/python2.5/site-packages/anuga_validation/automated_validation_tests}
275    where you can run validation tests to ensure the correct running of ANUGA:
276    \begin{verbatim}python validate_all.py\end{verbatim}
277    This may take some time.
278\end{enumerate}
279
280\section{Optional but recommended software}
281This software is not required to run the ANUGA toolbox, but it is recommended.
282\begin{itemize}
283  \item psyco. Speeds up ANUGA by about 30\%, so is strongly recommended.
284    Under Ubuntu install either through Synaptic or by:
285    \begin{verbatim}sudo apt-get install python-psyco\end{verbatim}
286    Under Windows install the file \code{psyco-1.6.win32-py25.exe}
287    which you can find on the \url{http://psyco.sourceforge.net/download.html} page.
288
289  \item VTK. The Visualization Toolkit. Under Ubuntu install either through Synaptic or by:
290    \begin{verbatim}sudo apt-get install python-vtk\end{verbatim}
291    Under Windows install the file \code{vtk-5.4.2-win32.exe}
292    from the \url{http://www.vtk.org/VTK/resources/software.html} page.
293\end{itemize}
294
295
296
297\section{Testing}
298
299In the ANUGA root directory, run the test suite:
300\begin{verbatim}
301python test_all.py
302\end{verbatim}
303ANUGA has been succesfully installed if the tests pass as follows:
304\begin{verbatim}
305  ...
306  test_data_manager.py
307  test_interpolate_sww.py
308  test_mesh.py
309  test_mesh_interface.py
310  test_triangmodule.py
311  test_triangmoduleII.py
312  test_advection.py
313.................................................................................
314.................................................................................
315.................................................................................
316.................................................................................
317.................................................................................
318.................................................................................
319.................................................................................
320..........................
321----------------------------------------------------------------------
322Ran 593 tests in 42.712s
323
324OK
325\end{verbatim}
326
327
328
329%\section{Other stuff to be included}
330%
331%\begin{verbatim}
332%Install tortoise from downloads (ITs didn't integrate wih explorer).
333%In settings set proxy to proxy.agso.gov.au  8080
334%%
335%
336%Install swollen from latest distro (in subversion)
337%
338%
339%\end{verbatim}
340
341
342\appendix
343\chapter{Miscellaneous procedures}
344\section{Setting the PATH on Windows}
345\label{sec:setwindowspath}
346
347The method of setting the PATH environment variable for Windows XP is shown here.
348Setting the variable for Windows Vista should be similar.
349
350\setlength\fboxsep{0pt}
351\setlength\fboxrule{1.0pt}
352
353First, open the Control Panel:
354\begin{figure}[ht]
355  \centerline{\fbox{\includegraphics[scale=0.75]{installgraphics/winsetpath1.png}}}
356%  \caption{Run Control Panel from the Start menu}
357  \label{fig:winsetpath1}
358\end{figure}
359
360Next, start the System applet:
361\begin{figure}[ht]
362  \centerline{\fbox{\includegraphics[scale=0.75]{installgraphics/winsetpath2.png}}}
363%  \caption{Start the System applet}
364  \label{fig:winsetpath2}
365\end{figure}
366
367\pagebreak
368
369Select the \code{Advanced} tab in the System Properties window:
370\begin{figure}[ht]
371  \centerline{\includegraphics[scale=0.5]{installgraphics/winsetpath3.png}}
372%  \caption{Select the Advanced tab}
373  \label{fig:winsetpath3}
374\end{figure}
375
376%\pagebreak
377
378Press the \code{Environment Variables} button in the \code{Advanced} tab:
379\begin{figure}[ht]
380  \centerline{\includegraphics[scale=0.5]{installgraphics/winsetpath4.png}}
381%  \caption{Press the Environment Variables button}
382  \label{fig:winsetpath4}
383\end{figure}
384
385\pagebreak
386
387If the \code{PATH} variable is not defined in the 'User variables' or 'System variables' windows,
388press the \code{New} button in either of the two windows (for a personal machine, choose the 'System variables' window).
389
390If \code{PATH} already exists in the 'User variable' or 'System variables' window,
391select the row with the \code{PATH} variable name in the appropriate window
392and press the \code{Edit} button next to the \code{New} button in that window:
393\begin{figure}[ht]
394  \centerline{\includegraphics[scale=0.5]{installgraphics/winsetpath5.png}}
395%  \caption{Press the New button}
396  \label{fig:winsetpath5}
397\end{figure}
398
399%\pagebreak
400
401You will be shown the editor window whichever button you pressed in the above step. If the \code{Variable name} box is empty
402type in the name \code{PATH}.  In the \code{Variable value} box type the value you want the \code{PATH} variable to have.  If there
403is already some text in the box, place your additional value at the front of the existing value, not forgetting to terminate your additional
404string with the ';' character. The final value string must be a series of directory names seperated by ';' characters:
405\begin{figure}[ht]
406  \centerline{\includegraphics[scale=0.75]{installgraphics/winsetpath6.png}}
407%  \caption{Modifying the PATH value}
408  \label{fig:winsetpath6}
409\end{figure}
410
411When you are finished, press the \code{OK} button and exit from the applet.
412
413\pagebreak
414
415\section{Associating animate.exe with a .sww file}
416\label{sec:assocanimatesww}
417
418The method of associating \code{animate.exe} with a \code{.sww} file is shown here for Windows XP.
419A similar process should work for Windows Vista.
420
421Double left-click on any \code{.sww} file.  This brings up a dialog because Windows doesn't know how to open the file:
422\begin{figure}[ht]
423  \centerline{\fbox{\includegraphics[scale=0.5]{installgraphics/winassoc1.png}}}
424%  \caption{Try to open the .sww file}
425  \label{fig:winassoc1}
426\end{figure}
427
428Select the "\code{Select the program from a list}" radiobutton and press the \code{OK} button:
429\begin{figure}[ht]
430  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc2.png}}
431%  \caption{Select the program from a list}
432  \label{fig:winassoc2}
433\end{figure}
434
435\pagebreak
436
437Press the \code{Browse...} button to find the \code{animate.exe} program:
438\begin{figure}[ht]
439  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc3.png}}
440%  \caption{Find animate.exe program}
441  \label{fig:winassoc3}
442\end{figure}
443
444Navigate to the \code{C:$\backslash$Program Files$\backslash$anuga_viewer} directory:
445\begin{figure}[ht]
446  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc4.png}}
447%  \caption{Navigate into Program Files|anuga_viewer directory}
448  \label{fig:winassoc4}
449\end{figure}
450
451\pagebreak
452
453Select \code{animate.exe} and press the \code{Open} button:
454\begin{figure}[ht]
455  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc5.png}}
456%  \caption{Select the animate.exe program press Open}
457  \label{fig:winassoc5}
458\end{figure}
459
460Finally, press the \code{OK} button:
461\begin{figure}[ht]
462  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc6.png}}
463%  \caption{Press the OK button}
464  \label{fig:winassoc6}
465\end{figure}
466
467
468\end{document}
Note: See TracBrowser for help on using the repository browser.