install.tex 27.5 KB
Newer Older
1
2
\section{Installation of \Dumux} \label{install}
\subsection{Preliminary remarks}
3

4
5
6
7
8
In this section about the installation of \Dumux it is assumed that you work on a UNIX or Linux compatible operating system
and that you are familiar with the use of a command line shell. Installation means that you unpack \Dune together with \Dumux in a certain directory.
You than compile it in that directory tree and do you further working on there too. You also should know how to install new software packages
or you should have a person aside which can give you assistance with the command line and package installation. In section \ref{sec:prerequisites} we list prerequisites for running \Dune and \Dumux. 
Please check this paragraph whether you can fulfill them. In addition, section \ref{sec:external-modules-libraries} provides some details on optional libraries and modules are given. \\
9

10
In a technical sense \Dumux is a module of \Dune. 
David Werner's avatar
David Werner committed
11
That's why the installation procedure of \Dumux is the same as that of \Dune. 
12
13
14
The details regarding the installation of \Dune are provided on the \Dune website \cite{DUNE-INST}. 
If you are interested in more details of the build system that is used,
you can find them in the {\Dune}'s Build System Howto \cite{DUNE-BS}.\\
15

16

17
As in a \Dune installation, all \Dune modules including \Dumux get extracted into a common directory. We refer to that directory for purpose of documentation abstractly as {\Dune} root directory or shortly as {\Dune}-Root. If it is used as directory's path of a shell command it is typed as \texttt{\Dune-Root}. For the real {\Dune} root directory on your file system any valid directory name can be chosen.\\
18

19
Source code files for each \Dune module are contained in their own subdirectory within {\Dune}-Root.
20
21
22
We name this directory of a certain module ``module root directory" or \texttt{module-root-directory} if it is a directory path's,
e.g. for module \texttt{dumux} these names are  ``dumux root directory" respective \texttt{dumux-root-directory}.
The real directory names for modules can be chosen arbitrarily, in this manual they are the same as the
23
module name or the module name extended by a version number suffix.
David Werner's avatar
David Werner committed
24
The name of a \Dune module itself is always defined via the content of file \texttt{dune.module} in its own root
25
directory, but this should not get changed by an user. The user is allowed to have own files and directories in \Dune-Root, which are not related to \Dune's need.
26

27
After installing source code for all relevant \Dune modules including \Dumux, \Dune is being built by the shell-command \texttt{dunecontrol} which is part of the \Dune build system. The \Dune build system is a front-end adapted to the needs of \Dune to the GNU build system.
28

David Werner's avatar
David Werner committed
29
\subsection{Prerequisites} \label{sec:prerequisites}
David Werner's avatar
David Werner committed
30
The GNU tool chain of \texttt{g++}  and tools of GNU build system \cite{GNU-BS} also known as GNU autotools
31
(i.e. \texttt{autoconf}, \texttt{automake}, \texttt{autogen}, \texttt{libtool}) as well as GNU's variant of \texttt{make}
32
must be available in a recent version. For Ubuntu Linux, e.g.,  these are contained in the
David Werner's avatar
David Werner committed
33
34
packages \texttt{autoconf}, \texttt{automake}, \texttt{libtool}
and the C++ compiler \texttt{g++} and \texttt{make} are contained in \texttt{build-essential}.
35

36
At the time of writing this manual, it is expected that \texttt{g++} of version $\geqslant$ 4.4.1, \texttt{automake} of version $\geqslant$ 1.11,
37
\texttt{autoconf} of version $\geqslant$ 2.65, \texttt{autogen} of version $\geqslant$ 5.9.7,  \texttt{libtool} of version $\geqslant$ 2.2.6
David Werner's avatar
David Werner committed
38
and GNU \texttt{make} version $\geqslant$ 3.81 should do their job for building \Dumux.\\
David Werner's avatar
David Werner committed
39

40
\Dumux makes use of the \texttt{boost} library in the version $\geqslant$ 1.33.1 but optional external modules may require a more recent version. 
David Werner's avatar
David Werner committed
41
It is thus necessary to install an appropriate developer package of \texttt{boost}
42
which is sometimes also named \texttt{libboost}. The matching Ubuntu Linux package is \texttt{libboost-dev}. \\
David Werner's avatar
David Werner committed
43

