diff --git a/doc/handbook/0_dumux-handbook.tex b/doc/handbook/0_dumux-handbook.tex
index 59d04dabe737d01037987ffa7b62fbc19e9fb41f..afd34f2bf8a2a775ccf1849cb7a2aff21cf1ffa3 100644
--- a/doc/handbook/0_dumux-handbook.tex
+++ b/doc/handbook/0_dumux-handbook.tex
@@ -11,6 +11,7 @@
\usepackage{enumerate}
\usepackage{hyperref}
\usepackage{graphicx}
+\usepackage{mhchem}
\usepackage{listings}
\usepackage[square,numbers]{natbib}
@@ -41,7 +42,7 @@
% Dune and Dumux logo
\newcommand{\Dune}{{DUNE}\xspace}
\newcommand{\Dumux}{\texorpdfstring{Du\-Mu$^\text{x}$\xspace}{DuMuX\xspace}}
-\newcommand{\DumuxVersion}{3.0}
+\newcommand{\DumuxVersion}{3.1}
\definecolor{dumuxYellow}{HTML}{E19417}
\definecolor{dumuxBlue}{HTML}{0C73CF}
@@ -114,7 +115,7 @@ your first \Dumux experience, including an install script with all necessary ins
on how to very quickly install the latest release version of \Dumux.
You should have a recent working Linux environment.
If you need more information, please have a look at the detailed installation
-instructions in the next chapter \ref{detailed-install}.
+instructions in chapter \ref{detailed-install}.
\input{2_quickinstall}
\chapter{Detailed Installation, Documentation, and Externals}\label{detailed-install}
@@ -124,15 +125,27 @@ how to build the documentation and about external libraries and modules.
\input{3_detailedinstall}
\chapter{Learning to use \Dumux}\label{chp:tutorial}
+So, you've downloaded your very own copy of \Dumux and its dependencies.
+You've run dunecontrol, and your example ``test$\_$dumux" not only compiles,
+but it even shows a nice simulation in ParaView.
+Maybe you've read through parts of the handbook, and even started looking
+through the Doxygen documentation.
+Well done. What now? \par
+%
+\textit{``How on earth is this going to help me solve my multi-(phase, component,
+ scale, physics) flow and transport problems in porous media systems?''}, you begin to wonder.
+Don't panic! In order to best ease our prospective users and developers into the
+wonderful \Dumux simulation environment, we've prepared a \Dumux course and extensively-documented examples.
\input{4_course}
+\input{4_examples}
\input{4_furtherpractice}
\chapter{Overview and Infrastructure}
-This chapter provides an overview of the general structure in \Dumux \ref{sc_structure}
+This chapter provides an overview of the general structure in \Dumux (\ref{sc_structure})
and gives help for basic work with \Dumux
-(\ref{sc_newfoldersetup},\ref{sc_parameterfiles},\ref{sc_restartsimulations}, \ref{sc_developingdumux}).
-Further it presents useful external tools \ref{sc_externaltools} and basic
-concepts \ref{sc_linearsystem}.
+(\ref{sc_newfoldersetup}-\ref{sc_developingdumux}).
+Further it presents useful external tools (\ref{sc_externaltools}) and basic
+concepts (\ref{sc_linearsystem}).
\input{5_structure}
\input{5_newfoldersetup}
\input{5_parameterfiles}
diff --git a/doc/handbook/1_introduction.tex b/doc/handbook/1_introduction.tex
index 705d692420fe6924edbae2a7e97923501011367b..4dfd1ed2d807784dcfe0f30e9ad5b13590c5c63d 100644
--- a/doc/handbook/1_introduction.tex
+++ b/doc/handbook/1_introduction.tex
@@ -66,7 +66,7 @@ solving the generated systems.
\Dumux comes in form of an additional module \texttt{dumux}.
It depends on the \Dune core modules
-\texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, and \texttt{dune-localfunctions}.
+\texttt{dune-common},\texttt{dune-geometry}, \texttt{dune-grid}, \texttt{dune-istl}, and \texttt{dune-localfunctions}.
The main intention of \Dumux is to provide a framework for an easy and efficient
implementation of new physical models for porous media flow problems,
ranging from problem formulation and the selection of
@@ -74,17 +74,12 @@ spatial and temporal discretization schemes as well as nonlinear solvers,
to general concepts for model coupling.
Moreover, \Dumux includes ready to use numerical models and a few example applications.
-This is the handbook to a new major version update of \Dumux: version 3.0.
-The release contains considerable improvements and many new features compared to the 2.x versions.
-Due to the major update, backwards compatibility with the last release 2.12 cannot be assured.
-To facilitate the transition for our users, we have created a
-git wiki entry describing how to update programs from version 2.12 to version 3.0.
+This is the handbook to a new minor version update of \Dumux: version 3.1.
+The release contains improvements and new features compared to the 3.0 version.
+The update is backwards compatible with the last release 3.0.
+To facilitate the transition for our users, we have created a changelog
+helping to update programs from version 3.0 to version 3.1, and giving an overview over new capabilities.
It is available online:
-\url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/wikis/Updating-programs-from-version-2.12-to-version-3.0}.
-The guide leads in detail through the interface changes from 2.12 to 3.0,
-concerning the \texttt{Problem} class, the \texttt{SpatialParams} class,
-the \texttt{Parameters} and \texttt{Properties}, i.e. the main user interface.
-Starting with version 3.0.0, all minor
-version updates will certainly be backward compatible again with at least the last minor version.
-We highly recommend all our users to transition with us to \Dumux-3.0
-and wish everyone a brand-new and exciting simulation experience.
+\url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CHANGELOG.md}.
+We highly recommend all our users to transition with us to the most recent version of \Dumux
+and wish everyone an exciting simulation experience.
diff --git a/doc/handbook/2_quickinstall.tex b/doc/handbook/2_quickinstall.tex
index 668f22ca4e4c04d96817dc24d0661b9d165d2b46..f829d901010acbdc56963d49bff1435059e7fe12 100644
--- a/doc/handbook/2_quickinstall.tex
+++ b/doc/handbook/2_quickinstall.tex
@@ -15,8 +15,7 @@ Copy the following lines into a text file named \texttt{installDumux.sh}:
\lstinputlisting[style=DumuxCode, numbersep=5pt, firstline=1, firstnumber=1]{installDumux.sh}
Place the \texttt{installDumux.sh} script in the directory where you want to install \Dumux and \Dune (a single
-root folder \texttt{DUMUX} will be produced, so you do not need to provide one).
-Run the script by typing into the terminal: \texttt{./installDumux.sh}
+root folder \texttt{DUMUX} will be produced, so you do not need to provide one). Make \texttt{installDumux.sh} executable and run the script by typing into the terminal: \texttt{./installDumux.sh}
Configuring \Dune and \Dumux is done by the command-line script \texttt{dunecontrol}
using optimized configure options, see the line entitled \texttt{\# run build} in the \texttt{installDumux.sh} script.
@@ -33,7 +32,7 @@ make -B test_1p_tpfa
./test_1p_tpfa params.input
paraview *pvd
\end{lstlisting}
-The script \texttt{test\_dumux.sh} can be executed by typing into the terminal: \texttt{./test\_dumux.sh}.
+After making \texttt{test\_dumux.sh} executable, it can be executed by typing into the terminal: \texttt{./test\_dumux.sh}.
If everything works fine, a ParaView window with the result should open automatically, showing the initial
-conditions. Advance ParaView to the next frame (green arrow button) and rescale to data range to admire
+conditions. Advance ParaView to the next frame (green arrow button) and rescale to data range (green double arrow on top right) to admire
the colorful pressure distribution.
diff --git a/doc/handbook/3_detailedinstall.tex b/doc/handbook/3_detailedinstall.tex
index 8abe54e971e3e8d74e3459a8e1a87bb20f4dbef8..a4858e078e2b85b3def0039727944eb202732b6e 100644
--- a/doc/handbook/3_detailedinstall.tex
+++ b/doc/handbook/3_detailedinstall.tex
@@ -60,7 +60,7 @@ $ tar xzvf path_to_tarball_of/dune-geometry-2.6.0.tar.gz
$ tar xzvf path_to_tarball_of/dune-grid-2.6.0.tar.gz
$ tar xzvf path_to_tarball_of/dune-istl-2.6.0.tar.gz
$ tar xzvf path_to_tarball_of/dune-localfunctions-2.6.0.tar.gz
-$ tar xzvf path_to_tarball_of/dumux-3.0.tar.gz
+$ tar xzvf path_to_tarball_of/dumux-3.1.tar.gz
\end{lstlisting}
Furthermore, if you wish to install the optional \Dune Grid-Howto which provides a tutorial
@@ -92,7 +92,7 @@ $ git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-geometry.g
$ git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-grid.git
$ git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-istl.git
$ git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-localfunctions.git
-$ git clone -b releases/3.0 https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git
+$ git clone -b releases/3.1 https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git
\end{lstlisting}
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.
@@ -132,7 +132,7 @@ on the Dune grid interface, act similar.
% $ path -p0 -R < ../dumux/patches/grid-2.3.1.patch
% \end{lstlisting}
-\section{Build of \Dune and \Dumux}
+\section{Building \Dune and \Dumux}
\label{buildIt}
Configuring \Dune and \Dumux is done by the shell-command \texttt{dunecontrol} which is part of the \Dune build system.
If you are interested in more details about the build system that is used,
@@ -150,7 +150,7 @@ $ # make sure you are in the common root directory
$ ./dune-common/bin/dunecontrol --configure-opts="CXXFLAGS=-fno-strict-aliasing" --use-cmake all
\end{lstlisting}
-Too many options can make life hard. That's why usually option files are being used together with \texttt{dunecontrol} and its sub-tools.
+Too many options within the command line can make life hard. That's why usually option files are being used together with \texttt{dunecontrol} and its sub-tools.
Larger sets of options are kept in them. If you are going to compile with modified options, the following
can be a starting point:
\begin{lstlisting}[style=Bash]
@@ -179,7 +179,7 @@ All executables are compiled in the \texttt{build} sub-directories of \Dumux.
If not specified differently in the options file, this is \texttt{build-cmake} as default.
\begin{enumerate}
-\item Enter the folder \texttt{porousmediumflow/2p/implicit/incompressible}.\\ Type \texttt{make test{\_}2p{\_}incompressible{\_}tpfa}
+\item Enter the folder \texttt{test/porousmediumflow/2p/implicit/incompressible} within your build directory.\\ Type \texttt{make test{\_}2p{\_}incompressible{\_}tpfa}
in order to compile the application\\\texttt{test{\_}2p{\_}incompressible{\_}tpfa}. To run the simulation,
type \texttt{./test{\_}2p{\_}incompressible{\_}tpfa params.input}
into the console.
@@ -192,21 +192,21 @@ If not specified differently in the options file, this is \texttt{build-cmake} a
files. It is possible to stop a running application by pressing $<$Ctrl$><$c$>$.
\item You can display the results using the visualization tool ParaView (or
alternatively VisIt). Just type \texttt{paraview} in the console and open the
- PVD file. On the left hand side, you can choose the desired parameter to be displayed.
+ PVD file. On the upper left hand side, you can choose the desired parameter to be displayed.
\end{enumerate}
\section{Building Documentation}
\label{sec:build-doc}
-The building of included documentation like this handbook requires \LaTeX{} and auxiliary tools
+Building the included documentation like this handbook requires \LaTeX{} and the auxiliary tool
\texttt{bibtex}. One usually chooses a \LaTeX{} distribution like \texttt{texlive} for this purpose.
-It is possible to switch off the building of the documentation by setting the switch \texttt{--disable-documentation}
+It is possible to switch off building the documentation by setting the switch \texttt{--disable-documentation}
in the \texttt{CONFIGURE\_FLAGS} of the building options, see section \ref{buildIt}.
\subsection{Doxygen}
\label{sec:build-doxy-doc}
Doxygen documentation is done by specifically formatted comments integrated in the source code,
which can get extracted by the program \texttt{doxygen}. Beside extracting these comments,
-\texttt{doxygen} builds up a web-browsable code structure documentation
+\texttt{doxygen} builds up a web-browsable code-structure documentation
like class hierarchy of code displayed as graphs, see \url{http://www.stack.nl/~dimitri/doxygen/}.
The Doxygen documentation of a module can be built if \texttt{doxygen} is installed,
diff --git a/doc/handbook/4_course.tex b/doc/handbook/4_course.tex
index c3dbee42f71ec5afc545bc5fa74d4bfe191c08c8..0d6c3df8f114ea72827cc9c52cff7543ea874edc 100644
--- a/doc/handbook/4_course.tex
+++ b/doc/handbook/4_course.tex
@@ -1,14 +1,4 @@
-So, you've downloaded your very own copy of \Dumux and its dependencies.
-You've run dunecontrol, and your example ``test$\_$dumux" not only compiles,
-but it even shows a nice simulation in ParaView.
-Maybe you've read through parts of the handbook, and even started looking
-through the Doxygen documentation.
-Well done. What now? \par
-%
-\textit{``How on earth is this going to help me solve my multi-(phase, component,
-scale, physics) flow and transport problems in porous media systems?''}, you begin to wonder.
-Don't panic! In order to best ease our prospective users and developers into the
-wonderful \Dumux simulation environment, we've prepared a \Dumux course.
+\section{Hands-on \Dumux experience -- the \Dumux course}
This course is offered once a year over a period of 3 days at the University of Stuttgart.
If you're looking for information on attending, subscribe to the \Dumux mailing list
and stay tuned for updates:
@@ -31,12 +21,12 @@ The \Dumux course material is available online:
In order to download this repository, which acts as an additional module to
the \Dumux base, you can download an installation script with the following command:
\begin{lstlisting}[style=Bash]
-$ wget https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/raw/releases/3.0/scripts/install.sh
+$ wget https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/raw/releases/3.1/scripts/install.sh
\end{lstlisting}
This script will install \texttt{dumux}, it's Dune dependencies, and the \texttt{dumux-course}
repository. Within the directory \texttt{dumux-course} there are a series of exercises
and slides describing the previously described examples. \par
%
The \Dumux course will be updated with each \Dumux release.
-The above script will download the correct version (\textbf{releases/3.0}) of both
+The above script will download the correct version (\textbf{releases/3.1}) of both
the \texttt{dumux} and \texttt{dumux-course} module.
diff --git a/doc/handbook/4_examples.tex b/doc/handbook/4_examples.tex
new file mode 100644
index 0000000000000000000000000000000000000000..24a8f0829936e18b3c2f718feae24297739eec65
--- /dev/null
+++ b/doc/handbook/4_examples.tex
@@ -0,0 +1,10 @@
+\section{Experience \Dumux by reading -- the \Dumux examples}
+As an alternative to going through exercises, you can have a look at our well-documented \Dumux examples. They show how to apply \Dumux to typical physical problems. In the \texttt{README.md} files, the setup is explained, the used code is presented and documented and images resulting from the simulation are included. The \texttt{README.md} files are located directly in the subfolders of \texttt{examples} and can be displayed by web browsers.
+
+We currently have the examples
+\begin{itemize}
+ \item \texttt{1ptracer}: one-phase groundwater flow including a tracer
+ \item \texttt{2pinfiltration}: two-phase infiltration problem
+ \item \texttt{shallowwaterfriction}: steady subcritical shallow water flow including bottom friction
+\end{itemize}
+The number of examples is continuously growing.
\ No newline at end of file
diff --git a/doc/handbook/4_furtherpractice.tex b/doc/handbook/4_furtherpractice.tex
index d31e227e73f23364c24f7a213110859fb817b96b..76c6c312097de64536b823c5cf1f4a51f8532bd3 100644
--- a/doc/handbook/4_furtherpractice.tex
+++ b/doc/handbook/4_furtherpractice.tex
@@ -21,25 +21,26 @@ The module is structured based on the different lectures:
\item mhs: Modelling of Hydrosystems.
\end{itemize}
The majority of applications is covered in the course Multiphase Modelling (mm),
-while there are also some basic examples from the
+while there are also some basic examples in the
courses Environmental Fluid Mechanics (efm) and Modelling of Hydrosystems (mhs).
These applications are primarily designed to enhance the understanding of conceptualizing the
governing physical processes and their implementation in a numerical simulator.
Different aspects of modeling multi-phase multi-component flow and transport processes are shown.
-The lectures focus on questions like, e. g., the assignment of boundary conditions, the choice of the
+The lectures focus on questions like the assignment of boundary conditions, the choice of the
appropriate physics for a given problem (which phases, which components), discretization issues,
time stepping. You can find, e. g., a comparison of different two-phase flow problems: The
-more simple approach considers two immiscible fluids while components in both phases with inter-phase
+simpler approach considers two immiscible fluids while components in both phases with inter-phase
mass transfer are considered in the more complex approach.
All scenarios and their physical background are explained in additional .tex-files,
which are provided in sub-directories named \texttt{description}. The following test cases are
contained in the \texttt{dumux-lecture} module:
\begin{itemize}
\item \texttt{buckleyleverett}: The Buckley-Leverett Problem is a classical porous media flow show case
-\item \texttt{co2plume}: Analysis of the influence of the gravitational number on the $\text{CO}_2$ plume
-\item \texttt{columnxylene}: A VEGAS experiment
+\item \texttt{co2plume}: Analysis of the influence of the gravitational number on a $\text{CO}_2$ plume
+\item \texttt{columnxylene}: An experiment of the Research Facility for Subsurface Remediation, University of Stuttgart
\item \texttt{convectivemixing}: A test case related to CO$_2$ storage
-\item \texttt{fuelcell}%TODO
+\item \texttt{fractures}: Two-phase flow in fractured porous media
+\item \texttt{fuelcell}: Water management in PEM fuel cells
\item \texttt{heatpipe}: A show case for two-phase two-component flow with heat fluxes
\item \texttt{heavyoil}: Steam assisted gravity drainage (SAGD)
\item \texttt{henryproblem}: A show case related to salt water intrusion
diff --git a/doc/handbook/5_assemblinglinearsystem.tex b/doc/handbook/5_assemblinglinearsystem.tex
index e05dad50ab5ad89acc3a9109a6f53a450fbd71ef..ddb50b41cb14ff400044c9d7305568422356e231 100644
--- a/doc/handbook/5_assemblinglinearsystem.tex
+++ b/doc/handbook/5_assemblinglinearsystem.tex
@@ -50,7 +50,7 @@ direction of maximum growth $\textbf{x}^i$ until our approximated solution becom
\subsection{Structure of matrix and vectors}
To understand the meaning of an entry in the matrix or the vector of the linear system, we have
to define their structure. Both have a blocking structure. Each block contains the degrees of
-freedom (also called variable or unknown) for a control volume. The equation index is used
+freedom (also called variables or unknowns) for a control volume. The equation index is used
to order of the degrees of freedom. For each control volume we have one block. The mapper is
used to order the blocks.
@@ -113,8 +113,8 @@ used to order the blocks.
\draw (11,2.2) -- (10.7,1.6);
\end{tikzpicture}
\end{center}
-\caption{Structure of matrix and vector, left blocking structure, right within block}
+\caption{Structure of matrix and vector, left: block structure, right: within block}
\end{figure}
-Accessing entries follows this structure. You can access the pressure value in the third sub-control volume in
-a vector \lstinline{sol} with \lstinline{sol[2][pressureIdx]}.
+Accessing entries follows this structure. You can access the pressure value in the third ($n=3$) sub-control volume in
+a solution vector \lstinline{sol} with \lstinline{sol[n-1][pressureIdx]=sol[2][pressureIdx]}.
diff --git a/doc/handbook/5_developingdumux.tex b/doc/handbook/5_developingdumux.tex
index 2ad63f31b0c387a05f7a04b697a823186d3661a4..29b85c69f3b42cd42a7ee9a749f9f8d16b0a77ed 100644
--- a/doc/handbook/5_developingdumux.tex
+++ b/doc/handbook/5_developingdumux.tex
@@ -5,7 +5,7 @@
\paragraph{Issues and Bug Tracking}
The bug-tracking system \emph{GitLab Issues} offers the possibility to report bugs or discuss new development requests.
-Feel free to register (if you don't have a \emph{Git} account already) and to contribute
+Feel free to register (if you don't have an account at out \emph{Git} yet) and to contribute
at \url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues}.
\paragraph{Commits, Merges, etc.}
@@ -33,7 +33,7 @@ For the style guide and instructions how to contribute to \Dumux visit
\subsection{Tips and Tricks}
-\Dumux users and developers at the LH2 are also referred to the internal Wiki for
+\Dumux users and developers at the LH2 are also referred to the internal confluence pages for
more information.
\paragraph{Optimized computation vs debugging}
@@ -46,13 +46,13 @@ in your options file. You can also do this in any of the \texttt{CMakeLists.txt}
set(CMAKE_BUILD_TYPE Debug)
\end{lstlisting}
-Afterwards rerun cmake again (run cmake <path-to-build-dir>).
+Afterwards rerun cmake (run cmake \texttt{$<$path-to-build-dir$>$}).
\paragraph{Dunecontrol for selected modules}
A complete build using \texttt{dunecontrol} takes some time. In many cases not all modules need to be re-built.
Pass the flag \texttt{--only=dumux} to \texttt{dunecontrol} for configuring or building only \Dumux. A more
-complex example would be the use of an additional module. Then you have to configure and build only \Dune{}-grid
-and \Dumux by adding \texttt{--only=MODULE,dumux}.
+complex example would be a case in which you have to configure and build only e.g. \Dune{}-grid
+and \Dumux. This is achieved by adding \texttt{--only=MODULE,dumux}.
\paragraph{Patching Files or Modules}
If you want to send changes to an other developer of \Dumux providing patches
@@ -72,7 +72,7 @@ $ patch -p1 < PATCHFILE
% See \ref{sc:patchingDUNE} if you need to apply patches to \Dumux or \Dune.
\paragraph{File Name and Line Number by Predefined Macro}
-If you want to know where some output or debug information came from, use the predefined
+If you want to create output in order to later know where some output or debug information came from, use the predefined
macros \texttt{\_\_FILE\_\_} and \texttt{\_\_LINE\_\_}:
\begin{lstlisting}[style=DumuxCode]
std::cout << "# This was written from "<< __FILE__ << ", line " << __LINE__ << std::endl;
diff --git a/doc/handbook/5_externaltools.tex b/doc/handbook/5_externaltools.tex
index dee059dc1dc7e5cd04d17b3f4f7f5986a7ce61e7..7cc542c46495cd50bda574a8fb99fe185fdfeaa6 100644
--- a/doc/handbook/5_externaltools.tex
+++ b/doc/handbook/5_externaltools.tex
@@ -75,5 +75,4 @@ Just save the specific code portion in a file and load it via \texttt{Macros} $\
\paragraph{Guide:}
Since ParaView 4.3.1, The ParaView Guide is partly
available for free download, see \url{http://www.paraview.org/documentation/}.
-It corresponds to the ParaView book, only three application chapters short.
-Attention, its size is 180 MiB.
+It contains similar content as the ParaView book.
diff --git a/doc/handbook/5_newfoldersetup.tex b/doc/handbook/5_newfoldersetup.tex
index ea26767b48355992a5353f51c5ee095db4eb67a1..50ffc8ade1075bfa3820fd3fe41c48cb07cf1820 100644
--- a/doc/handbook/5_newfoldersetup.tex
+++ b/doc/handbook/5_newfoldersetup.tex
@@ -5,7 +5,7 @@ the build system there is a new one.
\paragraph{Adding new Folders}
\begin{enumerate}[1)]
\item create new folder with content
- \item adapt the \verb+CMakeList.txt+ in the folder above and add a line with
+ \item adapt the \verb+CMakeList.txt+ in the folder above by adding a line with
\verb+add_subdirectory(NEW_FOLDER)+
\item create a \verb+CMakeList.txt+ in the newly created folder
\item go to your \texttt{build}-directory and type \verb+make+ to
@@ -24,4 +24,4 @@ dune_add_test(NAME my_test
Here, we create an executable called \texttt{my\_test} from a source file \texttt{main.cc}.
The name of the test will also be \texttt{my\_test} (has to be unique). The last argument specifies a command - here, we just run the executable \texttt{my\_test} with an input file \texttt{params.input}. For more advanced uses of
-the \texttt{add\_dune\_test} macro, have a look at the \texttt{test} directory. A complete documentation is given under \url{https://www.dune-project.org/sphinx/core-2.5/}.
+the \texttt{add\_dune\_test} macro, have a look at the \texttt{test} directory. A complete documentation is given under \url{https://www.dune-project.org/sphinx/core-2.6/}.
diff --git a/doc/handbook/5_parameterfiles.tex b/doc/handbook/5_parameterfiles.tex
index f6f615891ed7a405f7e41064ea98daf5bb1e00c2..126b2bf265262b6e71ec08f0a56b083fe09c6f00 100644
--- a/doc/handbook/5_parameterfiles.tex
+++ b/doc/handbook/5_parameterfiles.tex
@@ -1,7 +1,6 @@
\section{Parameters in \Dumux}
\label{sc_parameterfiles}
-Simulation parameters can be parsed to the program via a parameter file or the command line.
-A list of all available parameters is provided in the Doxygen documentation: \texttt{Parameter List}.
+Simulation parameters can be parsed to the program via a parameter file or via the command line.
After having run the example application from section \ref{quick-start-guide} you will
get the following output at the end of the simulation run
@@ -42,6 +41,7 @@ EnableShiftCriterion = "true"
MaxAbsoluteResidual = "1e-5"
MaxRelativeShift = "1e-8"
MaxSteps = "18"
+MinSteps = "2"
ResidualReduction = "1e-5"
SatisfyResidualAndShiftCriterion = "false"
TargetSteps = "10"
@@ -76,7 +76,7 @@ If you also want to set a default value for a parameter, just add it like this:
static const TYPE paramname = getParam<TYPE>("GROUPNAME.PARAMNAME", default);
\end{lstlisting}
-As this function call is relatively expensive, the respective variables should always be \texttt{static} (e.g., if used in a loop). When dealing with multiple group names, e.g., in the context of coupled models, the fowolling methods might be more convenient:
+As this function call is relatively expensive, the respective variables should always be \texttt{static} (e.g., if used in a loop). When dealing with multiple group names, e.g., in the context of coupled models, the following methods might be more convenient:
\begin{lstlisting}[name=propsyscars,style=DumuxCode]
auto modelParamGroup0 = "Model0";
diff --git a/doc/handbook/5_structure.tex b/doc/handbook/5_structure.tex
index a4146b5afc4d23dc44248eedb78f7d4ab6cb0192..c97c67b375cf6fce62c5ab70a84c54aba5a21342 100644
--- a/doc/handbook/5_structure.tex
+++ b/doc/handbook/5_structure.tex
@@ -6,9 +6,10 @@
\item \texttt{bin}: binaries, e.g. used for the automatic testing, post-processing, installation
\item \texttt{cmake}: the configuration options for building \Dumux
\item \texttt{doc}: files necessary for the Doxygen documentation and this handbook, and various logos
-\item \texttt{dumux}: the main folder, containing the source files. See \ref{fig:dumux-structure}
+\item \texttt{dumux}: the main folder, containing the source files. See Fig. \ref{fig:dumux-structure}
for a visualized structure. For more information on the models have a look at the
Doxygen documentation.
+\item \texttt{examples}: well-documented examples of applying \Dumux to typical physical problems. In the \texttt{README.md} files, the setup is explained, the used code is presented and documented and images resulting from the simulation are included. The \texttt{README.md} files are located directly in the subfolders of \texttt{examples} and can be displayed by web browsers.
\item \texttt{test}: tests for each numerical model and some functionality.
The structure is equivalent to the \texttt{dumux} folder, the \texttt{references} folder
contains solutions for the automatic testing. Each test program consist of a main file
@@ -86,7 +87,7 @@
[.\node[FirstLevel] {freeflow};
[.\node[SecondLevel] {\emph{models}};
\node[ThirdLevel] {Single-phase free flow models using Navier-Stokes
- and eddy-viscosity based Reynolds-averaged Navier-Stokes turbulence models.};
+ and eddy-viscosity based Reynolds-averaged Navier-Stokes turbulence models, and shallow water equation model.};
]
]
[.\node[FirstLevel] {geomechanics};
@@ -149,7 +150,7 @@
\node[ThirdLevel] {
Common infrastructure to couple multiple domains, models or physics.};
[.\node[SecondLevel] {embedded};
- \node[ThirdLevel] {Embedding of a lower-dimensional model into a higher-dimensional one};
+ \node[ThirdLevel] {Embedding a lower-dimensional model into a higher-dimensional one};
]
[.\node[SecondLevel] {facet};
\node[ThirdLevel] {Mixed-dimensional coupling at facets.};
diff --git a/doc/handbook/6_basics.tex b/doc/handbook/6_basics.tex
index a6ec76568a2291ac109ec977457a443ea5635d57..bfcfe229cf80b24722dadb1b1794ad9961dc2476 100644
--- a/doc/handbook/6_basics.tex
+++ b/doc/handbook/6_basics.tex
@@ -3,35 +3,30 @@ Here the basic definitions, the general models concept, and a list of
models available in \Dumux are given. The actual differential equations
can be found in the local residuals (see Doxygen documentation of the
model's \texttt{LocalResidual} class).
-%TODO: Add more physics
\subsection{Basic Definitions and Assumptions}
-The basic definitions and assumptions are made, using the example
-of a three-phase three-component system water-NAPL-gas
-\cite{A3:class:2002a}. The modification for other multi-component
-systems is straightforward and can be found, e.\ g., in
-\cite{A3:bielinski:2006,A3:acosta:2006}.
+Basic definitions and assumptions are given. More information can be found e.g. in \cite{A3:acosta:2006,A3:bielinski:2006}.
\begin{description}
+\item[Phases:]
+A \emph{phase} is defined as a continuum having distinct properties (e.g. density and viscosity). If phases are miscible, they contain dissolved portions of the substance of the other phase.
+Fluid and solid phases are distinguished. The fluid phases have different affinities to the solid phases. The phase, which has a higher affinity to the solid phases is referred to as the (more) wetting phase. In the case of two phases, the less wetting one is called the non-wetting phase.
+
+For compositional multi-phase models, fluid phases may be composed of several components, while the solid phases are assumed to consist exclusively of a single component.
+
\item[Components:]
The term \emph{component} stands for constituents of the phases which
can be associated with a unique chemical species, or, more generally, with
-a group of species exploiting similar physical behavior. In this work, we
-assume a water-gas-NAPL system composed of the phases water (subscript
+a group of species exploiting similar physical behavior. For example, Fig. \ref{fig:phaseMassEnergyTransfer} shows a water-gas-NAPL system composed of the phases water (subscript
$\text{w}$), gas ($\text{g}$), and NAPL ($\text{n}$). These phases are
composed of the components water (superscript $\text{w}$), the pseudo-component
-air ($\text{a}$), and the organic contaminant ($\text{c}$) (see Fig.
-\ref{fig:phaseMassEnergyTransfer}).
+air ($\text{a}$), and an organic contaminant ($\text{c}$).
-\item[Phases:]
-For compositional multi-phase models, \emph{phases}
-are not only matter of a single chemical substance. Instead, their
-composition in general includes several species/components. For mass transfer,
-the component behavior is quite different from the phase behavior.
+The composition of the components in a phase can influence the phase properties. Furthermore, for mass transfer, the phase behavior is quite different from the component behavior.
\item[Equilibrium:]
For the non-isothermal, multi-phase, multi-component processes in porous media
-we state that the assumption of \emph{local thermodynamic equilibrium}.
+we state the assumption of \emph{local thermodynamic equilibrium}.
Chemical equilibrium means that the mass/mole fractions of a component in
different phases are in equilibrium.
Thermal equilibrium assumes the same temperature for all considered phases.
@@ -39,8 +34,8 @@ Mechanical equilibrium is not valid in a porous medium, since discontinuities
in pressure can occur across a fluid-fluid interface due to capillary effects.
\item[Notation:]
-The subscript index $\alpha \in \{\text{w}, \text{n}, \text{g}\}$ refers
-to the phase, while the superscript $\kappa \in \{\text{w}, \text{a}, \text{c}\}$
+The subscript index $\alpha$, e.g. $\text{w}, \text{n} \text{ and } \text{g}$ in the example of Fig. \ref{fig:phaseMassEnergyTransfer}, refers
+to the phase, while the superscript $\kappa$, e.g. $\text{w}, \text{a} \text{ and } \text{c}$ in the example of Fig. \ref{fig:phaseMassEnergyTransfer},
refers to the component.
\end{description}
@@ -121,10 +116,204 @@ $\boldsymbol{v}_\alpha$ & velocity (Darcy or free flow)& & \\
\filldraw[black!40](6,-0.2) rectangle +(0.3,0.3) node at (6.3,-0.1)[right,black]{Organic contaminant (NAPL)};
\filldraw[black!70](6,-0.8) rectangle +(0.3,0.3) node at (6.3,-0.75)[right,black]{Solid phase};
\end{tikzpicture}
- \caption{Mass and energy transfer between the phases}
+ \caption{Mass and energy transfer between the phases in a water-NAPL-gas system \cite{A3:class:2002a}}
\label{fig:phaseMassEnergyTransfer}
\end{figure}
+\subsection[Scale]{Scale\footnote{\label{foot:hommel}This subsection is taken from \cite{hommel2016modeling} in a slightly adapted form.}}
+
+Depending on the scale of interest, physical and chemical processes and properties can be described
+using different approaches.
+On the molecular scale, the properties and interactions of individual molecules are described,
+which is only feasible for a restricted number of molecules.
+For larger systems, a continuum approach is used, where properties are averaged over
+groups of similar molecules, assuming continuous matter. This upscaling by averaging
+from the molecular scale results in the micro-scale, on which the system is described by
+the pore geometry and the distribution of distinct fluid phases within the pores.
+However, for larger laboratory or field-scale applications, the micro-scale is still
+computationally prohibitively expensive and system descriptions on the macro-scale
+are used for calculations. The macro-scale description is obtained by averaging over the
+micro-scale properties within a representative elementary volume (REV),
+which needs to be large enough to ensure that the averaged properties are independent of the REV size
+or position. However, it should in turn be much smaller than the entire domain size \citep{helmig1997multiphase}. %(Bear 1988)
+The detailed pore-geometry and phase-distribution information of the micro-scale is lost
+on the macro-scale and replaced by volume average quantities,
+such as porosity, permeability and phase saturation,
+and relations like the Darcy's law.
+The macro-scale is also called the REV (or Darcy) scale and is the scale of the
+models available in \Dumux.
+
+\subsection[Porous medium properties]{Porous medium properties\footref{foot:hommel}}
+\subsubsection{Porosity}
+The porosity $\phi$ is defined as the fraction of the volume occupied by fluids in an REV $V_\mathrm{fluid}$
+divided by the total volume of the REV $V_\mathrm{total}$.
+
+\begin{equation}\label{eq:def_poro}
+\phi=\frac{V_\mathrm{fluid}}{V_\mathrm{total}}=1-\frac{V_\mathrm{solid}}{V_\mathrm{total}}.
+\end{equation}
+
+
+\subsubsection{Intrinsic permeability}
+The intrinsic permeability is a measure on the REV scale of the ease of fluid flow through porous media.
+It relates the potential gradient and the resulting flow velocity in the Darcy equation.
+As the porous medium may have a structure leading to preferential flow in certain directions,
+intrinsic permeability is in general a tensorial quantity $\mathbf{K}$.
+For isotropic porous media, it can be reduced to a scalar quantity $K$.
+
+% \begin{equation}
+% \mathbf{v}=
+% \end{equation}
+
+\newpage
+\subsection[Mass fraction, mole fraction]{Mass fraction, mole fraction\footref{foot:hommel}}\label{sec:mole_frac_molality}
+The composition of a phase is described by mass or mole fractions of the components.
+The mole fraction $x^\kappa_\alpha$ of component $\kappa$ in phase $\alpha$ is defined as:
+
+\begin{equation}\label{eq:def_molefrac}
+x^\kappa_\alpha = \frac{n^\kappa_\alpha}{\sum_i n^i_\alpha},
+\end{equation}
+
+where $n^\kappa_\alpha$ is the number of moles of component $\kappa$ in phase $\alpha$.
+The mass fraction $X^\kappa_\alpha$ is defined similarly
+using the mass of component $\kappa$ in phase $\alpha$ instead of $n^\kappa_\alpha$,
+$X^\kappa_\alpha = \nicefrac{\mathrm{mass^\kappa_\alpha}}{\mathrm{mass^{total}_\alpha}}$.
+% as:
+%
+% \begin{equation}\label{eq:def_massfrac}
+% X^\kappa_\alpha = \frac{m^\kappa_\alpha}{\sum_i m^i_\alpha},
+% \end{equation}
+%
+% where $m^\kappa_\alpha$ is the mass of component $\kappa$ in phase $\alpha$.
+The molar mass $M^\kappa$ of the component $\kappa$ relates the mass fraction
+to the mole fraction and vice versa.
+
+\subsection[Fluid properties]{Fluid properties\footref{foot:hommel}}\label{sec:fluid_properties}
+The most important fluid properties to describe fluid flow on the REV scale are density and viscosity.
+
+\subsubsection{Density}\label{sec:density}
+The density $\rho_\alpha$ of a fluid phase $\alpha$ is defined as the ratio of its mass to its volume
+$(\rho_\alpha = \nicefrac{\mathrm{mass_\alpha}}{\mathrm{volume_\alpha}})$ while
+the molar density $\rho_{\mathrm{mol},\alpha}$ is defined as the ratio of the number of moles per volume
+$(\rho_{\mathrm{mol},\alpha} = \nicefrac{\mathrm{moles_\alpha}}{\mathrm{volume_\alpha}})$.
+
+\subsubsection{Viscosity}\label{sec:viscosity}
+The dynamic viscosity $\mu_\alpha$ characterizes the resistance of a fluid to flow.
+As density, it is a fluid phase property.
+For Newtonian fluids, it relates the shear stress $\tau_\mathrm{s}$ to the
+velocity gradient $\nicefrac{d v_{\alpha,\,x}}{d y}$:
+
+\begin{equation}\label{eq:def_viscosity}
+\tau_\mathrm{s} = \mu_\alpha \frac{d v_{\alpha,\,x}}{d y}.
+\end{equation}
+
+Density and viscosity are both dependent on pressure, temperature and phase composition.
+
+\subsection[Fluid phase interactions in porous media]{Fluid phase interactions in porous media\footref{foot:hommel}}\label{sec:fluid_interact}
+If more than a single fluid is present in the porous medium, the fluids interact with each other and the solids, which leads to additional properties for multi-phase systems.
+
+\subsubsection{Saturation}\label{sec:saturation}
+The saturation $S_\alpha$ of a phase $\alpha$ is defined as the ratio of the volume occupied
+by that phase to the total pore volume within an REV.
+As all pores are filled with some fluid, the sum of the saturations of all present phases is equal to one.
+
+\subsubsection{Capillary pressure}\label{sec:pc}
+Immiscible fluids form a sharp interface as a result of differences in their intermolecular forces
+translating into different adhesive and cohesive forces at the fluid-fluid and fluid-fluid-solid interfaces
+creating interfacial tension on the microscale.
+From the mechanical equilibrium which has also to be satisfied at the interface,
+a difference between the pressures of the fluid phases results defined as
+the capillary pressure $p_\mathrm{c}$:
+
+\begin{equation}\label{eq:pc-pn_pw}
+p_\mathrm{c} = p_\mathrm{n} - p_\mathrm{w}.
+\end{equation}
+
+On the microscale, $p_\mathrm{c}$ can be calculated from the surface tension
+according to the Laplace equation \citep[see][]{helmig1997multiphase}.
+
+On the REV scale, however, capillary pressure needs to be defined by quantities of that scale.
+Several empirical relations provide expressions to link $p_\mathrm{c}$ to the wetting-phase saturation $S_\mathrm{w}$.
+An example is the relation given by \citet{brooks1964hydrau} %, Corey1994}
+to determine $p_\mathrm{c}$ based on
+$S_\mathrm{e}$, which is the effective wetting-phase saturation,
+the entry pressure $p_\mathrm{d}$, and the parameter $\lambda$ describing the pore-size distribution:
+
+\begin{equation}\label{eq:pc-Sw}
+p_\mathrm{c} = p_\mathrm{d} S_\mathrm{e}^{-\frac{1}{\lambda}},
+\end{equation}
+
+with
+
+\begin{equation}\label{eq:Se}
+S_\mathrm{e} = \frac{S_\mathrm{w}-S_\mathrm{w,r}}{1-S_\mathrm{w,r}},
+\end{equation}
+
+where $S_\mathrm{w,r}$ is the residual wetting phase saturation which cannot be displaced
+by another fluid phase and remains in the porous medium.
+
+\subsubsection{Relative permeability}\label{sec:kr}
+The presence of two fluid phases in the porous medium reduces the space available for flow
+for each of the fluid phases.
+This increases the resistance to flow of the phases, which is accounted for by the means of
+the relative permeability $k_\mathrm{r,\alpha}$, which scales the intrinsic permeability.
+It is a value between zero and one, depending on the saturation.
+The relations describing the relative permeabilities of the wetting and non-wetting phase are different
+as the wetting phase predominantly occupies small pores and the edges of larger pores while the
+non-wetting phases occupies large pores.
+The relative permeabilities for the wetting phase $k_\mathrm{r,w}$ and the non-wetting phase are e.g. calculated as (also by \citet{brooks1964hydrau}):
+
+\begin{equation}\label{eq:krw}
+k_\mathrm{r,w} = S_\mathrm{e}^{\frac{2+3\lambda}{\lambda}}
+\end{equation}
+and
+\begin{equation}\label{eq:krn}
+k_\mathrm{r,n} = \left( 1- S_\mathrm{e}\right)^2 \left( 1- S_\mathrm{e}^{\frac{2+\lambda}{\lambda}}\right).
+\end{equation}
+
+\subsection[Transport processes in porous media]{Transport processes in porous media \footref{foot:hommel}}\label{sec:tipm}
+On the macro-scale, the transport of mass can be grouped according to the driving force of the
+transport process. Pressure gradients result in the advective transport of a fluid phase
+and all the components constituting the phase,
+while concentration gradients result in the diffusion of a component within a phase.
+
+\subsubsection{Advection}\label{sec:Advection}
+Advective transport is determined by the flow field.
+On the macro-scale, the velocity $\mathbf{v}$ is calculated using the Darcy equation
+depending on the potential gradient $(\nabla p_\alpha - \rho_\alpha \mathbf{g})$,
+accounting for both pressure difference and gravitation,
+the intrinsic permeability of the porous medium,
+and the viscosity $\mu$ of the fluid phase:
+
+\begin{equation} \label{eq:Darcy1p}
+\mathbf{v}=-\frac{\mathbf{K}}{\mu}(\nabla p - \rho \mathbf{g}).
+\end{equation}
+
+$\mathbf{v}$ is proportional to $(\nabla p - \rho \mathbf{g})$ with the proportional factor $\nicefrac{\mathbf{K}}{\mu}$.
+This equation can be extended to calculate the velocity $\mathbf{v}_{\alpha}$ of phase $\alpha$ in the case of
+two-phase flow by considering the relative permeability $k_\mathrm{r,\alpha}$ (Section~\ref{sec:kr}):
+
+\begin{equation} \label{eq:Darcy2p}
+\mathbf{v}_{\alpha}=-\frac{k_\mathrm{r,\alpha}\mathbf{K}}{\mu_{\alpha}}(\nabla p_{\alpha} - \rho_{\alpha} \mathbf{g})
+\end{equation}
+
+\subsubsection{Diffusion}\label{sec:Diffusion}
+Molecular diffusion is a process determined by the concentration gradient.
+It is commonly modeled as Fickian diffusion following Fick's first law:
+
+\begin{equation} \label{eq:Diffusion}
+\mathbf{j_d}=-\rho_{\alpha} D^\kappa_\alpha \nabla X^\kappa_\alpha,
+\end{equation}
+
+where $D^\kappa_\alpha$ is the molecular diffusion coefficient of component $\kappa$ in phase $\alpha$.
+In a porous medium, the actual path lines are tortuous due to the impact of the solid matrix.
+This tortuosity and the impact of the presence of multiple fluid phases
+is accounted for by using an effective diffusion coefficient $D^\kappa_\mathrm{pm, \alpha}$:
+
+\begin{equation} \label{eq:diffusion_coeff_pm}
+D^\kappa_\mathrm{pm, \alpha}= \phi \tau_\alpha S_\alpha D^\kappa_\alpha,
+\end{equation}
+
+where $\tau_\alpha$ is the tortuosity of phase $\alpha$.
\subsection{Gas mixing laws}
Prediction of the $p-\varrho-T$ behavior of gas mixtures is typically based on two (contradicting) concepts: Dalton's law or Amagat's law.
diff --git a/doc/handbook/6_inputoutput.tex b/doc/handbook/6_inputoutput.tex
index 33ad270bcb211a0c9b78530294101e9fa8d7619c..c508a20f7e6e126056c6934199191334aa57cb1d 100644
--- a/doc/handbook/6_inputoutput.tex
+++ b/doc/handbook/6_inputoutput.tex
@@ -6,8 +6,8 @@ the grid formats that can be used by \Dumux and introduces the \Dumux \texttt{Gr
Finally, this section informs about handling output in \Dumux.
\subsection{Supported grid file formats}
-\Dumux can read grids from file using the Dune Grid Format (DGF), the Gmsh mesh format (MSH), or the Eclipse grid format (GRDECL).
-Using the class \texttt{Dumux::VTKReader}, \Dumux has experimental support for reading grids and data from VTK files.
+\label{sec:supportedGridFormats}
+\Dumux can read grids from file using the Dune Grid Format (DGF), the Gmsh mesh format (MSH), the Eclipse grid format (GRDECL), or the Visualization ToolKit (VTK/VTU/VTP) format.
\subsubsection{Dune Grid Format}
Most of our \Dumux tests use the Dune Grid Format (DGF) to read in grids. A detailed description
@@ -38,15 +38,19 @@ Furthermore, petrophysical properties can be defined (for each cell), by using e
\Dumux supports the Eclipse Grid Format by using the \texttt{opm-grid} module (see (\url{https://opm-project.org}).
An example can be found in \texttt{dumux/test\allowbreak/porousmediumflow/2p/implicit/cornerpoint}.
+\subsubsection{VTK File Format}
+VTK format uses ASCII or XML format. It is mostly used by \Dumux for output purposes and can be visualized by programs such as Paraview, ViIt or Tecplot. Using VTK files to input grid and parameter data is also possible.
+An example can be found in \texttt{dumux/test\allowbreak/io/gridmanager}.
+
\subsubsection{Other Grid Formats}
-Grid formats other than DGF, MSH, GRDECL, VTK will have to be converted to the DGF, MSH, GRDECL, VTK format before they can be used in \Dumux.
+Grid formats other than DGF, MSH, GRDECL, or VTK will have to be converted to the DGF, MSH, GRDECL, or VTK format before they can be used in \Dumux.
If conversion is not an option, another possibility would be to write your own \texttt{GridManager}s. Examples of other grid formats,
which have previously been either converted or custom-created in \Dumux, are ArtMesh grids (fractured network grids), and ICEM grids (CAD developed grids).
\subsection{The \Dumux \texttt{GridManager}}
The \texttt{Dumux::GridManager} class constructs the grid from information in the input file and handles the data.
Currently, supported Dune grid interface implementations are \texttt{YaspGrid}, \texttt{OneDGrid}, \texttt{dune-uggrid}, \texttt{dune-alugrid}, \texttt{dune-foamgrid}, \texttt{dune-subgrid}, \texttt{opm-grid} (cornerpoint grids) and \texttt{dune-spgrid}.
-Grids can be constructed from a DGF or MSH file by simply providing the filename to the grid in the \texttt{Grid} group~\footnote{Note,
+Grids can be constructed from a DGF, VTK or MSH file by simply providing the filename to the grid in the \texttt{Grid} group~\footnote{Note,
that group name \texttt{Grid} is the default group name and can be customized in your problem changing the string property \texttt{GridParameterGroup}.
This way, it is possible, e.g., for problems with more than one grid, to set different group names for each grid, thus configuring them separately.}
of the input file:
@@ -55,12 +59,12 @@ of the input file:
File = mydgfgrid.dgf
\end{lstlisting}
-If you are using an unstructured grid interface like \texttt{UGGrid} or \texttt{ALUGrid}, constructing a grid from a MSH is just changing a line:
+If you are using an unstructured grid interface like \texttt{UGGrid} or \texttt{FOAMGrid}, constructing a grid from a VTK or MSH is just changing a line:
\begin{lstlisting}[style=DumuxParameterFile]
[Grid]
File = mygmshgrid.msh
\end{lstlisting}
-\Dumux will tell you in case your selected grid manager does not support reading MSH files.
+\Dumux will tell you in case your selected grid manager does not support reading such files.
You want to initially refine your grid? It's just adding a line:
\begin{lstlisting}[style=DumuxParameterFile]
@@ -69,7 +73,7 @@ File = mydgfgrid.dgf
Refinement = 4
\end{lstlisting}
-When reading a MSH file, further parameters are recognized. \texttt{Verbose} enables verbose output on grid construction when set to $1$.
+When reading a MSH or VTK file, further parameters are recognized. \texttt{Verbose} enables verbose output on grid construction when set to $1$.
\texttt{BoundarySegments} enables reading parameterized boundaries. \texttt{PhysicalEntities} enables reading boundary and element flags.
\subsubsection{Parameters specific to the grid implementation}
@@ -127,7 +131,7 @@ The VTK file format is supported by common visualisation programs like ParaView,
\subsubsection{Customize the VTK output}
Using the respective \texttt{initOutputModule} function of the model \texttt{IOFields}, a default
-set of variables is stored in the VTK files. It is also possible to add further variables,
+set of variables is defined for the output into the VTK files. It is also possible to add further variables,
using the member function \texttt{addField} of the \texttt{VtkOutputModule}. For example, to add a variable called \texttt{temperatureExact}:
\begin{lstlisting}[style=DumuxCode]
vtkWriter.addField(problem->getExactTemperature(), "temperatureExact");
@@ -146,10 +150,10 @@ It is important that the life-time of the added field exceeds the life-time of t
to the \texttt{addField} function. The vector has to be stored somewhere, e.g. in the program main file.
The second input argument is the name of the additional variable (as it should be written in the VTK files).
-The example above is taken from: \\ \texttt{test/porousmediumflow/1pnc/implicit/test\_1p2cni\_convection\_fv.cc}
+The example above is taken from: \\ \texttt{test/porousmediumflow/1pnc/implicit/1p2c/nonisothermal/convection/main.cc}
\subsubsection{VTK as input format}
-There is experimental support for reading data and grids from VTK files. Have a look at the \texttt{Dumux::VTKReader} class.
+There is support for reading data and grids from VTK files, see subsection \ref{sec:supportedGridFormats}.
\subsubsection{Gnuplot interface}
\Dumux provides a small interface to GNUPlot, which can be used to plot results and generate
diff --git a/doc/handbook/6_parallel.tex b/doc/handbook/6_parallel.tex
index ba4a3580a23b233e01604e2ea43364646d588d3c..6fb1907eab02600cb9a381b9d328b9aec755d319 100644
--- a/doc/handbook/6_parallel.tex
+++ b/doc/handbook/6_parallel.tex
@@ -45,7 +45,7 @@ constructed with a \texttt{Dune::GridView} object and a mapper, in order to cons
parallel index set needed for communication.
\begin{lstlisting}[style=DumuxCode]
-auto linearSolver = std::make_shared<LinearSolver>(leafGridView, fvGridGeometry->dofMapper());
+auto linearSolver = std::make_shared<LinearSolver>(leafGridView, gridGeometry->dofMapper());
\end{lstlisting}
\subsection{Run a Parallel Application}
diff --git a/doc/handbook/6_propertysystem.tex b/doc/handbook/6_propertysystem.tex
index bfe58b3fa3f8779e8c38364541eae359ecbc152a..63a8f78c586fa4851f949b92726859051595132f 100644
--- a/doc/handbook/6_propertysystem.tex
+++ b/doc/handbook/6_propertysystem.tex
@@ -20,7 +20,7 @@ defined for arbitrary levels of the inheritance hierarchy.
\subsection{How-to}
All source files which use the property system should include
-the header file \path{dumux/common/propertysystem.hh}.
+the header file \path{dumux/common/properties/propertysystem.hh}.
Declaration of type tags and
property tags as well as defining properties must be done inside the
namespace \texttt{Dumux::Properties}.
@@ -269,16 +269,16 @@ make sense for at least one of the nodes of Figure
follows:
\begin{lstlisting}[name=propsyscars,style=DumuxCode]
template<class TypeTag, class MyTypeTag>
+struct GasUsage { using type = UndefinedProperty; }; // [l/100km]
+template<class TypeTag, class MyTypeTag>
struct TopSpeed { using type = UndefinedProperty; }; // [km/h]
template<class TypeTag, class MyTypeTag>
struct NumSeats { using type = UndefinedProperty; }; // []
template<class TypeTag, class MyTypeTag>
-struct CanonCaliber { using type = UndefinedProperty; }; // [mm]
-template<class TypeTag, class MyTypeTag>
-struct GasUsage { using type = UndefinedProperty; }; // [l/100km]
-template<class TypeTag, class MyTypeTag>
struct AutomaticTransmission { using type = UndefinedProperty; }; // true/false
template<class TypeTag, class MyTypeTag>
+struct CanonCaliber { using type = UndefinedProperty; }; // [mm]
+template<class TypeTag, class MyTypeTag>
struct Payload { using type = UndefinedProperty; }; // [t]
\end{lstlisting}
diff --git a/doc/handbook/6_stepsofasimulation.tex b/doc/handbook/6_stepsofasimulation.tex
index 7ac80d80dc4be8e87c5d9a3dc70e82d3ffd0b40d..c078583155d1176456066b5da27c93e5627ed773 100644
--- a/doc/handbook/6_stepsofasimulation.tex
+++ b/doc/handbook/6_stepsofasimulation.tex
@@ -61,4 +61,4 @@ solution scheme is illustrated down to the element level.
\subsection{Structure -- by Implementation}
A possible starting point to understand how the above mentioned algorithm is implemented within \Dumux,
is the example main file
-\url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/releases/3.0/exercises/exercise-mainfile/exercise_1p_a.cc}
+\url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/releases/3.1/exercises/exercise-mainfile/exercise_1p_a.cc}
diff --git a/doc/handbook/6_temporaldiscretizations.tex b/doc/handbook/6_temporaldiscretizations.tex
index fd424205bd1065597c4113cc34e2d2bd661a116e..f3fdb36492e3e90adfcd9a487026b6e7a136fbfb 100644
--- a/doc/handbook/6_temporaldiscretizations.tex
+++ b/doc/handbook/6_temporaldiscretizations.tex
@@ -1,5 +1,6 @@
\section{Temporal Discretization and Solution Strategies}
-%TODO: Intro sentences
+In this section, the temporal discretization as well as solution strategies (monolithic/sequential) are presented.
+
\subsection{Temporal discretization}
Our systems of partial differential equations are discretized in space and in time.
diff --git a/doc/handbook/dumux-handbook.bib b/doc/handbook/dumux-handbook.bib
index 169292f20708b5c5cacb1d619623742d0ecf050c..88860ce45fe6aca8bff3da2bc3c0d3e7b22764e9 100644
--- a/doc/handbook/dumux-handbook.bib
+++ b/doc/handbook/dumux-handbook.bib
@@ -1854,3 +1854,31 @@ year={1999}
year={1993},
publisher={John Wiley \& Sons}
}
+
+@phdthesis{hommel2016modeling,
+ author = {Hommel, Johannes},
+ isbn = {978-3-942036-48-1},
+ month = {2},
+ school = {Universität Stuttgart, TASK},
+ title = {Modeling biogeochemical and mass transport processes in the subsurface: Investigation of microbially induced calcite precipitation},
+ type = {Promotionsschrift},
+ url = {https://elib.uni-stuttgart.de/handle/11682/8787},
+ volume = 244,
+ year = 2016
+}
+
+@book{helmig1997multiphase,
+ title={Multiphase flow and transport processes in the subsurface: a contribution to the modeling of hydrosystems.},
+ author={Helmig, Rainer and others},
+ year={1997},
+ publisher={Springer-Verlag}
+}
+
+@article{brooks1964hydrau,
+ title={HYDRAU uc properties of porous media},
+ author={Brooks, R and Corey, T},
+ journal={Hydrology Papers, Colorado State University},
+ volume={24},
+ pages={37},
+ year={1964}
+}
diff --git a/doc/handbook/installDumux.sh b/doc/handbook/installDumux.sh
index 60295e5089cdf053438b69d0578a55c9b8df123f..fe06600aa2eb76805ee94991995be912093c5f90 100644
--- a/doc/handbook/installDumux.sh
+++ b/doc/handbook/installDumux.sh
@@ -14,7 +14,7 @@ for MOD in common geometry grid localfunctions istl; do
done
# dumux
-git clone -b releases/3.0 https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git
+git clone -b releases/3.1 https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git
if [ $? -ne 0 ]; then
echo "*************************************************"