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 | |
---|
49 | This document outlines the procedure for installing the Anuga toolbox. |
---|
50 | All components are licensed as open source and readily available from the net. |
---|
51 | It is assumed that the reader is familiar with the Python programming language |
---|
52 | and the process of downloading, installing and unpacking files into directories. |
---|
53 | |
---|
54 | |
---|
55 | \section{System requirements} |
---|
56 | \label{sec:requirements} |
---|
57 | |
---|
58 | To run ANUGA you will need a Windows PC (XP or Vista) or a Linux PC with at |
---|
59 | least 512MB RAM. |
---|
60 | |
---|
61 | The viewer (Windows only) requires a graphics adapter that |
---|
62 | is OpenGL compatible. It has been tested with ATI FireGL X1 cards |
---|
63 | and the NVIDIA family. It may not work with other cards such as those from the |
---|
64 | Intel(R) 82915G Express chipset family. |
---|
65 | |
---|
66 | |
---|
67 | \section{Installation} |
---|
68 | |
---|
69 | Below are the install procedures for Windows XP, Windows Vista and Linux. |
---|
70 | |
---|
71 | \subsection{Quick install - Windows XP} |
---|
72 | \label{sec:winxp} |
---|
73 | |
---|
74 | This procedure assumes that you do not have python installed on the target machine. |
---|
75 | If you do have a python installed already then skip the installation of python as |
---|
76 | long 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 | |
---|
169 | There has been one reported instance of ANUGA being installed successfully on Windows Vista. |
---|
170 | The 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 | |
---|
189 | Some 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 | |
---|
194 | The procedure to install onto a Linux platform is targetted at a Debian-like Linux, such as Ubuntu. |
---|
195 | If you use another Linux the overall procedure should be followed, although the details will vary. |
---|
196 | |
---|
197 | The steps below assume that you do not have python installed on the target machine. |
---|
198 | If you do have a python installed already then skip the installation of python as |
---|
199 | long as you have version 2.3 or later. |
---|
200 | |
---|
201 | Note 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} |
---|
237 | This 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 | |
---|
257 | In the ANUGA root directory, run the test suite: |
---|
258 | \begin{verbatim} |
---|
259 | python test_all.py |
---|
260 | \end{verbatim} |
---|
261 | ANUGA 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 | ---------------------------------------------------------------------- |
---|
280 | Ran 593 tests in 42.712s |
---|
281 | |
---|
282 | OK |
---|
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 | |
---|
305 | The method of setting the PATH environment variable for Windows XP is shown here. |
---|
306 | Setting the variable for Windows Vista should be similar. |
---|
307 | |
---|
308 | \setlength\fboxsep{0pt} |
---|
309 | \setlength\fboxrule{1.0pt} |
---|
310 | |
---|
311 | First, 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 | |
---|
318 | Next, 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 | |
---|
327 | Select 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 | |
---|
336 | Press 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 | |
---|
345 | If the \code{PATH} variable is not defined in the 'User variables' or 'System variables' windows, |
---|
346 | press the \code{New} button in either of the two windows (for a personal machine, choose the 'System variables' window). |
---|
347 | |
---|
348 | If \code{PATH} already exists in the 'User variable' or 'System variables' window, |
---|
349 | select the row with the \code{PATH} variable name in the appropriate window |
---|
350 | and 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 | |
---|
359 | You will be shown the editor window whichever button you pressed in the above step. If the \code{Variable name} box is empty |
---|
360 | type in the name \code{PATH}. In the \code{Variable value} box type the value you want the \code{PATH} variable to have. If there |
---|
361 | is already some text in the box, place your additional value at the front of the existing value, not forgetting to terminate your additional |
---|
362 | string 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 | |
---|
369 | When 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 | |
---|
376 | The method of associating \code{animate.exe} with a \code{.sww} file is shown here for Windows XP. |
---|
377 | A similar process should work for Windows Vista. |
---|
378 | |
---|
379 | Double 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 | |
---|
386 | Select 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 | |
---|
395 | Press 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 | |
---|
402 | Navigate 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 | |
---|
411 | Select \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 | |
---|
418 | Finally, 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} |
---|