diff git a/LICENSE.md b/LICENSE.md
index c923b620a54a447b18e3488c936e9281f29705cd..1582b6114037bea7282ae09725239fb7ace8b35f 100644
 a/LICENSE.md
+++ b/LICENSE.md
@@ 49,6 +49,7 @@ Copyright holders
 20122014  Alexandru Tatomir 
 20152017  Larissa de Vries 
 2013  Katharina Türk 
+ 2018  Martin Utz 
 20102014  Lena Walter 
 20152017  Kilian Weishaupt 
 20102011  David Werner 
diff git a/doc/handbook/0_dumuxhandbook.tex b/doc/handbook/0_dumuxhandbook.tex
index 0a2416b866fa6490e81cffb4fc34f1439d5ba11e..7d8185ce932364fe073dc33f783f213f183c70f1 100644
 a/doc/handbook/0_dumuxhandbook.tex
+++ b/doc/handbook/0_dumuxhandbook.tex
@@ 11,6 +11,7 @@
\usepackage{enumerate}
\usepackage{hyperref}
\usepackage{graphicx}
+
\usepackage{listings}
\usepackage{makeidx}
\usepackage[square,numbers]{natbib}
@@ 72,6 +73,7 @@
\DeclareMathOperator{\grad}{\mathbf{grad}}
\DeclareMathOperator{\curl}{curl}
\DeclareMathOperator{\Div}{div}
+\newcommand{\meas}[1]{\lvert{#1}\rvert}
\pagestyle{scrheadings}
@@ 109,31 +111,32 @@ Universit\"at Stuttgart, Paffenwaldring 61, D70569 Stuttgart, Germany}\\
\chapter{Introduction}
\input{1_introduction}
\chapter{Getting started}
+\chapter{Quick Start}\label{quickinstall}
In this chapter we provide a quick start guide to
your first \Dumux experience.
The first section contains instructions on how to very quickly install \Dumux.
More detailed information on how to obtain source code, build and test \Dune and \Dumux
follows in the second section of this chapter. The second section also contains information on
how to build the documentation and about external libraries and modules.
+your first \Dumux experience, including an install script with all necessary instructions
+on how to very quickly install the latest release version of \Dumux.
\input{2_quickinstall}
+
+\chapter{Detailed Installation, Documentation, and Externals}\label{detailedinstall}
+In this chapter, we provide more detailed information on how to obtain source code, build and test \Dune and \Dumux.
+It further contains information on
+how to build the documentation and about external libraries and modules.
\input{2_detailedinstall}
\chapter{Tutorial}\label{chp:tutorial}
\input{3_tutorial}
+\chapter{Learning to use \Dumux}\label{chp:tutorial}
+\input{3_course}
\input{3_furtherpractice}
\chapter{Overview and Infrastructure}
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_guidelines},\ref{sc_developingdumux}).
+(\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}.
\input{4_structure}
\input{4_newfoldersetup}
\input{4_parameterfiles}
\input{4_restartsimulations}
\input{4_guidelines}
\input{4_developingdumux}
\input{4_externaltools}
\input{4_assemblinglinearsystem}
@@ 145,7 +148,8 @@ in deeper modifications of underlying \Dumux models, classes, functions, etc.
\input{5_spatialdiscretizations}
\input{5_stepsofasimulation}
\input{5_propertysystem}
\input{5_grids}
+\input{5_inputoutput}
+\input{5_parallel}
\bibliographystyle{plainnat}
\bibliography{dumuxhandbook}
diff git a/doc/handbook/1_introduction.tex b/doc/handbook/1_introduction.tex
index 526f021c8ae803a42309073bac542d5bdbc8626e..370786c3f5faa72bfed9909419b1afa43c301f85 100644
 a/doc/handbook/1_introduction.tex
