3_detailedinstall.tex 16.1 KB
Newer Older
1
Installing \Dumux means that you first unpack \Dune and \Dumux in a root directory
2
3
4
(section \ref{sc:ObtainingSourceCode}).
In a second step of the installation, all modules are configured with CMake
(section \ref{buildIt}).
5
After the successful installation of \Dumux, we guide you to start a test application,
6
described in section \ref{quick-start-guide}.
7
In section \ref{sec:build-doc}, we explain how to build the \Dumux documentation.
8
Lastly, section \ref{sec:external-modules-libraries} provides details on optional libraries and modules.
Thomas Fetzer's avatar
Thomas Fetzer committed
9

10
In a technical sense, \Dumux is a module of \Dune.
Thomas Fetzer's avatar
Thomas Fetzer committed
11
Thus, the installation procedure of \Dumux is the same as that of \Dune.
12
Details regarding the installation of \Dune are provided on the \Dune website \cite{DUNE-HP}.
David Werner's avatar
David Werner committed
13

14

15
\section{Obtaining Source Code for \Dune and \Dumux}
16
17
\label{sc:ObtainingSourceCode}
The \Dumux release and trunk (developer tree) are based on the most recent
18
\Dune release 2.7, comprising the core modules \texttt{dune-common}, \texttt{dune-geometry},
19
\texttt{dune-grid}, \texttt{dune-istl} and \texttt{dune-localfunctions}.
20
For working with \Dumux, these modules are required.
21
All \Dune modules, including the \Dumux module, get extracted into a common root directory, as it
22
23
is done in a typical \Dune installation.
We usually name our root directory \texttt{DUMUX}, but an arbitrary name can be chosen.
Timo Koch's avatar
Timo Koch committed
24
25
Source code files for each \Dune module are contained in their own sub-directory within the root directory.
The sub-directories for the modules are named after the module names (depending on how
26
the modules were obtained, a version number is added to the module name).
27
28
The name of each \Dune module is defined in the file \texttt{dune.module}, which is
in the root directory of the respective module. This should not be changed by the user.
29

30
In section \ref{sec:prerequisites}, we list some prerequisites for running \Dune and \Dumux.
31
Please check in said paragraph whether you can fulfill them before continuing.
32

Thomas Fetzer's avatar
Thomas Fetzer committed
33
\paragraph{Obtaining \Dune and \Dumux from software repositories}
34
35
\Dune and \Dumux use Git for their software repositories. To access them,
you need to have a working installation of the version control software Git.
36

37
In the jargon of Git, \emph{cloning a certain software version} means nothing more then fetching
38
a local copy from the software repository and laying it out in the file system.
39
In addition to the software, some more files for the use of the software revision
40
control system itself are created. (If you have developer access to \Dumux, it is
41
also possible to do the opposite, i.\,e. to load up a modified revision of software
42
into the software repository. This is usually termed as \emph{commit} and \emph{push}.)
43

44
The download procedure is done as follows:
45
Create a common root directory, named e.g. \texttt{DUMUX} in the lines below.
Thomas Fetzer's avatar
Thomas Fetzer committed
46
Then, enter the previously created directory and check out the desired modules.
47
As you see below, the check-out uses two different servers for getting the sources,
48
one for \Dune and one for \Dumux.
49

50
\begin{lstlisting}[style=Bash,escapechar=\%]
51
52
$ mkdir DUMUX
$ cd DUMUX
53
54
55
56
57
$ git clone -b releases/2.7 https://gitlab.dune-project.org/core/dune-common.git
$ git clone -b releases/2.7 https://gitlab.dune-project.org/core/dune-geometry.git
$ git clone -b releases/2.7 https://gitlab.dune-project.org/core/dune-grid.git
$ git clone -b releases/2.7 https://gitlab.dune-project.org/core/dune-istl.git
$ git clone -b releases/2.7 https://gitlab.dune-project.org/core/dune-localfunctions.git
58
$ git clone -b releases/%\DumuxVersion% https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git
59
\end{lstlisting}
Bernd Flemisch's avatar
Bernd Flemisch committed
60