44
The building of included documentation like this handbook requires \LaTeX\  and auxiliary tools
David Werner's avatar
David Werner committed
45
like \texttt{dvipdf} and \texttt{bibtex}. One usually chooses a \LaTeX\  distribution like \texttt{texlive} for doing that.
46
It is possible to switch off the building of the documentation by setting the switch \texttt{--disable-documentation} in the \texttt{CONFIGURE\_FLAGS} of the building options as.
David Werner's avatar
David Werner committed
47
Additional parts of documentation are contained in source code files as special formatted comments.
48
Extracting them can be done by program \texttt{doxygen} (version $\geqslant$ 1.7.2 works). See for this optional step section \ref{sec:build-doxy-doc}.\\
David Werner's avatar
David Werner committed
49
50
51
52

Depending whether you are going to use external libraries and modules for additional \Dune features 
additional software packages  may required. Some hints on that are given in section \ref{sec:external-modules-libraries}.\\

53
54
For the extraction of the content of tar-files, the GNU version of \texttt{tar} is used.
The subversion (SVN) software repositories can be accessed with the help of a subversion client. We recommend the Apache Subversion command-line client \texttt{svn}
David Werner's avatar
David Werner committed
55
contained in Apache Subversion of version $\geqslant$ 1.6.0 \cite{APACHE-SUBVERSION-HP}. 
56

57
\subsection{Obtaining source code for \Dune and \Dumux}
58
As written before the \Dumux release 2.0 is based on the \Dune release 2.0, comprising the core modules 
David Werner's avatar
David Werner committed
59
\texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, \texttt{dune-localfunctions} and the external dune
60
61
module \texttt{dune-pdelab}. Thus, for a proper \Dumux installation these modules are required.
Naturally, the external \Dune module \texttt{dumux} is required, too.\\
62

63
64
Two possibilities exist to get the source code of \Dune and \Dumux.
Firstly, \Dune and \Dumux can be downloaded as tar-files from the respective {\Dune} and {\Dumux} website. They have to be extracted as described in the next paragraph.
65
Secondly, a method to obtain the most recent source code (or more generally any of its the previous revisions) by direct access via Internet to the software repositories of the revision control system is described in the subsequent part. \Dune and \Dumux use Apache Subversion for their software repositories. However, if a user does not want to use the most recent version,
66
certain version tags (i.e. special names), version numbers and even software branches are means of the software revision control system to provide access to different versions of the software.
67

68
\paragraph{Obtaining the software by installing tar-files}
69
70
The slightly old-fashioned named tape-archive-file shortly named tar-file or tarball is a common file format for distributing collections of files contained in these archives.
The extraction from the tar-files is done as follows: 
71
72
Download the tarballs from the respective \Dune (version 2.0) and \Dumux websites to a certain folder in your file system.
Create the {\Dune} root directory, named below in the example DUMUX, then extract the content of the tar-files by the command-line program tar there.
73
This can be achieved by the following shell commands. Replace \texttt{path\_to\_tarball} with the directory name where the downloaded files are actually located.
74
75
76
77
78
79
80
81
82
83
84

\begin{lstlisting}[style=Bash]
$ mkdir DUMUX
$ cd DUMUX
$ tar xzvf path_to_tarball_of/dune-common-2.0.tar.gz 
$ tar xzvf path_to_tarball_of/dune-grid-2.0.tar.gz 
$ tar xzvf path_to_tarball_of/dune-istl-2.0.tar.gz 
$ tar xzvf path_to_tarball_of/dune-localfunctions-2.0.tar.gz 
$ tar xzvf path_to_tarball_of/dumux-2.0.tar.gz
\end{lstlisting}

85
After extraction, the actual name of the dumux root directory is \texttt{dumux-2.0}.\\
86

87
Furthermore, if you with to install the optional \Dune Grid-Howto:
88
89
90
91
92

\begin{lstlisting}[style=Bash]
$ tar xzvf path_to_tarball_of/dune-grid-howto-2.0.tar.gz
\end{lstlisting}

93
94
However, the required \Dune-module \texttt{dune-pdelab} is not available as tar-file.
That's why one has to install it from a software repository by the second method.
95
If the svn command is available in the command line, it can done as follows: 
96