+++ b/doc/handbook/1_introduction.tex
@@ 25,7 +25,7 @@ libraries\footnote{In fact, the performance penalty resulting from the
use of \Dune's grid interface is usually negligible~\cite{BURRI2006}.}.
\begin{figure}[hbt]
\centering
 \includegraphics[width=.5\linewidth, keepaspectratio]{PNG/dunedesign.png}
+ \includegraphics[width=.5\linewidth, keepaspectratio]{png/dunedesign.png}
\caption{
\label{fig:dunedesign}
A highlevel overview of \Dune's design is available on the project's
@@ 49,7 +49,10 @@ entity can be thought of as a prototype for the actual grid
entity. For example, if we used a grid which applied hexahedrons as cells,
the reference element for each cell would be the unit cube $[0, 1]^3$
and the geometry function would scale and translate the cube so that
it matches the grid's cell. For a more thorough description of \Dune's
+it matches the grid's cell. A quick overview of reference elements and the
+related numbering can be gotten from the DUNE cheat sheet
+(\url{https://www.duneproject.org/pdf/dunecheatsheet.pdf}).
+For a more thorough description of \Dune's
grid definition, see~\cite{BASTIAN2008}.
In addition to the grid interface, \Dune also provides quite a few
@@ 71,3 +74,17 @@ 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.
+It is available online:
+\url{https://git.iws.unistuttgart.de/dumuxrepositories/dumux/wikis/Updatingprogramsfromversion2.12toversion3.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 \Dumux3.0
+and wish everyone a brandnew and exciting simulation experience.
diff git a/doc/handbook/2_detailedinstall.tex b/doc/handbook/2_detailedinstall.tex
index 504d33049e51056871dfa4dbed86a9e060cf7ac6..a4b8286eebea4bb8b692590231eaa47dceecc767 100644
 a/doc/handbook/2_detailedinstall.tex
+++ b/doc/handbook/2_detailedinstall.tex
@@ 1,5 +1,5 @@
\section{Detailed Installation Instructions}
\label{install}
+% \section{Detailed Installation Instructions}
+% \label{install}
Installing \Dumux means that you first unpack \Dune and \Dumux in a root directory,
(section \ref{sc:ObtainingSourceCode}).
@@ 15,10 +15,10 @@ Thus, the installation procedure of \Dumux is the same as that of \Dune.
Details regarding the installation of \Dune are provided on the \Dune website \cite{DUNEHP}.
\subsection{Obtaining Source Code for \Dune and \Dumux}
+\section{Obtaining Source Code for \Dune and \Dumux}
\label{sc:ObtainingSourceCode}
The \Dumux release and trunk (developer tree) are based on the most recent
\Dune release 2.5, comprising the core modules dunecommon, dunegeometry, dunegrid,
+\Dune release 2.6, comprising the core modules dunecommon, dunegeometry, dunegrid,
duneistl and dunelocalfunctions. For working with \Dumux, these modules are required.
All \Dune modules, including the \Dumux module, get extracted into a common root directory, as it
is done in an ordinary \Dune installation.
@@ 32,45 +32,45 @@ in the root directory of the respective module. This should not be changed by th
Two possibilities exist to get the source code of \Dune and \Dumux.
Firstly, \Dune and \Dumux can be downloaded as tar files from the respective \Dune and \Dumux website.
They have to be extracted as described in the next paragraph.
% TODO: alpha version was not released with a tarball. For the next releases the following lines need to be deleted again
There is no tar file for the current \DumuxVersion~release.
Secondly, a method to obtain the most recent source code (or, more generally, any of its previous revisions) by direct access
to the software repositories of the revision control system is described in the subsequent part.
Be aware that you cannot get \texttt{dumuxdevel} or the external libraries from \texttt{dumuxexternal} unless
you have an GitLab account with the right privileges.
+% % TODO: alpha version was not released with a tarball. For the next releases the following lines need to be deleted again
+% There is no tar file for the current \DumuxVersion~release.
+% Secondly, a method to obtain the most recent source code (or, more generally, any of its previous revisions) by direct access
+% to the software repositories of the revision control system is described in the subsequent part.
+% Be aware that you cannot get \texttt{dumuxdevel} or the external libraries from \texttt{dumuxexternal} unless
+% you have an GitLab account with the right privileges.
In section \ref{sec:prerequisites} we list some prerequisites for running \Dune and \Dumux.
Please check in said paragraph whether you can fulfill them before continuing.
% TODO: alpha version was not released with a tarball. For the next releases the following lines need to be uncommented again
% \paragraph{Obtaining the software by installing tar files}
% The slightly oldfashionedly named tapearchivefile, shortly named tar file or
% tarball, is a common file format for distributing collections of files contained
% within these archives.
% The extraction from the tar files is done as follows:
% Download the tarballs from the respective \Dune (version 2.5) and \Dumux websites
% to a certain folder in your file system.
% Create the common root directory, named \texttt{DUMUX} in the example below.
% Then extract the content of the tar files, e.\,g. with the commandline program
% \texttt{tar}.
% This can be achieved by the following shell commands. Replace \texttt{path\_to\_tarball}
% with the directory name where the downloaded files are actually located.
% After extraction, the actual name of the dumux subdirectory is \texttt{dumux\DumuxVersion}
% (or whatever version you downloaded).
%
% \begin{lstlisting}[style=Bash]
% $ mkdir DUMUX
% $ cd DUMUX
% $ tar xzvf path_to_tarball_of/dunecommon2.5.0.tar.gz
% $ tar xzvf path_to_tarball_of/dunegeometry2.5.0.tar.gz
% $ tar xzvf path_to_tarball_of/dunegrid2.5.0.tar.gz
% $ tar xzvf path_to_tarball_of/duneistl2.5.0.tar.gz
% $ tar xzvf path_to_tarball_of/dunelocalfunctions2.5.0.tar.gz
% $ tar xzvf path_to_tarball_of/dumux3.0alpha.tar.gz
% \end{lstlisting}
%
% Furthermore, if you wish to install the optional \Dune GridHowto which provides a tutorial
% on the Dune grid interface, act similar.
+\paragraph{Obtaining the software by installing tar files}
+The slightly oldfashionedly named tapearchivefile, shortly named tar file or
+tarball, is a common file format for distributing collections of files contained
+within these archives.
+The extraction from the tar files is done as follows:
+Download the tarballs from the respective \Dune (version 2.6) and \Dumux websites
+to a certain folder in your file system.
+Create the common root directory, named \texttt{DUMUX} in the example below.
+Then extract the content of the tar files, e.\,g. with the commandline program
+\texttt{tar}.
+This can be achieved by the following shell commands. Replace \texttt{path\_to\_tarball}
+with the directory name where the downloaded files are actually located.
+After extraction, the actual name of the dumux subdirectory is \texttt{dumux\DumuxVersion}
+(or whatever version you downloaded).
+
+\begin{lstlisting}[style=Bash]
+$ mkdir DUMUX
+$ cd DUMUX
+$ tar xzvf path_to_tarball_of/dunecommon2.6.0.tar.gz
+$ tar xzvf path_to_tarball_of/dunegeometry2.6.0.tar.gz
+$ tar xzvf path_to_tarball_of/dunegrid2.6.0.tar.gz
+$ tar xzvf path_to_tarball_of/duneistl2.6.0.tar.gz
+$ tar xzvf path_to_tarball_of/dunelocalfunctions2.6.0.tar.gz
+$ tar xzvf path_to_tarball_of/dumux3.0.tar.gz
+\end{lstlisting}
+
+Furthermore, if you wish to install the optional \Dune GridHowto which provides a tutorial
+on the Dune grid interface, act similar.
\paragraph{Obtaining \Dune and \Dumux from software repositories}
Direct access to a software revision control system for downloading code can be of advantage later on.
@@ 93,48 +93,50 @@ one for \Dune and one for \Dumux.
\begin{lstlisting}[style=Bash]
$ mkdir DUMUX
$ cd DUMUX
$ git clone b releases/2.5 https://gitlab.duneproject.org/core/dunecommon.git
$ git clone b releases/2.5 https://gitlab.duneproject.org/core/dunegeometry.git
$ git clone b releases/2.5 https://gitlab.duneproject.org/core/dunegrid.git
$ git clone b releases/2.5 https://gitlab.duneproject.org/core/duneistl.git
$ git clone b releases/2.5 https://gitlab.duneproject.org/core/dunelocalfunctions.git
$ git clone b 3.0.0alpha https://git.iws.unistuttgart.de/dumuxrepositories/dumux.git
+$ git clone b releases/2.6 https://gitlab.duneproject.org/core/dunecommon.git
+$ git clone b releases/2.6 https://gitlab.duneproject.org/core/dunegeometry.git
+$ git clone b releases/2.6 https://gitlab.duneproject.org/core/dunegrid.git
+$ git clone b releases/2.6 https://gitlab.duneproject.org/core/duneistl.git
+$ git clone b releases/2.6 https://gitlab.duneproject.org/core/dunelocalfunctions.git
+$ git clone b releases/3.0 https://git.iws.unistuttgart.de/dumuxrepositories/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.
Please check the \Dune website \cite{DUNEHP} for further information on the \Dune development. We always try to keep up with the latest developments of \Dune.
However, the current \Dumux release is based on the stable 2.5 release and it might not compile without further adaptations using the newest versions of \Dune.
+However, the current \Dumux release is based on the stable 2.6 release and it might not compile without further adaptations using the newest versions of \Dune.
Furthermore, if you wish to install the optional \Dune GridHowto which provides a tutorial
on the Dune grid interface, act similar.
\paragraph{Patching \Dune or external libraries}
\label{sc:patchingDUNE}
Patching of \Dune modules in order to work together with \Dumux can be necessary for several reasons.
Software like a compiler or even a standard library
changes at times. But, for example, a certain release of a software component that we depend on,
may not reflect that change and thus it has to be modified.
In the dynamic developing process of software which depends on other modules it is not always feasible
to adapt everything to the most recent version of each module. They may fix problems with a certain module
of a certain release without introducing too much structural change.

\Dumux contains patches and documentation about their usage and application within the
directory \texttt{dumux/patches}.
Please check the README file in that directory for recent information.
In general, a patch can be applied as follows
(the exact command or the used parameters may be slightly different).
We include here an example of a patching dunegrid.

\begin{lstlisting}[style=Bash]
$ # make sure you are in the common root directory
$ cd dunegrid
$ patch p0 < ../dumux/patches/grid2.3.1.patch
\end{lstlisting}

It can be removed by
\begin{lstlisting}[style=Bash]
$ path p0 R < ../dumux/patches/grid2.3.1.patch
\end{lstlisting}
+%TODO:currently, no DUNE patches necessary! Uncomment this section in case this changes again in the future.
+%
+% \paragraph{Patching \Dune or external libraries}
+% \label{sc:patchingDUNE}
+% Patching of \Dune modules in order to work together with \Dumux can be necessary for several reasons.
+% Software like a compiler or even a standard library
+% changes at times. But, for example, a certain release of a software component that we depend on,
+% may not reflect that change and thus it has to be modified.
+% In the dynamic developing process of software which depends on other modules it is not always feasible
+% to adapt everything to the most recent version of each module. They may fix problems with a certain module
+% of a certain release without introducing too much structural change.
+%
+% \Dumux contains patches and documentation about their usage and application within the
+% directory \texttt{dumux/patches}.
+% Please check the README file in that directory for recent information.
+% In general, a patch can be applied as follows
+% (the exact command or the used parameters may be slightly different).
+% We include here an example of a patching dunegrid.
+%
+% \begin{lstlisting}[style=Bash]
+% $ # make sure you are in the common root directory
+% $ cd dunegrid
+% $ patch p0 < ../dumux/patches/grid2.3.1.patch
+% \end{lstlisting}
+%
+% It can be removed by
+% \begin{lstlisting}[style=Bash]
+% $ path p0 R < ../dumux/patches/grid2.3.1.patch
+% \end{lstlisting}
\paragraph{Hints for \DumuxDevelopers}
If you also want to actively participate in the development of \Dumux, you can allways send patches
@@ 144,14 +146,14 @@ access or for developer access on certain parts of \Dumux. Granted developer acc
you are allowed to commit own code and that you can access the \texttt{dumuxdevel} module.
This enhances \texttt{dumux} by providing maybe unstable code from the developer group.
\subsection{Build of \Dune and \Dumux}
+\section{Build of \Dune and \Dumux}
\label{buildIt}
Configuring \Dune and \Dumux is done by the shellcommand \texttt{dunecontrol} which is part of the \Dune build system.
If you are interested in more details about the build system that is used,
they can be found in the \Dune buildsystem documentation\footnote{\url{https://www.duneproject.org/buildsystem/}} and
CMake's documentation\footnote{\url{https://cmake.org/documentation/}}.
If something fails during the execution of \texttt{dunecontrol} feel free to report it to the \Dune or \Dumux developer mailing list,
but also try to include error details.
+but please include error details.
It is possible to compile \Dumux with nearly no explicit options to the build system.
However, for the successful compilation of \Dune and \Dumux, it is currently necessary to pass
@@ 178,7 +180,7 @@ $ cp dumux/optim.opts myoptim.opts
$ ./dunecommon/bin/dunecontrol opts=myoptim.opts usecmake all
\end{lstlisting}
Sometimes it is necessary to have additional options which
+Sometimes, it is necessary to have additional options which
are specific to a package set of an operating system or
sometimes you have your own preferences.
Feel free to work with your own set of options, which may evolve over time.
@@ 188,12 +190,11 @@ The use of external libraries can make it necessary to add quite many options in
It can be helpful to give your customized option file its own name, as done above,
to avoid confusing it with the option files which came out of the distribution.
\subsection{The First Run of a Test Application}
+\section{The First Run of a Test Application}
\label{quickstartguide}
The previous section showed how to install and compile \Dumux. This chapter
+The previous section showed how to install and compile \Dumux. This section
shall give a very brief introduction how to run a first test application and how
to visualize the first output files. A more detailed explanations can be found in
the tutorials in the following chapter.\\
+to visualize the first output files.\par
All executables are compiled in the \texttt{build} subdirectories of \Dumux.
If not given differently in the input files, this is \texttt{buildcmake} as default.
@@ 201,15 +202,14 @@ If not given differently in the input files, this is \texttt{buildcmake} as def
\item Go to the directory \texttt{buildcmake/test}. There, various test application
folders can be found. Let us consider as example\\
\texttt{porousmediumflow/2p/implicit/incompressible/test{\_}2p{\_}incompressible{\_}tpfa}.
\item Enter the folder \texttt{porousmediumflow/2p/implicit/incompressible}.\\ 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}
 into the console. If you explicitly want to state a parameter file, type\\
 \texttt{./test{\_}2p{\_}incompressible{\_}tpfa test\_2p.input}.
 Adding \texttt{test\_2p.input} specifies that all
 important parameters (like first timestep size, end of simulation and location
+\item Enter the folder \texttt{porousmediumflow/2p/implicit/incompressible}.\\ 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.
+ The added \texttt{params.input} specifies that all
+ important runtime parameters (like first timestep size, end of simulation and location
of the grid file) can be found in a text file in the same directory with the
 name \texttt{test\_2p.input}.
+ name \texttt{params.input}.
\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
files. It is possible to stop a running application by pressing $<$Ctrl$><$c$>$.
@@ 218,8 +218,14 @@ If not given differently in the input files, this is \texttt{buildcmake} as def
.pvd file. On the left hand side, you can choose the desired parameter to be displayed.
\end{enumerate}
\subsection{Building Documentation}
\subsubsection{Doxygen}
+\section{Building Documentation}
+
+The building of included documentation like this handbook requires \LaTeX{} and auxiliary tools
+\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{disabledocumentation}
+in the \texttt{CONFIGURE\_FLAGS} of the building options, see section \ref{buildIt}.
+
+\subsection{Doxygen}
\label{sec:builddoxydoc}
Doxygen documentation is done by especially formatted comments integrated in the source code,
which can get extracted by the program \texttt{doxygen}. Beside extracting these comments,
@@ 232,12 +238,12 @@ by running \texttt{dunecontrol}, entering the \texttt{build*}directory, and exe
\texttt{MODULE\_BUILD\_DIRECTORY/doc/doxygen/html/index.html} to read the generated documentation.
This should also work for other \Dune modules.
\subsubsection{Handbook}
+\subsection{Handbook}
To build the \Dumux handbook go into the \texttt{build}directory and
run \texttt{make doc} or \texttt{make 0\_dumuxhandbook\_pdf}. The pdf can then be found
in \texttt{MODULE\_BUILD\_DIRECTORY/doc/handbook/0\_dumuxhandbook.pdf}.
\subsection{External Libraries and Modules} \label{sec:externalmoduleslibraries}
+\section{External Libraries and Modules} \label{sec:externalmoduleslibraries}
The libraries described below provide additional functionality but are not generally required to run \Dumux.
If you are going to use an external library check the information provided on the \Dune website%
\footnote{DUNE: External libraries, \url{https://www.duneproject.org/doc/externallibraries/}}.
@@ 259,7 +265,7 @@ An easy way to install some of the libraries and modules given below is the
has to be called from your common root directory.
\subsubsection{List of External Libraries and Modules}
+\subsection{List of External Libraries and Modules}
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.
@@ 274,6 +280,19 @@ and some more libraries and tools which are prerequisites for their use.
of choice for simulating structures such as foams, discrete fracture networks,
or network flow problems.
Download: \url{https://gitlab.duneproject.org/extensions/dunefoamgrid}
+
+\item \textbf{opmgrid}: opmgrid is a DUNE module supporting grids in a cornerpoint format.
+ Download: \url{https://github.com/OPM/opmgrid.git}
+
+\item \textbf{dunesubgrid}: The dunesubgrid module is a metagrid implementation that allows
+to mark elements of another hierarchical dune grid and use this subgrid just like a regular grid.
+The set of marked elements can then be accessed as a hierarchical dune grid in its own right.
+DuneSubgrid provides the full grid interface including adaptive mesh refinement.
+ Download: \url{https://git.imp.fuberlin.de/agnumpde/dunesubgrid.git}
+
+\item \textbf{dunespgrid}: The DUNE module dunespgrid provides a structured, parallel grid
+and supports periodic boundary conditions.
+ Download: \url{https://gitlab.duneproject.org/extensions/dunespgrid.git}
\item \textbf{SuperLU}: External library for solving linear equations. SuperLU is a general purpose
library for the direct solution of large, sparse, nonsymmetric systems of linear equations.
diff git a/doc/handbook/2_quickinstall.tex b/doc/handbook/2_quickinstall.tex
index 91a4139a886b9fe9c24338d7d5fc9ad3df1f82c5..9235e5c59d8a8b5759827e5c9568da5affb3d0d6 100644
 a/doc/handbook/2_quickinstall.tex
+++ b/doc/handbook/2_quickinstall.tex
@@ 1,13 +1,10 @@
\section{Quick Installation of \Dumux}
\label{quickinstall}

This section only provides one quick way of installing \Dumux.
+This chapter provides one quick way of installing \Dumux.
You should have a recent working Linux environment and no \Dune core modules should be installed.
If you need more information or
have \Dune already installed, please have a look at the detailed installation
instructions in Section \ref{install}.
+instructions in the more detailed intructions in the next chapter \ref{detailedinstall}.
\subsection{Prerequisites} \label{sec:prerequisites}
+\section{Prerequisites} \label{sec:prerequisites}
For this quick start guide the following software packages are required:
\begin{itemize}
\item GitLab client
@@ 17,12 +14,7 @@ For this quick start guide the following software packages are required:
\item paraview (to visualize the results)
\end{itemize}
The building of included documentation like this handbook requires \LaTeX{} and auxiliary tools
\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{disabledocumentation}
in the \texttt{CONFIGURE\_FLAGS} of the building options, see Chapter \ref{buildIt}.

\subsection{Obtaining code and configuring all modules with a script}
+\section{Obtaining code and configuring all modules with a script}
We provide you with a shellscript \texttt{installDumux.sh} that facilitates setting up a {\Dune}/{\Dumux} directory tree
and configures all modules with CMake.
% TODO: uncomment/delete the following lines when next is the only release
@@ 36,7 +28,7 @@ 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}
Configuring \Dune and \Dumux is done by the commandline script \texttt{dunecontrol}
using optimized configure options, see the line entitled \texttt{\# run build} in the \texttt{installDumux.sh} script.
+using optimized configure options, see the line entitled \texttt{\# run build} in the \texttt{installDumux.sh} script.
More details about the buildsystem can be found in section \ref{buildIt}.
\subsection{A first test run of \Dumux}
@@ 51,4 +43,4 @@ make B test_1pcctpfa
paraview *pvd
\end{lstlisting}
The script \texttt{test\_dumux.sh} can be executed by typing into the terminal: \texttt{./test\_dumux.sh}.
If everything works fine, a paraviewwindow with the result should open automatically.
+If everything works fine, a paraview window with the result should open automatically.
diff git a/doc/handbook/3_course.tex b/doc/handbook/3_course.tex
new file mode 100644
index 0000000000000000000000000000000000000000..6624f677239e5d3c673a711c39ee6f8324378078
 /dev/null
+++ b/doc/handbook/3_course.tex
@@ 0,0 +1,42 @@
+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.
+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:
+\url{https://listserv.unistuttgart.de/mailman/listinfo/dumux}. \par
+%
+\textit{``But the course won't take place for another 6 months!"} and,
+\textit{``I want to start developing a numerical model of my challenging and
+ interesting process now!"}, you think.
+Not a problem. The course materials are all shared online in their own
+git repository. A series of beginnerlevel exercises are explained
+such that you can see how a model is developed in \Dumux. As a teaser, we've
+ also included a suite of examples from hot topics we're working on. Models
+ exploring ``Coupling free flow and porousmedia flow", ``Flow in fractured
+ porous media" and ``Fluidsolid phase change" are all introduced. \par
+ %
+\textit{``Sounds great, but where is this material? I can't find it within
+what I've downloaded."}, you question.
+The \Dumux course material is available online:
+\url{https://git.iws.unistuttgart.de/dumuxrepositories/dumuxcourse}. \par
+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.unistuttgart.de/dumuxrepositories/dumuxcourse/raw/releases/3.0/scripts/install.sh
+\end{lstlisting}
+This script will install \texttt{dumux}, it's Dune dependencies, and the \texttt{dumuxcourse}
+repository. Within the directory \texttt{dumuxcourse} 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 \texttt{dumux} and \texttt{dumuxcourse} module.
diff git a/doc/handbook/3_tutorial.tex b/doc/handbook/3_tutorial.tex
deleted file mode 100644
index b31d3a39f357a5c524e26bd7c60d6b387a52cd49..0000000000000000000000000000000000000000
 a/doc/handbook/3_tutorial.tex
+++ /dev/null
@@ 1,2 +0,0 @@
The tutorial provides instructions ranging from how to set boundary conditions in \Dumux to how to set up your own \Dumux module.
Go to the directory \texttt{tutorial} in the \texttt{dumux} module and read the \texttt{README.md} (best to be opened in a web browser) for instructions on the tutorial.
diff git a/doc/handbook/4_developingdumux.tex b/doc/handbook/4_developingdumux.tex
index e5c02ee1cbc6174a20b4d876f7b8d02aed99365b..c6ee4c559b5f9d83b3dac188f082f0ca936827a9 100644
 a/doc/handbook/4_developingdumux.tex
+++ b/doc/handbook/4_developingdumux.tex
@@ 25,6 +25,13 @@ You can subscribe to the mailing list via
\url{https://listserv.unistuttgart.de/mailman/listinfo/dumux}, then you
will be informed about upcoming releases or events.
+\subsection{Coding Guidelines}
+Writing code in a readable manner is very important, especially
+for future code developers (e.g. for adding features, debugging, etc.).
+For the style guide and instructions how to contribute to \Dumux visit
+\url{https://git.iws.unistuttgart.de/dumuxrepositories/dumux/blob/master/CONTRIBUTING.md}.
+
+
\subsection{Tips and Tricks}
\Dumux users and developers at the LH2 are also referred to the internal Wiki for
more information.
@@ 34,7 +41,7 @@ more information.
The options needed to be specified for that are provided using option files like
\texttt{debug.opts} and \texttt{optim.opts}. These two compile \Dune and \Dumux
either for debugging or for fast simulation. Programs compiled with optimization options
can lead to a speedup of factor up to ten!\\
+can lead to a speedup of factor up to ten!\par
In contrast programs that are compiled with optimization can hardly be debugged.
You can modify the files and change the compiler, the name of the build director,
add thirdparty dependencies, add additional compiler flags, ... .
@@ 64,7 +71,10 @@ To apply a patch in the same directory type:
\begin{lstlisting}[style=Bash]
$ patch p1 < PATCHFILE
\end{lstlisting}
See \ref{sc:patchingDUNE} if you need to apply patches to \Dumux or \Dune.
+
+%TODO: currently, no DUNE patches necessary! Thus, this section is commented and the missing refrence would be bad.
+% Uncomment the following statement again when patches might be necessary.
+% 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
@@ 98,9 +108,3 @@ To check one header file for all necessary includes to compile the contained cod
Include the option \texttt{DENABLE\_HEADERCHECK=1} in your opts file and run \texttt{dunecontrol}.
Then go to the top level in your builddirectory and type \texttt{make headercheck} to check all headers
or press 'tab' to use the autocompletion to search for a specific header.

\paragraph{Naming conventions}
General guidelines for naming conventions are specified in Section \ref{sc_guidelines}.
However, in order to avoid ambiguity a list of proposed names for variables, types,
functions etc is provided where users and mainly \Dumux developers can refer for
standards (check \texttt{dumuxdevel/\allowbreak doc/\allowbreak naminglist/\allowbreak namingconventions.odt}).
diff git a/doc/handbook/4_externaltools.tex b/doc/handbook/4_externaltools.tex
index 875b70559bea1eb67e4837c45f16cb1af699a5e5..8085a37e0d190cf7d48d64f69a350ff104b76153 100644
 a/doc/handbook/4_externaltools.tex
+++ b/doc/handbook/4_externaltools.tex
@@ 30,9 +30,42 @@ The basic Git commands are:
\subsection{Gnuplot}
+\label{gnuplot}
A gnuplot interface is available to plot or visualize results during a simulation run.
This is achieved with the help of the class provided in \texttt{io/gnuplotinterface.hh}.
Have a look at tests including this header for examples how to use this interface.
+
+To use the gnuplot interface you have to make some modifications in your file, e.g., your main file.
+
+First, you have to include the corresponding header file for the gnuplot interface.
+\begin{lstlisting}[style=DumuxCode]
+#include gnuplot;
+\end{lstlisting}
+
+As an example, to plot the mole fraction of nitrogen (\texttt{y}) over time (\texttt{x}),
+extract the variables after each time step in the time loop.
+The actual plotting is done using the method of the gnuplot interface:
+
+\begin{lstlisting}[style=DumuxCode]
+gnuplot.resetPlot(); // reset the plot
+gnuplot.setXRange(0.0, 72000.0); // specify xmin and xmax
+gnuplot.setYRange(0.0, 1.0); // specify ymin and ymax
+gnuplot.setXlabel("time [s]"); // set xlabel
+gnuplot.setYlabel("mole fraction mol/mol"); // set ylabel
+
+// set xvalues, yvalues, the name of the data file and the Gnuplot options
+gnuplot.addDataSetToPlot(x, y, "N2.dat", options);
+
+gnuplot.plot("mole_fraction_N2"); // set the name of the output file
+\end{lstlisting}
+
+It is also possible to add several data sets to one plot by calling \texttt{addDataSetToPlot()} more than once.
+For more information have a look into a test including the gnuplot interface header file or
+the header file itself (\texttt{dumux/io/gnuplotinterface.hh}).
\subsection{Gstat}
diff git a/doc/handbook/4_guidelines.tex b/doc/handbook/4_guidelines.tex
deleted file mode 100644
index a815a27197c9c883826c1b7460c2b729db45d3b0..0000000000000000000000000000000000000000
 a/doc/handbook/4_guidelines.tex
+++ /dev/null
@@ 1,6 +0,0 @@
\section{Coding Guidelines}
\label{sc_guidelines}
Writing code in a readable manner is very important, especially
for future code developers (e.g. for adding features, debugging, etc.).
For the style guide and instructions how to contribute to \Dumux visit
\url{https://git.iws.unistuttgart.de/dumuxrepositories/dumux/blob/master/CONTRIBUTING.md}.
diff git a/doc/handbook/4_newfoldersetup.tex b/doc/handbook/4_newfoldersetup.tex
index c1700cd9a09937afa0048f9c1de08b201208c2bb..9490c9ef2a01bf5eb37c7d882c67927a5a5f2654 100644
 a/doc/handbook/4_newfoldersetup.tex
+++ b/doc/handbook/4_newfoldersetup.tex
@@ 13,12 +13,15 @@ the build system there is a new one.
\end{enumerate}
\paragraph{Adding new Test Programs}
\noindent To add a test use the \texttt{add\_dumux\_test} macro.
The command has four arguments:
\begin{enumerate}[1)]
 \item name of test (has to be unique)
 \item name of executable
 \item source file (*.cc)
 \item command to be executed as test  either the executable or a
 some helper script with arguments
\end{enumerate}
+\noindent To add a test use the \texttt{add\_dune\_test} macro within the \texttt{CMakeList.txt} file.
+The macro can be used with a variable amount of arguments. A simple call could look like this:
+
+\begin{lstlisting}[style=DumuxCode]
+dune_add_test(NAME my_test
+ SOURCES mainfile.cc
+ CMD_ARGS my_test params.input)
+\end{lstlisting}
+
+Here, we create an executable called \texttt{my\_test} from a source file \texttt{mainfile.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 executbable \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.duneproject.org/sphinx/core2.5/}.
diff git a/doc/handbook/4_parameterfiles.tex b/doc/handbook/4_parameterfiles.tex
index df325e477a878c6592c4cfdfd58dcdacdd9bb5eb..7bddd051edf5d17921a91bba13819a3705279312 100644
 a/doc/handbook/4_parameterfiles.tex
+++ b/doc/handbook/4_parameterfiles.tex
@@ 5,9 +5,7 @@ A list of all available parameters is provided in the Doxygen documentation: \te
After having run the example application from section \ref{quickstartguide} you will
get the following output at the end of the simulation run
\footnote{If you did not get the output, restart the application the following way:
\texttt{./test{\_}2p{\_}incompressible{\_}tpfa test{\_}2p.input PrintParameters true},
this will print the parameters once your simulation is finished}:
+\footnote{If you did not get the output, add \texttt{Parameters::print();} to your main file.}:
\begin{lstlisting}[style=Bash]
# Runtimespecified parameters used:
[ Grid ]
@@ 24,8 +22,9 @@ DtInitial = "250"
TEnd = "3000"
# Default parameters used:
[ Implicit ]
+[ Assembly ]
NumericDifferenceMethod = "1"
+[ Flux ]
UpwindWeight = "1.0"
[ LinearSolver ]
MaxIterations = "250"
@@ 64,20 +63,33 @@ A number of things can be learned:
\subsection{Parameter Values}
If you want to get the value of a parameter please use:
+To get the value of an input parameter please use:
\begin{lstlisting}[name=propsyscars,style=DumuxCode]
paramname_ = getParam("GROUPNAME.PARAMNAME");
+static const TYPE paramname = getParam("GROUPNAME.PARAMNAME");
\end{lstlisting}
If you also want to set a default value for a parameter, just add it like this:
\begin{lstlisting}[name=propsyscars,style=DumuxCode]
paramname_ = getParam("GROUPNAME.PARAMNAME", default);
+static const TYPE paramname = getParam("GROUPNAME.PARAMNAME", default);
\end{lstlisting}
For further information you can also look at the \Dumux tutorial, especially exercise 1.
+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:
All applications have a help message which you can read by giving
\texttt{help} as a command line argument to the application.
For further details, please have a look at \texttt{Dune::ParameterTree}
in the \Dune documentation.
+\begin{lstlisting}[name=propsyscars,style=DumuxCode]
+auto modelParamGroup0 = "Model0";
+static const TYPE paramname0 = getParamFromGroup(modelParamGroup0, "GROUPNAME.PARAMNAME");
+auto modelParamGroup1 = "Model1";
+static const TYPE paramname1 = getParamFromGroup(modelParamGroup1, "GROUPNAME.PARAMNAME");
+\end{lstlisting}
+
+The \texttt{FVProblem} class provides a convenience function \texttt{paramGroup()}.
+
+The parameters can then be specified in the input file:
+
+\begin{lstlisting}[style=Bash]
+[ Model0.Grid ]
+File = file0.dgf
+[ Model1.Grid ]
+File = file1.dgf
+\end{lstlisting}
diff git a/doc/handbook/4_restartsimulations.tex b/doc/handbook/4_restartsimulations.tex
index 30ce43199130c08f732e92fc3fff16ff43d8272e..fbd12fe9f9804268b218c330928e3aa5fa66c66a 100644
 a/doc/handbook/4_restartsimulations.tex
+++ b/doc/handbook/4_restartsimulations.tex
@@ 1,26 +1,19 @@
\section{Restart \Dumux Simulations}
\label{sc_restartsimulations}
Restart is currently not available in the \DumuxVersion~release. We are working on it!
% You can restart the simulation
% from a specific point in time or extend the simulation beyond the originally
% end of simulation. What you need is a \texttt{*.drs} file (which contains the
% all necessary restart information.
% Then you can simply restart a simulation via
% \begin{lstlisting}[style=Bash]
% ./test_program TimeManager.Restart RESTART_TIME
% \end{lstlisting}
% To test restart behavior, use the \texttt{test\_box1p2cni} problem
% in the \texttt{test/implicit/1p2c} folder.
% You get the \texttt{RESTART\_TIME} from the name of your \texttt{.drs} file.
% Restarting will only work when the exact time from an existing restart file is given.
% If you need more restart files, you can change the frequency
% by including the function into your problem:
% \begin{lstlisting}[style=DumuxCode]
% // Writes a restart file every 5th time step
% bool shouldWriteRestartFile() const
% {
% return (this>timeManager().timeStepIndex() % 5 == 0);
% }
% \end{lstlisting}
+\Dumux has some experimental support for checkpointing (restarting paused/stopped/crashed simulations).
+You can restart a \Dumux simulation from any time point where a VTK file was written out.
+This is currently only supported for sequential, nonadaptive simulations. For adaptive simulation
+the full hierarchical grid has to be stored. This is usually done with the grid's \texttt{BackupRestoreFacility}.
+There is currently no special support by \Dumux for that, but it is possible to implement
+a restart using \texttt{BackupRestoreFacility} with plain Dune.
+For VTK files the output can be read with the free function \texttt{loadSolution}. Grids can be read with
+the \texttt{Dumux::VTKReader} or you can simply recreate the grid as you did in the first simulation run.
+
+Unfortunately, writing doubleprecision floating point numbers to VTK files is only available with Dune master (will be in 2.7).
+That's why we currently only support single precision restart, meaning some information will be lost if you are computing
+in double precision.
+
+The restart capabilities will hopefully be improved in future versions of \Dumux 3.
+We are happy about any contributions (especially HDF5 / XDMF support, improvement of VTK support).
diff git a/doc/handbook/4_structure.tex b/doc/handbook/4_structure.tex
index 649eb2f79a08ee53ce60c43b7fa35f94d90c6dcc..0c1dfbf496f70e3371377bbca87afd2a250113e6 100644
 a/doc/handbook/4_structure.tex
+++ b/doc/handbook/4_structure.tex
@@ 15,7 +15,6 @@
\texttt{*.cc}, the problem definition \texttt{*problem.hh}, and an input file \texttt{*.input}.
If necessary, spatially dependent parameters are defined in \texttt{*spatialparameters.hh}.
For more detailed descriptions of the tests, please have a look at the Doxygen documentation.
\item \texttt{tutorial}: contains the tutorials.
\end{itemize}
\begin{figure}
@@ 71,20 +70,16 @@
[.\node[SecondLevel] {properties};
\node[ThirdLevel] {Base properties for all models.};
]
+ [.\node[SecondLevel] {typetraits};
+ \node[ThirdLevel] {Helper classes to query type information on compiletime. };
+ ]
]
[.\node[FirstLevel] {discretization};
% [.\node[SecondLevel] {\emph{models}};
 \node[ThirdLevel] {Common methods for all discretizations: variable caching, advective and diffusive fluxes, upwinding...};
% ]
 [.\node[SecondLevel] {box};
 \node[ThirdLevel] {Specific files for the box finite volume method:
 specifications for advective and diffusive fluxes...};
 ]
 [.\node[SecondLevel] {cellcentered};
 \node[ThirdLevel] {Specific files for cell centered finite volume methods.};
 ]
 [.\node[SecondLevel] {staggered};
 \node[ThirdLevel] {Specific files for staggered finite volume method.};
+ \node[ThirdLevel] {Common methods for all discretizations (box, cellcentered TPFA/MPFA, staggered grid): variable caching, advective and diffusive fluxes, ...};
+ ]
+ [.\node[FirstLevel] {flux};
+ [\node[ThirdLevel] {
+ Collection of classes used to calculate advective and diffusive fluxes.};
]
]
[.\node[FirstLevel] {freeflow};
@@ 93,6 +88,11 @@
and eddyviscosity based Reynoldsaveraged NavierStokes turbulence models.};
]
]
+ [.\node[FirstLevel] {geomechanics};
+ [.\node[SecondLevel] {\emph{models}};
+ \node[ThirdLevel] {Elastic and poroelastic geomechanics models.};
+ ]
+ ]
[.\node[FirstLevel] {io};
\node[ThirdLevel] {Additional in/output possibilities like restart files, gnuplotinterface,
VTKWriter extensions and files for grid generation.};
@@ 126,28 +126,35 @@
]
[.\node[SecondLevel] {fluidstates};
\node[ThirdLevel] {Fluid states are responsible for caching the thermodynamic
 configuration of a system at a given spatial and temporal position.};
+ configuration of a fluid system at a given spatial and temporal position.};
]
[.\node[SecondLevel] {fluidsystems};
\node[ThirdLevel] {Fluid systems express the thermodynamic relations between quantities.};
]
+ [.\node[SecondLevel] {solidstates};
+ \node[ThirdLevel] {Solid states are responsible for caching the thermodynamic
+ configuration of a solid system at a given spatial and temporal position.};
+ ]
+ [.\node[SecondLevel] {solidsystems};
+ \node[ThirdLevel] {Solid systems express the thermodynamic properties of a solid.};
+ ]
[.\node[SecondLevel] {spatialparams};
\node[ThirdLevel] {Base class for all spatially dependent variables, like permeability and
porosity. Includes spatial averaging routines. All other properties are
specified in the specific files of the respective models.};
]
]
 [.\node[FirstLevel] {mixeddimension};
+ [.\node[FirstLevel] {multidomain};
\node[ThirdLevel] {
 Coupled model with different dimensions.};
+ Common infrastructure to couple multiple domains, models or physics.};
[.\node[SecondLevel] {embedded};
 \node[ThirdLevel] {Embedded mixed dimension method.};
+ \node[ThirdLevel] {Embedding of a lowerdimensional model into a higherdimensional one};
]
[.\node[SecondLevel] {facet};
 \node[ThirdLevel] {Facet mixed dimension method.};
+ \node[ThirdLevel] {Mixeddimensional coupling at facets.};
]
 [.\node[SecondLevel] {glue};
 \node[ThirdLevel] {Grid glue backend.};
+ [.\node[SecondLevel] {boundary};
+ \node[ThirdLevel] {Coupling at the domain boundaries.};
]
]
[.\node[FirstLevel] {nonlinear};
diff git a/doc/handbook/5_grids.tex b/doc/handbook/5_grids.tex
deleted file mode 100644
index aaad10db862fd27761bcd521b3b5fbfdd3ee025b..0000000000000000000000000000000000000000
 a/doc/handbook/5_grids.tex
+++ /dev/null
@@ 1,137 +0,0 @@
\section{Grid Handling}
\label{sec:gridhandling}

This section summarizes some ideas about grid generation and grid formats that can be used by \Dumux. In general,
\Dumux can read grids from file, or, construct grids inside the code. All grids are constructed inside a so called \texttt{GridCreator} which is a \Dumux property.
Note that some \texttt{GridCreator}s are already available in \Dumux, so e.g.
construction of a structured grid is fairly easy. We will subsequently introduce the supported file formats, the standard grid creator and its capabilities,
and briefly mention how to customize and deal with common other grid formats.

\subsection{Supported file formats}
\Dumux can read grids from file using the Dune Grid Format (DGF) or the Gmsh mesh format.

\subsubsection{Dune Grid Format}
Most of our \Dumux tests and tutorials use the Dune Grid Format (DGF) to read in grids. A detailed description
of the DGF format and some examples can be found in the \Dune doxygen documentation
\textbf{(Modules $\rightarrow$ I/O $\rightarrow$ Dune Grid Format (DGF)}). To generate larger or more
complex DGF files, we recommend to write your own scripts, e.g in \Cplusplus, Matlab or Python.

The DGF format can also used to read in spatial parameters defined on the grid. These parameters can
be defined on nodes as well as on the elements. An example for predefined parameters on a grid
can be found in the \texttt{dumux/test/porousmediumflow/co2/implicit/} folder.

\subsubsection{Gmsh Mesh Format}
Gmsh is an opensource flexible grid generator for unstructured finiteelement meshes (\cite{GEUZAINE2009}, \url{http://geuz.org/gmsh/}).
\Dumux supports the default Gmsh mesh format (MSH). For the format specifics and how to create grids with Gmsh, e.g. using
the provided GUI, we refer to the Gmsh documentation (\url{http://geuz.org/gmsh/doc/texinfo/gmsh.html}).

The MSH format can contain element and boundary markers defined in the grid. Thus, boundaries can be easily marked as e.g. inflow boundaries
using Gmsh. Further, the format supports higher order elements. They can be used to create boundary parameterization supported by e.g. the grid
manager \texttt{UGGrid}.
An example can be found in \texttt{dumux/test\allowbreak/io/gridcreator}.



\subsection{The default \texttt{GridCreator}}
The default \texttt{GridCreator} is called \texttt{GridCreator} and is automatically avaible in all problems.
It can construct grids from a DGF file (*.dgf) 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:
\begin{lstlisting}[style=DumuxParameterFile]
[Grid]
File = mydgfgrid.dgf
\end{lstlisting}
If you are using an unstructured grid manager like \texttt{UGGrid} or \texttt{ALUGrid}, constructing a grid from a Gmsh mesh file (*.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 Gmsh files. You want to intially refine your grid? It's just adding a line:
\begin{lstlisting}[style=DumuxParameterFile]
[Grid]
File = mydgfgrid.dgf
Refinement = 4
\end{lstlisting}
When reading a Gmsh file, further parameters are recognized. \texttt{Verbose} enables verbose output on grid construction when set to $1$.
\texttt{BoundarySegments} enables reading parametrized boundaries. \texttt{PhysicalEntities} enables reading boundary and element flags.

\subsubsection{Grid manager specific parameters}
The default \texttt{GridCreator} supports also a selection of grid specific parameters.
To give an example we look at the commonly used unstructured grid manager \texttt{UGGrid}.
\texttt{UGGrid}s support redgreen refinement per default. One can turn off the green closure by setting the grid's closure type
\begin{lstlisting}[style=DumuxParameterFile]
[Grid]
File = mydgfgrid.dgf
ClosureType = None # or Green
\end{lstlisting}
For all available parameters see the Doxygen documentation.

\subsubsection{Structured grids}
If you want to construct a structured grid with the default grid creator instead of the \texttt{File} key supply
\begin{lstlisting}[style=DumuxParameterFile]
[Grid]
LowerLeft = 0 0 0
UpperRight = 1 1 1
Cells = 10 10 20
\end{lstlisting}
where \texttt{LowerLeft} is a vector to the lower left corner of the grid and \texttt{UpperRight} a vector to the upper right corner.
\texttt{Cells} is a vector with the number of cells in each coordinate direction. Note that for a grid in a twodimensional world, the
vectors only have two entries.

Depending on the grid manager further parameters are recognized.
\texttt{UGGrid}s, for example, supports simplex elements as well as hexahedral elements
(called simplified ``cube'' in \Dune). When creating a structured grid, we can select the cell type as follows
\begin{lstlisting}[style=DumuxParameterFile]
[Grid]
LowerLeft = 0 0 0
UpperRight = 1 1 1
Cells = 10 10 20
CellType = Cube # or Simplex
\end{lstlisting}
For all available parameters see the Doxygen documentation.

\subsection{Other grid formats and customized grid creators}
Other grid formats than DGF and MSH have to be converted to DGF or MSH to be read into \Dumux. A second possiblity (advanced \Cplusplus) is to write your own
\texttt{GridCreator}.
A (noncomprehensive) list of hints for some other common grid formats follows.

\subsubsection{Petrel}
Grids from Petrel (in ASCII format with the extension *.GRDECL) can be imported into \Dumux in two ways:
 \begin{enumerate}
 \item Using the GRDECL format directly with the help of the gridmanager \texttt{dunecornerpoint}.
 \item Converting the GRDECL file into the DGF format.
 \end{enumerate}
The fist options requires the installation of \texttt{dunecornerpoint} along with its dependencies. Set the property \texttt{Grid} to \texttt{Dune::CpGrid} in your problem file.

The second option has the advantage that you end up with a DGF which can then be used with any gridmanager (\texttt{dunealugrid}, \texttt{UG} etc.) You also have to install \texttt{dunecornerpoint}. Additionally you have to modify the converter \texttt{grdecl2vtu} found in \texttt{dunecornerpoint/examples} to also write a DGF. To do so you have to:
\begin{itemize}
 \item Include the \texttt{dgfwriter.hh} found in \texttt{dunegrid/dune/grid/io/file/dgfparser}
 \item Create an object of the \texttt{Dune::DGFWriter} and call the its function \texttt{write()} within the \texttt{main} function for example after the \texttt{vtkwriter()} is called:
\begin{lstlisting}[style=DumuxCode]
Dune::DGFWriterParam dgfWriter(grid.leafView()))
dgfWriter.write(fnamebase + ".dgf")
\end{lstlisting}
\end{itemize}
Material parameters for elements with Petrel specific keywords like \texttt{PORO} are parsed by the converter \texttt{grdecl2vtu} (see the \texttt{main} function). They are available as vectors within the \texttt{main} function. The main GRDECL file with the coordinates must include the GRDECL files of the parameters, if for example the parameters are not already included, include the file bearing your parameter in your main GRDECL file:
\begin{lstlisting}
INCLUDE
'PARAMETER_X.GRDECL'
/
\end{lstlisting}
To add the parameters to your DGF you have to make changes to the header \texttt{dgfwriter.hh} such that they are passed as arguments of the \texttt{write()} function and written after each element (modify \texttt{writeElement()} and internal \texttt{write()} functions accordingly). Take caution that you stick to the correct DGF syntax (see \textbf{Modules $\rightarrow$ I/O $\rightarrow$ Dune Grid Format (DGF)} for reference).

\subsubsection{ArtMesh}
\href{http://www.topologica.org/toplog/wp/}{ArtMesh} is a 3D mesh generation software. It has its own mesh file format
which can be read by \Dumux via the \texttt{ArtGridCreator}. Traditionally it was used within \Dumux for fracture simulations with
the discrete fracture matrix model (\texttt{2pdfm}). A detailed description of the fracture network creation and gridding
can be found for example in \cite{Tatomir2012a}, pp. 68.

\subsubsection{ICEM}
For complex geometries a graphical tool to create grids might be appropriate. One possibility to mesh for example CAD
geometry data is the commercial software \href{http://www.ansys.com/Products/Other+Products/ANSYS+ICEM+CFD/}{ANSYS ICEM
CFD}. A very detailed, but outdated description can be found at the LH2 internal wiki. A more recent best practice guide is available
in dumuxdevel at dumuxdevel/util/gridconverters/Documentation\_ICEM\_CFD\_create\_mesh.odt. At LH2 exists a script which converts the ICEM mesh into the DGF.

% \subsubsection{Cornerpoint grids}
% TODO
diff git a/doc/handbook/5_inputoutput.tex b/doc/handbook/5_inputoutput.tex
new file mode 100644
index 0000000000000000000000000000000000000000..8cfc5c6f2dae93b82dd33d8bba9c7cbf491c7499
 /dev/null
+++ b/doc/handbook/5_inputoutput.tex
@@ 0,0 +1,149 @@
+\section{Input and Output}
+\label{sec:inputandoutput}
+
+This section briefly explains grid generation in \Dumux, summarizes
+the grid formats that can be used by \Dumux and introduces the \Dumux \texttt{GridManager}.
+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) or the Gmsh mesh format (MSH).
+Using the class \texttt{Dumux::VTKReader}, \Dumux has experimental support for reading grids and data from VTK files.
+
+\subsubsection{Dune Grid Format}
+Most of our \Dumux tests use the Dune Grid Format (DGF) to read in grids. A detailed description
+of the DGF format and some examples can be found in the \Dune doxygen documentation
+\textbf{(Modules $\rightarrow$ I/O $\rightarrow$ Dune Grid Format (DGF)}). To generate larger or more
+complex DGF files, we recommend to write your own scripts, e.g, in \Cplusplus, Matlab or Python.
+
+The DGF format can also be used to read in spatial parameters defined on the grid. These parameters can
+be defined on nodes as well as on the elements. An example for predefined parameters on a grid
+can be found in \texttt{dumux/test/porousmediumflow/co2/implicit/}.
+
+\subsubsection{Gmsh Mesh Format}
+Gmsh is an opensource flexible grid generator for unstructured finiteelement meshes (\cite{GEUZAINE2009}, \url{http://geuz.org/gmsh/}).
+\Dumux supports the default Gmsh mesh format (MSH). For the format specifics and how to create grids with Gmsh, e.g., using
+the provided GUI, we refer to the Gmsh documentation (\url{http://geuz.org/gmsh/doc/texinfo/gmsh.html}).
+
+The MSH format can contain element and boundary markers defined on the grid. Thus, boundaries can be easily marked as, e.g., inflow boundaries
+using Gmsh. Further, the format supports higher order elements. They can be used to create boundary parameterization supported by, e.g., the grid
+manager \texttt{UGGrid}.
+An example can be found in \texttt{dumux/test\allowbreak/io/gridmanager}.
+
+\subsubsection{Other Grid Formats}
+Grid formats other than DGF, MSH, VTK will have to be converted to the DGF, MSH, 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}. Examples of other grid formats,
+which have previously been either converted or customcreated in \Dumux, are Petrel grids (cornerpoint grids),
+ArtMesh grids (fractured network grids), and ICEM grids (CAD developed grids).
+
+\subsection{The \Dumux \texttt{GridManager}}
+The \Dumux \texttt{GridManager} constructs the grid from information in the input file and handles the data.
+Currently, supported grid managers are \texttt{YaspGrid}, \texttt{OneDGrid}, \texttt{duneuggrid}, \texttt{dunealugrid}, \texttt{dunefoamgrid}, \texttt{dunesubgrid}, \texttt{opmgrid} (cornerpoint grids) and \texttt{dunespgrid}.
+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,
+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:
+\begin{lstlisting}[style=DumuxParameterFile]
+[Grid]
+File = mydgfgrid.dgf
+\end{lstlisting}
+
+If you are using an unstructured grid manager like \texttt{UGGrid} or \texttt{ALUGrid}, constructing a grid from a 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.
+
+You want to intially refine your grid? It's just adding a line:
+\begin{lstlisting}[style=DumuxParameterFile]
+[Grid]
+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$.
+\texttt{BoundarySegments} enables reading parameterized boundaries. \texttt{PhysicalEntities} enables reading boundary and element flags.
+
+\subsubsection{Parameters specific to the grid manager}
+The \Dumux \texttt{GridManager} supports also a selection of parameters that are specific to the chosen grid manager.
+To give an example, we take a look at the unstructured grid manager \texttt{UGGrid}.
+\texttt{UGGrid} supports redgreen refinement per default. One can turn off the green closure by setting the grid's closure type
+\begin{lstlisting}[style=DumuxParameterFile]
+[Grid]
+File = mydgfgrid.dgf
+ClosureType = None # or Green
+\end{lstlisting}
+
+For all available parameters see the Doxygen documentation.
+
+\subsubsection{Structured grids}
+If you want to construct a structured grid without using a specific grid file, insert the following into the input file:
+\begin{lstlisting}[style=DumuxParameterFile]
+[Grid]
+LowerLeft = 0 0 0
+UpperRight = 1 1 1
+Cells = 10 10 20
+\end{lstlisting}
+where \texttt{LowerLeft} is a vector to the lower left corner of the grid and \texttt{UpperRight} a vector to the upper right corner.
+\texttt{Cells} is a vector with the number of cells in each coordinate direction. Note, that for a grid in a twodimensional world, the
+vectors only have two entries.
+
+Depending on the grid manager, further parameters are recognized.
+\texttt{UGGrid}, for example, supports simplex elements as well as hexahedral elements
+(called ``cube'' in \Dune). When creating a structured grid, we can select the cell type as follows
+\begin{lstlisting}[style=DumuxParameterFile]
+[Grid]
+LowerLeft = 0 0 0
+UpperRight = 1 1 1
+Cells = 10 10 20
+CellType = Cube # or Simplex
+\end{lstlisting}
+
+For all available parameters see the Doxygen documentation.
+
+\subsection{Input and Output formats}
+
+\subsubsection{VTK file format}
+Dumux allows to write out simulation results via the \texttt{VtkOutputModule}.
+For every printout step, a single \texttt{*.vtu} file is created. For parallel simulations one file
+per printout step is generated for each processor.
+The \texttt{*.pvd} file groups the single \texttt{*.vtu} files and contains additionally the time step information.
+The VTK file format is supported by common visualisation programs like ParaView, VisIt, and Tecplot.
+
+\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,
+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");
+\end{lstlisting}
+
+The first input argument of this method is the value of the additional variable, provided by a method of the corresponding problem.
+If it does not already exists, the user has to provide this method.
+\begin{lstlisting}[style=DumuxCode]
+//! get the analytical temperature
+const std::vector& getExactTemperature()
+{
+ return temperatureExact_;
+}
+\end{lstlisting}
+It is important that the lifetime of the added field exceeds the lifetime of the writer. That means you can't pass temporaries
+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}
+
+\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.
+
+\subsubsection{Gnuplot interface}
+\Dumux provides a small interface to GNUPlot, which can be used to plot results and generate
+image files (e.g., png). To use the gnuplot, gnuplot has to be installed. For more information see \ref{gnuplot}.
+
+\subsubsection{Container I/O}
+\Dumux supports writing to file from and reading to some standard \Cplusplus containers like \texttt{std::vector} or \texttt{std::vector}.
+If you want to read and write simple vectors, have a look at the header \texttt{dumux/io/container.hh}.
+
+\subsubsection{Matrix and Vector I/O}
+\texttt{duneistl} supports writing and reading vectors and matrices to/from different format. For example you can write a matrix in a sparse matrix format that
+can be read by Matlab (see \texttt{dune/istl/io.hh}).
diff git a/doc/handbook/5_models.tex b/doc/handbook/5_models.tex
index 17d6deb998d5ba9545ec897468928c13c819bcb9..6fc5e5319374193c59173003d57a21056bcbfd78 100644
 a/doc/handbook/5_models.tex
+++ b/doc/handbook/5_models.tex
@@ 1,6 +1,8 @@
\section{Models}
Here the basic definitions, the general models concept, and a list of
models available in \Dumux are given.
+models available in \Dumux are given. The actual differential equations
+can be found in the localresiduals (see doxygen documentation of the
+model's \texttt{LocalResidual} class).
\subsection{Basic Definitions and Assumptions}
The basic definitions and assumptions are made, using the example
@@ 134,11 +136,11 @@ Dalton's law assumes that the gases in the mixture are noninteracting (with eac
p = \sum_{i}^{}p_i.
\end{equation}
Here $p_i$ refers to the partial pressure of component i.
As an example, if two equal volumes of gas A and gas B are mixed, the volume of the mixture stays the same but the pressures add up (see Figure \ref{fig:dalton1}).
+As an example, if two equal volumes of gas A and gas B are mixed, the volume of the mixture stays the same but the pressures add up (see Figure \ref{fig:dalton1}).
%
\begin{figure}[ht]
\centering
 \includegraphics[width=0.7\textwidth]{PNG/dalton1.png}
+ \includegraphics[width=0.7\textwidth]{png/dalton1.png}
\caption{Dalton's law visualized}
\label{fig:dalton1}
\end{figure}
@@ 154,7 +156,7 @@ or for an arbitrary number of gases:
\end{equation}
%
\subsubsection{Amagat's law}
Amagat's law assumes that the volumes of the component gases are additive; the interactions of the different gases are the same as the average interactions of the components. This is known as Amagat's law:
+Amagat's law assumes that the volumes of the component gases are additive; the interactions of the different gases are the same as the average interactions of the components. This is known as Amagat's law:
%
\begin{equation}
V = \sum_{i}^{}V_i.
@@ 164,14 +166,14 @@ As an example, if two volumes of gas A and B at equal pressure are mixed, the pr
%
\begin{figure}[ht]
\centering
 \includegraphics[width=0.7\textwidth]{PNG/dalton2.png}
+ \includegraphics[width=0.7\textwidth]{png/dalton2.png}
\caption{Amagat's law visualized}
\label{fig:dalton2}
\end{figure}
%
The density of the mixture, $\varrho$, can be calculated as follows:
\begin{equation}
\varrho = \frac{m}{V} = \frac{m}{V_\mathrm{A} + V_\mathrm{B}} = \frac{m}{\frac{m_\mathrm{A}}{\varrho_\mathrm{A}} \frac{m_\mathrm{B}}{\varrho_\mathrm{B}}} =
+\varrho = \frac{m}{V} = \frac{m}{V_\mathrm{A} + V_\mathrm{B}} = \frac{m}{\frac{m_\mathrm{A}}{\varrho_\mathrm{A}} \frac{m_\mathrm{B}}{\varrho_\mathrm{B}}} =
\frac{m}{\frac{X_\mathrm{A} m}{\varrho_\mathrm{A}} \frac{X_\mathrm{B} m}{\varrho_\mathrm{B}}} = \frac{1}{\frac{X_\mathrm{A}}{\varrho_\mathrm{A}} \frac{X_\mathrm{B}}{\varrho_\mathrm{B}}},
\end{equation}
%
@@ 182,7 +184,7 @@ or for an arbitrary number of gases:
\end{equation}
%
\subsubsection{Ideal gases}
An ideal gas is defined as a gas whose molecules are spaced so far apart that the behavior of a molecule is not influenced by the presence of other molecules.
+An ideal gas is defined as a gas whose molecules are spaced so far apart that the behavior of a molecule is not influenced by the presence of other molecules.
This assumption is usually valid at low pressures and high temperatures. The ideal gas law states that, for one gas:
%
\begin{equation}
@@ 193,7 +195,7 @@ Using the assumption of ideal gases and either Dalton's law or Amagat's law lead
%
\begin{equation}
\varrho = \frac{p}{RT} \sum_{i}^{}M_i x_i ; \quad \varrho_m = \frac{p}{RT}.
\end{equation}
+\end{equation}
%
\subsection{Available Models}
A list of all available models can be found
@@ 201,10 +203,49 @@ in the Doxygen documentation at
\url{http://www.dumux.org/doxygenstable/html\DumuxVersion/modules.php}.
The documentation includes a detailed description for every model.
\subsubsection{Temporal discretization}
We discretize time with an explicit or implicit Euler
method.
% TODO: make section with more details on temporal discretization
+\subsubsection{Time discretization}
+
+Our systems of partial differential equations are discretized in space and in time.
+
+Let us consider the general case of a balance equation of the following form
+\begin{equation}\label{eq:generalbalance}
+\frac{\partial m(u)}{\partial t} + \nabla\cdot\mathbf{f}(u, \nabla u) + q(u) = 0,
+\end{equation}
+seeking an unknown quantity $u$ in terms of storage $m$, flux $\mathbf{f}$ and source $q$.
+All available Dumux models can be written mathematically in form of \eqref{eq:generalbalance}
+with possibly vectorvalued quantities $u$, $m$, $q$ and a tensorvalued flux $\mathbf{f}$.
+For the sake of simplicity, we assume scalar quantities $u$, $m$, $q$ and a vectorvalued
+flux $\mathbf{f}$ in the notation below.
+
+For discretizing \eqref{eq:generalbalance} we need to choose an
+approximation for the temporal derivative $\partial m(u)/\partial t$.
+While many elaborate methods for this approximation exist,
+we focus on the simplest one of a first order difference quotient
+\begin{equation}\label{eq:euler}
+\frac{\partial m(u_{k/k+1})}{\partial t}
+\approx \frac{m(u_{k+1})  m(u_k)}{\Delta t_{k+1}}
+\end{equation}
+for approximating the solution $u$ at time $t_k$ (forward) or $t_{k+1}$ (backward).
+The question of whether to choose the forward or the backward quotient leads to the
+explicit and implicit Euler method, respectively.
+In case of the former, inserting \eqref{eq:euler} in \eqref{eq:generalbalance}
+at time $t_k$ leads to
+\begin{equation}\label{eq:expliciteuler}
+\frac{m(u_{k+1})  m(u_k)}{\Delta t_{k+1}} + \nabla\cdot\mathbf{f}(u_k, \nabla u_k) + q(u_k) = 0,
+\end{equation}
+whereas the implicit Euler method is described as
+\begin{equation}\label{eq:impliciteuler}
+\frac{m(u_{k+1})  m(u_k)}{\Delta t_{k+1}}
++ \nabla\cdot\mathbf{f}(u_{k+1}, \nabla u_{k+1}) + q(u_{k+1}) = 0.
+\end{equation}
+Once the solution $u_k$ at time $t_k$ is known, it is straightforward
+to determine $m(u_{k+1})$ from \eqref{eq:expliciteuler},
+while attempting to do the same based on \eqref{eq:impliciteuler}
+involves the solution of a system of equations.
+On the other hand, the explicit method \eqref{eq:expliciteuler} is stable only
+if the time step size $\Delta t_{k+1}$ is below a certain limit that depends
+on the specific balance equation, whereas the implicit method \eqref{eq:impliciteuler}
+is unconditionally stable.
\subsubsection{Algorithms to solve equations}
The governing equations of each model can be solved monolithically or sequentially.
@@ 220,5 +261,5 @@ In comparison to solving the equations monolothically, the sequential structure
different discretization methods for the different equations. The standard method
used in the sequential algorithm is a cellcentered finite volume method. Further schemes,
so far only available for the twophase pressure equation, are cellcentered finite
volumes with multipoint flux approximation (MPFA Omethod) and mimetic finite differences.
+volumes with multipoint flux approximation (MpfaO method) and mimetic finite differences.
An $h$adaptive implementation of both sequential algorithms is provided for two dimensions.
diff git a/doc/handbook/5_parallel.tex b/doc/handbook/5_parallel.tex
new file mode 100644
index 0000000000000000000000000000000000000000..10fd57d646fb0124ea1174e5197250d13471903d
 /dev/null
+++ b/doc/handbook/5_parallel.tex
@@ 0,0 +1,70 @@
+\section{Parallel Computation}
+\label{sec:parallelcomputation}
+This section explains how \Dumux can be used
+on multicore / multinode systems.
+
+There are different concepts and methods for parallel programming, which are
+often grouped in \textit{sharedmemory} and \textit{distributedmemory}
+approaches. The parallelization in \Dumux is based on the model supported by Dune which is currently based on
+\textit{Message Passing Interface} (MPI) (distributedmemory approach).
+
+The main idea behind the MPI parallelization is the concept of \textit{domain
+decomposition}. For parallel simulations, the computational domain is split into
+subdomains and one process (\textit{rank}) is used to solve the local problem of each
+subdomain. During the global solution process, some data exchange between the
+ranks/subdomains is needed. MPI is used to send data to other ranks and to receive
+data from other ranks. The domain decomposition in Dune is handled by the grid managers.
+The grid is partitioned and distributed on several nodes. Most grid managers contain own domain decomposition methods to split the
+computational domain into subdomains. Some grid managers also support external
+tools like METIS, ParMETIS, PTScotch or ZOLTAN for partitioning.
+On the other hand linear algebra types such as matrices and vectors
+do not know that they are in a parallel environment. Communication is then handled by the components of the
+parallel solvers. Currently, the only parallel solver backend is \texttt{Dumux::AMGBackend}, a parallel AMGpreconditioned
+BiCGSTAB solver.
+
+In order for \Dumux simulation to run in parallel, an
+MPI library (e.g. OpenMPI, MPICH or IntelMPI) implementation
+must be installed on the system.
+
+\subsection{Prepare a Parallel Application}
+Not all parts of \Dumux can be used in parallel. In order to switch to the parallel \texttt{Dumux::AMGBackend}
+solver backend include the respective header
+
+\begin{lstlisting}[style=DumuxCode]
+#include
+\end{lstlisting}
+
+Second, the linear solver must be switched to the AMG backend
+
+\begin{lstlisting}[style=DumuxCode]
+using LinearSolver = Dumux::AMGBackend;
+\end{lstlisting}
+
+and the application must be recompiled. The parallel \texttt{Dumux::AMGBackend} instance has to be
+constructed with a \texttt{Dune::GridView} object and a mapper, in order to construct the
+parallel index set needed for communication.
+
+\begin{lstlisting}[style=DumuxCode]
+auto linearSolver = std::make_shared(leafGridView, fvGridGeometry>dofMapper());
+\end{lstlisting}
+
+\subsection{Run a Parallel Application}
+The starting procedure for parallel simulations depends on the chosen MPI library.
+Most MPI implementations use the \textbf{mpirun} command
+
+\begin{lstlisting}[style=Bash]
+mpirun np
+\end{lstlisting}
+
+where \textit{np} sets the number of cores (\texttt{n\_cores}) that should be used for the
+computation. On a cluster you usually have to use a queuing system (e.g. slurm) to
+submit a job. Check with your cluster administrator how to run parallel applications on the cluster.
+
+\subsection{Handling Parallel Results}
+For serial computations, \Dumux produces single vtufiles as default output format.
+During a simulation, one vtufile is written for every output step.
+In the parallel case, one vtufile for each step and processor is created.
+For parallel computations, an additional variable \texttt{"process rank"} is written
+into the file. The process rank allows the user to inspect the subdomains
+after the computation. The parallel vtufiles are combined in a single pvd file
+like in sequential simulations that can be opened with e.g. ParaView.
diff git a/doc/handbook/5_propertysystem.tex b/doc/handbook/5_propertysystem.tex
index e66b20aae04d9a004962bdee90234a1e4820235c..bfe58b3fa3f8779e8c38364541eae359ecbc152a 100644
 a/doc/handbook/5_propertysystem.tex
+++ b/doc/handbook/5_propertysystem.tex
@@ 4,28 +4,19 @@ A high level overview over the property system's design and principle ideas
are given, then follows a reference and a selfcontained example.
\subsection{Motivation and features}
The \Dumux property system was designed as an attempt to mitigate the
problems of traits classes. It can be seen as a traits system
which allows easy inheritance and any acyclic dependency of parameter
definitions. Just like traits, the \Dumux property system is a compile
time mechanism, thus there is no runtime performance penalty associated
with it.
+The \Dumux property system is a traits system
+which allows easy inheritance.
In the context of the \Dumux property system, a property is an arbitrary
class body which may contain type definitions, values and methods. Each
property has a socalled \emph{property tag} which labels its name.
+class body which may contain type definitions, values and methods.
Just like normal classes, properties can be arranged in hierarchies. In
the context of the \Dumux property system, nodes of the inheritance
hierarchy are called \emph{type tags}.
It also supports \emph{property nesting} and
\emph{introspection}. Property nesting means that the definition of
+It also supports \emph{property nesting}. Property nesting means that the definition of
a property can depend on the value of other properties which may be
defined for arbitrary levels of the inheritance hierarchy. The term
introspection denotes the ability to generate diagnostic messages
which can be used to find out where a certain property was defined and
how it was inherited.
+defined for arbitrary levels of the inheritance hierarchy.
\subsection{Howto}
All source files which use the property system should include
@@ 35,64 +26,85 @@ property tags as well as defining properties must be done inside the
namespace \texttt{Dumux::Properties}.
\subsubsection{Defining Type Tags}
New nodes in the type tag hierarchy can be defined using
+New nodes in the type tag hierarchy can be defined in the \texttt{TTag} namespace using
\begin{lstlisting}[style=DumuxCode]
NEW_TYPE_TAG(NewTypeTagName, INHERITS_FROM(BaseTagName1, BaseTagName2, ...));
+// Create new type tags
+namespace TTag {
+struct NewTypeTagName { using InheritsFrom = std::tuple; };
+} // end namespace TTag
\end{lstlisting}
where the \texttt{INHERITS\_FROM} part is optional. To avoid
+where the \texttt{InheritsFrom} alias is optional. To avoid
inconsistencies in the hierarchy, each type tag may be defined only
once for a program.
+once for a program. If you call \texttt{GetProp} the property system will first look for the properties defined in \texttt{BaseTagName1} in the \texttt{InheritsFrom} list.
+If a defined property is found this property is returned. If no defined property is found the search will continue in the ancestors of \texttt{BaseTagName1}.
+If again no defined property is found the search will continue in the second \texttt{BaseTagName2} in the list, and so on.
+If no defined property is found at all, a compiler error is triggered.
\vskip1ex\noindent
Example:
\begin{lstlisting}[style=DumuxCode]
namespace Dumux {
namespace Properties {
NEW_TYPE_TAG(MyBaseTypeTag1);
NEW_TYPE_TAG(MyBaseTypeTag2);
+namespace TTag {
+struct MyBaseTypeTag1 {};
+struct MyBaseTypeTag2 {};
NEW_TYPE_TAG(MyDerivedTypeTag, INHERITS_FROM(MyBaseTypeTag1, MyBaseTypeTag2));
+struct MyDerivedTypeTag { using InheritsFrom = std::tuple; };
+} // end namespace TTag
}}
\end{lstlisting}
\subsubsection{Declaring Property Tags}
New property tags, i.e. labels for properties, are declared
using
+\subsubsection{Defining new Property Tags}
+New property tags are defined using
+
\begin{lstlisting}[style=DumuxCode]
NEW_PROP_TAG(NewPropTagName);
+template
+struct NewPropTagName { using type = UndefinedProperty; };
\end{lstlisting}
A property tag can be declared arbitrarily often, in fact it is
recommended that all properties are declared in each file where they
are used.
\vskip1ex\noindent
Example:
\begin{lstlisting}[style=DumuxCode]
namespace Dumux {
namespace Properties {
NEW_PROP_TAG(MyPropertyTag);
+template
+struct MyPropertyTag { using type = UndefinedProperty; };
}}
\end{lstlisting}
+If you need to forward declare a property use
+
+\begin{lstlisting}[style=DumuxCode]
+// forward declaration
+template
+struct NewPropTagName;
+\end{lstlisting}
+
\subsubsection{Defining Properties}
The value of a property on a given node of the type tag hierarchy is
defined using
\begin{lstlisting}[style=DumuxCode]
SET_PROP(TypeTagName, PropertyTagName)
+template
+struct PropertyTagName
{
// arbitrary body of a struct
};
\end{lstlisting}
For each program, a property itself can be declared at most once,
although properties may be overwritten for derived type tags.
Also, the following convenience macros are available to define simple
properties:
+This means a property is defined for a specific type tag node \texttt{TTag::TypeTagName}
+by providing a partial template specialization of \texttt{PropertyTagName}.
+The body typically contains either the alias \texttt{type}, or a data member \texttt{value}.
+However, you can of course write in the body whatever you like.
+
\begin{lstlisting}[style=DumuxCode]
SET_TYPE_PROP(TypeTagName, PropertyTagName, type);
SET_BOOL_PROP(TypeTagName, PropertyTagName, booleanValue);
SET_INT_PROP(TypeTagName, PropertyTagName, integerValue);
SET_SCALAR_PROP(TypeTagName, PropertyTagName, floatingPointValue);
+template
+struct PropertyTagName { using type = type; };
+
+template
+struct PropertyTagName { static constexpr bool value = booleanValue; };
+
+template
+struct PropertyTagName { static constexpr int value = integerValue; };
\end{lstlisting}
\vskip1ex\noindent
@@ 100,84 +112,53 @@ Example:
\begin{lstlisting}[style=DumuxCode]
namespace Dumux {
namespace Properties {
NEW_TYPE_TAG(MyTypeTag);
NEW_PROP_TAG(MyCustomProperty);
NEW_PROP_TAG(MyType);
+// Create new type tag
+namespace TTag {
+struct MyTypeTag {};
+}
NEW_PROP_TAG(MyBoolValue);
NEW_PROP_TAG(MyIntValue);
NEW_PROP_TAG(MyScalarValue);
+// Define some properties
+template struct MyCustomProperty { using type = UndefinedProperty; };
+template struct MyType { using type = UndefinedProperty; };
+template struct MyBoolValue { using type = UndefinedProperty; };
+template struct MyIntValue { using type = UndefinedProperty; };
+template struct MyScalarValue { using type = UndefinedProperty; };
SET_PROP(MyTypeTag, MyCustomProperty)
+// Set the properties for the new type tag
+template
+struct MyCustomProperty
{
 static void print() { std::cout << "Hello, World!\n"; }
+ static void print()
+ { std::cout << "Hello, World!\n"; }
};
SET_TYPE_PROP(MyTypeTag, MyType, unsigned int);
SET_BOOL_PROP(MyTypeTag, MyBoolValue, true);
SET_INT_PROP(MyTypeTag, MyIntValue, 12345);
SET_SCALAR_PROP(MyTypeTag, MyScalarValue, 12345.67890);
}}
\end{lstlisting}
+template
+struct MyType { using type = unsigned int; };
\subsubsection{Unsetting Properties}
Sometimes an inherited properties do not make sense for a certain
node in the type tag hierarchy. These properties can be explicitly
unset using
\begin{lstlisting}[style=DumuxCode]
UNSET_PROP(TypeTagName, PropertyTagName);
\end{lstlisting}
The unset property can not be set for the same type tag, but of
course derived type tags may set it again.

\vskip1ex\noindent
Example:
\begin{lstlisting}[style=DumuxCode]
namespace Dumux {
namespace Properties {
NEW_TYPE_TAG(BaseTypeTag);
NEW_TYPE_TAG(DerivedTypeTag, INHERITS_FROM(BaseTypeTag));
+template
+struct MyBoolValue { static constexpr bool value = true; };
NEW_PROP_TAG(TestProp);
+template
+struct MyIntValue { static constexpr int value = 12345; };
SET_TYPE_PROP(BaseTypeTag, TestProp, int);
UNSET_PROP(DerivedTypeTag, TestProp);
// trying to access the 'TestProp' property for 'DerivedTypeTag'
// will trigger a compiler error!
+template
+struct MyScalarValue { static constexpr double value = 12345.67890; };
}}
\end{lstlisting}
\subsubsection{Converting Tag Names to Tag Types}
For the \Cplusplus compiler, property and type tags are like ordinary
types. Both can thus be used as template arguments. To convert a
property tag name or a type tag name into the corresponding type, the
macros \texttt{TTAG(TypeTagName)} and \texttt{PTAG(PropertyTagName)}
ought to be used.

\subsubsection{Retrieving Property Values}
The value of a property can be retrieved using
+The type of a property can be retrieved using
\begin{lstlisting}[style=DumuxCode]
GET_PROP(TypeTag, PropertyTag)
\end{lstlisting}
or using the convenience macros
\begin{lstlisting}[style=DumuxCode]
GET_PROP_TYPE(TypeTag, PropertyTag)
GET_PROP_VALUE(TypeTag, PropertyTag)
+using Prop = GetProp;
\end{lstlisting}
\vskip1ex
\noindent
The first convenience macro retrieves the type defined using
\texttt{SET\_TYPE\_PROP} and is equivalent to
\begin{lstlisting}[style=DumuxCode]
GET_PROP(TypeTag, PropertyTag)::type
\end{lstlisting}
while the second convenience macro retrieves the value of any property
defined using one of the macros \texttt{SET\_}$\{$\texttt{INT,BOOL,SCALAR}$\}$\texttt{\_PROP} and is
equivalent to
+There is a helper struct and a helper function to retrieve the \texttt{type} and \texttt{value}
+members of a property
+
\begin{lstlisting}[style=DumuxCode]
GET_PROP(TypeTag, PropertyTag)::value
+using PropType = GetPropType;
+constexpr auto propValue = getPropValue();
\end{lstlisting}
\vskip1ex\noindent
@@ 185,32 +166,31 @@ Example:\nolinebreak
\begin{lstlisting}[style=DumuxCode]
template
class MyClass {
 // retrieve the ::value attribute of the 'NumEq' property
 enum { numEq = GET_PROP(TypeTag, NumEq)::value };
 // retrieve the ::value attribute of the 'NumPhases' property using the convenience macro
 enum { numPhases = GET_PROP_VALUE(TypeTag, NumPhases) };

 // retrieve the ::type attribute of the 'Scalar' property
 typedef typename GET_PROP(TypeTag, Scalar)::type Scalar;
 // retrieve the ::type attribute of the 'Vector' property using the convenience macro
 typedef typename GET_PROP_TYPE(TypeTag, Vector) Vector;
+ // retrieve the ::value attribute of the 'UseMoles' property
+ static constexpr bool useMoles = getPropValue();
+ static constexpr bool useMoles2 = GetProp::value; // equivalent
+
+ // retrieve the ::type attribute of the 'Scalar' property
+ using Scalar = GetPropType;
+ using Scalar2 = GetProp::type; // equivalent
};
\end{lstlisting}
\subsubsection{Nesting Property Definitions}
Inside property definitions there is access to all other properties
which are defined somewhere on the type tag hierarchy. The node for
which the current property is requested is available via the keyword
\texttt{TypeTag}. Inside property class bodies this can be used to
retrieve other properties using the \texttt{GET\_PROP} macros.
+which the current property is requested is available via the template argument
+\texttt{TypeTag}. Inside property class bodies \texttt{GetPropType} can be used to
+retrieve other properties and create aliases.
\vskip1ex\noindent
Example:
\begin{lstlisting}[style=DumuxCode]
SET_PROP(MyModelTypeTag, Vector)
+template
+struct Vector
{
private: typedef typename GET_PROP_TYPE(TypeTag, Scalar) Scalar;
public: typedef std::vector type;
+ using Scalar = GetPropType;
+ using type = std::vector;
};
\end{lstlisting}
@@ 272,25 +252,34 @@ defined by:
namespace Dumux {
namespace Properties {
NEW_TYPE_TAG(CompactCar);
NEW_TYPE_TAG(Truck);
NEW_TYPE_TAG(Tank);
NEW_TYPE_TAG(Sedan, INHERITS_FROM(CompactCar));
NEW_TYPE_TAG(Pickup, INHERITS_FROM(Sedan, Truck));
NEW_TYPE_TAG(HummerH1, INHERITS_FROM(Pickup, Tank));
+namespace TTag{
+struct CompactCar {};
+struct Truck {};
+struct Tank {};
+
+struct Sedan { using InheritsFrom = std::tuple; };
+struct Pickup { using InheritsFrom = std::tuple; };
+struct HummerH1 { using InheritsFrom = std::tuple; };
+}}} // end namespace TTag
\end{lstlisting}
Figure \ref{fig:carpropertynames} lists a few property names which
make sense for at least one of the nodes of Figure
\ref{fig:carhierarchy}. These property names can be declared as
+\ref{fig:carhierarchy}. These property names can be defined as
follows:
\begin{lstlisting}[name=propsyscars,style=DumuxCode]
NEW_PROP_TAG(TopSpeed); // [km/h]
NEW_PROP_TAG(NumSeats); // []
NEW_PROP_TAG(CanonCaliber); // [mm]
NEW_PROP_TAG(GasUsage); // [l/100km]
NEW_PROP_TAG(AutomaticTransmission); // true/false
NEW_PROP_TAG(Payload); // [t]
+template
+struct TopSpeed { using type = UndefinedProperty; }; // [km/h]
+template
+struct NumSeats { using type = UndefinedProperty; }; // []
+template
+struct CanonCaliber { using type = UndefinedProperty; }; // [mm]
+template
+struct GasUsage { using type = UndefinedProperty; }; // [l/100km]
+template
+struct AutomaticTransmission { using type = UndefinedProperty; }; // true/false
+template
+struct Payload { using type = UndefinedProperty; }; // [t]
\end{lstlisting}
\noindent
@@ 321,35 +310,52 @@ the following:
Using the \Dumux property system, these assumptions are formulated
using
\begin{lstlisting}[name=propsyscars,style=DumuxCode]
SET_INT_PROP(CompactCar, TopSpeed, GET_PROP_VALUE(TypeTag, GasUsage) * 30);
SET_INT_PROP(CompactCar, NumSeats, 5);
SET_INT_PROP(CompactCar, GasUsage, 4);
+template
+struct TopSpeed
+{static constexpr int value = getPropValue() * 30};
SET_INT_PROP(Truck, TopSpeed, 100);
SET_INT_PROP(Truck, NumSeats, 2);
SET_INT_PROP(Truck, GasUsage, 18);
SET_INT_PROP(Truck, Payload, 35);
+template
+struct NumSeats { static constexpr int value = 5; };
SET_INT_PROP(Tank, TopSpeed, 60);
SET_INT_PROP(Tank, GasUsage, 65);
SET_INT_PROP(Tank, CanonCaliber, 120);
+template
+struct GasUsage { static constexpr int value = 4; };
SET_INT_PROP(Sedan, GasUsage, 7);
SET_BOOL_PROP(Sedan, AutomaticTransmission, true);
+template
+struct TopSpeed { static constexpr int value = 100; };
SET_INT_PROP(Pickup, TopSpeed, 120);
SET_INT_PROP(Pickup, Payload, 5);
+template
+struct NumSeats { static constexpr int value = 2; };
SET_INT_PROP(HummerH1, TopSpeed, GET_PROP_VALUE(TTAG(Pickup), TopSpeed));
\end{lstlisting}
+template
+struct GasUsage { static constexpr int value = 18; };
\noindent
At this point, the HummerH1 has a $\unit[120]{mm}$ canon which it inherited
from its military ancestor. It can be removed by
\begin{lstlisting}[name=propsyscars,style=DumuxCode]
UNSET_PROP(HummerH1, CanonCaliber);
+template
+struct Payload { static constexpr int value = 35; };
}} // close namespaces
+template
+struct TopSpeed { static constexpr int value = 60; };
+
+template
+struct GasUsage { static constexpr int value = 65; };
+
+template
+struct CanonCaliber { static constexpr int value = 120; };
+
+template
+struct GasUsage { static constexpr int value = 7; };
+
+template
+struct AutomaticTransmission { static constexpr bool value = true; };
+
+template
+struct TopSpeed { static constexpr int value = 120; };
+
+template
+struct Payload { static constexpr int value = 5; };
+
+template
+struct TopSpeed
+{ static constexpr int value = getPropValue>(); };
\end{lstlisting}
\noindent
@@ 358,30 +364,12 @@ be generated. For example
\begin{lstlisting}[name=propsyscars,style=DumuxCode]
int main()
{
 std::cout << "top speed of sedan: " << GET_PROP_VALUE(TTAG(Sedan), TopSpeed) << "\n";
 std::cout << "top speed of truck: " << GET_PROP_VALUE(TTAG(Truck), TopSpeed) << "\n";

 std::cout << PROP_DIAGNOSTIC(TTAG(Sedan), TopSpeed);
 std::cout << PROP_DIAGNOSTIC(TTAG(HummerH1), CanonCaliber);

 Dumux::Properties::print();
+ std::cout << "top speed of sedan: " << getPropValue() << "\n";
+ std::cout << "top speed of truck: " << getPropValue() << "\n";
}
\end{lstlisting}
will yield the following output:
\begin{lstlisting}[style=Bash, basicstyle=\ttfamily\scriptsize\let\textcolor\textcolordummy]
$ top speed of sedan: 210
$ top speed of truck: 100
$ Properties for Sedan:
$ bool AutomaticTransmission = 'true' defined at test_propertysystem.cc:68
$ int GasUsage = '7' defined at test_propertysystem.cc:67
$ Inherited from CompactCar:
$ int NumSeats = '5' defined at test_propertysystem.cc:55
$ int TopSpeed = '::Dumux::Properties::GetProperty::p::value * 30' defined at test_propertysystem.cc:54
\end{lstlisting}

\subsection{Property Values}
To get the value of a property use:
\begin{description}
\item[\texttt{{\small GET\_PROP\_VALUE:}}]
Always returns the \emph{compiletime} specified value of the property.
\end{description}
diff git a/doc/handbook/5_spatialdiscretizations.tex b/doc/handbook/5_spatialdiscretizations.tex
index 516d1bfe8405256ef26e3acf08d9a0ac38e768f3..d45be682e004bb7f22ca4fba56425d8fa09ecd16 100644
 a/doc/handbook/5_spatialdiscretizations.tex
+++ b/doc/handbook/5_spatialdiscretizations.tex
@@ 1,10 +1,9 @@
\section{Spatial Discretization Schemes}
\label{spatialdiscretization}
We discretize space with the cellcentered finite volume method (\ref{box} ), the box method (\ref{cc})
+We discretize space with the cellcentered finite volume method (\ref{cc} ), the box method (\ref{box})
or a staggered grid scheme.
Grid adaption is available for both box and cellcentered finite volume method.
Note that the current implementation only ensures mass conservation for incompressible fluids.
In general, the spatial parameters, especially the porosity, have to be assigned on
the coarsest level of discretization.
@@ 13,13 +12,13 @@ the coarsest level of discretization.
The so called box method unites the advantages of the finitevolume (FV) and
finiteelement (FE) methods.
First, the model domain $G$ is discretized with a FE mesh consisting of nodes
+First, the model domain $\Omega$ is discretized with a FE mesh consisting of nodes
$i$ and corresponding elements $E_k$. Then, a secondary FV mesh is constructed
by connecting the midpoints and barycenters of the elements surrounding node
$i$ creating a box $B_i$ around node $i$ (see Figure \ref{pc:box}a).
\begin{figure} [ht]
\includegraphics[width=0.8\linewidth,keepaspectratio]{PNG/box_disc.png}
+\includegraphics[width=0.8\linewidth,keepaspectratio]{png/box_disc.png}
\caption{\label{pc:box} Discretization of the box method}
\end{figure}
@@ 46,17 +45,17 @@ In the following, the discretization of the balance equation is going to be deri
From the \textsc{Reynolds} transport theorem follows the general balance equation:
\begin{equation}
 \underbrace{\int_G \frac{\partial}{\partial t} \: u \: dG}_{1}
 + \underbrace{\int_{\partial G} (\mathbf{v} u + \mathbf w) \cdot \textbf n \: d\varGamma}_{2} = \underbrace{\int_G q \: dG}_{3}
+ \underbrace{\int_\Omega \frac{\partial}{\partial t} \: u \, \mathrm{d}x}_{1}
+ + \underbrace{\int_{\partial\Omega} (\mathbf{v} u + \mathbf w) \cdot \textbf n \, \mathrm{d}\Gamma}_{2} = \underbrace{\int_\Omega q \, \mathrm{d}x}_{3}
\end{equation}
\begin{equation}
 f(u) = \int_G \frac{\partial u}{\partial t} \: dG + \int_{G} \nabla \cdot
 \underbrace{\left[ \mathbf{v} u + \mathbf w(u)\right] }_{F(u)} \: dG  \int_G q \: dG = 0
+ f(u) = \int_\Omega \frac{\partial u}{\partial t} \, \mathrm{d}x + \int_{\Omega} \nabla \cdot
+ \underbrace{\left[ \mathbf{v} u + \mathbf w(u)\right] }_{F(u)} \, \mathrm{d}x  \int_\Omega q \, \mathrm{d}x = 0
\end{equation}
where term 1 describes the changes of entity $u$ within a control volume over
time, term 2 the advective, diffusive and dispersive fluxes over the interfaces
of the control volume and term 3 is the source and sink term. $G$ denotes the
+of the control volume and term 3 is the source and sink term. $\Omega$ denotes the
model domain and $F(u) = F(\mathbf v, p) = F(\mathbf v(x,t), p(x,t))$.
Like the FE method, the box method follows the principle of weighted residuals.
@@ 68,30 +67,30 @@ this means:
\begin{minipage}[b]{0.47\textwidth}
\begin{equation}
\label{eq:p}
 \tilde p = \sum_i N_i \hat{p_i}
+ \tilde p = \sum_i N_i \hat{p}_i
\end{equation}
\begin{equation}
\label{eq:v}
 \tilde{\mathbf v} = \sum_i N_i \hat{\mathbf v}
+ \tilde{\mathbf v} = \sum_i N_i \hat{\mathbf v}_i
\end{equation}
\begin{equation}
\label{eq:x}
 \tilde x^\kappa = \sum_i N_i \hat x^\kappa
+ \tilde x^\kappa = \sum_i N_i \hat x_i^\kappa
\end{equation}
\end{minipage}
\hfill
\begin{minipage}[b]{0.47\textwidth}
\begin{equation}
\label{eq:dp}
 \nabla \tilde p = \sum_i \nabla N_i \hat{p_i}
+ \nabla \tilde p = \sum_i \nabla N_i \hat{p}_i
\end{equation}
\begin{equation}
\label{eq:dv}
 \nabla \tilde{\mathbf v} = \sum_i \nabla N_i \hat{\mathbf v}
+ \nabla \tilde{\mathbf v} = \sum_i \nabla N_i \hat{\mathbf v}_i
\end{equation}
\begin{equation}
\label{eq:dx}
 \nabla \tilde x^\kappa = \sum_i \nabla N_i \hat x^\kappa .
+ \nabla \tilde x^\kappa = \sum_i \nabla N_i \hat x_i^\kappa .
\end{equation}
\end{minipage}
@@ 107,103 +106,231 @@ of the residual $\varepsilon$ with a weighting function $W_j$ and claiming that
this product has to vanish within the whole domain,
\begin{equation}
 \int_G W_j \cdot \varepsilon \: \overset {!}{=} \: 0 \qquad \textrm{with} \qquad \sum_j W_j =1
+ \int_\Omega \varepsilon W_j \, \mathrm{d}x \overset {!}{=} \: 0 \qquad \textrm{with} \qquad \sum_j W_j =1
\end{equation}
yields the following equation:
\begin{equation}
 \int_G W_j \frac{\partial \tilde u}{\partial t} \: dG + \int_G W_j
 \cdot \left[ \nabla \cdot F(\tilde u) \right] \: dG  \int_G W_j
 \cdot q \: dG = \int_G W_j \cdot \varepsilon \: dG \: \overset {!}{=} \: 0 .
+ \int_\Omega \frac{\partial \tilde u}{\partial t} W_j \, \mathrm{d}x + \int_\Omega
+ \left[ \nabla \cdot F(\tilde u) \right] W_j \, \mathrm{d}x  \int_\Omega q W_j \, \mathrm{d}x = \int_\Omega \varepsilon W_j \, \mathrm{d}x \: \overset {!}{=} \: 0.
+\label{eq:weightedResidual}
\end{equation}
Then, the chain rule and the \textsc{GreenGaussian} integral theorem are applied.
+For standard Galerkin schemes, the weighting functions $W_j$ are chosen the same as the ansatz functions $N_j$. However, this does not yield a locally massconservative scheme.
+Therefore, for the Box method, the weighting functions $W_j$ are chosen as
+the piecewise constant functions over a
+control volume box $B_j$, i.e.
\begin{equation}
 \int_G W_j \frac{\partial \sum_i N_i \hat u_i}{\partial t} \: dG
 + \int_{\partial G} \left[ W_j \cdot F(\tilde u)\right]
 \cdot \mathbf n \: d\varGamma_G + \int_G \nabla W_j \cdot F(\tilde u)
 \: dG  \int_G W_j \cdot q \: dG = 0
+ W_j(x) = \begin{cases}
+ 1 &x \in B_j \\
+ 0 &x \notin B_j.\\
+ \end{cases}
+\label{eq:weightingFunctions}
\end{equation}
+Thus, the Box method is a PetrovGalerkin scheme, where the weighting functions do not belong to the same function space than the ansatz functions.
A mass lumping technique is applied by assuming that the storage capacity is
reduced to the nodes. This means that the integrals $M_{i,j} = \int_G W_j \: N_i \: dG$
are replaced by the mass lumping term $M^{lump}_{i,j}$ which is defined as:
+Inserting definition \eqref{eq:weightingFunctions} into equation \eqref{eq:weightedResidual} and using the \textsc{GreenGaussian} integral theorem results in
+\begin{equation}
+ \int_{B_j} \frac{\partial \tilde u}{\partial t} \, \mathrm{d}x + \int_{\partial B_j} F(\tilde u) \cdot \mathbf n \, \mathrm{d}\Gamma_{B_j}  \int_{B_j} q \, \mathrm{d}x \overset {!}{=} \: 0,
+\label{eq:BoxMassBlance}
+\end{equation}
+which has to hold for every box $B_j$.
+The first term in equation \eqref{eq:BoxMassBlance} can be written as
\begin{equation}
 M^{lump}_{i,j} =\begin{cases} \int_G W_j \: dG = \int_G N_i \: dG = V_i &i = j\\
 0 &i \neq j\\
+\int_{B_j} \frac{\partial \tilde u}{\partial t} \, \mathrm{d}x = \frac{d}{dt} \int_{B_j} \sum_i \hat u_i N_i \, \mathrm{d}x = \sum_i \frac{\partial \hat u_i}{\partial t} \int_{B_j} N_i \, \mathrm{d}x.
+\end{equation}
+Here, a mass lumping technique is applied by assuming that the storage capacity is
+reduced to the nodes. This means that the integrals $M_{i,j} = \int_{B_j} N_i \, \mathrm{d}x$
+are replaced by some mass lumped terms $M^{lump}_{i,j}$ which are defined as
+\begin{equation}
+ M^{lump}_{i,j} =\begin{cases} B_j &j = i\\
+ 0 &j \neq i,\\
\end{cases}
\end{equation}
where $V_i$ is the volume of the FV box $B_i$ associated with node $i$.
The application of this assumption in combination with
$\int_G W_j \:q \: dG = V_i \: q$ yields
+where $B_j$ is the volume of the FV box $B_j$ associated with node $j$.
+The application of this assumption yields
\begin{equation}
 V_i \frac{\partial \hat u_i}{\partial t}
 + \int_{\partial G} \left[ W_j \cdot F(\tilde u)\right]
 \cdot \mathbf n \: d\varGamma_G + \int_G \nabla W_j \cdot F(\tilde u)
 \: dG V_i \cdot q = 0 \, .
+\label{eq:disc1}
+ B_j \frac{\partial \hat u_j}{\partial t}
+ + \int_{\partial B_j} F(\tilde u) \cdot \mathbf n \, \mathrm{d}\Gamma_{B_j}  Q_j = 0,
\end{equation}
+where $Q_j$ is an approximation (using some quadrature rule) of the integrated source/sink term $\int_{B_j} q \, \mathrm{d}x$.
Defining the weighting function $W_j$ to be piecewisely constant over a
control volume box $B_i$
+Using an implicit Euler time discretization finally
+leads to the discretized form which will be applied to the mathematical
+flow and transport equations:
\begin{equation}
 W_j(x) = \begin{cases}
 1 &x \in B_i \\
 0 &x \notin B_i\\
 \end{cases}
+\label{eq:discfin}
+ B_j \frac{\hat u_j^{n+1}  \hat u_j^{n}}{\Delta t}
+ + \int_{\partial B_j} F(\tilde u^{n+1}) \cdot \mathbf n
+ \; \mathrm{d}\Gamma_{B_j}  Q_j^{n+1} \: = 0.
\end{equation}
+Equation \eqref{eq:discfin} has to be fulfilled for each box $B_j$.
causes $\nabla W_j = 0$:
+\subsection{Cell Centered Finite Volume Methods  A Short Introduction}\label{cc}
+Cellcentered finite volume methods use the elements of the grid as control volumes.
+For each control volume the discrete values are determined at the element/control
+volume center (not required to be the barycenters).
+We consider a domain $\Omega \subset \mathbb{R}^d$, $d \in \{ 2, 3 \}$ with boundary $\Gamma = \partial \Omega$. Within this section, we consider the following elliptic problem
\begin{equation}
\label{eq:disc1}
 V_i \frac{\partial \hat u_i}{\partial t}
 + \int_{\partial B_i} \left[ W_j \cdot F(\tilde u)\right]
 \cdot \mathbf n \; d{\varGamma}_{B_i}  V_i \cdot q = 0 .
+ \begin{aligned}
+ \nabla \cdot \left(  \mathbf{\Lambda} \nabla u \right) &= q &&\mathrm{in} \, \Omega \\
+ \left(  \mathbf{\Lambda} \nabla u \right) \cdot \mathbf{n} &= v_N &&\mathrm{on} \, \Gamma_N \\
+ u &= u_D &&\mathrm{on} \, \Gamma_D.
+ \label{eq:elliptic}
+ \end{aligned}
\end{equation}
The consideration of the time discretization and inserting $W_j = 1$ finally
leads to the discretized form which will be applied to the mathematical
flow and transport equations:
+Here, $\mathbf{\Lambda} = \mathbf{\Lambda}(\mathbf{x}, \mathbf{u})$ is a symmetric and positive definite tensor of second rank (e.g. permeability, diffusivity, etc.), $u = u (\mathbf{x})$ is unknown and $q = q(\mathbf{x}, \mathbf{u})$ is a source/sink.
+We denote by $\mathcal{M}$ the mesh that results from the division of the domain $\Omega$ into $n_e$ control volumes $K \subset \Omega$. Each $K$ is a polygonal open set such that $K \cap L = \emptyset, \forall{K \neq L}$ and $\overline{\Omega} = \cup_{K \in \mathcal{M}} \overline{K}$.
+
+For the derivation of the finitevolume formulation we integrate the first equation of \eqref{eq:elliptic} over a control volume $K$ and apply the Gauss divergence theorem:
\begin{equation}
\label{eq:discfin}
 V_i \frac{\hat u_i^{n+1}  \hat u_i^{n}}{\Delta t}
 + \int_{\partial B_i} F(\tilde u^{n+1}) \cdot \mathbf n
 \; d{\varGamma}_{B_i}  V_i \: q^{n+1} \: = 0
+ \int_{\partial K} \left(  \mathbf{\Lambda} \nabla u \right) \cdot \mathbf{n} \, \mathrm{d} \Gamma = \int_K q \, \mathrm{d}x.
+ \label{eq:ellipticIntegrated}
\end{equation}
\subsection{Cell Centered Finite Volume Method  A Short Introduction}\label{cc}
+Splitting the control volume boundary $\partial K$ into a finite number of faces $\sigma \subset \partial K$ (such that $\sigma = \overline{K} \cap \overline{L}$ for some neighboring control volume $L$) and replacing the exact fluxes by an approximation, i.e. $F_{K, \sigma} \approx \int_{\sigma} \left(  \mathbf{\Lambda}_K \nabla u \right) \cdot \mathbf{n} \mathrm{d} \Gamma$ (here $\mathbf{\Lambda}_K$ is the value of $\mathbf{\Lambda}$ associated with control volume $K$), yield
+\begin{equation}
+ \sum_{\sigma \subset \partial K} F_{K, \sigma} = Q_K, \quad \forall \, {K \in \mathcal{M}},
+\label{eq:ccdisc}
+\end{equation}
+where $F_{K, \sigma}$ is the discrete flux through face $\sigma$ flowing out of cell $K$ and $Q_K := \int_K q \, \mathrm{d}x$ is the integrated source/sink term. Equation \eqref{eq:ccdisc} is the typical cellcentered finitevolume formulation.
+Finitevolume schemes differ in the way how the term
+$(\mathbf{\Lambda}_K \nabla u ) \cdot \mathbf{n} $ is approximated (i.e. the choice of the fluxes $F_{K, \sigma}$). Using the symmetry of the tensor $\mathbf{\Lambda}_K$, this term can be rewritten as
+$\nabla u \cdot \mathbf{\Lambda}_K\mathbf{n}$, which corresponds to the directional derivative of $u$ in conormal direction $\mathbf{\Lambda}_K\mathbf{n}$.
+In the following, the main ideas of the twopoint flux approximation and the multipoint flux approximation methods are briefly described. Hereby, we restrict the discussion to the twodimensional case.
+
+Please also note that other types of equations, e.g. instationary parabolic problems, can be discretized by applying some time discretization scheme to the time derivatives and by using the finitevolume scheme for the flux discretization. For simplicity the discussion is restricted to the elliptic problem \eqref{eq:elliptic}.
+
+\subsubsection{Tpfa Method}\label{cc_tpfa}
+The linear twopoint flux approximation is a simple but robust cellcentered finitevolume scheme, which is commonly used in commercial software.
+This scheme can be derived by using the conormal decomposition, which reads
+\begin{equation}
+\mathbf{\Lambda}_K \mathbf{n}_{K, \sigma} = t_{K,\sigma} \mathbf{d}_{K,\sigma} + \mathbf{d}^{\bot}_{K,\sigma}, \quad t_{K,\sigma} = \frac{\mathbf{n}_{K, \sigma}^T \mathbf{\Lambda}_K \mathbf{d}_{K,\sigma} }{\mathbf{d}_{K,\sigma}^T \mathbf{d}_{K,\sigma}}, \; \mathbf{d}^{\bot}_{K,\sigma} = \mathbf{\Lambda}_K \mathbf{n}_{K, \sigma}  t_{K,\sigma} \mathbf{d}_{K,\sigma},
+\label{eq:conormalDecTpfa}
+\end{equation}
+with the tensor $\mathbf{\Lambda}_K$ associated with control volume $K$, the distance vector $\mathbf{d}_{K,\sigma} := \mathbf{x}_\sigma  \mathbf{x}_K$ and $\mathbf{d}_{K,\sigma}^T \mathbf{d}^{\bot}_{K,\sigma} = 0$, see Figure \ref{pc:cctpfa} for the used notations. The same can be done for the conormal $\mathbf{\Lambda}_L \mathbf{n}_{L, \sigma}$. The $t_{K,\sigma}$ and $t_{L,\sigma}$ are the transmissibilities associated with the face $\sigma$. These transmissibilities are calculated in \Dumux by using the function \texttt{computeTpfaTransmissibility}.
\begin{figure} [ht]
\centering
\includegraphics[width=0.4\linewidth,keepaspectratio]{PNG/cc_disc.png}
\caption{\label{pc:cc} Discretization of the cell centered finite volume method}
+\includegraphics[width=0.4\linewidth,keepaspectratio]{png/cctpfa.png}
+\caption{Two neighboring control volumes sharing the face $\sigma$.}
+\label{pc:cctpfa}
\end{figure}
The cell centered finite volume method uses the elements of the grid as control volumes.
For each control volume all discrete values are determined at the element/control
volume center (see Figure~\ref{pc:cc}).
The mass or energy fluxes are evaluated at the integration points ($x_{ij}$),
which are located at the midpoints of the control
volume faces. This is a two point flux approximation since the flux between
the element/control volume centers $i$ and $j$ is calculated
only with information from these two points. In contrast the box method uses
a multipoint flux approximation where all nodes of the
element influence the flux between two specific nodes. \\
Neumann boundary conditions are applied at the boundary control volume faces
and Dirichlet boundary conditions at the boundary control volumes. \\
The cell centered finite volume method is robust and mass conservative but
should only be applied for structured grids
(the control volume face normal vector ($n_{ij}$) should be parallel to the
direction of the gradient between the two element/control
volume centers).

% \subsubsection{MPFA}\label{cc_mpfa}
% TODO
+
+With these notations, it follows that for each cell $K$ and face $\sigma$
+\begin{equation}
+\nabla u \cdot \mathbf{\Lambda}_K \mathbf{n}_{K, \sigma} = t_{K,\sigma} \nabla u \cdot \mathbf{d}_{K,\sigma} + \nabla u \cdot \mathbf{d}^{\bot}_{K,\sigma}.
+\end{equation}
+For the Tpfa scheme, the second part in the above equation is neglected. By using the fact that $\nabla u \cdot \mathbf{d}_{K,\sigma} \approx u_\sigma  u_K$, the discrete fluxes for face $\sigma$ are given by
+\begin{equation}
+F_{K,\sigma} = \meas{\sigma} t_{K,\sigma} (u_\sigma  u_K), \qquad F_{L,\sigma} = \meas{\sigma} t_{L,\sigma} (u_\sigma  u_L).
+\label{eq:TPFAOneSided}
+\end{equation}
+Enforcing local flux conservation, i.e. $F_{K,\sigma}+F_{L,\sigma}=0$, results in
+\begin{equation}
+u_\sigma = \frac{t_{K,\sigma} u_K + t_{L,\sigma} u_L}{t_{K,\sigma} + t_{L,\sigma}}.
+\end{equation}
+With this, the fluxes \eqref{eq:TPFAOneSided} are rewritten as
+\begin{equation}
+F_{K,\sigma} = \meas{\sigma} \frac{t_{K,\sigma} t_{L,\sigma}}{t_{K,\sigma} + t_{L,\sigma}} (u_K  u_L), \quad F_{L,\sigma} = \meas{\sigma} \frac{t_{K,\sigma} t_{L,\sigma}}{t_{K,\sigma} + t_{L,\sigma}} (u_L  u_K).
+\label{eq:TPFAFlux}
+\end{equation}
+By neglecting the orthogonal term, the consistency of the scheme is lost for general grids, where $\nabla u \cdot \mathbf{d}^{\bot}_{K,\sigma} \not = 0$. The consistency is achieved only for socalled Korthogonal grids for which $\mathbf{d}^{\bot}_{K,\sigma} = 0$. For such grids we deduce that
+\begin{equation}
+\frac{t_{K,\sigma} t_{L,\sigma}}{t_{K,\sigma} + t_{L,\sigma}} = \frac{\tau_{K,\sigma} \tau_{L,\sigma}}{\tau_{K,\sigma} d_{L,\sigma} + \tau_{L,\sigma} d_{K,\sigma}},
+\label{eq:TPFAcoeffNew}
+\end{equation}
+with $\tau_{K,\sigma} := \mathbf{n}_{K, \sigma} \mathbf{\Lambda}_K\mathbf{n}_{K, \sigma}, \tau_{L,\sigma} := \mathbf{n}_{L, \sigma} \mathbf{\Lambda}_L\mathbf{n}_{L, \sigma}$, $d_{K,\sigma}:= \mathbf{n}_{K, \sigma} \cdot \mathbf{d}_{K, \sigma}$, and $d_{L,\sigma}:= \mathbf{n}_{L, \sigma} \cdot \mathbf{d}_{L, \sigma}$. This reduces, for the case of scalar permeability, to a distance weighted harmonic averaging of permeabilities.
+
+
+
+\subsubsection{Mpfa Method}\label{cc_mpfa}
+Expressions for the face fluxes $F_{K, \sigma}$ are obtained by introducing intermediate face unknowns $u_\sigma$ in addition to the cell unknowns $u_K$ and enforcing the physically motivated continuity of fluxes and continuity of the solution across the faces. For a face $\sigma$ between the two polygons $K$ and $L$ these conditions read:
+\begin{equation}
+ \begin{aligned}
+ &F_{K, \sigma} + F_{L, \sigma} = 0 \\
+ &{u}_{K,\sigma} = {u}_{L,\sigma} = {u}_{\sigma}.
+ \label{eq:sigmaConditions}
+ \end{aligned}
+\end{equation}
+Using these conditions, the intermediate face unknowns ${u}_\sigma$ can be eliminated and the fluxes are expressed as a function of the cell unknowns $u_N$ and associated transmissibilities $t^N_{K,\sigma}$:
+
+\begin{equation}
+ F_{K,\sigma} = \sum_{N \in \mathcal{S}_{K,\sigma}} t^N_{K,\sigma} u_{N}.
+ \label{eq:FVFluxExpression}
+\end{equation}
+
+\begin{figure} [ht]
+\centering
+\includegraphics[width=0.8\linewidth,keepaspectratio]{png/mpfa_iv.png}
+\caption{Interaction region for the MpfaO method. The graphic on the right illustrates how the subcontrol volume $L^v$ and face $\sigma^v_2$ are embedded in cell $L$. Note that the face stencils for all subcontrol volume faces in the depicted interaction region are $\mathcal{S}_{\sigma^v_i} = \{ K,L,M \}$, meaning that the fluxes over the subcontrol volume faces depend on the three cell unknowns $u_K, u_L, u_M$.}
+\label{pc:interactionRegion_mpfa}
+\end{figure}
+
+The main difference between the various finitevolume schemes available is the assembly of the face fluxes, i.e. the computation of the $t^N_{K,\sigma}$ and the size of $\mathcal{S}_{K,\sigma}$. For the Tpfa, that has been presented in the last section, the stencil and transmissibilities are given as
+\begin{equation*}
+\mathcal{S}_{K,\sigma} = \lbrace K,L \rbrace, \quad t^K_{K,\sigma} = \meas{\sigma} \frac{t_{K,\sigma} t_{L,\sigma}}{t_{K,\sigma} + t_{L,\sigma}},\; t^L_{K,\sigma} = \meas{\sigma} \frac{t_{K,\sigma} t_{L,\sigma}}{t_{K,\sigma} + t_{L,\sigma}},
+\end{equation*}
+with $t_{K,\sigma},t_{L,\sigma}$ as defined in equation \eqref{eq:conormalDecTpfa}.
+
+In the following, a multipoint flux approximation method (MpfaO method), which was introduced in \citet{A3:aavatsmark:2002}, is presented. The main difference to the Tpfa scheme is the fact that a consistent discrete gradient is constructed, i.e. the term $\nabla u \cdot \mathbf{d}^{\bot}_{K,\sigma}$ is not neglected.
+
+For this scheme, a dual grid is created by connecting the barycenters of the cells with the barycenters of the faces ($d=2$) or the barycenters of the faces and edges ($d=3$). This divides each cell into subcontrol volumes $K^v$. Analogously, each face is subdivided into subcontrol volume faces $\sigma^v$, see Figure \ref{pc:interactionRegion_mpfa}. We allow for piecewise constant $\mathbf{\Lambda}$ (denoted as $\mathbf{\Lambda}_K$ for each cell $K$) and construct discrete gradients $\nabla_\mathcal{D}^{K^v} u$ (per subcontrol volume $K^v$).
+In the following, we restrict our discussion to the twodimensional setup that is shown in Figure \ref{pc:interactionRegion_mpfa}.
+Here, the discrete gradients are constructed to be consistent such that the following conditions hold:
+\begin{equation}
+\nabla_\mathcal{D}^{K^v} u \cdot (\mathbf{x}_{\sigma^v_1} \mathbf{x}_{K}) = u_{\sigma^v_1}  u_K, \quad \nabla_\mathcal{D}^{K^v} u \cdot (\mathbf{x}_{\sigma^v_3} \mathbf{x}_{K}) = u_{\sigma^v_3}  u_K.
+\end{equation}
+Thus, a discrete gradient (for subcontrol volume $K^v$) that fulfills these conditions is given as
+\begin{equation}
+\nabla_\mathcal{D}^{K^v} u = \mathbb{D}^{T}_{K^v}
+ \begin{bmatrix}
+ u_{\sigma^v_1}  u_K \\
+ u_{\sigma^v_3}  u_K
+ \end{bmatrix}, \qquad \text{ with }\; \mathbb{D}_{K^v} :=
+ \begin{bmatrix}
+ \mathbf{x}_{\sigma^v_1} \mathbf{x}_K & \mathbf{x}_{\sigma^v_3}  \mathbf{x}_K
+ \end{bmatrix}.
+ \label{eq:MPFAGradientRecons}
+\end{equation}
+
+This enables us to write the discrete flux across $\sigma^v_1$ from cell $K$ as follows:
+\begin{equation}
+ F_{K, \sigma^v_1} :=  \sigma^v_1 \mathbf{n}_{\sigma^v_1}^T \mathbf{\Lambda}_K \nabla_\mathcal{D}^{K^v} u.
+ \label{eq:discreteFlux}
+\end{equation}
+Inserting the discrete gradient, yields
+\begin{equation}
+ F_{K, \sigma^v_1} = \omega_{K,\sigma^v_1\sigma^v_1}(u_K  u_{\sigma^v_1}) + \omega_{K,\sigma^v_1 \sigma^v_3}(u_K  u_{\sigma^v_3}),
+ \label{eq:discreteFluxRef}
+\end{equation}
+with $(\omega_{K,\sigma^v_1\sigma^v_1},\omega_{K,\sigma^v_1 \sigma^v_3})^T = \sigma^v_1 \mathbb{D}^{1}_{K^v}\mathbf{\Lambda}_K \mathbf{n}_{\sigma^v_1}$. These values are calculated in \Dumux by using the function \texttt{computeMpfaTransmissibility}.
+\\ \ \\
+To deduce a cellcentered scheme, the introduced face unknowns $u_{\sigma^v_i}$ have to be eliminated. This is done by enforcing flux continuity for each subcontrol volume face, i.e.
+\begin{align}
+F_{K, \sigma^v_1} + F_{L, \sigma^v_1} &= 0, \\ F_{K, \sigma^v_3} + F_{M, \sigma^v_3} &= 0, \\ F_{L, \sigma^v_2} + F_{M, \sigma^v_2} &= 0.
+\end{align}
+This results in a system of equations for the face unknowns $\mathbf{u}_{\sigma}$
+\begin{equation}
+\mathbb{A}^{3\times 3} \mathbf{u}_{\sigma} = \mathbb{B}^{3\times 3} \mathbf{u},
+\end{equation}
+where $\mathbf{u}$ contains the three cell unknowns $u_K,u_L,u_M$ and $\mathbf{u}_{\sigma}$ the three face unknowns $u_{\sigma^v_1}, u_{\sigma^v_2}, u_{\sigma^v_3}$.
+Inserting these face unknowns into the flux expression \eqref{eq:discreteFluxRef} yields
+\begin{equation}
+ F_{K,\sigma^v_i} = \sum_{N \in \lbrace K,L,M \rbrace } t^N_{K,\sigma^v_i} u_{N} = \mathbf{t}_{K,\sigma^v_i} \cdot \mathbf{u},
+ \label{eq:FVFluxExpressionSubFace}
+\end{equation}
+for each cell $K$ and subcontrol volume face $\sigma^v_i$.
+
% \subsubsection{NLTPFA}\label{cc_nltpfa}
% TODO
@@ 211,64 +338,12 @@ volume centers).
\begin{figure}[ht]
\centering
\begin{tikzpicture}[scale=3.0,font=\normalsize]
\begin{scope}[shift={(0,2.5)}]
% control volume pressure
\fill[gray!40] (1,1) rectangle (2,2);
% control volume for vertical velocity
\fill[dumuxBlue!30] (0.0,0.5) rectangle (1.0,1.5);
% control volume for horizontal velocity
\fill[dumuxYellow!30] (0.5,0) rectangle (1.5,1);

% grid cells
\draw [thick] (0,0) grid (2,2);

% cell centers
\foreach \x in {0.5,...,1.5}
 \foreach \y in {0.5,...,1.5}
 \fill[gray](\x,\y) circle(0.06);
% velocity x
\foreach \x in {0,1,2}
 \foreach \y in {0.5,...,1.5}
 \draw[dumuxYellow,>,ultra thick](\x0.15,\y)  (\x+0.15,\y);
% velocity y
\foreach \x in {0.5,...,1.5}
 \foreach \y in {0,...,2.0}
 \draw[dumuxBlue,>,ultra thick](\x,\y0.15)  (\x,\y+0.15);
\end{scope}

% annotations
\begin{scope}[shift={(1.0,2.7)}]
\fill[gray](2.3,1.8) circle(0.06);
\draw(2.5,1.8) node[right, align=left] {cellcentered primary variables\\\color{gray}($p_\alpha$, $x^\kappa_\alpha$, $T$, $k$, $\varepsilon$, ...)};
\draw[dumuxYellow,>,ultra thick](2.2,1.4)  (2.4,1.4);
\draw[dumuxYellow](2.5,1.4) node[right, align=left] {$v_{\alpha\textrm{,x}}$};
\draw[dumuxBlue,>,ultra thick](2.3,0.9)  (2.3,1.1);
\draw[dumuxBlue](2.5,1.0) node[right, align=left] {$v_{\alpha\textrm{,y}}$};

\draw[thick](2.2,0.5) rectangle (2.4,0.7);
\draw(2.5,0.6) node[right, align=left] {finite volume mesh};
\draw[draw=none,fill=gray!40](2.2,0.1) rectangle (2.4,0.3);
\draw(2.5,0.2) node[right, align=left] {control volumes\\(cellcentered primary variables)};
\draw[draw=none,fill=dumuxYellow!30](1.9,0.1) rectangle (2.1,0.3);
\draw[draw=none,fill=dumuxBlue!30](2.2,0.1) rectangle (2.4,0.3);
\draw(2.5,0.2) node[right, align=left] {staggered control volumes\\(velocity components)};
\end{scope}
\end{tikzpicture}
\caption{\label{pc:staggered} Discretization of the staggeredgrid method}
+\includegraphics[width=.8\linewidth]{./pdf/staggered_grid.pdf}
+\caption{\label{pc:staggered} Discretization of the staggeredgrid method. The figure shows the different control volume arrangements, which are staggered with respect to each other. There are the control volumes centered around the scalar primary variables in black, the control volumes located around the $x$component of the velocity in blue and the control volumes located around the $y$components of the velocity in red. The control volume boundaries are given by lines. Additionally, there is one shaded example control volume each.\\
+In the twodimensional freeflow models, the continuity equation is discretized using the black control volumes, the $x$component of the momentum equation is discretized using the blue control volumes and the $y$component is discretized using the red control volumes. In three dimensions this works analogously.}
\end{figure}
The staggeredgrid or markerandcell method uses a cellcentered finite volume method
for the scalar primary variables.
The control volumes for the velocity components are shifted halfacell in each direction,
such that the velocity components are located on the edges of the
cellcentered finite volume mesh (see Figure~\ref{pc:staggered}).
As for the cellcentered method, the fluxes are evaluated at the edges
of each control volume with a twopoint flux approximation, cf. \ref{cc}.\\
For cellcentered variables, the boundary handling is as for the cellcentered method.
For the velocity components, Dirichlet values for the component normal to the boundary
face can directly be applied.
For the tangential components the boundary values are treated with contribution of the boundary flux. \\
+The staggeredgrid or markerandcell method uses a finite volume method with different control volumes for different equations. There are control volumes centered around the scalar primary variables. They correspond to the finite volume mesh. Additionally, there are control volumes located around the $x,y$ and (in 3D) $z$ velocity components which are shifted in the $x,y$ and $z$ direction, such that the velocity components are located on the edges of the cellcentered finite volume mesh (see Figure~\ref{pc:staggered}). As for the cellcentered method, the fluxes are evaluated at the edges of each control volume with a twopoint flux approximation, cf. \ref{cc}.\par
The staggeredgrid method is robust, mass conservative, and free of pressure oscillations
but should, as the cellcentered TPFA method, only be applied for structured grids.
At the moment the staggeredgrid is the base discretization for all freeflow models.
+Currently, all freeflow models in \Dumux use the staggeredgrid discretization.
diff git a/doc/handbook/5_stepsofasimulation.tex b/doc/handbook/5_stepsofasimulation.tex
index d95e350aa94cf004be9bd1118f06f733baae9b24..96e521aa9d6e41208c68356b49ed7b725f533285 100644
 a/doc/handbook/5_stepsofasimulation.tex
+++ b/doc/handbook/5_stepsofasimulation.tex
@@ 2,17 +2,12 @@
\label{flow}
This chapter is supposed to show how things are ``handed around'' in \Dumux. It
+This chapter is supposed to give a short overview over how things are ``handed around'' in \Dumux. It
is not a comprehenisve guide through the modeling framework of \Dumux, but
hopefully it will help getting to grips with it.
In Section \ref{content} the structure of \Dumux is shown from a \emph{content}
point of view.
% TODO: revise section about implementation structure
% Section \ref{implementation} however is written from the point of view of the \emph{implementation}.
% The same coloration in the flowcharts of both sections refers to the same level of calculation. For keeping things
% simple, the program flow of a \verb+2p+ model is shown in section \ref{implementation}. There are extensive comments
% regarding the formating in the tex file: so feel free, to enhance this description.
\subsection{Structure  by Content}
@@ 21,12 +16,11 @@ In Figure \ref{fig:algorithm}, the algorithmic representations of a monolithical
solution solution scheme is illustrated down to the element level.
\begin{figure}[hbt]
% \begin{tabular}{ l  l }
% \begin{minipage}[t]{0.48\textwidth}
\setcounter{thingCounter}{0}
\scriptsize
\sffamily
+\begin{center}\parbox{0cm}{
\begin{tabbing}
\textbf{{\begin{turn}{45}\color{black}\numberThis{main}{init}\end{turn}}} \=
\textbf{{\begin{turn}{45}\color{dumuxBlue}\numberThis{time step}{prep}\end{turn}}} \=
@@ 36,7 +30,6 @@ solution solution scheme is illustrated down to the element level.
\color{black}initialize \\
\color{black}\textbf{foreach} time step\\
 \> \color{dumuxBlue}prepare update\\
\> \color{dumuxBlue}\textbf{foreach} \textsc{Newton} iteration \\
\> \> \color{Mulberry}\textbf{foreach} element \\
@@ 59,354 +52,13 @@ solution solution scheme is illustrated down to the element level.
\> \color{dumuxBlue} write result\\
\color{black}\textbf{endfor}\\
\color{black}finalize
\end{tabbing}

% \end{minipage}
%
% &

% TODO: revise second figure
% \begin{minipage}[t]{0.48\textwidth}
% \setcounter{thingCounter}{0}
%
% \scriptsize
% \sffamily
% \begin{tabbing}
% \textbf{{\begin{turn}{45}\color{black}1. main\end{turn}}} \=
% \textbf{{\begin{turn}{45}\color{dumuxBlue}2. time step\end{turn}}} \=
% \textbf{{\begin{turn}{45}\color{Mulberry}3. \textsc{IMPES/C}\end{turn}}} \=
% \textbf{{\begin{turn}{45}\color{dumuxYellow}4. element\end{turn}}} \= \\
% \\
% \color{black}initialize \\
% \color{black}\textbf{foreach} time step\\
%
% \> \color{dumuxBlue}prepare update\\
% \> \color{dumuxBlue}\textbf{foreach} \textsc{IMPES/C} step \\
% \> \> \color{Mulberry}\textbf{if} grid is adaptive\\
% \> \> \> \color{dumuxYellow} calculate refinement indicator\\
% \> \> \> \color{dumuxYellow} mark elements, adapt the grid\\
% \> \> \> \color{dumuxYellow} map old solution to new grid\\
% \> \> \color{Mulberry} calculate {flow field}\\
% \> \> \color{Mulberry}\textbf{foreach} element \\
%
% \> \> \> \color{dumuxYellow} calculate element stiffness matrix \\
% \> \> \> \color{dumuxYellow} assemble into global matrix \\
%
% \> \> \color{Mulberry} \textbf{endfor} \\
% \> \> \color{Mulberry} solve linear system\\
%
% \> \> \color{Mulberry} calculate {transport} \\
% \> \> \color{Mulberry}\; (saturations, concentrations,...) \\
% \> \> \color{Mulberry}\textbf{foreach} element \\
% \> \> \> \color{dumuxYellow}calculate update (explicitly) \\
% \> \> \> \color{dumuxYellow} adapt time step ({CFL}like criterion) \\
% \> \> \color{Mulberry}\textbf{endfor} \\
% \> \> \color{Mulberry} update old solution \\
% \> \> \color{Mulberry} postprocess (flash calculation, etc.)\\
% \> \color{dumuxBlue}\textbf{endfor}\\
% \> \color{dumuxBlue} write result\\
% \color{black}\textbf{endfor}\\
% finalize
% \end{tabbing}
%
% \end{minipage}
% \end{tabular}

% \caption{Structure of a fully implicit (\textbf{left}) and a sequential
% (\textbf{right}) scheme in \Dumux.}
+\end{tabbing}}
+\end{center}
\caption{Structure of a monolithical solution scheme in \Dumux.}
\label{fig:algorithm}
\end{figure}
% \subsection{Structure  by Implementation}
% \label{implementation}
% This section is supposed to help you in getting an idea how things are handled in
% \Dumux and in which files things are written down.
% This is not intuitivly clear, therefore it is mentioned for each \fbox{stepstone}.
% \textbf{called by} tells you from which file a function is
% accessed. \textbf{implemented in} tells you in which file the function is written
% down. The name of the function is set in \verb+typewriter+.
% Being a function is indicated by round brackets \verb+()+ but only the function
% name is given and not the full signature (arguments...) .
% Comments regarding the events within one stepstone are set \scriptsize{smaller}.
%
% \begin{landscape}
% \pagestyle{empty} % switch off headings and footer in order to get more space for the flowchart
% \setlength{\voffset}{4.2cm}
%
% % command for blocks
% \newcommand{\step}[6]{
% \begin{minipage}{7.5cm}
% {\tiny \color{#1}\texttt{#2} $\Rightarrow$ \texttt{#3}}\\
% \fcolorbox{#1}{white}{
% \begin{minipage}{7.0cm}
% \begin{scriptsize}
% \texttt{#4} \hfill \color{gray}in: #5\color{black}\\
% \hphantom{m}\begin{minipage}[t]{6.8cm}#6\end{minipage}
% \end{scriptsize}
% \end{minipage}}
% \end{minipage}
% }
%
% % command for the arrow with text
% \newcommand{\longArrow}[1]{
% \begin{minipage}[b]{7.5cm}
% \fcolorbox{white}{white}{
% \begin{minipage}[b]{7.0cm}
% \begin{center}
% \begin{scriptsize}
% $\overrightarrow{ %an arrow under which things may be written
% \begin{array}{c} % in order to be able to write multiple lines under the arrow
% #1\\
% \hphantom{\hspace{6.5cm}}
% \end{array}
% }$
% \end{scriptsize}
% \end{center}
% \end{minipage}%
% }
% \end{minipage}%
% \hphantom{ $\overrightarrow{}$}%
% }
%
% % command for the arrow between steps
% \newcommand{\shortArrow}{$\overrightarrow{}$}
%
% % command for marking things as model specific
% \newcommand{\modelSpecific}{\emph{model specific}\xspace}
%
% % the distance between two lines
% \newcommand{\dummyDistance}{\\[4\baselineskip]}
%
% % THE FLOW CHART STARTS HERE
% \noindent
% \step{black}{main()}{Dumux::start() $\Rightarrow$ start\_()}{start\_()}{start.hh}%
% {start the simulation}
% \shortArrow
% \step{black}{start\_()}{timeManager.init()}{init()}{timemanager.hh}%
% {initialization}
% \shortArrow
% \step{black}{start\_()}{timeManager.run()}{run()}{timemanager.hh}%
% {time step management}
% \dummyDistance
% %
% \longArrow{
% \textnormal{\texttt{while(!finished)}}\\
% \textnormal{\color{black}main}
% \rightarrow \textnormal{\color{dumuxBlue}time step}
% }
% \step{dumuxBlue}{run()}{problem>timeIntegration()}{timeIntegration()}{implicitproblem.hh}%
% {execute time integration scheme}%
% \longArrow{
% \textnormal{define number of allowed \textsc{Newton} fails}\\
% \textnormal{(each halving dt)}
% }
% \dummyDistance
% %
% \step{dumuxBlue}{timeIntegration()}{model>update()}{update()}{implicitmodel.hh}%
% {sth like numerical model}
% \shortArrow
% \step{dumuxBlue}{update()}{solver.execute()}{execute()}{newtonmethod.hh}%
% {applying \textsc{Newton} method\\
% keeps track of things, catching errors}
% \longArrow{
% \textnormal{\color{dumuxBlue}time step}
% \rightarrow \textnormal{\color{Mulberry}Newton step}\\
% \texttt{while(ctl.newtonProceed()}\\
% \textnormal{uLastIter = uCurrentIter(model.uCur())}
% }
% \dummyDistance
% %
% \noindent
% \step{Mulberry}{execute() $\Rightarrow$ execute\_()}{jacobianAsm.assemble()}{assemble()}{implicitassembler.hh}%
% {linearize the problem:\\
% add all element contributions to global \textsc{Jacobian}
% and global residual}%
% \shortArrow
% \step{Mulberry}{assemble() $\Rightarrow$ asImp\_().assemble\_()}{resetSystem\_()}{resetSystem\_()}{implicitassembler.hh}%
% {set r.h.s. (i.e. residual)\\
% set \textsc{Jacobian} to zero }
% \longArrow{
% \textnormal{\color{Mulberry}Newton step}
% \rightarrow \textnormal{\color{dumuxYellow}element}\\
% \texttt{loop all elements}\\
% }
% \dummyDistance
% %
% \noindent
% \step{dumuxYellow}{assemble() $\Rightarrow$ asImp\_().assemble\_()}{asImp\_().assembleElement\_()}{assembleElement\_()}{e.g. boxassembler.hh}%
% {call local \textsc{Jacobian} and residual assembly}%
% \shortArrow
% \step{dumuxYellow}{assembleElement\_()}{model\_().localJacobian().assemble()}{assemble()}{implicitlocaljacobian.hh}%
% {set curr. element, update element's fin.vol.geom.\\
% reset local \textsc{Jacobian} to 0\\
% update types of boundaries on this element}%
% \shortArrow
% \step{dumuxYellow}{assemble()}{prevVolVars\_.update(),curVolVars\_.update()}{update()}{e.g. 2pvolumevariables.hh}%
% {call model (e.g. \texttt{2p})specific update of quantities defined for the volume:\\
% variables for the \emph{current} and \emph{previous} timestep}%
% \dummyDistance
% %
% \noindent
% \step{dumuxYellow}{update()}{completeFluidState()}{completeFluidState()}{e.g. 2pvolumevariables.hh}%
% {calculate all required fluid properties from the primary variables,
% here the fluid system does the real work:\\
% calculates, saves, and provides: densities, etc.}
% \shortArrow
% \step{dumuxYellow}{assemble()}{localResidual().eval()$\Rightarrow$asImp\_().eval()}{eval()}{e.g. implicitlocalresidual.hh}%
% {the element's local residual is calculated:\\
% see the next two stepstones}%
% \shortArrow
% \step{dumuxYellow}{eval()}{asImp\_().evalFluxes\_()}{evalFluxes\_()}{e.g. boxlocalresidual.hh}%
% {evaluate the fluxes going into each finite volume,
% this is \modelSpecific}
% \dummyDistance
% %
% \step{dumuxYellow}{evalFluxes\_()}{this$\rightarrow$asImp\_().computeFlux()}{computeFlux()}{e.g. 2plocalresidual.hh}%
% {this calculate the \modelSpecific fluxes (e.g. advective and diffusive)
% using the \texttt{FluxVariables}}
% \shortArrow
% \step{dumuxYellow}{eval()}{asImp\_().evalVolumeTerms\_()}{evalVolumeTerms\_()}{implicitlocalresidual.hh}%
% {evaluate the \modelSpecific storage and source terms for each finite volume}%
% \shortArrow
% \step{dumuxYellow}{eval()}{asImp\_().evalBoundary\_()}{evalBoundary\_()}{implicitlocalresidual.hh}%
% {evaluate the \modelSpecific boundary conditions}%
% \dummyDistance
% %
% \step{dumuxYellow}{assemble()}{asImp\_().evalPartialDerivative\_()}{evalPartialDerivative\_()}{e.g. implicitlocaljacobian.hh}%
% {actually calculate the element's (local) \textsc{Jacobian}\\
% matrix a property chooses backward/central/foward\\
% differences. here: central differences}
% \shortArrow
% \begin{minipage}{0.50\textwidth}
% \begin{scriptsize}\textnormal{approximation of partial derivatives: numerical differentiation}\end{scriptsize}\\
% \begin{scriptsize}\textnormal{add $\pm \epsilon$ solution, divide difference of residual by $2\epsilon$}\end{scriptsize}\\
% \begin{scriptsize}\textnormal{all partial derivatives for the element from the local \textsc{Jacobian} matrix}\end{scriptsize}\\
% $\left \lbrace
% \begin{tabular}{l}%these question marks are for the \verb, not meant as ``unclear''
% \verb?priVars[pvIdx]+=eps?\\
% \begin{scriptsize}\textnormal{this is adding eps to the current solution}\end{scriptsize}\\
% \verb?curVolVars_[scvIdx].update(+eps)?\\
% \begin{scriptsize}\textnormal{recalculate volume variables, having $\epsilon$ added}\end{scriptsize}\\
% \verb?localResidual().eval(+eps)?\\
% \begin{scriptsize}\textnormal{calculate local residual for modified solution as before: involves}\end{scriptsize}\\
% {\scriptsize $\begin{array}{l}
% \textnormal{ \textbf{computeFlux}}\\
% \textnormal{ \textbf{computeStorage}}\\
% \textnormal{ \textbf{computeSource}} \\
% \end{array}$} \\
% \verb?store the residual()?\\
% \verb?repeat for priVars[pvIdx]=eps?\\
% \verb?derivative is (residual(+eps)  residual(eps))/2eps?\\
% \end{tabular}
% \right .
% $
% \end{minipage}
% \dummyDistance
% %
% \step{dumuxYellow}{assemble\_()}{asImp\_().assembleElement\_()}{assembleElement\_()}{implicitassembler.hh}%
% {Residual of the current solution is now\\
% ``numerically differentiated'', for the element i.e.\\
% the local \textsc{Jacobian} matrix is calculated. }%
% \longArrow{
% \textnormal{The contribution of a single element is done.}\\
% \textnormal{Now, it needs to be added to the global quantities:}\\
% \textnormal{Add to global residual and global \textsc{Jacobian}}.}
% \step{dumuxYellow}{assemble\_()}{asImp\_().assembleElement\_()}{assembleElement\_()}{e.g. boxassembler.hh}
% {Add to global residual.:\\
% \texttt{resdidual\_[globI+=\\model\_().globalJacobian().resdidual(i)]}}
% \dummyDistance
% %
% \longArrow{
% \textnormal{loop vertices}\\
% \textnormal{of an element}
% }
% \step{dumuxYellow}{assemble\_()}{asImp\_().assembleElement\_()}{assembleElement\_()}{e.g. boxassembler.hh}
% {Add to global residual:\\
% \texttt{(*matrix\_)[globI][globJ] +=\\model\_().localJacobian().mat(i,j)}}
% \longArrow{
% \textbf{\textbf{\color{dumuxYellow}element}}
% \rightarrow \textbf{\color{Mulberry}Newton step}\\
% \textnormal{Assembling of elements to global quantities is done.}
% }
% \dummyDistance
% %
% \step{Mulberry}{execute\_()}{while(ctl.newtonProceed())}{newtonProceed()}{newtoncontroller.hh}%
% {Print information.\\
% Start/ stop timer.}%
%
% \longArrow{
% \textnormal{set delta Vector to zero} \\
% \textnormal{(this is what is}\\
% \textnormal{solved for later)}\\
% }
% \step{Mulberry}{execute\_()}{ctl.newtonSolveLinear()}{newtonSolveLinear()}{newtoncontroller.hh}%
% {Catching errors.\\
% Ask the linear solver to solve the system.\\
% i.e.: give \textsc{Jacobian}(matrix), delta(x), r.h.s.(residual) to linear solver\\
% $\nabla r(x^k) \cdot \Delta x^k = r(x^k)$\\
% tricky: each \textsc{Newton} step solves a linear system of equations.}%
% \shortArrow
% \step{Mulberry}{newtonSolveLinear()}{int converged = linearSolver\_.solve()}{solve()}{boxlinearsolver.hh}%
% {Solve the linear system with the chosen backend.}%
% \dummyDistance
% %
% \step{Mulberry}{execute\_()}{ctl.newtonUpdate()}{newtonUpdate()}{newtoncontroller.hh}%
% {We solved for the change in solution, but need the solution:\\
% Calculate current (this iteration) solution\\
% \quad from last (iteration) solution and current (iteration) change in solution:\\
% $x^{k+1} = x^k  \Delta x^k$ where $\Delta x^k = (\nabla r(x^k))^{1} \cdot r(x^k)$}
% \shortArrow
% \step{Mulberry}{execute\_()}{ctl.newtonEndStep()}{newtonEndStep()}{newtoncontroller.hh}%
% {Increase counter for number of \textsc{Newton} steps.\\
% Print info.}%
% \longArrow{
% \textnormal{check whether to do another \textsc{Newton} iteration:} \\
% \textnormal{that is: check if the error is below tolerance or}\\
% \textnormal{maximum number of iterations was reached.}
% }
% \dummyDistance
% %
% \longArrow{
% \textbf{\textbf{\color{Mulberry}Newton step}}
% \rightarrow \textbf{\color{dumuxBlue}Time step}\\
% \textnormal{\textsc{Newton} done}\\
% \textnormal{if failed $\rightsquigarrow$ halve timestep size, restart loop}\\
% }
% \step{dumuxBlue}{execute\_()}{ctl.newtonEnd()}{newtonEnd()}{newtoncontroller.hh}%
% {Tell the controller we are done}%
% \shortArrow
% \step{dumuxBlue}{update()}{asImp\_().updateSuccessful()}{updateSuccessful()}{e.g. implicitmodel.hh}%
% {can be filled \modelSpecific}%
% \dummyDistance
% %
% \longArrow{
% \textnormal{in while(!finished)}
% }
% \step{dumuxBlue}{run()}{problem\_>postTimeStep()}{postTimeStep(),writeOutput()}{implicitproblem.hh}%
% {Give the problem the chance to postprocess the solution.}%
% \longArrow{
% \textnormal{write output}\\
% \textnormal{uPrev $\leftarrow$ uCur}\\
% \textnormal{time += dt, timestepIdx++}\\
% \textnormal{deal with restart and episodes }
% }
% \dummyDistance
% %
% \step{dumuxBlue}{run()$\Rightarrow$setTimeStepSize(problem\_>nextTimeStepSize(dt))\\
% $\Rightarrow$nextTimeStepSize()}
% {newtonCtl\_.suggestTimestepSize()}{suggestTimestepSize()}{newtoncontroller.hh}%
% {Determine new time step size from number of \textsc{Newton} steps.}%
% \longArrow{
% \textbf{\color{dumuxBlue}Time step}
% \rightarrow \textbf{\color{black}main}\\
% \textnormal{loop until simulation is finished}
% }
%
% \end{landscape}
%
% \newpage
% % Original pagestyle (headings and footer) were switched off,
% % in order to get more space for the flowchart.
% \pagestyle{scrheadings}
% \normalsize
+\subsection{Structure  by Implementation}
+A possible starting point to understand how the abovementioned algorithm is implemented within \Dumux,
+is the example main file
+\url{https://git.iws.unistuttgart.de/dumuxrepositories/dumuxcourse/releases/3.0/exercises/exercisemainfile/exercise_1p_a.cc}
diff git a/doc/handbook/CMakeLists.txt b/doc/handbook/CMakeLists.txt
index ea2f0e6c6cfee59ffa8912e00154110383478cc5..5b3a54ea25982e5640bbc939e4e6cf579352b358 100644
 a/doc/handbook/CMakeLists.txt
+++ b/doc/handbook/CMakeLists.txt
@@ 4,31 +4,33 @@ set(TEX_INPUTS
1_introduction.tex
2_detailedinstall.tex
2_quickinstall.tex
 3_tutorial.tex
+ 3_course.tex
3_furtherpractice.tex
4_assemblinglinearsystem.tex
 4_guidelines.tex
4_developingdumux.tex
4_externaltools.tex
4_newfoldersetup.tex
4_parameterfiles.tex
4_restartsimulations.tex
4_structure.tex
 5_stepsofasimulation.tex
 5_grids.tex
+ 5_inputoutput.tex
5_models.tex
+ 5_parallel.tex
5_propertysystem.tex
5_spatialdiscretizations.tex
+ 5_stepsofasimulation.tex
installDumux.sh)
set(TEX_IMAGES
 PNG/box_disc.png
 PNG/cc_disc.png
 PNG/dumux_strucutre_flowchart_horizontal_explained.png
 PNG/dunedesign.png
+ png/box_disc.png
+ png/cctpfa.png
+ png/dumux_strucutre_flowchart_horizontal_explained.png
+ png/dunedesign.png
../logo/dumux_logo_hires_whitebg.png
 PNG/dalton1.png
 PNG/dalton2.png)
+ png/dalton1.png
+ png/dalton2.png
+ pdf/staggered_grid.pdf
+ png/mpfa_iv.png)
dune_add_latex_document(0_dumuxhandbook.tex
BIBFILES dumuxhandbook.bib
diff git a/doc/handbook/PNG/dalton1.png b/doc/handbook/PNG/dalton1.png
deleted file mode 100644
index f78081daeb94c010ee1986d1ea4523f4800dc530..0000000000000000000000000000000000000000
Binary files a/doc/handbook/PNG/dalton1.png and /dev/null differ
diff git a/doc/handbook/PNG/dalton2.png b/doc/handbook/PNG/dalton2.png
deleted file mode 100644
index 6d8a861bedadeb6cba69402e750fed07adafdfe3..0000000000000000000000000000000000000000
Binary files a/doc/handbook/PNG/dalton2.png and /dev/null differ
diff git a/doc/handbook/installDumux.sh b/doc/handbook/installDumux.sh
index bca2ab4612c51921a4048f3826fbda70edb282f2..74b14f05cb754c75aab1060ceca63cbc5c6a3d64 100644
 a/doc/handbook/installDumux.sh
+++ b/doc/handbook/installDumux.sh
@@ 11,22 +11,22 @@ echo "*************************************************"
# the core modules
for MOD in common geometry grid localfunctions istl; do
if [ ! d "dune$MOD" ]; then
 git clone b releases/2.5 https://gitlab.duneproject.org/core/dune$MOD.git
+ git clone b releases/2.6 https://gitlab.duneproject.org/core/dune$MOD.git
else
echo "Skip cloning dune$MOD because the folder already exists."
cd dune$MOD
 git checkout releases/2.5
+ git checkout releases/2.6
cd ..
fi
done
# dumux
if [ ! d "dumux" ]; then
 git clone b 3.0.0alpha https://git.iws.unistuttgart.de/dumuxrepositories/dumux.git
+ git clone b releases/3.0 https://git.iws.unistuttgart.de/dumuxrepositories/dumux.git
else
echo "Skip cloning dumux because the folder already exists."
cd dumux
 git checkout 3.0.0alpha
+ git checkout releases/3.0
cd ..
fi
@@ 42,7 +42,7 @@ echo "(2/2) Configure dune modules and dumux. Build the
dune libaries. This may take several minutes."
echo "*************************************************"
# run build
./dunecommon/bin/dunecontrol opts=dumux/myoptim.opts all
+./dunecommon/bin/dunecontrol opts=dumux/optim.opts all
#
if [ $? ne 0 ]; then
echo "*************************************************"
diff git a/doc/handbook/pdf/staggered_grid.pdf b/doc/handbook/pdf/staggered_grid.pdf
new file mode 100644
index 0000000000000000000000000000000000000000..35fd6e39ef023091f7745dc16e306560fc4dce10
Binary files /dev/null and b/doc/handbook/pdf/staggered_grid.pdf differ
diff git a/doc/handbook/PNG/box_disc.png b/doc/handbook/png/box_disc.png
similarity index 100%
rename from doc/handbook/PNG/box_disc.png
rename to doc/handbook/png/box_disc.png
diff git a/doc/handbook/PNG/cc_disc.png b/doc/handbook/png/cc_disc.png
similarity index 100%
rename from doc/handbook/PNG/cc_disc.png
rename to doc/handbook/png/cc_disc.png
diff git a/doc/handbook/png/cctpfa.png b/doc/handbook/png/cctpfa.png
new file mode 100644
index 0000000000000000000000000000000000000000..ef61ef9cba8a11c77cda9f2fa847b91c5a26f12e
Binary files /dev/null and b/doc/handbook/png/cctpfa.png differ
diff git a/doc/handbook/png/dalton1.png b/doc/handbook/png/dalton1.png
new file mode 100644
index 0000000000000000000000000000000000000000..b681e597953cffe3cae320f8d029188c5e187cab
Binary files /dev/null and b/doc/handbook/png/dalton1.png differ
diff git a/doc/handbook/png/dalton2.png b/doc/handbook/png/dalton2.png
new file mode 100644
index 0000000000000000000000000000000000000000..be04f04bfad603d43b39830d4174b3cc3749f913
Binary files /dev/null and b/doc/handbook/png/dalton2.png differ
diff git a/doc/handbook/PNG/dumux_strucutre_flowchart_horizontal_explained.png b/doc/handbook/png/dumux_strucutre_flowchart_horizontal_explained.png
similarity index 100%
rename from doc/handbook/PNG/dumux_strucutre_flowchart_horizontal_explained.png
rename to doc/handbook/png/dumux_strucutre_flowchart_horizontal_explained.png
diff git a/doc/handbook/PNG/dunedesign.png b/doc/handbook/png/dunedesign.png
similarity index 100%
rename from doc/handbook/PNG/dunedesign.png
rename to doc/handbook/png/dunedesign.png
diff git a/doc/handbook/png/mpfa_iv.png b/doc/handbook/png/mpfa_iv.png
new file mode 100644
index 0000000000000000000000000000000000000000..a54765dd8792a7e66b783696048467143c90cdec
Binary files /dev/null and b/doc/handbook/png/mpfa_iv.png differ
diff git a/doc/handbook/SVG/box_disc.svg b/doc/handbook/svg/box_disc.svg
similarity index 100%
rename from doc/handbook/SVG/box_disc.svg
rename to doc/handbook/svg/box_disc.svg
diff git a/doc/handbook/SVG/cc_disc.svg b/doc/handbook/svg/cc_disc.svg
similarity index 100%
rename from doc/handbook/SVG/cc_disc.svg
rename to doc/handbook/svg/cc_disc.svg
diff git a/doc/handbook/svg/cctpfa.svg b/doc/handbook/svg/cctpfa.svg
new file mode 100644
index 0000000000000000000000000000000000000000..490ab0a792c6faf5e8f196c3df9696449fb35c7d
 /dev/null
+++ b/doc/handbook/svg/cctpfa.svg
@@ 0,0 +1,800 @@
+
+
+
+
diff git a/doc/handbook/SVG/dalton1.svg b/doc/handbook/svg/dalton1.svg
similarity index 100%
rename from doc/handbook/SVG/dalton1.svg
rename to doc/handbook/svg/dalton1.svg
diff git a/doc/handbook/SVG/dalton2.svg b/doc/handbook/svg/dalton2.svg
similarity index 100%
rename from doc/handbook/SVG/dalton2.svg
rename to doc/handbook/svg/dalton2.svg
diff git a/doc/handbook/svg/mpfa_iv.svg b/doc/handbook/svg/mpfa_iv.svg
new file mode 100644
index 0000000000000000000000000000000000000000..5642e339cdb545b4a545efc3cea73f21c3886c51
 /dev/null
+++ b/doc/handbook/svg/mpfa_iv.svg
@@ 0,0 +1,2764 @@
+
+
+
+
diff git a/doc/handbook/svg/staggered_grid.svg b/doc/handbook/svg/staggered_grid.svg
new file mode 100644
index 0000000000000000000000000000000000000000..fce64bce78441c35e199bd708ad4fb3d8b6d9f40
 /dev/null
+++ b/doc/handbook/svg/staggered_grid.svg
@@ 0,0 +1,4525 @@
+
+
+
+