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

4
5
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 shell. 
You should also know how to install new software packages or you should have a person aside which can give you assistance with the shell and the package installation. 
6
Below, we list some basic prerequisites for running \Dune and \Dumux. 
7
Please check this paragraph to evaluate whether it is possible for you to run \Dune and \Dumux. 
8
In addition some optional libraries and modules are listed which can be helpful for the work with \Dumux. \\
9

10
11
12
In a technical sense \Dumux is a module of \Dune. 
The installation procedure of \Dumux is strongly related to that of \Dune. 
Thus, for details of the installation please check also the {\Dune} website \cite{DUNE-HP}. 
13
If you are interested in more details of the buildsystem we refer to the {\Dune} Build System Howto \cite{DUNE-BS}.\\
14

15
As in a \Dune installation, all \Dune modules including \Dumux should be extracted into a common directory. We refer to that directory for purpose of documentation abstactly as {\Dune} root directory or shortly as {\Dune}-Root, but in real life the user is free to choose any valid directory name for his instance of {\Dune} root direcory.\\
16

17
18
Source code files for each \Dune module are contained in subdirectory of {\Dune}-Root which exactly is itself associated with module.
We name that subdirectory of a certain module, ``modules root directory", or ``module-root-directory`, e.g. for module dumux the name are  ``dumux' root directory" respective ``dumux-root-directory". The real directory names can be choosen abitrary, in this manual they are the same as the module name or the module name extended by an version number suffix. The name of a module is always defined via the content of file \texttt{dune.module} in its root directory, and should not get changed by an user. Note that it also possible to have subdirectories in \Dune-Root which contain no module.\\
19

20
After installing source code for all required \Dune modules including the \Dumux parts, \Dune is being built by the shell-command \texttt{dunecontrol} which is part of the {\Dune} build system. The {\Dune} build system is essentially a front-end of the gnu tool \texttt{autoconf} which was specialized for the \Dune project.
21

22
23
24
\paragraph{Basic prerequisites} \label{prerequisites}
The gnu tool-chain of \texttt{g++}  and related gnu variants of autotools
(\texttt{autoconf}, \texttt{automake}, \texttt{libtool}) must be available in a recent version. E.g. for ubuntu linux these are contained in packages \texttt{autoconf}, \texttt{automake}, \texttt{libtool} and \texttt{build-essential}.
25

26
27
28
%
The \Dumux property system makes use of library \texttt{boost} of version $\geqslant$ 1.33.1.
It is thus necessary to install developer package of \texttt{boost} or sometimes named \texttt{libboost}, the matching ubuntu linux package is \texttt{libboost-dev}. \\
29

30
The building of the documentation requires \LaTeX\ and auxiliary tools like \texttt{dvipdf} and \texttt{bibtex}. 
31
If you use the configuration switch \texttt{--enable-doxygen} in your options or option-file (see below) in order to extract inline documentation from source code files you will also need \texttt{doxygen}.\\
32

33
Depending on the usage of external libraries the required software packages may vary. 
34
Beside the section on external modules below it is a good idea to check the {\Dune}-Wiki \cite{DUNE-MAIN-WIKI} for information about the external packages.
35

36
\subsection{Obtaining source code for \Dune and \Dumux}
37
38
From version 2.0 of \Dune on, it was decided to develop \Dumux based on \Dune releases, comprising the core modules 
\texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, \texttt{dune-localfunctions} and the external dune module \texttt{dune-pdelab}. Thus for a \Dumux installation these modules are required to be installed. Of course the external dune module \texttt{dumux} from \Dumux website ist required too. Using further (external) \Dune modules and/or external \Dune libraries can be necessary, if you are going to use more than basic features of \Dune or \Dumux. To some of these we only refer briefly in end of this chapter.\\
39
40
41
42
43
44