97
98
99
\begin{lstlisting}[style=Bash]
$ svn co https://svn.dune-project.org/svn/dune-pdelab/branches/2.0snapshot dune-pdelab
\end{lstlisting}
100

101
102
\paragraph{Obtaining \Dune and \Dumux from software repositories} 

103
104
Direct access to a software revision control system for downloading code can be of later advantage for the user. 
It can be easier for him to keep up with code changes and to receive important bug fixes using the update command of the revision control system. \Dune and \Dumux use Apache Subversion. \\
Bernd Flemisch's avatar
Bernd Flemisch committed
105

106
107
To access the software repositories a certain program is needed which is referred here shortly as subversion client. In our description, we use the subversion client of the Apache Subversion software itself, which is a command-line tool named \texttt{svn}. 
The Apache Subversion client \texttt{svn} is available for most Linux and UNIX distributions as software package.
108

109
110
111
In the technical speech of Apache Subversion ``checking out a certain software version" means nothing more then fetching 
a local copy from the software repository and laying it out in the file system.  Additionally to the software some more files for the use of the software revision control system itself are created. They are kept in directories named \texttt{.svn} and can be found in each subfolder that is under version control.
If you have developer access to \Dumux, it is also possible to do the opposite, i.e. loading up a modified revision of software into the software repository. This is usually termed as ``software commit".\\
112

113
The installation procedure is done as follows:
114
115
116
117
Create a  {\Dune} root directory, named DUMUX in the lines below.
Then, enter the previously created directory and check out the desired modules. 
As you see below, the check-out uses two different servers for getting the sources, one for \Dune and one for {\Dumux}.
The \Dune modules of the stable 2.0 release are checked out as described on the \Dune website \cite{DUNE-DOWNLOAD-SVN}:
118
119

\begin{lstlisting}[style=Bash]
David Werner's avatar
David Werner committed
120
121
$ mkdir DUMUX
$ cd DUMUX
122
123
124
125
126
127
$ svn co https://svn.dune-project.org/svn/dune-common/releases/2.0 dune-common
$ svn co https://svn.dune-project.org/svn/dune-grid/releases/2.0 dune-grid
$ svn co https://svn.dune-project.org/svn/dune-istl/releases/2.0 dune-istl
$ svn co https://svn.dune-project.org/svn/dune-localfunctions/releases/2.0 dune-localfunctions
$ svn co https://svn.dune-project.org/svn/dune-pdelab/branches/2.0snapshot dune-pdelab
\end{lstlisting}
Bernd Flemisch's avatar
Bernd Flemisch committed
128

129
130
131
132
133
The newest (unstable) developments are also provided in these repositories (usually in a folder called ``trunk''). Please check the \Dune website \cite{DUNE-DOWNLOAD-SVN} for further information. However, the current \Dumux release is based on the stable 2.0 release and it will not compile without further adaptations using the the newest versions of \Dune.\\

The additional module \texttt{dune-grid-howto} is a tutorial which provides information about the \Dune grid interface.
It may give you an idea how some abstractions in \Dune are done.
The \texttt{dune-grid-howto} is not required by \Dumux, the installation is optional. It is done by: 
134
135
136
137

\begin{lstlisting}[style=Bash]
$ svn co https://svn.dune-project.org/svn/dune-grid-howto/releases/2.0 dune-grid-howto
\end{lstlisting}
138

139
140
141
The \texttt{dumux} module is then checked out as described below (see also the \Dumux website \cite{DUMUX-HP}).
Its file tree has to be created in the \Dune-Root directory, where the \Dune modules are also have been checked out to. That's why the next command
is executed there, too:
142

143
144
145
\begin{lstlisting}[style=Bash]
$ svn co --username=anonymous --password='' svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux
\end{lstlisting}
146

147
We call the dumux root directory just \texttt{dumux} here.
148

149
\paragraph{Hints for \Dumux-Developers}
150
If you also want to actively participate in the development of \Dumux, you can apply either for full developer
151
access or for developer access on certain parts of \Dumux. Granted developer access means that
152
153
154
you are allowed to commit own code and that you can access the \texttt{dumux-devel} module.
This enhances \texttt{dumux} by providing code from the developer group, which is currently being developed.
A developer usually checks out non-anonymously the modules \texttt{dumux} and \texttt{dumux-devel}.
155
This is done by the commands below. But \texttt{joeuser} needs to replaced by
156
the actual user name of the developer for accessing the software repository:
157
158
159
160
161
162

