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

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

Made instructions for setting an environment variable clearer.

  • Property svn:keywords set to LastChangedDate LastChangedRevision LastChangedBy HeadURL Id
File size: 18.3 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.
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
66
67\section{Installation}
68
69Below are the install procedures for Windows XP, Windows Vista and Linux.
70
71\subsection{Quick install - Windows XP}
72\label{sec:winxp}
73
74This procedure assumes that you do not have python installed on the target machine.
75If you do have a python installed already then skip the installation of python as
76long as you have version 2.3 or later installed.
77
78\begin{enumerate} 
79  \item Install the support software.
80    These packages are available from either:
81    \begin{itemize} 
82      \item The supplied ANUGA distribution folder: \code{pre_requisites$\backslash$2.5}.
83        Install in order:
84        \begin{enumerate}
85          \item Execute \code{python-2.5.msi} to install python.
86          \item Execute \code{Numeric-23.8.2.win32-py2.5.exe} to install Numeric Python.
87          \item Execute \code{ScientificPython-2.7.8.win32-py2.5.exe} to install Scientific Python.
88          \item Execute \code{MinGW-5.1.4.exe} to install MinGW.
89        \end{enumerate} and then unpack \code{netcdf-3.6.1-win32dll.zip} into a folder that is available on the system path.
90        We suggest unpacking it into \code{C:$\backslash$bin}.
91      \item The Internet. Install in order:
92        \begin{enumerate} 
93          \item \url{http://www.python.org/download/}. Click on the \code{Python 2.5.x Windows installer} link to get
94            \code{python-2.5.x.msi}. Execute this file to install python.
95          \item \url{http://sourcesup.cru.fr/frs/?group\%5Fid=180}. Download \code{Numeric-23.8.2.win32-py2.5.exe}
96            and execute it to install Numeric Python.
97          \item \url{http://sourcesup.cru.fr/frs/?group\%5Fid=180}. Download \code{ScientificPython-2.X.X.win32-py2.5.exe}
98            and execute it to install Scientific Python.
99          \item \url{http://sourceforge.net/project/showfiles.php?group\%5Fid=2435}. Click on the \code{Download} link for
100            the \code{Automated MinGW Installer}.  Download and execute the file \code{MinGW-5.X.X.exe} to install the MinGW environment.
101            Note that you need a working internet connection to install WinGW.
102          \item \url{http://www.unidata.ucar.edu/software/netcdf/binaries.html}. Click on the
103            \code{Windows DLL} link in the NetCDF 3.6.1 section.  This will download the file \code{netcdf-3.6.1-win32.zip}.
104            Unpack this in a folder that is available on the system path.
105            We suggest unpacking it into \code{C:$\backslash$bin}.
106        \end{enumerate}   
107    \end{itemize}   
108 
109  \item Add the following to the PATH environment variable:
110    \begin{verbatim}PATH=C:\Python25;C:\MingW\bin;C:\bin\end{verbatim}
111    For details on how to do this under Windows please refer to Appendix \ref{sec:setwindowspath}.
112
113    Note that if you have another version of python installed, 2.4  say, you would replace any
114    \code{Python25} above with \code{Python24}.
115    A similar replacement should be made in all following steps wherever you see \code{Python25}.
116
117  \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 -
118                                                                          the remedy is to rename them back or use another browser such as Firefox.} 
119    in the python site-packages directory \code{C:$\backslash$Python25$\backslash$Lib$\backslash$site-packages}.
120    This is often done in Windows by double clicking on the \code{.tgz} file and then 'browse to' the destination directory.
121
122  \item In the ANUGA root directory (\code{C:$\backslash$Python25$\backslash$Lib$\backslash$site-packages$\backslash$anuga}),
123    run the compilation script (either from the commandline or by running it in IDLE):
124    \begin{verbatim}python compile_all.py\end{verbatim}
125
126  \item In the ANUGA root directory (\code{C:$\backslash$Python25$\backslash$Lib$\backslash$site-packages$\backslash$anuga}),
127    run the test suite (either from the commandline or by running it in IDLE):
128    \begin{verbatim}python test_all.py\end{verbatim} ANUGA has been succesfully installed if the tests pass.
129
130  \item To verify that ANUGA succesfully reproduces a series of validation examples, go
131    to the directory
132    \linebreak
133    \code{anuga_validation$\backslash$automated_validation_tests} under the ANUGA root directory where you can run:
134    \begin{verbatim}python validate_all.py\end{verbatim}
135    This may take some time.
136
137  \item To install the ANUGA viewer:
138    \begin{enumerate} 
139      \item Unpack the distribution (\code{anuga_viewer_1.0.tgz}) into:
140        \begin{verbatim}C:\Program Files\end{verbatim}
141
142      \item Double click on the test file:
143        \begin{verbatim}C:\Program Files\anuga_viewer\cylinders.sww\end{verbatim}
144
145      \item Associate \code{.sww} files with the executable:
146      \begin{verbatim}C:\Program Files\anuga_viewer\animate.exe\end{verbatim}       
147      For details on how to do this under Windows please refer to Appendix \ref{sec:assocanimatesww}.
148    \end{enumerate} 
149
150    Try the demonstrations provided in the ANUGA directory \code{anuga\_demos} 
151    (discussed in the ANUGA user manual at
152    \url{http://datamining.anu.edu.au/\%7Eole/anuga/user\%5Fmanual/anuga\%5Fuser\%5Fmanual.pdf})
153    and view the resulting \code{.sww} files with the ANUGA viewer.
154\end{enumerate}   
155
156
157%To run the ANUGA against the Okushiri Island wave tank validation dataset
158%(\url{http://www.cee.cornell.edu/longwave})
159%go to \code{anuga_validation}
160% into
161%any directory and run the scripts \code{create_okushiri.py},
162%\code{run_okushiri.py} and \code{compare_timeseries.py}.  See also the
163%\code{README.txt} file that comes with the validation scripts for more
164%details.
165
166\subsection{Quick install - Windows Vista}
167\label{sec:winvista}
168
169There has been one reported instance of ANUGA being installed successfully on Windows Vista.
170The following steps should be read in conjunction with the windows XP procedures above:
171
172\begin{enumerate} 
173  \item Install \code{python-2.5.msi}.
174  \item Add the directory \code{C:$\backslash$Python25} to the \code{PATH} environment variable (appendix \ref{sec:setwindowspath}).
175  \item Install \code{Numeric-23.8.2.win32-py2.5.exe} (as administrator).
176  \item Install \code{ScientificPython-2.7.8.win32-py2.5.exe} (as administrator).
177  \item Install \code{MinGW-5.1.4.exe} (as administrator). Use the default package selection.  Don't use old packages and let it make fresh downloads.
178  \item Unpack \code{netcdf-3.6.1-beta1-win32dll.zip} into \code{C:$\backslash$bin}.
179  \item Add the directory \code{C:$\backslash$bin} to the \code{PATH} environment variable (appendix \ref{sec:setwindowspath}).
180  \item Install \code{pysco-1.6.win32-py2.5.exe} (as administrator).
181  \item Install \code{matplotlib-0.91.2.win32-py2.5.exe} (as administrator).
182  \item Install \code{numpy-1.1.0-win32-superpack-python2.5.exe} (as administrator).
183  \item Check that the system variable \code{PATH} contains
184        \code{C:$\backslash$Python2.5;C:$\backslash$Python25$\backslash$DLLs;C:$\backslash$bin;C:$\backslash$MinGW$\backslash$bin}
185        (appendix \ref{sec:setwindowspath}).
186  \item Now follow the Windows XP install steps from the ANUGA source code install step.
187\end{enumerate}
188
189Some of the installed packages above are optional and may not be required, but this is the reported working install we have received.
190
191\subsection{Quick install - Linux}
192\label{sec:linux}
193
194The procedure to install onto a Linux platform is targetted at a Debian-like Linux, such as Ubuntu.
195If you use another Linux the overall procedure should be followed, although the details will vary.
196
197The steps below assume that you do not have python installed on the target machine.
198If you do have a python installed already then skip the installation of python as
199long as you have version 2.3 or later.
200
201Note that even if you already have python installed you should still check if things like
202\code{python-dev} and \code{python-profiler} need to be installed.
203
204\begin{itemize}
205  \item Install support software (in order):
206    \begin{enumerate} 
207      \item Install python development environment, either through Synaptic or by:
208        \begin{verbatim}sudo apt-get install python python-dev python-profiler\end{verbatim}
209      \item Install Numeric Python, either through Synaptic or by:
210        \begin{verbatim}sudo apt-get install python-numeric\end{verbatim}
211      \item Install Scientific Python, either through Synaptic or by:
212        \begin{verbatim}sudo apt-get install python-scientific\end{verbatim}
213      \item Install NetCDF, either through Synaptic or by:
214        \begin{verbatim}sudo apt-get install python-netcdf\end{verbatim}
215      \item Install \code{gcc} and its development environment if you don't have it, either through Synaptic or by:
216        \begin{verbatim}sudo apt-get install gcc libc6-dev\end{verbatim}
217        Ensure that \code{libc6-dev} is installed even if \code{gcc} is already installed.
218    \end{enumerate}   
219  \item Get the ANUGA source from \url{http://sourceforge.net/projects/anuga} (\code{anuga-1.0_5789.tgz} say),
220    and expand it into the python site-packages directory \code{/usr/lib/python2.5/site-packages}.
221    In the unpacked ANUGA directory \code{/usr/lib/python2.5/site-packages/anuga} run the command:
222    \begin{verbatim}sudo python compile_all.py\end{verbatim}
223  \item In the ANUGA root directory (\code{/usr/lib/python2.5/site-packages/anuga})
224    run the test suite:
225    \begin{verbatim}python test_all.py\end{verbatim} ANUGA has been succesfully installed if the tests pass.
226  \item To verify that ANUGA succesfully reproduces a series of validation examples, go
227    to the directory
228    \linebreak
229    \code{/usr/lib/python2.5/site-packages/anuga_validation/automated_validation_tests}
230    where you can run validation tests to ensure the correct running of ANUGA:
231    \begin{verbatim}python validate_all.py\end{verbatim}
232    This may take some time.
233
234\end{itemize}
235
236\section{Optional but recommended software}
237This software is not required to run the ANUGA toolbox, but it is recommended.
238\begin{itemize}
239  \item psyco. Speeds up ANUGA by about 30\%. Under Ubuntu install either through Synaptic or by:
240    \begin{verbatim}sudo apt-get install python-psyco\end{verbatim}
241    Under Windows install the file \code{psyco-1.6.win32-py25.exe}
242    which you can find from the \url{http://psyco.sourceforge.net/download.html} page.
243  \item matplotlib. For quality 2d plotting (moving towards mandatory requirement). Under Ubuntu install either through Synaptic or by:
244    \begin{verbatim}sudo apt-get install python-matplotlib\end{verbatim}
245    Under Windows install the file \code{matplotlib-0.98.3.win32-py2.5.exe}
246    which you can find from the \url{http://sourceforge.net/projects/matplotlib} page.
247  \item VTK. The Visualization Toolkit. Under Ubuntu install either through Synaptic or by:
248    \begin{verbatim}sudo apt-get install python-vtk\end{verbatim}
249    Under Windows install the file \code{vtk-5.2.0-win32.exe}
250    from the \url{http://www.vtk.org/get-software.php} page.
251\end{itemize}
252
253
254
255\section{Testing}
256
257In the ANUGA root directory, run the test suite:
258\begin{verbatim}
259python test_all.py
260\end{verbatim}
261ANUGA has been succesfully installed if the tests pass as follows:
262\begin{verbatim}
263  ...
264  test_data_manager.py
265  test_interpolate_sww.py
266  test_mesh.py
267  test_mesh_interface.py
268  test_triangmodule.py
269  test_triangmoduleII.py
270  test_advection.py
271.................................................................................
272.................................................................................
273.................................................................................
274.................................................................................
275.................................................................................
276.................................................................................
277.................................................................................
278..........................
279----------------------------------------------------------------------
280Ran 593 tests in 42.712s
281
282OK
283\end{verbatim}
284
285
286
287%\section{Other stuff to be included}
288%
289%\begin{verbatim}
290%Install tortoise from downloads (ITs didn't integrate wih explorer).
291%In settings set proxy to proxy.agso.gov.au  8080
292%%
293%
294%Install swollen from latest distro (in subversion)
295%
296%
297%\end{verbatim}
298
299
300\appendix
301\chapter{Miscellaneous procedures}
302\section{Setting the PATH on Windows}
303\label{sec:setwindowspath}
304
305The method of setting the PATH environment variable for Windows XP is shown here.
306Setting the variable for Windows Vista should be similar.
307
308\setlength\fboxsep{0pt}
309\setlength\fboxrule{1.0pt}
310
311First, open the Control Panel:
312\begin{figure}[ht]
313  \centerline{\fbox{\includegraphics[scale=0.75]{installgraphics/winsetpath1.png}}}
314%  \caption{Run Control Panel from the Start menu}
315  \label{fig:winsetpath1}
316\end{figure}
317
318Next, start the System applet:
319\begin{figure}[ht]
320  \centerline{\fbox{\includegraphics[scale=0.75]{installgraphics/winsetpath2.png}}}
321%  \caption{Start the System applet}
322  \label{fig:winsetpath2}
323\end{figure}
324
325\pagebreak
326
327Select the \code{Advanced} tab in the System Properties window:
328\begin{figure}[ht]
329  \centerline{\includegraphics[scale=0.5]{installgraphics/winsetpath3.png}}
330%  \caption{Select the Advanced tab}
331  \label{fig:winsetpath3}
332\end{figure}
333
334%\pagebreak
335
336Press the \code{Environment Variables} button in the \code{Advanced} tab:
337\begin{figure}[ht]
338  \centerline{\includegraphics[scale=0.5]{installgraphics/winsetpath4.png}}
339%  \caption{Press the Environment Variables button}
340  \label{fig:winsetpath4}
341\end{figure}
342
343\pagebreak
344
345If the \code{PATH} variable is not defined in the 'User variables' or 'System variables' windows,
346press the \code{New} button in either of the two windows (for a personal machine, choose the 'System variables' window).
347
348If \code{PATH} already exists in the 'User variable' or 'System variables' window,
349select the row with the \code{PATH} variable name in the appropriate window
350and press the \code{Edit} button next to the \code{New} button in that window:
351\begin{figure}[ht]
352  \centerline{\includegraphics[scale=0.5]{installgraphics/winsetpath5.png}}
353%  \caption{Press the New button}
354  \label{fig:winsetpath5}
355\end{figure}
356
357%\pagebreak
358
359You will be shown the editor window whichever button you pressed in the above step. If the \code{Variable name} box is empty
360type in the name \code{PATH}.  In the \code{Variable value} box type the value you want the \code{PATH} variable to have.  If there
361is already some text in the box, place your additional value at the front of the existing value, not forgetting to terminate your additional
362string with the ';' character. The final value string must be a series of directory names seperated by ';' characters:
363\begin{figure}[ht]
364  \centerline{\includegraphics[scale=0.75]{installgraphics/winsetpath6.png}}
365%  \caption{Modifying the PATH value}
366  \label{fig:winsetpath6}
367\end{figure}
368
369When you are finished, press the \code{OK} button and exit from the applet.
370
371\pagebreak
372
373\section{Associating animate.exe with a .sww file}
374\label{sec:assocanimatesww}
375
376The method of associating \code{animate.exe} with a \code{.sww} file is shown here for Windows XP.
377A similar process should work for Windows Vista.
378
379Double left-click on any \code{.sww} file.  This brings up a dialog because Windows doesn't know how to open the file:
380\begin{figure}[ht]
381  \centerline{\fbox{\includegraphics[scale=0.5]{installgraphics/winassoc1.png}}}
382%  \caption{Try to open the .sww file}
383  \label{fig:winassoc1}
384\end{figure}
385
386Select the "\code{Select the program from a list}" radiobutton and press the \code{OK} button:
387\begin{figure}[ht]
388  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc2.png}}
389%  \caption{Select the program from a list}
390  \label{fig:winassoc2}
391\end{figure}
392
393\pagebreak
394
395Press the \code{Browse...} button to find the \code{animate.exe} program:
396\begin{figure}[ht]
397  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc3.png}}
398%  \caption{Find animate.exe program}
399  \label{fig:winassoc3}
400\end{figure}
401
402Navigate to the \code{C:$\backslash$Program Files$\backslash$anuga_viewer} directory:
403\begin{figure}[ht]
404  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc4.png}}
405%  \caption{Navigate into Program Files|anuga_viewer directory}
406  \label{fig:winassoc4}
407\end{figure}
408
409\pagebreak
410
411Select \code{animate.exe} and press the \code{Open} button:
412\begin{figure}[ht]
413  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc5.png}}
414%  \caption{Select the animate.exe program press Open}
415  \label{fig:winassoc5}
416\end{figure}
417
418Finally, press the \code{OK} button:
419\begin{figure}[ht]
420  \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc6.png}}
421%  \caption{Press the OK button}
422  \label{fig:winassoc6}
423\end{figure}
424
425
426\end{document}
Note: See TracBrowser for help on using the repository browser.