Two possibilities exist to get source code for \Dune and \Dumux.
Firstly \Dune and \Dumux can obtained as tar-archive files by download from respective {\Dune} and {\Dumux} website. They then need to be extracted, as described in the next section.
Secondly, described in the section next but one, is a method to obtain most recent source or even also every predecessors by direct access via internet to software repositories of software revision control system of the software developer. \Dune and \Dumux use for their software repositories \texttt{apache subversion} or more shortly \texttt{subversion} or \texttt{svn}.
As a user does not always want the most recent version
certain version tags (i.e. special names) and version numbers and even software branches are means of software revision control system to provide different versions of a software from a software repository.
45

46
\paragraph{Obtaining the software by installing tar-files}
47
The a bit 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.
48
49
This part of installation is done as follows: 
Download the tarballs from the respective \Dune (version 2.0) and \Dumux websites to a certain path in your filesystem.
50
51
Create the {\Dune} root directory, named here DUMUX, then extract content of tar-files by commandline program tar into it.
Above, except download, it can achieved by the following shell commands, replace in them \texttt{path\_to\_tarball} with the direcory pathname where the downloaded files are located.
52
53
54
55
56
57
58
59
60
61
62

\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}

63
To rephrase above remark about modules root directory, here dumux-root-directory name which came after extracting the tarfile is \texttt{dumux-2.0}.
64

65
Optional:
66
67
68
69
70
71
72
73
\begin{lstlisting}[style=Bash]
$ tar xzvf path_to_tarball_of/dune-grid-howto-2.0.tar.gz
\end{lstlisting}

However, the required \Dune-module \texttt{dune-pdelab} is not available as tar-file, thus you have to install it from software repository by the second method.  Thus if svn command is available, it can done as follows: 
\begin{lstlisting}[style=Bash]
$ svn co https://svn.dune-project.org/svn/dune-pdelab/branches/2.0snapshot dune-pdelab
\end{lstlisting}
74

75
76
77
78
\paragraph{Obtaining \Dune and \Dumux from software repositories} 

Using a software revision control system as subversion and its software repositories has beside it advantages for developer or developing groups as a tool for assisting them to keep the source code worked on in consistent fashion for an user, i.e. a member who is not in the developing group of a software project, of software also some advantages.
In general With direct access to the software repositories it is easier to keep up with code changes, to receive important bug fixes and to keep up with general developments of code.
Bernd Flemisch's avatar
Bernd Flemisch committed
79

80
81
82
To access apache subversion software repositories a certain program is needed which is referred here shortly as \texttt{subversion client} or \texttt{svn client}. We use in our description the svn client of the apache subversion software itself, which is a commandline (shell) tool, mostly named \texttt{svn}. 
Apache subversion client is available for most Linux and UNIX distributions as software package by the distributor or can get installed by building it directly from source.

83
In technical speach of apache subversion ``checking out a certain software version" means nothing more then fetching 
84
85
it from software repository and laying it out in the filesystem, additionally with software some files with metainformation regarding the software revision control system itself are also laid out.
For a developer in \Dumux project it is easily possible to do the opposite i.e. uploading a modified version he created into software repository. This is usually termed as ``software check in".
86
87

The installation procedure is as follows:
88
Create {\Dune} root directory, named here below DUMUX.
89
90
91
92
Then, enter the previously created directory and checkout the modules. 
As you see below the checkout uses two different servers for sources one for \Dune and one for \Dumux, also the 
anonymous access to these repositories varies a little bit. 

93
94
95
96
97
98
99
100
101
102
103
As described on \Dune's website, \cite{DUNE-DOWNLOAD-SVN}, we first do a checkout of some \Dune modules:

\begin{lstlisting}[style=Bash]
$ mkdir DUMUX}
$ cd DUMUX}
$ 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
104

105
106
The \texttt{dune-grid-howto} is a tutorial which aims to give an understanding of the \Dune grid interface, which can 
give you an idea how abstractions in \Dune are done. \texttt{Dune-grid-howto} is not required by \Dumux, thus installing is purely optional. It is done by: 
107
108
109
110

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

112
113
To obtain the needed \texttt{dumux} module, which is is as mentioned before, just an external module of \Dune. You have to check it out which is as also described on \Dumux website, \cite{DUMUX-HP}.
Its filetree should laid out as for any other \Dune module directly into \Dune-Root. This is done if you are in it and execute the following command within \Dune root directory.
114