\begin{lstlisting}[style=Bash]
$ svn co --username=joeuser svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux
$ svn co --username=joeuser svn://svn.iws.uni-stuttgart.de/DUMUX/dune-mux/trunk dumux-devel
\end{lstlisting}

163
164
\texttt{Dumux-devel} itself makes use of the stable part \texttt{dumux}. Hence, the two parts have to be checked out together. 
One can omit the \texttt{--username} option in the commands above, if the user name for the repository access is
165
identical to the one for the system account.\\
166

167
Please choose either not to store the password by subversion in an insecure way or
168
169
choose to store it by subversion in a secure way, e.g. together with \texttt{kwallet} or \texttt{gnomekeyring}.
Check the documentation of subversion, how this is being done.
170
A leaked out password can be used by evil persons to abuse a software repository.
171

David Werner's avatar
David Werner committed
172
173
\paragraph{checkout-dumux script}
The shell-script \texttt{checkout-dumux} facilitates setting up a {\Dune}/{\Dumux} directory tree.
174
175
It is contained in the download section of \Dumux' web page \cite{DUMUX-HP}.
For example the second line below will check out the required \Dune modules and \texttt{dumux}, \texttt{dumux-devel} and the \texttt{external} folder, which contains some useful external software and libraries.
David Werner's avatar
David Werner committed
176
177
178
179
180
181

\begin{lstlisting}[style=Bash]
$ checkout-dumux -h      # show help,
$ checkout-dumux -gme -u joeuser -p password -d DUMUX 
\end{lstlisting}

182
183
\subsection{Patching \Dune or external libraries}
Patching of \Dune modules in order to work together with \Dumux
184
can be necessary for several reasons.
185
Software like a compiler or even a standard library
186
187
188
changes at times. But, for example, a certain release of a software-component that we depend on, does not reflect that change.
In the dynamic developing process of software that depends on other modules it is not always feasible 
to adapt everything to the most recent version of each module. That's why patches exist or they are be brought into existence, which fix problems with a certain module
189
of a certain release but do not introduce to much structural change. It can also happen 
190
that a release gets amendments (updates) and a formerly useful patch becomes obsolete.\\
191

192
193
194
\Dumux contains within the directory \texttt{dumux/patches} patches and documentation about their usage and application.
Please check the README file in that directory for recent information. 
In general, a patch can be applied as follows (but the exact command or the used parameters may be slightly different).
David Werner's avatar
David Werner committed
195

196
197
\begin{lstlisting}[style=Bash]
$ # make sure you are in DUNE-Root
David Werner's avatar
David Werner committed
198
$ cd dune-istl
199
200
201
$ patch -p1 < ../dumux/patches/dune-istl-2.0.patch
\end{lstlisting}

202
The \texttt{checkout-dumux} script also applies patches, if not explicitly requested to do not so.
David Werner's avatar
David Werner committed
203

204
205
\subsection{Build of \Dune and \Dumux}
\label{buildIt}
206
207
208
209
Building of \Dune and \Dumux is done by the command-line script \texttt{dunecontrol} as described in \Dune Installation Notes \cite{DUNE-INST}
and in much more comprehensive form in the \Dune Buildsystem Howto \cite{DUNE-BS}.
If something fails during the execution of \texttt{dunecontrol} feel free to report it to the \Dune or \Dumux developer mailing list,
but also try to include error details.\\
210

211
212
213
214
215
216
217
218
It is possible to compile \Dumux with nearly no explicit options to the build system.
%, but experience showed that the code quality through all parts of \Dune is not yet high enough to give the compiler full 
%freedom for allowing certain kind optimizations. 
However, for the successful compilation of \Dune and \Dumux, it is currently necessary to pass the
%As options, switches for the optimization can be set in parts
%build system for code by default, it is safer to pass 
the option \texttt{-fno-strict-aliasing} to the C++-compiler
\cite{WIKIPED-ALIASING}, which is done here via a command-line argument to \texttt{dunecontrol}:
219
220
221