61
62
The newest and maybe unstable developments of \Dune and \Dumux are also provided in these repositories and can be found in the \emph{master} branch.
Please check the \Dune website \cite{DUNE-HP} for further information on the \Dune development. We always try to keep up with the latest developments of \Dune.
63
However, the current \Dumux release is based on the stable 2.7 release and it might not compile without further adaptations using the newest versions of \Dune.
64

65
\section{Building \Dune and \Dumux}
66
\label{buildIt}
67
Configuring \Dune and \Dumux is done by the shell-command \texttt{dunecontrol}, which is part of the \Dune build system.
68
If you are interested in more details about the build system that is used,
Timo Koch's avatar
Timo Koch committed
69
they can be found in the \Dune build system documentation\footnote{\url{https://www.dune-project.org/buildsystem/}} and
70
CMake's documentation\footnote{\url{https://cmake.org/documentation/}}.
71
If something fails during the execution of \texttt{dunecontrol}, feel free to report it to the \Dune or \Dumux developer mailing list,
72
but please include error details.
73

74
75
76
77
78
It is possible to compile \Dumux without explicitly passing options to the build system.
However, this will usually not result in the most performant code. A set of default options
that will usually work well is provided with \Dumux in a file and can be passed
to \texttt{dunecontrol}. The following command will configure \Dune and \Dumux
and build all necessary libraries
79
80
\begin{lstlisting}[style=Bash]
$ # make sure you are in the common root directory
81
$ ./dune-common/bin/dunecontrol --opts=dumux/cmake.opts all
82
83
\end{lstlisting}

84
If you are going to compile with modified options, the following
85
86
87
can be a starting point:
\begin{lstlisting}[style=Bash]
$ # make sure you are in the common root directory
88
89
90
$ cp dumux/cmake.opts my-cmake.opts      # create a personal version
$ gedit my-cmake.opts                    # optional editing the options file
$ ./dune-common/bin/dunecontrol --opts=my-cmake.opts all
91
92
\end{lstlisting}

93
Sometimes, it is necessary to have additional options which
94
95
are specific to a package set of an operating system or
sometimes you have your own preferences.
96
97
98
Feel free to work with your own set of options, which may change over time.
The option file, that comes with the distribution, is to be understood more as a starting point
for setting up own customization than as something which is fixed.
99
The use of external libraries can make it necessary to add quite many options in an option file.
100
It can be helpful to give your customized option file a unique name, as done above,
101
102
to avoid confusing it with the option files which came out of the distribution.

103
\section{The First Run of a Test Application}
104
\label{quick-start-guide}
105
106
107
108

We recommend the "Getting Started" guide on the \Dumux website: \url{https://dumux.org/gettingstarted/}.
Nevertheless, here is a brief description of how to run a first application.

109
The previous section showed how to install and compile \Dumux. This section
110
shall give a very brief introduction on how to run a first test application and how
111
to visualize the first output files.\par
112
All executable files are compiled in the \texttt{build} sub-directories of \Dumux.
113
If not specified differently in the options file, this is \texttt{build-cmake} as default.
114
115

\begin{enumerate}
116
\item Enter the folder \texttt{test/porousmediumflow/2p/incompressible} within your build directory.\\ Type \texttt{make test{\_}2p{\_}incompressible{\_}tpfa}
117
      in order to compile the application\\\texttt{test{\_}2p{\_}incompressible{\_}tpfa}. To run the simulation,
118
119
120
      type \texttt{./test{\_}2p{\_}incompressible{\_}tpfa params.input}
      into the console.
      The added \texttt{params.input} specifies that all
121
      important run-time parameters (such as first time step size, end of simulation and location
122
      of the grid file) can be found in a text file in the same directory  with the
123
      name \texttt{params.input}.
124
125
\item The simulation starts and produces some VTU output files and also a PVD
      file. The PVD file can be used to examine time series and summarizes the VTU
126
      files. (It is possible to abort a running application by pressing $<$Ctrl$><$c$>$.)
127
128
\item You can display the results using the visualization tool ParaView (or
      alternatively VisIt). Just type \texttt{paraview} in the console and open the
129
      PVD file. On the upper left-hand side, you can choose the desired parameter to be displayed.
130
131
\end{enumerate}

132
\section{Building Documentation}
133
\label{sec:build-doc}
134
Building the included documentation like this handbook requires \LaTeX{} and the auxiliary tool
135
\texttt{bibtex}. One usually chooses a \LaTeX{} distribution like \texttt{texlive} for this purpose.
136
It is possible to switch off building the documentation by setting the switch \texttt{--disable-documentation}
137
138
139
in the \texttt{CONFIGURE\_FLAGS} of the building options, see section \ref{buildIt}.

\subsection{Doxygen}
Thomas Fetzer's avatar
Thomas Fetzer committed
140
\label{sec:build-doxy-doc}
141
142
Doxygen documentation is done by specifically formatted comments included in the source code,
which can get extracted by the program \texttt{doxygen}. Besides extracting these comments,
143
\texttt{doxygen} builds up a web-browsable code-structure documentation
144
like class hierarchy of code displayed as graphs, see \url{https://www.doxygen.nl/index.html}.
David Werner's avatar
David Werner committed
145

146
The Doxygen documentation of a module can be built by running \texttt{dunecontrol} (if \texttt{doxygen} is installed), entering the \texttt{build-*}directory, and executing
Thomas Fetzer's avatar
Thomas Fetzer committed
147
\texttt{make doc}. Then point your web browser to the file
Thomas Fetzer's avatar
Thomas Fetzer committed
148
149
\texttt{MODULE\_BUILD\_DIRECTORY/doc/doxygen/html/index.html} to read the generated documentation.
This should also work for other \Dune modules.
David Werner's avatar
David Werner committed
150

151
\subsection{Handbook}
152
To build the \Dumux handbook, navigate to the \texttt{build-}directory and
153
154
run \texttt{make doc} or \texttt{make doc\_handbook\_0\_\\dumux-handbook\_pdf}. The pdf can then be found
in \texttt{MODULE\_BUILD\_DIRECTORY/doc/handbook/0\_dumux\\-handbook.pdf}.
David Werner's avatar
David Werner committed
155

156
\section{External Libraries and Modules} \label{sec:external-modules-libraries}
Thomas Fetzer's avatar
Thomas Fetzer committed
157
The libraries described below provide additional functionality but are not generally required to run \Dumux.
158
If you are going to use an external library, check the information provided on the \Dune website%
159
160
161
162
163
164
\footnote{DUNE: External libraries, \url{https://www.dune-project.org/doc/external-libraries/}}. You can consult the \Dune website for higher-level \Dune modules, such as Grid Modules
\footnote{DUNE: Grid modules, \url{https://www.dune-project.org/groups/grid/}},
Discretization Modules
\footnote{DUNE: Discretization modules, \url{https://www.dune-project.org/groups/disc/}},
 and Extension Modules
\footnote{DUNE: Extension modules, \url{https://www.dune-project.org/groups/extension/}}.
165

Thomas Fetzer's avatar
Thomas Fetzer committed
166
Installing an external library can require additional libraries which are also used by \Dune.
167
For some libraries, such as BLAS or MPI, multiple versions can be installed on the system.
168
Make sure that it uses the same library as \Dune when configuring the external library.
169

170
171
Some of the libraries are then compiled within that directory and are not installed in
a different place, but \Dune may need to know their location. Thus, one may have to refer to
172
them as options for \texttt{dunecontrol}, for example via the options file \texttt{my-cmake.opts}.
173
Make sure you compile the required external libraries before you run \texttt{dunecontrol}.
174
An easy way to install some of the libraries and modules, given below, is the \texttt{installexternal.py} script located in \texttt{bin}. The script has to be called from your common root directory.
175

Thomas Fetzer's avatar
Thomas Fetzer committed
176

177
\subsection{List of External Libraries and Modules}
178
179
\label{sec:listofexternallibs}

Thomas Fetzer's avatar
Thomas Fetzer committed
180
181
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.
182

183
\begin{itemize}
184
\item \textbf{dune-ALUGrid}: Grid library, comes as a \Dune module.
185
186
  The parallel version needs also a graph partitioner, such as {ParMETIS}.
  Download: \url{https://gitlab.dune-project.org/extensions/dune-alugrid}
187

188
189
190
191
192
\item \textbf{dune-foamgrid}: External grid module. One- and two-dimensional grids
  in a physical space of arbitrary dimension; non-manifold grids, growth, element
  paramterizations, and movable vertices. This makes FoamGrid the grid data structure
  of choice for simulating structures such as foams, discrete fracture networks,
  or network flow problems.
193
  Download: \url{https://gitlab.dune-project.org/extensions/dune-foamgrid}
Timo Koch's avatar
Timo Koch committed
194

195
\item \textbf{opm-grid}: opm-grid is a DUNE module supporting grids in a corner-point format.
196
  Download: \url{https://github.com/OPM/opm-grid.git} and \url{https://github.com/OPM/opm-common.git}
Timo Koch's avatar
Timo Koch committed
197
198

\item \textbf{dune-subgrid}: The dune-subgrid module is a meta-grid implementation that allows
199
to mark elements of another hierarchical dune grid and use this sub-grid just like a regular grid.
200
The set of marked elements can then be accessed as a hierarchical dune grid in its own right.
201
Dune-Subgrid provides the full grid interface including adaptive mesh refinement.
202
  Download: \url{https://git.imp.fu-berlin.de/agnumpde/dune-subgrid.git}
Timo Koch's avatar
Timo Koch committed
203

204
205
\item \textbf{dune-spgrid}: The DUNE module dune-spgrid provides a structured, parallel grid
and supports periodic boundary conditions.
206
  Download: \url{https://gitlab.dune-project.org/extensions/dune-spgrid.git}
207

208
209
\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.
210
  Download: \url{http://crd.lbl.gov/~xiaoye/SuperLU}
211

Timo Koch's avatar
Timo Koch committed
212
\item \textbf{UMFPack}: External library for solving linear equations. It is part of SuiteSparse.
213
  See: \url{http://faculty.cse.tamu.edu/davis/suitesparse.html}. On Debian/Ubuntu you can install the package \texttt{libsuitesparse-dev}.
214

215
\item \textbf{dune-UG}: External library for use as grid. UG is a toolbox for unstructured grids, released under GPL.
216
  To build UG the tools \texttt{lex}/\texttt{yacc} or the GNU variants of \texttt{flex}/\texttt{bison} must be provided.
217
  Download: \url{https://gitlab.dune-project.org/staging/dune-uggrid}
218
219
\end{itemize}

Thomas Fetzer's avatar
Thomas Fetzer committed
220
221
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.
222

223
\begin{itemize}
224
225
\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
226
  version have been reported to work.
227

228
\item \textbf{BLAS}: SuperLU makes use of BLAS. Thus install GotoBLAS2, ATLAS, non-optimized BLAS
229
230
  or BLAS provided by a chip manufacturer. Take care that the installation scripts select the intended
  version of BLAS.
231

232
\item \textbf{METIS} and \textbf{ParMETIS}: This are dependencies of ALUGrid and can be used with UG, if run in parallel.
233

234
235
\item \textbf{Compilers}: Beside \texttt{g++}, \Dune can be built with Clang from the LLVM project and
  Intel \Cplusplus compiler. C and Fortran compilers are needed for some external libraries. As code of
236
  different compilers is linked together, they have to be be compatible with each other.
237
\end{itemize}
238
239
240
241

\section{Backwards Compatibility}
\label{sec:backwardscompatibility}

242
243
244
Dumux Releases are split into major (e.g. 2.0, 3.0) and minor (e.g. 3.1, 3.2, 3.3, 3.4) releases.
Major releases are not required to maintain backwards compatibility 
but would provide a detailed guide on updating dependent modules.
245
246
247
248
249
250
For each minor release, maintaining backwards compatibility is strongly encouraged and recommended.

Maintaining backwards compatibility means for all changes made to the dumux master, each tests and all dumux dependent modules should still compile. In addition, the user should be warned at compile time of any relevant interface changes. This can be done by deprecating the old method with a deprecation message and forwarding it to the new method. Examples of this are shown in the \href{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CONTRIBUTING.md}{contribution guide}. Each of these deprecation messages should also include the release in which the interface will be removed, and all changes should be documented thoroughly in the \href{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/CHANGELOG.md}{changelog.md}.

Despite the goal of maintaining backwards compatibility across minor releases,
for more complicated changes, this is to be decided upon on a case-by-case basis, due to limited developer resources.
251
In the case that implementing full backwards compatibility for an update is not feasible, or would require unreasonable resources, the degree of backwards compatibility will be decided by a vote in one of the monthly core developer meetings.