115
116
117
\begin{lstlisting}[style=Bash]
$ svn co --username=anonymous --password='' svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux
\end{lstlisting}
118

119
120
\paragraph{Hints for \Dumux-Developers}
If you also want to check in your own \Dumux developments to \Dumux software repositories, you can apply for either full developers access or access for developer access on certain parts of \Dumux. Granted developer access means that you are allowed to check in own code to the software repository and that you can access the \texttt{dumux-devel} module which enhances \texttt{dumux} by staging code of developer group, which is unavailable for user not being member of the developer group.
121
If you are member of developer group rights the checkout with developer access for \texttt{dumux} and \texttt{dumux-devel} is non-anonymously done with the commands below, insert your username
122
123
124
125
126
127
128
for accessing \Dumux software repository in place \texttt{joeuser} below.

\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}

129
This time the name for dumux root directory is just as the name of the module \texttt{dumux}.
130

131
132
\texttt{Dumux-devel} itself makes use of stable part \texttt{dumux} and hence it needs also being checked out. 
You can omit in commands above the username option, if your username for the repository access is identical to the one for your system account.
133
134
Please choose either not to store the password or to store it by subversion in a secure way (check the documentation of subversion for that). 
A leaked out password can be used by evil persons to vandalize a software repository.
135

136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
\subsection{Build of \Dune and \Dumux}
\label{buildIt}
Building of \Dune is done by \texttt{dunecontrol} as descibed in \Dune Installation Notes, \cite{DUNE-INST}, and in much more comprehensive form in \Dune Build System Howto, \cite{DUNE-BS}.
If something fails with \texttt{dunecontrol} feel to report it to \Dune or \Dumux developer or mailing list, but also try to report also error details. People will likely help you.


It is possible to compile \Dumux with nearly no explicit options to the buildsystem 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. As option switches for optimization can switched on in parts buildsystem for code be 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 commandline argument to \texttt{dune-control}.


\begin{lstlisting}[style=Bash]
$ ./dune-common/bin/dunecontrol --configure-opts="CXXFLAGS=-fno-strict-aliasing"  all
\end{lstlisting}

Too many options can make life hard, thats why one usually uses option-files for dune-control and its subtools.
Larger sets of options are kept in them. 
If you are going to compile with options suited for code debugging with a debugger, the following
can be a starting point:

Insert below for \verb+$DUMUX_ROOT+ in shell-commandline just the name of dumux' (or dumux-devels) root directory, which is in case of installation from tarfiles \texttt{dumux-2.0} or in case of installation from svn just \texttt{dumux} (or if one takes a version of option-file from module \texttt{dumux-devel} available only to members of \Dumux developers group, \texttt{dumux-devel}.

\begin{lstlisting}[style=Bash]
$ ./dune-common/bin/dunecontrol --opts=$DUMUX_ROOT/debug.opts all
\end{lstlisting}

More optimized code, but which is typically not as useful for standard tasks in debugger can produced by 

\begin{lstlisting}[style=Bash]
$ ./dune-common/bin/dunecontrol --opts=$DUMUX_ROOT/optim.opts all
\end{lstlisting}

Sometimes it is necessary to have additional options which are specific to tools set of an operating system or just mirror your preferences, feel free to work with your own set of options which may evolve over time. Above option files are more to understand as examples as a starting setting for own customization than as something fixed to \Dumux.

%Alternatively, the tool CMake can be used to build \Dumux. Please check the file \texttt{INSTALL.cmake} for details.
\subsection{External libraries and modules}
171

172
The following libraries provide additional functionality but are not required to run \Dumux. 
173
If you are going to use an external library check the information provided on the \Dune website. If you are going to use an external \Dune module beside {\Dune}s website a website regarding the external modules in question can be helpful too. Too make the picture complete we list here complete some of external modules, some of external libraries and some of typical libaries and tools which get used by \Dune.
174