\begin{lstlisting}[style=Bash]
David Werner's avatar
David Werner committed
222
$ # make sure you are in the directory DUNE-Root
223
224
225
$ ./dune-common/bin/dunecontrol --configure-opts="CXXFLAGS=-fno-strict-aliasing"  all
\end{lstlisting}

226
Too many options can make life hard, that's why usually option-files are being used together with dunecontrol and its sub-tools.
227
228
Larger sets of options are kept in them. \\

229
If you are going to compile with options suited for debugging of the code, the following
230
231
can be a starting point:

232
%Below in command-line make sure to insert the right name of dumux' root directory, which is in case of installation from tar-files \texttt{dumux-2.0} or in case of installation from subversion just \texttt{dumux}. For a developer it is also possible to take options file from \texttt{dumux-devel}.
233
234

\begin{lstlisting}[style=Bash]
David Werner's avatar
David Werner committed
235
$ # make sure you are in the directory DUNE-Root
236
237
$ cp dumux/debug.opts my-debug.opts      # create a personal version
$ gedit my-debug.opts                    # optional editing the options file 
David Werner's avatar
David Werner committed
238
$ ./dune-common/bin/dunecontrol --opts=my-debug.opts all 
239
240
\end{lstlisting}

241
More optimized code, which is typically not usable for standard debugging tasks, can produced by 
242
243

\begin{lstlisting}[style=Bash]
David Werner's avatar
David Werner committed
244
245
$ cp dumux/optim.opts my-optim.opts 
$ ./dune-common/bin/dunecontrol --opts=my-optim.opts all
246
247
\end{lstlisting}

248
249
250
251
Sometimes it is necessary to have additional options which
are specific to a package set of an operating system or
sometimes you have your own preferences.
Feel free to work with your own set of options, which may evolve over time.
252
253
The option files above are more to be understood as a starting point
for setting up an own customization than as something which is fixed.
254
255
The use of external libraries can make it necessary to add quite many options in an option-file.
It can be helpful to give your customized option file its own name, as done above.
256
257
One avoids to be confused with option files that came out of the distribution
and that can be possible updated by subversion later on.
David Werner's avatar
David Werner committed
258
259
260

\subsection{Building doxygen documentation} \label{sec:build-doxy-doc}

261
262
Doxygen documentation is done by especially formatted comments in source code, which can get extracted by the program 
\texttt{doxygen}. Beside extracting these comments, \texttt{doxygen} builds up web-browsable code structure documentation
David Werner's avatar
David Werner committed
263
264
like class hierarchy of code displayed as graphs, see \cite{DOXYGEN-HP}.\\

265
266
Building a modules doxygen documentation is done as follows provided the program \texttt{doxygen} is installed:
Set in building options the \texttt{--enable-doxygen} switch.
David Werner's avatar
David Werner committed
267
This is either accomplished by adding it in \texttt{dunecontrol} options-file to  \texttt{CONFIGURE\_FLAGS}, or by adding
268
269
it to  \texttt{dunecontrol}'s command-line-argument \texttt{--configure-opts}. 
After running \texttt{dunecontrol} enter in module's root directory the subdirectory \texttt{doc/doxygen}.
270
271
272
273
You then run the command \texttt{doxygen} within that directory. Point your web browser to the file 
\texttt{module-root-directory/doc/doxygen/html/index.html} to read the generated documentation.
All  \Dune-modules that are used here except \texttt{dune-grid-howto}  including also \texttt{dumux} contain some doxygen documentation, which can be extracted as
described in the following lines. The external library UG has also a \texttt{doc/doxygen} directory for building its doxygen documentation.
David Werner's avatar
David Werner committed
274

David Werner's avatar
David Werner committed
275
276
277
278
279
280
281
\begin{lstlisting}[style=Bash]
$ # change before next command your directory to DUNE-Root
$ cd dumux/doc/doxygen
$ doxygen
$ firefox html/index.html
\end{lstlisting}

David Werner's avatar
David Werner committed
282
283
\subsection{Building documentation of other \Dune modules}

284
285
286
287
288
If the \texttt{--enable-documentation} switch has been set to configure flags of
\texttt{dunecontrol}, this does not necessarily mean that for every 
\Dune module the documentation is being build.
However, at least Makefiles for building the documentation are generated.
Provided you run \texttt{dunecontrol} with the option above,
289
it should be possible to build documentation if available.
290
291
Check in \texttt{module-root-directory/doc/Makefile.am} which targets you can build.
E.g., for the module \texttt{dune-istl} you can build the documentation \texttt{istl.pdf} by typing the following into the console, when you are in the \Dune-Root:
David Werner's avatar
David Werner committed
292
293

