source: trunk/anuga_core/documentation/user_manual/anuga_installation_guide.tex @ 7828

Last change on this file since 7828 was 7527, checked in by nariman, 15 years ago

Added extra notes for the Windows one-click installer.

  • Property svn:keywords set to LastChangedDate LastChangedRevision LastChangedBy HeadURL Id
File size: 18.9 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{nariman.habili@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
83If you already have previous versions of Python, ANUGA support software or the ANUGA source code installed
84on the target machine, start off by uninstalling them. Next, download the latest version of the ANUGA
85Windows installer from \url{http://sourceforge.net/projects/anuga/files/}. The Windows installer will
86install Python, MingW (select the "Minimal" install), NumPy, NetCDF, Scientific Python, Matplotlib, the
87ANUGA source code and the viewer (animate). Note that you will need an internet connection to install MingW.
88
89After all the necessary packages have been installed, the installer will proceed to compile the ANUGA C code,
90run the test suite (optional) and then run a series of validation examples (optional). This may take some time.
91Try the demonstrations provided in the ANUGA directory \code{anuga\_demos} (discussed in the ANUGA user manual at
92\url{http://datamining.anu.edu.au/\%7Eole/anuga/user\%5Fmanual/anuga\%5Fuser\%5Fmanual.pdf})
93and view the resulting \code{.sww} files with the ANUGA viewer.
94
95%This procedure assumes that you do not have python installed on the target machine.
96%If you do have a python installed already then skip the installation of python as
97%long as you have version 2.5 or later installed.
98%
99%\begin{itemize} 
100%  \item Install the support software, in order.
101%    \begin{enumerate}
102%      \item Execute \code{python-2.5.4.msi} to install python.
103%
104%      \item Install MinGW from \code{MinGW-5.1.4.exe}.  Install components:
105%        \begin{enumerate}
106%          \item MinGW base tools
107%          \item g++ compiler
108%          \item MinGW Make
109%        \end{enumerate}
110%        Note that you will need an internet connection for the above install.
111%
112%      \item Execute \code{numpy-1.3.0-win32-superpack-python2.5.exe} to install numpy.
113%
114%      \item Execute \code{netCDF_binary_4.0.exe} to install NetCDF.
115%
116%      \item Execute \code{ScientificPython-2.9.0.win32-py2.5.exe} to install Scientific Python.
117
118%      \item Execute \code{matplotlib-0.98.5.2.win32-py2.5.exe} to install matplotlib.
119%    \end{enumerate}
120
121%  \item Add the following to the end of the PATH environment variable:
122%    \begin{verbatim};C:\Python25;C:\MingW\bin;C:\netcdf4\bin\end{verbatim}
123%    For details on how to do this under Windows please refer to Appendix \ref{sec:setwindowspath}.
124%\end{itemize} 
125%
126%\subsubsection{ANUGA Installation}
127%\label{sec:ANUGA}
128%
129%\begin{itemize} 
130%  \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 -
131%                                                                          the remedy is to rename them back or use another browser such as Firefox.}
132%    in the python site-packages directory \code{C:$\backslash$Python25$\backslash$Lib$\backslash$site-packages}.
133%    This is often done in Windows by double clicking on the \code{.tgz} file and then 'browse to' the destination directory.
134%
135%  \item In the ANUGA root directory (\code{C:$\backslash$Python25$\backslash$Lib$\backslash$site-packages$\backslash$anuga}),
136%    run the compilation script (either from the commandline or by running it in IDLE):
137%    \begin{verbatim}python compile_all.py\end{verbatim}
138%
139%  \item In the ANUGA root directory (\code{C:$\backslash$Python25$\backslash$Lib$\backslash$site-packages$\backslash$anuga}),
140%    run the test suite (either from the commandline or by running it in IDLE):
141%    \begin{verbatim}python test_all.py\end{verbatim} ANUGA has been succesfully installed if the tests pass.
142%
143%  \item To verify that ANUGA succesfully reproduces a series of validation examples, go
144%    to the directory
145%    \linebreak
146%    \code{anuga_validation$\backslash$automated_validation_tests} under the ANUGA root directory where you can run:
147%    \begin{verbatim}python validate_all.py\end{verbatim}
148%    This may take some time.
149%
150%  \item To install the ANUGA viewer:
151%    \begin{enumerate}
152%      \item Unpack the distribution (\code{anuga_viewer_1.0.tgz}) into:
153%        \begin{verbatim}C:\Program Files\end{verbatim}
154%
155%      \item Double click on the test file:
156%        \begin{verbatim}C:\Program Files\anuga_viewer\cylinders.sww\end{verbatim}
157%
158%      \item Associate \code{.sww} files with the executable:
159%      \begin{verbatim}C:\Program Files\anuga_viewer\animate.exe\end{verbatim}       
160%      For details on how to do this under Windows please refer to Appendix \ref{sec:assocanimatesww}.
161%    \end{enumerate}
162%
163%    Try the demonstrations provided in the ANUGA directory \code{anuga\_demos}
164%    (discussed in the ANUGA user manual at
165%    \url{http://datamining.anu.edu.au/\%7Eole/anuga/user\%5Fmanual/anuga\%5Fuser\%5Fmanual.pdf})
166%    and view the resulting \code{.sww} files with the ANUGA viewer.
167%\end{itemize}   
168
169
170%To run the ANUGA against the Okushiri Island wave tank validation dataset
171%(\url{http://www.cee.cornell.edu/longwave})
172%go to \code{anuga_validation}
173% into
174%any directory and run the scripts \code{create_okushiri.py},
175%\code{run_okushiri.py} and \code{compare_timeseries.py}.  See also the
176%\code{README.txt} file that comes with the validation scripts for more
177%details.
178
179\subsection{Quick install - Windows Vista}
180\label{sec:winvista}
181
182The installation of the support software and the ANUGA software should be the same as for Windows XP above.
183The installation and use of ANUGA under Windows Vista has not been heavily tested.  Feedback on any aspect
184of using ANUGA under Vista is welcomed.
185
186\subsection{Quick install - Linux}
187\label{sec:linux}
188
189The procedure to install onto a Linux platform is targetted at a Debian-like Linux, such as Ubuntu.
190If you use another Linux the overall procedure should be followed, although the details will vary.
191
192The steps below assume that you do not have python installed on the target machine.
193If you do have a python installed already then skip the installation of python as
194long as you have version 2.5 or later.
195
196Note that even if you already have python installed you should still check if things like
197\code{python-dev} and \code{python-profiler} need to be installed.
198
199\subsubsection{Support Software - Linux 32 bit}
200\label{sec:linux32bit}
201
202Install support software (in order):
203\begin{enumerate} 
204  \item Install the python development environment, either through Synaptic or by:
205    \begin{verbatim}sudo apt-get install python python-dev python-profiler\end{verbatim}
206    If you already have python 2.5 or later installed, don't include \code{python} above.
207
208  \item Install g++, either through Synaptic or by:
209    \begin{verbatim}sudo apt-get install g++\end{verbatim}
210
211  \item Install the numpy package, either through Synaptic or by:
212    \begin{verbatim}sudo apt-get install python-numpy\end{verbatim}
213
214  \item Install the NetCDF package from the .tar.gz file:
215    \begin{verbatim}tar xzf netcdf.tar.gz
216cd netcdf-4.0.1
217./configure
218make check
219sudo make install
220cd\end{verbatim}
221
222  \item Install the ScientificPython package from the .tar.gz file:
223    \begin{verbatim}tar xzf ScientificPython-2.9.0.tar.gz
224cd ScientificPython-2.9.0
225python setup.py build --numpy
226sudo python setup.py install
227cd\end{verbatim}
228
229  \item Install matplotlib, either through Synaptic or by:
230    \begin{verbatim}sudo apt-get install python-matplotlib\end{verbatim}
231\end{enumerate}   
232
233\subsubsection{Support Software - Linux 64 bit}
234\label{sec:linux64bit}
235
236Install support software (in order):
237\begin{enumerate} 
238  \item Install the python development environment, either through Synaptic or by:
239    \begin{verbatim}sudo apt-get install python python-dev python-profiler\end{verbatim}
240    If you already have python 2.5 or later installed, don't include \code{python} above.
241
242  \item Install g++, either through Synaptic or by:
243    \begin{verbatim}sudo apt-get install g++\end{verbatim}
244
245  \item Define a CFLAGS value:
246    \begin{verbatim}export CFLAGS=-fPIC\end{verbatim}
247
248  \item Install the numpy package, either through Synaptic or by:
249    \begin{verbatim}sudo apt-get install python-numpy\end{verbatim}
250
251  \item Install the NetCDF package from the .tar.gz file:
252    \begin{verbatim}tar xzf netcdf.tar.gz
253cd netcdf-4.0.1
254./configure
255make check
256sudo make install
257cd\end{verbatim}
258
259  \item Install the ScientificPython package from the .tar.gz file:
260    \begin{verbatim}tar xzf ScientificPython-2.9.0.tar.gz
261cd ScientificPython-2.9.0
262python setup.py build --numpy
263sudo python setup.py install
264cd\end{verbatim}
265
266  \item Install matplotlib, either through Synaptic or by:
267    \begin{verbatim}sudo apt-get install python-matplotlib\end{verbatim}
268\end{enumerate}   
269
270\subsubsection{ANUGA Installation - 32 or 64 bit}
271\label{sec:ANUGA32-64bit}
272
273\begin{enumerate} 
274  \item Get the ANUGA source from \url{http://sourceforge.net/projects/anuga} (\code{anuga-1.0_5789.tgz} say),
275    and expand it into the python site-packages directory \code{/usr/lib/python2.5/site-packages}.
276    In the unpacked ANUGA directory \code{/usr/lib/python2.5/site-packages/anuga} run the command:
277    \begin{verbatim}sudo python compile_all.py\end{verbatim}
278
279  \item In the ANUGA root directory (\code{/usr/lib/python2.5/site-packages/anuga})
280    run the test suite:
281    \begin{verbatim}python test_all.py\end{verbatim} ANUGA has been succesfully installed if the tests pass.
282
283  \item To verify that ANUGA succesfully reproduces a series of validation examples, go
284    to the directory
285    \linebreak
286    \code{/usr/lib/python2.5/site-packages/anuga_validation/automated_validation_tests}
287    where you can run validation tests to ensure the correct running of ANUGA:
288    \begin{verbatim}python validate_all.py\end{verbatim}
289    This may take some time.
290\end{enumerate}
291
292\section{Optional but recommended software}
293This software is not required to run the ANUGA toolbox, but it is recommended.
294\begin{itemize}
295  \item psyco. Speeds up ANUGA by about 30\%, so is strongly recommended.
296    Under Ubuntu install either through Synaptic or by:
297    \begin{verbatim}sudo apt-get install python-psyco\end{verbatim}
298    Under Windows install the file \code{psyco-1.6.win32-py25.exe}
299    which you can find on the \url{http://psyco.sourceforge.net/download.html} page.
300
301  \item VTK. The Visualization Toolkit. Under Ubuntu install either through Synaptic or by:
302    \begin{verbatim}sudo apt-get install python-vtk\end{verbatim}
303    Under Windows install the file \code{vtk-5.4.2-win32.exe}
304    from the \url{http://www.vtk.org/VTK/resources/software.html} page.
305\end{itemize}
306
307
308
309\section{Testing}
310
311In the ANUGA root directory, run the test suite:
312\begin{verbatim}
313python test_all.py
314\end{verbatim}
315ANUGA has been succesfully installed if the tests pass as follows:
316\begin{verbatim}
317  ...
318  test_data_manager.py
319  test_interpolate_sww.py
320  test_mesh.py
321  test_mesh_interface.py
322  test_triangmodule.py
323  test_triangmoduleII.py
324  test_advection.py
325.................................................................................
326.................................................................................
327.................................................................................
328.................................................................................
329.................................................................................
330.................................................................................
331.................................................................................
332..........................
333----------------------------------------------------------------------
334Ran 593 tests in 42.712s
335
336OK
337\end{verbatim}
338
339Note that if psycho is not installed, a number of psycho related warnings will appear. These warnings
340can be ignored.
341
342%\section{Other stuff to be included}
343%
344%\begin{verbatim}
345%Install tortoise from downloads (ITs didn't integrate wih explorer).
346%In settings set proxy to proxy.agso.gov.au  8080
347%%
348%
349%Install swollen from latest distro (in subversion)
350%
351%
352%\end{verbatim}
353
354
355\appendix
356\chapter{Miscellaneous procedures}
357\section{Setting the PATH on Windows}
358\label{sec:setwindowspath}
359
360The Windows one-click installer should automatically set the necessary PATH
361environment "System variables". However, in case you do not have
362permission to modify the system variable, then the method of setting the PATH environment "User variable"
363for Windows XP is shown here. Setting the variable for Windows Vista should be similar.
364
365\setlength\fboxsep{0pt}
366\setlength\fboxrule{1.0pt}
367
368First, open the Control Panel:
369\begin{figure}[ht]
370  \centerline{\fbox{\includegraphics[scale=0.75]{installgraphics/winsetpath1.png}}}
371%  \caption{Run Control Panel from the Start menu}
372  \label{fig:winsetpath1}
373\end{figure}
374
375Next, start the System applet:
376\begin{figure}[ht]
377  \centerline{\fbox{\includegraphics[scale=0.75]{installgraphics/winsetpath2.png}}}
378%  \caption{Start the System applet}
379  \label{fig:winsetpath2}
380\end{figure}
381
382\pagebreak
383
384Select the \code{Advanced} tab in the System Properties window:
385\begin{figure}[ht]
386  \centerline{\includegraphics[scale=0.5]{installgraphics/winsetpath3.png}}
387%  \caption{Select the Advanced tab}
388  \label{fig:winsetpath3}
389\end{figure}
390
391%\pagebreak
392
393Press the \code{Environment Variables} button in the \code{Advanced} tab:
394\begin{figure}[ht]
395  \centerline{\includegraphics[scale=0.5]{installgraphics/winsetpath4.png}}
396%  \caption{Press the Environment Variables button}
397  \label{fig:winsetpath4}
398\end{figure}
399
400\pagebreak
401
402If the \code{PATH} variable is not defined in the 'User variables' or 'System variables' windows,
403press the \code{New} button in either of the two windows (for a personal machine, choose the 'System variables' window).
404
405If \code{PATH} already exists in the 'User variable' or 'System variables' window,
406select the row with the \code{PATH} variable name in the appropriate window
407and press the \code{Edit} button next to the \code{New} button in that window:
408\begin{figure}[ht]
409  \centerline{\includegraphics[scale=0.5]{installgraphics/winsetpath5.png}}
410%  \caption{Press the New button}
411  \label{fig:winsetpath5}
412\end{figure}
413
414%\pagebreak
415
416You will be shown the editor window whichever button you pressed in the above step. If the \code{Variable name} box is empty
417type in the name \code{PATH}.  In the \code{Variable value} box type the value you want the \code{PATH} variable to have.  If there
418is already some text in the box, place your additional value at the front of the existing value, not forgetting to terminate your additional
419string with the ';' character. The final value string must be a series of directory names seperated by ';' characters:
420\begin{figure}[ht]
421  \centerline{\includegraphics[scale=0.75]{installgraphics/winsetpath6.png}}
422%  \caption{Modifying the PATH value}
423  \label{fig:winsetpath6}
424\end{figure}
425
426When you are finished, press the \code{OK} button and exit from the applet.
427
428\pagebreak
429
430\section{Associating animate.exe with a .sww file}
431\label{sec:assocanimatesww}
432
433The one-click installer should associate animate.exe with .sww files automatically. However, the method of associating
434\code{animate.exe} with a \code{.sww} file manually is shown here for Windows XP.
435A similar process should work for Windows Vista.
436
437Double left-click on any \code{.sww} file.  This brings up a dialog because Windows doesn't know how to open the file:
438\begin{figure}[ht]
439  \centerline{\fbox{\includegraphics[scale=0.5]{installgraphics/winassoc1.png}}}
440%  \caption{Try to open the .sww file}
441  \label{fig:winassoc1}
442\end{figure}
443
444Select the "\code{Select the program from a list}" radiobutton and press the \code{OK} button:
445\begin{figure}[ht]
446  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc2.png}}
447%  \caption{Select the program from a list}
448  \label{fig:winassoc2}
449\end{figure}
450
451\pagebreak
452
453Press the \code{Browse...} button to find the \code{animate.exe} program:
454\begin{figure}[ht]
455  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc3.png}}
456%  \caption{Find animate.exe program}
457  \label{fig:winassoc3}
458\end{figure}
459
460Navigate to the \code{C:$\backslash$Program Files$\backslash$anuga_viewer} directory:
461\begin{figure}[ht]
462  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc4.png}}
463%  \caption{Navigate into Program Files|anuga_viewer directory}
464  \label{fig:winassoc4}
465\end{figure}
466
467\pagebreak
468
469Select \code{animate.exe} and press the \code{Open} button:
470\begin{figure}[ht]
471  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc5.png}}
472%  \caption{Select the animate.exe program press Open}
473  \label{fig:winassoc5}
474\end{figure}
475
476Finally, press the \code{OK} button:
477\begin{figure}[ht]
478  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc6.png}}
479%  \caption{Press the OK button}
480  \label{fig:winassoc6}
481\end{figure}
482
483
484\end{document}
Note: See TracBrowser for help on using the repository browser.