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

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

Smoothed out the Windows part of installation.

  • Property svn:keywords set to LastChangedDate LastChangedRevision LastChangedBy HeadURL Id
File size: 12.9 KB
Line 
1\documentclass{manual}
2
3
4\title{ANUGA Installation Guide}
5
6\author{Ole Nielsen, Duncan Gray, Jane Sexton}
7
8% Please at least include a long-lived email address;
9% the rest is at your discretion.
10\authoraddress{Geoscience Australia \\
11  Email: \email{ole.nielsen@ga.gov.au}
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
47This document outlines the required software for installing the Anuga toolbox.
48All components are licensed as open source and readily available from the net.
49It is assumed that the reader is familiar with the Python programming language and the process of downloading, installing and unpacking files into directories.
50
51
52\section{System requirements}
53\label{sec:requirements}
54
55To run ANUGA you will need a Windows (2000 or XP) or a Linux PC with at
56least 512MB RAM. The viewer (Windows only) requires a graphics adapter that
57is OpenGL compatible. It has been tested with ATI FireGL X1 cards
58and the NVIDIA family. It may not work with other cards such as those from the
59Intel(R) 82915G Express Chipset Family.
60
61
62
63\section{Quick install (Windows only)}
64
65This section provides the quickest path to getting ANUGA up and running on a Windows machine.
66For Linux and for more details please refer to Section \ref{sec:prerequisites}.
67
68\begin{enumerate} 
69  \item For Python 2.5, install: Python2.5, Scientific Python, Mingw, Numeric
70    and the NetCDF library. Note that the scientific Python installation
71    sometimes ends with an error message, although ANUGA still works.
72    These packages are available from either:
73    \begin{itemize} 
74      \item The supplied ANUGA distribution folder: \code{pre_requisites$\backslash$2.5} .
75        Install in order:
76        \begin{enumerate}
77          \item \code{python-2.5.msi}
78          \item \code{Numeric-23.8.2.win32-py2.5.exe}
79          \item \code{ScientificPython-2.7.8.win32-py2.5.exe}
80          \item \code{MinGW-5.1.4.exe}
81        \end{enumerate} and then unpack \code{netcdf-3.6.1-win32.zip} into \code{C:$\backslash$bin} as suggested below.
82      \item The WEB. Install in order:
83          \begin{enumerate} 
84              \item \url{http://www.python.org/download/} and click on the \code{Python 2.5.x Windows installer} link to get
85                \code{python-2.5.x.msi}. Execute this file to install Python 2.5.
86              \item \url{http://sourcesup.cru.fr/frs/?group\%5Fid=180}. Download \code{Numeric-23.8.2.win32-py2.5.exe}
87                and execute it to install Numeric Python.
88              \item \url{http://sourcesup.cru.fr/frs/?group\%5Fid=180}. Download \code{ScientificPython-2.X.X.win32-py2.5.exe}
89                and execute it to install Scientific Python.
90              \item \url{http://sourceforge.net/project/showfiles.php?group\%5Fid=2435}. Click on the \code{Download} link for
91                the \code{Automated MinGW Installer} package. Execute the file \code{MinGW-5.X.X.exe} to install the MinGW environment.
92                Note that you will need a working internet connection to install WinGW.
93              \item \url{http://www.unidata.ucar.edu/software/netcdf/binaries.html} and click on the
94                "\code{Windows DLL}" link in the NetCDF 3.6.1 section.  This will download the file \code{netcdf-3.6.1-win32.zip}.
95                Unpack this in a folder that is available on the system path.
96                We suggest unpacking it into \code{C:$\backslash$bin}.
97          \end{enumerate}   
98    \end{itemize}   
99 
100  \item For Python 2.4, install: The Enthought version of Python2.4, Scientific Python
101    and the NetCDF library\footnote{Separate installation of Scientific
102    Python and NetCDF
103    will become unneccesary once Enthought sorts out netcdf support
104    (see \url{https://svn.enthought.com/enthought/ticket/917})}.
105    These are available from either:
106    \begin{itemize} 
107      \item The supplied ANUGA distribution, under the folder \code{pre_requisites} .
108        Install in order:
109        \begin{enumerate}
110          \item enthon-python2.4-1.0.0.exe
111          \item ScientificPython-2.4.9.win32-py2.4.exe
112        \end{enumerate}
113        and then unpack \code{netcdf-3.6.1-beta1-win32dll.zip} into \code{C:$\backslash$bin} as suggested below.
114      \item The WEB. Install in order:
115      \begin{enumerate} 
116        \item \url{http://code.enthought.com/projects/} and install the Enthought environment for Python 2.4.x.
117        \item \url{http://sourceforge.net/project/showfiles.php?group\%5Fid=172848}. Click on the \code{Download} link for Scientific Python
118          and download \code{ScientificPython-2.4.9.win32-py2.4.exe} which will install Scientific Python.
119        \item \url{http://www.unidata.ucar.edu/software/netcdf/binaries.html} and click on the
120          "\code{Windows DLL}" link in the NetCDF 3.6.1 section.  This will download the file \code{netcdf-3.6.1-win32.zip}.
121          Unpack this in a folder that is available on the system path. We suggest unpacking it into \code{C:$\backslash$bin} .
122      \end{enumerate}   
123    \end{itemize}   
124 
125  \item Add the following to the PATH environment variable:
126    \begin{verbatim}PATH=C:\Python24;C:\Python24\Enthought\MingW\bin;C:\bin\end{verbatim}
127    For details on how to do this under windows please refer to Section \ref{sec:windowspath}.
128
129  \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 -
130                                                                          the remedy is to rename them back or use another browser such as Firefox.} 
131    in the python site-packages directory \code{C:$\backslash$Python24$\backslash$Lib$\backslash$site-packages}.
132    This is often done in Windows by double clicking on the .tgz file and then 'browse to' the destination directory.
133
134  \item In the ANUGA root directory (\code{C:$\backslash$Python24$\backslash$Lib$\backslash$site-packages$\backslash$anuga}),
135    run the compilation script (either from the commandline or by running it in IDLE):
136    \begin{verbatim}python compile_all.py\end{verbatim}
137
138  \item In the ANUGA root directory, run the test suite (either from the commandline or by running it in IDLE):
139    \begin{verbatim}python test_all.py\end{verbatim} ANUGA has been succesfully installed if the tests pass.
140
141  \item To verify that ANUGA succesfully reproduces a series of validation examples, go
142    to the directory \code{anuga_validation$\backslash$automated_validation_tests} in which you can run
143    \begin{verbatim}python validate_all.py\end{verbatim}
144
145
146  \item To install the ANUGA viewer:
147    \begin{enumerate} 
148      \item Unpack the distribution (\code{anuga_viewer_1.0.tgz}) into
149        \begin{verbatim}C:\Program Files\end{verbatim}
150      \item Double click on the test file
151        \begin{verbatim}C:\Program Files\anuga_viewer\cylinders.sww\end{verbatim}       
152      \item Associate .sww files with the executable
153      \begin{verbatim}C:\Program Files\anuga_viewer\animate.exe\end{verbatim}       
154    \end{enumerate} 
155
156    Try the demos provided in the ANUGA directory \code{anuga\_demos} 
157    (discussed in the ANUGA user manual
158    and also at
159    \url{http://datamining.anu.edu.au/\~{}ole/anuga/user_manual/anuga_user_manual.pdf})
160    and view the resulting .sww files with the anuga_viewer.
161\end{enumerate}   
162
163
164%To run the ANUGA against the Okushiri Island wave tank validation dataset
165%(\url{http://www.cee.cornell.edu/longwave})
166%go to \code{anuga_validation}
167% into
168%any directory and run the scripts \code{create_okushiri.py},
169%\code{run_okushiri.py} and \code{compare_timeseries.py}.  See also the
170%\code{README.txt} file that comes with the validation scripts for more
171%details.
172
173
174\clearpage
175\section{Pre-requisites (software)}
176\label{sec:prerequisites}
177
178This and the following sections is for custom installations and
179installations using Linux.
180
181The ANUGA software core (shallow\_water, pmesh, least\_squares, ...) depends on the following software:
182\begin{itemize}
183  \item python 2.3 or later\footnote{Problems have been observed with
184    Python 2.5 and Numeric on 64 bit platforms. See
185    \url{https://datamining.anu.edu.au/anuga/ticket/221}} 
186    \url{http://www.python.org}
187  %\footnote{Note, the
188  %dll python2X.dll is needed to compile ANUGA, but is not always
189  %automatically added for versions 2.4 and above.  Install it into the
190  %python2X directory, if you need it.}. 
191  \item python-numeric for Linux.  It's called Numeric in Windows. 
192  %\item python-dev (Interestingly, numeric seems to be installed as
193  %well) for Linux.  This is not necessary for Windows.
194  \item python-scientific (to provide python-netcdf) for Linux.  It's
195    called ScientificPython in Windows.
196  \item NETCDF.  Extract the file netcdf.dll, and put in C://Windows//System32// (Windows XP) or C://WINNT//System32 (Windows NT or 2000).     
197  \item A C compiler such as gcc (from GNU in case of Linux and MinGW
198  in case of Windows)
199  %\item scons for automatically compiling the distribution.
200\end{itemize}
201
202Note: All of these can be installed in one go on Windows platforms by
203using the Enthought Python
204distribution available at \url{http://code.enthought.com/projects/} .
205
206\section{Recommended software}
207
208\begin{itemize}
209  \item psyco: \url{http://psyco.sourceforge.net/index.html} .  Speeds up anuga by about 30\%.
210  %\item visual python \url{http://vpython.org}
211  \item matplotlib: (pylab) for quality 2d plotting (moving towards mandatory requirement and now part of Enthought).
212  \item VTK: \url{http://mayavi.sourceforge.net/dwnld/vtk/win32/} - also now part of Enthought.
213\end{itemize}
214
215
216
217\section{System configuration}
218
219
220The system path on Win32 architectures must contain the
221directories (this examples assumes the Enthought Python 2.4 distribution
222has been installed. Path names may vary depending on the
223exact configuration).
224\begin{verbatim}
225PATH=C:\Python24;C:\Python24\Enthought\MingW\bin;C:\Program Files\anuga_viewer
226\end{verbatim}
227The path should be analoguous for Unix operating systems.
228
229If anuga is not installed in the python site-packages directory
230the root directory for all
231anuga/inundation modules must be on the pythonpath, e.g.\
232\begin{verbatim}
233PYTHONPATH=C:\anuga_core\source
234\end{verbatim}
235
236
237
238
239
240\section{Installation of source zip file}
241Get a source zip file, for example, anuga_source_3807.zip, and expand
242it in the python site-packages directory (\code{C:$\backslash$Python24$\backslash$Lib$\backslash$site-packages})
243
244In the ANUGA root directory (\code{C:$\backslash$Python24$\backslash$Lib$\backslash$site-packages$\backslash$anuga}),
245run the compilation script:
246\begin{verbatim}
247python compile_all.py
248\end{verbatim}
249
250%or (in anuga_core)
251% scons install
252% scons -c #(clean)
253
254
255\subsection{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----------------------------------------------------------------------
277Ran 593 tests in 42.712s
278
279OK
280\end{verbatim}
281
282
283
284%\section{Other stuff to be included}
285%
286%\begin{verbatim}
287%Install tortoise from downloads (ITs didn't integrate wih explorer).
288%In settings set proxy to proxy.agso.gov.au  8080
289%%
290%
291%Install swollen from latest distro (in subversion)
292%
293%
294%\end{verbatim}
295
296
297\chapter{Appendix}
298\section{Setting the PATH on Windows}
299\label{sec:windowspath}
300
301
302
303\end{document}
Note: See TracBrowser for help on using the repository browser.