\begin{lstlisting}[style=Bash]
David Werner's avatar
David Werner committed
294
$ # change before next command your directory to DUNE-Root
David Werner's avatar
David Werner committed
295
296
297
298
$ cd dune-istl/doc
$ make istl.pdf
\end{lstlisting}

299
Or for module \texttt{dune-grid-howto} the documentation can be build by: 
300
301
302
303
304
305
306

\begin{lstlisting}[style=Bash]
$ # change before next command your directory to DUNE-Root
$ cd dune-grid-howto/doc
$ make grid-howto.pdf
\end{lstlisting}

307
This applies for \Dumux too. Rebuilding the handbook can be done as follows:
308
309
310
311
312
313
314

\begin{lstlisting}[style=Bash]
$ cd dumux/doc/handbook
$ make dumux-handbook.pdf
\end{lstlisting}


315
%At the time writing this to the author no general method of building documentation contained in \Dune's modules is known.
316
317

%Alternatively, the tool CMake can be used to build \Dumux. Please check the file \texttt{INSTALL.cmake} for details.
David Werner's avatar
David Werner committed
318
319

\subsection{External libraries and modules} \label{sec:external-modules-libraries}
320

321
The libraries described in the sequel of this paragraph provide additional functionality but are not generally required to run \Dumux. 
322
323
If you are going to use an external library check the information provided on the \Dune website \cite{DUNE-EXT-LIB}.
If you are going to use an external \Dune module the website on external modules \cite{DUNE-EXT-MOD} can be helpful.\\
David Werner's avatar
David Werner committed
324
%Further information on external modules and libraries seemed to be contained in {\Dune}s Wiki \cite{DUNE-MAIN-WIKI}.
325
326


327
328
329
Installing an external library can require additional libraries which are also used by \Dune. 
For some libraries, such as BLAS or MPI, multiple versions can be installed on system.
Make sure that it uses the same library as \Dune when configuring the external library.\\
330

331
In the following list, you can find some external modules and external libraries, and some more libraries and tools which are prerequisites for their use.
332

