[5799] | 1 | \documentclass{manual} |
---|
| 2 | |
---|
[5803] | 3 | \title{ANUGA Installation Guide} |
---|
[5799] | 4 | |
---|
| 5 | \usepackage{graphicx} |
---|
[7951] | 6 | \usepackage{hyperref} |
---|
[5799] | 7 | |
---|
| 8 | % Please at least include a long-lived email address; |
---|
| 9 | % the rest is at your discretion. |
---|
| 10 | \authoraddress{Geoscience Australia \\ |
---|
[7951] | 11 | Email: \email{anuga@ga.gov.au} |
---|
[5799] | 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 | |
---|
| 47 | This document outlines the procedure for installing the Anuga toolbox. |
---|
| 48 | All components are licensed as open source and readily available from the net. |
---|
| 49 | It is assumed that the reader is familiar with the Python programming language |
---|
| 50 | and the process of downloading, installing and unpacking files into directories. |
---|
| 51 | |
---|
| 52 | |
---|
| 53 | \section{System requirements} |
---|
| 54 | \label{sec:requirements} |
---|
| 55 | |
---|
[7951] | 56 | To run ANUGA you will need a Windows PC (XP, Vista or 7) or a Linux PC with at |
---|
[7299] | 57 | least 512MB RAM. As ANUGA is a memory-intensive numerical system, more memory is better than less. |
---|
[5799] | 58 | |
---|
| 59 | The viewer (Windows only) requires a graphics adapter that |
---|
| 60 | is OpenGL compatible. It has been tested with ATI FireGL X1 cards |
---|
| 61 | and the NVIDIA family. It may not work with other cards such as those from the |
---|
| 62 | Intel(R) 82915G Express chipset family. |
---|
| 63 | |
---|
[7299] | 64 | The instructions below are written for the numpy version of ANUGA. ANUGA changed from |
---|
| 65 | relying on the Numeric package to the numpy package early in July, 2009. If you have a Numeric ANUGA, |
---|
| 66 | you should refer to the installation instructions for that version. The last Numeric version of |
---|
| 67 | ANUGA had a build number of 7163. |
---|
[5799] | 68 | |
---|
[7299] | 69 | Where the text below refers to a specific package file such as \code{python-2.5.msi} you will find that |
---|
| 70 | file in a download area linked through the \emph{numpy_support_software} link on the page |
---|
| 71 | \url{https://datamining.anu.edu.au/anuga/wiki/NumpyInstall}. |
---|
| 72 | |
---|
| 73 | |
---|
[5799] | 74 | \section{Installation} |
---|
| 75 | |
---|
[7951] | 76 | Below are the install procedures for Windows XP, Windows Vista, Windows 7 (all 32 bit) and Linux (32 and 64 bit). |
---|
[5799] | 77 | |
---|
[7299] | 78 | \subsection{Quick install - Windows XP (32 bit)} |
---|
[5799] | 79 | \label{sec:winxp} |
---|
| 80 | |
---|
[7526] | 81 | If you already have previous versions of Python, ANUGA support software or the ANUGA source code installed |
---|
| 82 | on the target machine, start off by uninstalling them. Next, download the latest version of the ANUGA |
---|
| 83 | Windows installer from \url{http://sourceforge.net/projects/anuga/files/}. The Windows installer will |
---|
| 84 | install Python, MingW (select the "Minimal" install), NumPy, NetCDF, Scientific Python, Matplotlib, the |
---|
| 85 | ANUGA source code and the viewer (animate). Note that you will need an internet connection to install MingW. |
---|
[5799] | 86 | |
---|
[7526] | 87 | After all the necessary packages have been installed, the installer will proceed to compile the ANUGA C code, |
---|
| 88 | run the test suite (optional) and then run a series of validation examples (optional). This may take some time. |
---|
| 89 | Try the demonstrations provided in the ANUGA directory \code{anuga\_demos} (discussed in the ANUGA user manual at |
---|
[7951] | 90 | \url{https://datamining.anu.edu.au/anuga/attachment/wiki/WikiStart/anuga_user_manual-1.2.0.pdf}) |
---|
[7526] | 91 | and view the resulting \code{.sww} files with the ANUGA viewer. |
---|
[7299] | 92 | |
---|
| 93 | |
---|
| 94 | |
---|
[5799] | 95 | %To run the ANUGA against the Okushiri Island wave tank validation dataset |
---|
| 96 | %(\url{http://www.cee.cornell.edu/longwave}) |
---|
| 97 | %go to \code{anuga_validation} |
---|
| 98 | % into |
---|
| 99 | %any directory and run the scripts \code{create_okushiri.py}, |
---|
| 100 | %\code{run_okushiri.py} and \code{compare_timeseries.py}. See also the |
---|
| 101 | %\code{README.txt} file that comes with the validation scripts for more |
---|
| 102 | %details. |
---|
| 103 | |
---|
[7951] | 104 | \subsection{Quick install - Windows Vista and 7} |
---|
[5799] | 105 | \label{sec:winvista} |
---|
| 106 | |
---|
[7526] | 107 | The installation of the support software and the ANUGA software should be the same as for Windows XP above. |
---|
[7951] | 108 | The installation and use of ANUGA under Windows Vista and 7 have not been heavily tested. Feedback on any aspect |
---|
| 109 | of using ANUGA under Vista or 7 is welcomed. |
---|
[5799] | 110 | |
---|
| 111 | \subsection{Quick install - Linux} |
---|
| 112 | \label{sec:linux} |
---|
| 113 | |
---|
[7951] | 114 | Please note that the following applies only to Ubuntu 10.04 (\"Lucid Lynx\"). We currently do not |
---|
| 115 | support any other Linux distributions. |
---|
[5799] | 116 | |
---|
[7951] | 117 | \subsubsection{Method 1} |
---|
[5799] | 118 | |
---|
[7951] | 119 | Choose the appropriate deb package for your architecture, download and use the package installer to install. |
---|
[5799] | 120 | |
---|
[7951] | 121 | i386: \url{https://sourceforge.net/projects/anuga/files/anuga_ubuntu_package/python-anuga_1.2.0-0ubuntu3_i386.deb/download}\\ |
---|
| 122 | AMD64: \url{https://sourceforge.net/projects/anuga/files/anuga_ubuntu_package/python-anuga_1.2.0-0ubuntu3_amd64.deb/download} |
---|
[7299] | 123 | |
---|
[7951] | 124 | \subsubsection{Method 2} |
---|
[7299] | 125 | |
---|
[7951] | 126 | Open a terminal and enter: |
---|
| 127 | \begin{verbatim} |
---|
| 128 | sudo add-apt-repository ppa:anuga/ppa |
---|
| 129 | sudo apt-get update |
---|
| 130 | sudo apt-get install python-anuga |
---|
| 131 | \end{verbatim} |
---|
[7299] | 132 | |
---|
[7951] | 133 | \subsubsection{Method 3} |
---|
[7299] | 134 | |
---|
[7951] | 135 | Add the following lines to your \code{/etc/apt/sources.list}: |
---|
| 136 | \begin{verbatim} |
---|
| 137 | deb http://ppa.launchpad.net/anuga/ppa/ubuntu lucid main |
---|
| 138 | deb-src http://ppa.launchpad.net/anuga/ppa/ubuntu lucid main |
---|
| 139 | \end{verbatim} |
---|
| 140 | Download the ANUGA key from \url{https://datamining.anu.edu.au/anuga/raw-attachment/wiki/WikiStart/anuga.key}. You can add this key with: |
---|
| 141 | \begin{verbatim} |
---|
| 142 | sudo apt-key add anuga.key |
---|
| 143 | \end{verbatim} |
---|
| 144 | or go to System -$>$ Administration -$>$ Software Sources -$>$ Authentication -$>$ Import Key File |
---|
[7299] | 145 | |
---|
[7951] | 146 | Open a terminal and enter: |
---|
| 147 | \begin{verbatim} |
---|
| 148 | sudo apt-get update |
---|
| 149 | sudo apt-get install python-anuga |
---|
| 150 | \end{verbatim} |
---|
[7299] | 151 | |
---|
| 152 | |
---|
| 153 | |
---|
| 154 | |
---|
[5799] | 155 | \section{Optional but recommended software} |
---|
| 156 | This software is not required to run the ANUGA toolbox, but it is recommended. |
---|
| 157 | \begin{itemize} |
---|
[7299] | 158 | \item psyco. Speeds up ANUGA by about 30\%, so is strongly recommended. |
---|
| 159 | Under Ubuntu install either through Synaptic or by: |
---|
[5799] | 160 | \begin{verbatim}sudo apt-get install python-psyco\end{verbatim} |
---|
| 161 | Under Windows install the file \code{psyco-1.6.win32-py25.exe} |
---|
[7299] | 162 | which you can find on the \url{http://psyco.sourceforge.net/download.html} page. |
---|
| 163 | |
---|
[5799] | 164 | \item VTK. The Visualization Toolkit. Under Ubuntu install either through Synaptic or by: |
---|
| 165 | \begin{verbatim}sudo apt-get install python-vtk\end{verbatim} |
---|
[7299] | 166 | Under Windows install the file \code{vtk-5.4.2-win32.exe} |
---|
| 167 | from the \url{http://www.vtk.org/VTK/resources/software.html} page. |
---|
[5799] | 168 | \end{itemize} |
---|
| 169 | |
---|
| 170 | |
---|
| 171 | |
---|
| 172 | \section{Testing} |
---|
| 173 | |
---|
| 174 | In the ANUGA root directory, run the test suite: |
---|
| 175 | \begin{verbatim} |
---|
| 176 | python test_all.py |
---|
| 177 | \end{verbatim} |
---|
| 178 | ANUGA has been succesfully installed if the tests pass as follows: |
---|
| 179 | \begin{verbatim} |
---|
| 180 | ... |
---|
| 181 | test_data_manager.py |
---|
| 182 | test_interpolate_sww.py |
---|
| 183 | test_mesh.py |
---|
| 184 | test_mesh_interface.py |
---|
| 185 | test_triangmodule.py |
---|
| 186 | test_triangmoduleII.py |
---|
| 187 | test_advection.py |
---|
[5801] | 188 | ................................................................................. |
---|
| 189 | ................................................................................. |
---|
| 190 | ................................................................................. |
---|
| 191 | ................................................................................. |
---|
| 192 | ................................................................................. |
---|
| 193 | ................................................................................. |
---|
| 194 | ................................................................................. |
---|
| 195 | .......................... |
---|
[5799] | 196 | ---------------------------------------------------------------------- |
---|
| 197 | Ran 593 tests in 42.712s |
---|
| 198 | |
---|
| 199 | OK |
---|
| 200 | \end{verbatim} |
---|
| 201 | |
---|
[7527] | 202 | Note that if psycho is not installed, a number of psycho related warnings will appear. These warnings |
---|
| 203 | can be ignored. |
---|
[5799] | 204 | |
---|
| 205 | %\section{Other stuff to be included} |
---|
| 206 | % |
---|
| 207 | %\begin{verbatim} |
---|
| 208 | %Install tortoise from downloads (ITs didn't integrate wih explorer). |
---|
| 209 | %In settings set proxy to proxy.agso.gov.au 8080 |
---|
| 210 | %% |
---|
| 211 | % |
---|
| 212 | %Install swollen from latest distro (in subversion) |
---|
| 213 | % |
---|
| 214 | % |
---|
| 215 | %\end{verbatim} |
---|
| 216 | |
---|
| 217 | |
---|
| 218 | \appendix |
---|
| 219 | \chapter{Miscellaneous procedures} |
---|
| 220 | \section{Setting the PATH on Windows} |
---|
| 221 | \label{sec:setwindowspath} |
---|
| 222 | |
---|
[7527] | 223 | The Windows one-click installer should automatically set the necessary PATH |
---|
| 224 | environment "System variables". However, in case you do not have |
---|
| 225 | permission to modify the system variable, then the method of setting the PATH environment "User variable" |
---|
| 226 | for Windows XP is shown here. Setting the variable for Windows Vista should be similar. |
---|
[5799] | 227 | |
---|
| 228 | \setlength\fboxsep{0pt} |
---|
| 229 | \setlength\fboxrule{1.0pt} |
---|
| 230 | |
---|
| 231 | First, open the Control Panel: |
---|
| 232 | \begin{figure}[ht] |
---|
| 233 | \centerline{\fbox{\includegraphics[scale=0.75]{installgraphics/winsetpath1.png}}} |
---|
| 234 | % \caption{Run Control Panel from the Start menu} |
---|
| 235 | \label{fig:winsetpath1} |
---|
| 236 | \end{figure} |
---|
| 237 | |
---|
| 238 | Next, start the System applet: |
---|
| 239 | \begin{figure}[ht] |
---|
| 240 | \centerline{\fbox{\includegraphics[scale=0.75]{installgraphics/winsetpath2.png}}} |
---|
| 241 | % \caption{Start the System applet} |
---|
| 242 | \label{fig:winsetpath2} |
---|
| 243 | \end{figure} |
---|
| 244 | |
---|
| 245 | \pagebreak |
---|
| 246 | |
---|
| 247 | Select the \code{Advanced} tab in the System Properties window: |
---|
| 248 | \begin{figure}[ht] |
---|
| 249 | \centerline{\includegraphics[scale=0.5]{installgraphics/winsetpath3.png}} |
---|
| 250 | % \caption{Select the Advanced tab} |
---|
| 251 | \label{fig:winsetpath3} |
---|
| 252 | \end{figure} |
---|
| 253 | |
---|
| 254 | %\pagebreak |
---|
| 255 | |
---|
| 256 | Press the \code{Environment Variables} button in the \code{Advanced} tab: |
---|
| 257 | \begin{figure}[ht] |
---|
| 258 | \centerline{\includegraphics[scale=0.5]{installgraphics/winsetpath4.png}} |
---|
| 259 | % \caption{Press the Environment Variables button} |
---|
| 260 | \label{fig:winsetpath4} |
---|
| 261 | \end{figure} |
---|
| 262 | |
---|
| 263 | \pagebreak |
---|
| 264 | |
---|
[6960] | 265 | If the \code{PATH} variable is not defined in the 'User variables' or 'System variables' windows, |
---|
| 266 | press the \code{New} button in either of the two windows (for a personal machine, choose the 'System variables' window). |
---|
| 267 | |
---|
| 268 | If \code{PATH} already exists in the 'User variable' or 'System variables' window, |
---|
| 269 | select the row with the \code{PATH} variable name in the appropriate window |
---|
| 270 | and press the \code{Edit} button next to the \code{New} button in that window: |
---|
[5799] | 271 | \begin{figure}[ht] |
---|
| 272 | \centerline{\includegraphics[scale=0.5]{installgraphics/winsetpath5.png}} |
---|
| 273 | % \caption{Press the New button} |
---|
| 274 | \label{fig:winsetpath5} |
---|
| 275 | \end{figure} |
---|
| 276 | |
---|
| 277 | %\pagebreak |
---|
| 278 | |
---|
| 279 | You will be shown the editor window whichever button you pressed in the above step. If the \code{Variable name} box is empty |
---|
| 280 | 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 |
---|
| 281 | is already some text in the box, place your additional value at the front of the existing value, not forgetting to terminate your additional |
---|
| 282 | string with the ';' character. The final value string must be a series of directory names seperated by ';' characters: |
---|
| 283 | \begin{figure}[ht] |
---|
| 284 | \centerline{\includegraphics[scale=0.75]{installgraphics/winsetpath6.png}} |
---|
| 285 | % \caption{Modifying the PATH value} |
---|
| 286 | \label{fig:winsetpath6} |
---|
| 287 | \end{figure} |
---|
| 288 | |
---|
| 289 | When you are finished, press the \code{OK} button and exit from the applet. |
---|
| 290 | |
---|
| 291 | \pagebreak |
---|
| 292 | |
---|
| 293 | \section{Associating animate.exe with a .sww file} |
---|
| 294 | \label{sec:assocanimatesww} |
---|
| 295 | |
---|
[7527] | 296 | The one-click installer should associate animate.exe with .sww files automatically. However, the method of associating |
---|
| 297 | \code{animate.exe} with a \code{.sww} file manually is shown here for Windows XP. |
---|
[5799] | 298 | A similar process should work for Windows Vista. |
---|
| 299 | |
---|
| 300 | Double left-click on any \code{.sww} file. This brings up a dialog because Windows doesn't know how to open the file: |
---|
| 301 | \begin{figure}[ht] |
---|
| 302 | \centerline{\fbox{\includegraphics[scale=0.5]{installgraphics/winassoc1.png}}} |
---|
| 303 | % \caption{Try to open the .sww file} |
---|
| 304 | \label{fig:winassoc1} |
---|
| 305 | \end{figure} |
---|
| 306 | |
---|
| 307 | Select the "\code{Select the program from a list}" radiobutton and press the \code{OK} button: |
---|
| 308 | \begin{figure}[ht] |
---|
| 309 | \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc2.png}} |
---|
| 310 | % \caption{Select the program from a list} |
---|
| 311 | \label{fig:winassoc2} |
---|
| 312 | \end{figure} |
---|
| 313 | |
---|
| 314 | \pagebreak |
---|
| 315 | |
---|
| 316 | Press the \code{Browse...} button to find the \code{animate.exe} program: |
---|
| 317 | \begin{figure}[ht] |
---|
| 318 | \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc3.png}} |
---|
| 319 | % \caption{Find animate.exe program} |
---|
| 320 | \label{fig:winassoc3} |
---|
| 321 | \end{figure} |
---|
| 322 | |
---|
| 323 | Navigate to the \code{C:$\backslash$Program Files$\backslash$anuga_viewer} directory: |
---|
| 324 | \begin{figure}[ht] |
---|
| 325 | \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc4.png}} |
---|
| 326 | % \caption{Navigate into Program Files|anuga_viewer directory} |
---|
| 327 | \label{fig:winassoc4} |
---|
| 328 | \end{figure} |
---|
| 329 | |
---|
| 330 | \pagebreak |
---|
| 331 | |
---|
| 332 | Select \code{animate.exe} and press the \code{Open} button: |
---|
| 333 | \begin{figure}[ht] |
---|
| 334 | \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc5.png}} |
---|
| 335 | % \caption{Select the animate.exe program press Open} |
---|
| 336 | \label{fig:winassoc5} |
---|
| 337 | \end{figure} |
---|
| 338 | |
---|
| 339 | Finally, press the \code{OK} button: |
---|
| 340 | \begin{figure}[ht] |
---|
| 341 | \centerline{\includegraphics[scale=0.5]{installgraphics/winassoc6.png}} |
---|
| 342 | % \caption{Press the OK button} |
---|
| 343 | \label{fig:winassoc6} |
---|
| 344 | \end{figure} |
---|
| 345 | |
---|
| 346 | |
---|
| 347 | \end{document} |
---|