175
\begin{itemize}
176
177
178
\item \textbf{\Dune-multidomaingrid}: If you going to run on the same grid different domains or subdomains, this can be the package of choice. 
To be precise, this is an external \Dune module which, like \Dumux, is built by the \Dune build system. The \Dune-multidomaingrid module provides a meta grid that allows the subdivison of arbitrary \Dune grids into subdomains, e.g. for multi-physics approaches (\texttt{\url{http://gitorious.org/dune-multidomaingrid}}).

179
\item \textbf{UG}: UG is a toolbox for Unstructured Grids: As \Dumux, it is build by \texttt{autotools} and a C++-compiler. Additionally, the tools \texttt{lex}/\texttt{yacc} or the gnu-versions \texttt{flex}/\texttt{bison} are needed. 
180

181
\item \textbf{Alberta}: Adaptive multi Level finite element toolbox using Bisectioning refinement and Error control by Residual Techniques for scientific Applications: A Fortran compiler like \texttt{gfortran} is required.
182

183
\item \textbf{ALUGrid}: 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} or \texttt{PARTY}. It was run successfully in combination with \Dune using \texttt{METIS}.
184

185
\item \textbf{PARDISO}: 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}}).
186

187
\item \textbf{SuperLU}: SuperLU is a general purpose library for the direct solution of large, sparse, nonsymmetric systems of linear equations (\texttt{\url{http://crd.lbl.gov/~xiaoye/SuperLU}}).
188

189
190
\end{itemize}

191
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.
192
\begin{itemize}
193
\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} and \texttt{MPICH} in a recent version have been reported to work. 
194

195
\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.
196

197
\item \textbf{BLAS}: Alberta makes use of BLAS. Thus install LibGOTO, ATLAS, non-optimized BLAS or BLAS by chipmanufacturer. Take care that the installation scripts select the intended version of BLAS. 
198

199
\item \textbf{METIS}: This is a dependency of ALUGrid. If you run it parallel this part is being used to partition your grid.
David Werner's avatar
David Werner committed
200

201
\item \textbf{LibGOTO}: is an optimized version of BLAS. It is not always available for all architectures and 
202
203
the license is not open. For research and education it is possible to obtain a copy without additional costs.
A Fortran compiler like \texttt{gfortran} is needed to compile it.
David Werner's avatar
David Werner committed
204

205
\item \textbf{\LaTeX, doxygen}: In order to build the \Dumux documentation these tools are needed.  
206
\LaTeX\ is a front-end to the \TeX\ font setting system. Install texlive for example. A great part of the code documentation is done inline using doxygen, which extracts the documentation and makes HTML or \LaTeX\ out of that.
207

208
209
210
\item \textbf{Compilers}: We recommend to use the gnu compiler suite, i.e. \texttt{gcc}/\texttt{g++}/\texttt{gfortran} version 4.4 or 4.5.
It is also reported that \Dune was successfully build with the Intel C++ compiler. 
\Dune is build by a C++ compiler. The C and Fortran compiler is only needed for a few external libraries.
211

212
\item \textbf{libgomp}: \Dune can make use of OpenMP. Thus it can be necessary to install the \texttt{libgomp} library.
213
214
% http://openmp.org/

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

219
\paragraph{Hint for Users from IWS} Users from the Institute of Hydraulic Engineering, University of Stuttgart,
220
can also checkout a svn repository with several external libraries: 
221

222
223
224
\begin{lstlisting}[style=Bash]
$ svn checkout svn://svn.iws.uni-stuttgart.de/DUMUX/external/trunk external
\end{lstlisting}
225

226
This directory \texttt{external} contains a script to install external libraries, such as 
227
Alberta, ALUGrid, UG, METIS and an optimized version of BLAS named LibGOTO: 
228
229
230
\begin{lstlisting}[style=Bash]
$ ./installExternal.sh all
\end{lstlisting}
231
it is also possible to install only certain parts of the external libraries:
232
233
234
\begin{lstlisting}[style=Bash]
$ ./installExternal.sh alberta
\end{lstlisting}
235

236
237
The libraries are then build within the external-directory and are not installed in a different place. 
But a \Dune build still needs to know where they are. You have to refer to them as options for the \Dune build, for example in your options file \texttt{debug.opts}.
238