333
\begin{itemize}
334
\item \textbf{ALBERTA}: External library for use as GRID. Adaptive multi Level finite element toolbox using Bisectioning refinement and Error control by Residual Techniques for scientific Applications. Building it requires a FORTRAN compiler \texttt{gfortran}. Download: \texttt{\url{http://www.alberta-fem.de}}.
335

336
337
\item \textbf{ALUGrid}: External library for use as GRID. ALUGrid is build by a C++-compiler like \texttt{g++}. If you want to build a parallel version, you will need \texttt{MPI}. It was successfully run with \texttt{openmpi}. The parallel version needs also a graph partitioner, such as \texttt{METIS}. It was run successfully in combination with \Dune using \texttt{METIS}. \\
Download: \texttt{\url{http://aam.mathematik.uni-freiburg.de/IAM/Research/alugrid}}
338

339
340
341
\item \textbf{\Dune-multidomaingrid}: External module. If you going to run on the same grid different domains or subdomains,
this can be the package of choice. This is done by providing a meta grid. It can be useful for multi-physics approaches or domain decomposition methods. Download: \texttt{\url{http://gitorious.org/dune-multidomaingrid}}. 
%Furthermore, the external module \textbf{\Dune-multidomain} can be useful for solving heterogenous problems on spatial subdomains. These subdomains are managed using another DUNE module called dune-multidomaingrid.
342

343
\item \textbf{PARDISO}: External library for solving linear equations. The package PARDISO is a thread-safe, high-performance, robust, memory efficient and easy to use software for solving large sparse symmetric and asymmetric linear systems of equations on shared memory multiprocessors. The precompiled binary can be downloaded after personal registration from the PARDISO website (\texttt{\url{http://www.pardiso-project.org}}).
344

345
346
347
\item \textbf{SuperLU}: External library for solving linear equations. SuperLU is a general purpose library for the direct solution of large, sparse, non-symmetric systems of linear equations. \\ (\texttt{\url{http://crd.lbl.gov/~xiaoye/SuperLU}}).

\item \textbf{UG}: External library for use as GRID. UG is a toolbox for Unstructured Grids: For \Dumux it has to be build by GNU buildsystem and a C++-compiler. That's why \Dune specific patches need applied before use. Building it makes use of the tools \texttt{lex}/\texttt{yacc} or the GNU variants \texttt{flex}/\texttt{bison}. 
348

349
350
\end{itemize}

351
The following are dependencies of some of the used libraries. You will need them depending on which modules of \Dune and which external libraries you use.
352

353
\begin{itemize}
354
\item \textbf{MPI}: The parallel version of \Dune and also some of the external dependencies need MPI when they are going to be built for parallel computing. \texttt{Openmpi} version $\geqslant$ 1.4.2 and \texttt{MPICH} in a recent version have been reported to work. 
355

356
\item \textbf{lex/yacc} or \textbf{flex/bison}: These are quite common developing tools, code generators for lexical analyzers and parsers. This is a prerequisite for UG.
357

David Werner's avatar
David Werner committed
358
\item \textbf{BLAS}: Alberta makes use of BLAS. Thus install GotoBLAS2, ATLAS, non-optimized BLAS or BLAS provided by a chip manufacturer. Take care that the installation scripts select the intended version of BLAS. See \texttt{\url{http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms}}.
359

360
\item \textbf{GotoBLAS2}: This is an optimized version of BLAS. It covers not always available all processors of the day, but quite a broad range. Its license is now very open.  A FORTRAN compiler like \texttt{gfortran} is needed to compile it.\\
David Werner's avatar
David Werner committed
361
Available by \texttt{\url{http://www.tacc.utexas.edu/tacc-projects/gotoblas2/}}.
362

363
364
\item \textbf{METIS}: This is a dependency of ALUGrid, if you are going to run it parallel.

David Werner's avatar
David Werner committed
365
\item \textbf{Compilers}: Beside \texttt{g++} it has been reported that \Dune was successfully build with the Intel C++ compiler. 
David Werner's avatar
David Werner committed
366
C and FORTRAN compiler is needed for a some external libraries. As code of different compilers is linked together they have to be be compatible with each other. A good choice is the GNU compiler suite \texttt{gcc},\texttt{g++} and \texttt{gfortran}.
367

368
\item \textbf{libgomp}: External libraries, such as ALUGrid, can make use of OpenMP when used together with METIS. For that purpose it can be necessary to install the \texttt{libgomp} library.
369
370
% http://openmp.org/

David Werner's avatar
David Werner committed
371
%\item \textbf{libgmp}: The Gnu Multiple Precision Arithmetic Library (GMP) is also a prerequisite for \Dune. It may be necessary to install it.
372
% http://gmplib.org/
373
\end{itemize}
Klaus Mosthaf's avatar
Klaus Mosthaf committed
374

375
376
377
378
379
\subsection{Hints for Users from IWS}
We provide some features to make life a little bit easier for
users from the Institute of Hydraulic Engineering, University of Stuttgart.

There exists internally a svn repository made for several external libraries.
380
If you are allowed to access it, go to the {\Dune}-Root, then do: 
381
\paragraph{prepared external directory}
382

383
\begin{lstlisting}[style=Bash]
384
$ # Make sure you are in DUNE-Root
385
386
$ svn checkout svn://svn.iws.uni-stuttgart.de/DUMUX/external/trunk external
\end{lstlisting}
387

388
This directory \texttt{external} contains a script to install external libraries, such as 
389
390
ALBERTA, ALUGrid, UG, METIS and GotoBLAS2: 

391
\begin{lstlisting}[style=Bash]
392
$ cd external
393
394
$ ./installExternal.sh all
\end{lstlisting}
395

396
It is also possible to install only the actual needed external libraries:
397

398
\begin{lstlisting}[style=Bash]
399
400
$ ./installExternal.sh -h      # show, what options this script provide
$ ./installExternal.sh --parallel alu
401
\end{lstlisting}
402

403
The libraries are then compiled within that directory and are not installed in a different place. 
404
A \Dune build may need to know their location. That's why one may have to refer to them as options for \texttt{dunecontrol}, for example via options file \texttt{my-debug.opts}.
405