From cc391e21650e8347bec8f1e325cceee954baf8f0 Mon Sep 17 00:00:00 2001
From: =?UTF8?q?Dennis=20Gl=C3=A4ser?=
Date: Thu, 20 Dec 2018 15:38:36 +0000
Subject: [PATCH] Merge branch 'feature/cleanuphandbook' into 'master'
Feature/cleanup handbook
Closes #635
See merge request dumuxrepositories/dumux!1456
(cherry picked from commit 97589d56095893e4b2b29251d060344e6063c42e)
4ff969b2 [handbook] cleanup, restructure discretization
c00a1139 [handbook] rename files
2e56a9a5 [handbook] correct quick installation and cleanup

doc/handbook/0_dumuxhandbook.tex  36 +
doc/handbook/1_introduction.tex  8 +
doc/handbook/2_quickinstall.tex  25 +
...ailedinstall.tex => 3_detailedinstall.tex}  53 ++
doc/handbook/{3_course.tex => 4_course.tex}  0
...therpractice.tex => 4_furtherpractice.tex}  3 
...ystem.tex => 5_assemblinglinearsystem.tex}  0
...elopingdumux.tex => 5_developingdumux.tex}  0
..._externaltools.tex => 5_externaltools.tex}  31 +
...ewfoldersetup.tex => 5_newfoldersetup.tex}  4 +
...arameterfiles.tex => 5_parameterfiles.tex}  6 +
...mulations.tex => 5_restartsimulations.tex}  2 +
.../{4_structure.tex => 5_structure.tex}  7 +
doc/handbook/{5_models.tex => 6_basics.tex}  64 +
.../{5_inputoutput.tex => 6_inputoutput.tex}  4 +
.../{5_parallel.tex => 6_parallel.tex}  8 +
...ropertysystem.tex => 6_propertysystem.tex}  0
...tions.tex => 6_spatialdiscretizations.tex}  330 +++++++++
...imulation.tex => 6_stepsofasimulation.tex}  0
doc/handbook/6_temporaldiscretizations.tex  62 ++++
doc/handbook/CMakeLists.txt  33 +
doc/handbook/installDumux.sh  18 +
22 files changed, 329 insertions(+), 365 deletions()
rename doc/handbook/{2_detailedinstall.tex => 3_detailedinstall.tex} (87%)
rename doc/handbook/{3_course.tex => 4_course.tex} (100%)
rename doc/handbook/{3_furtherpractice.tex => 4_furtherpractice.tex} (94%)
rename doc/handbook/{4_assemblinglinearsystem.tex => 5_assemblinglinearsystem.tex} (100%)
rename doc/handbook/{4_developingdumux.tex => 5_developingdumux.tex} (100%)
rename doc/handbook/{4_externaltools.tex => 5_externaltools.tex} (70%)
rename doc/handbook/{4_newfoldersetup.tex => 5_newfoldersetup.tex} (95%)
rename doc/handbook/{4_parameterfiles.tex => 5_parameterfiles.tex} (96%)
rename doc/handbook/{4_restartsimulations.tex => 5_restartsimulations.tex} (98%)
rename doc/handbook/{4_structure.tex => 5_structure.tex} (96%)
rename doc/handbook/{5_models.tex => 6_basics.tex} (73%)
rename doc/handbook/{5_inputoutput.tex => 6_inputoutput.tex} (97%)
rename doc/handbook/{5_parallel.tex => 6_parallel.tex} (92%)
rename doc/handbook/{5_propertysystem.tex => 6_propertysystem.tex} (100%)
rename doc/handbook/{5_spatialdiscretizations.tex => 6_spatialdiscretizations.tex} (99%)
rename doc/handbook/{5_stepsofasimulation.tex => 6_stepsofasimulation.tex} (100%)
create mode 100644 doc/handbook/6_temporaldiscretizations.tex
diff git a/doc/handbook/0_dumuxhandbook.tex b/doc/handbook/0_dumuxhandbook.tex
index 7d8185ce9..9de687ab3 100644
 a/doc/handbook/0_dumuxhandbook.tex
+++ b/doc/handbook/0_dumuxhandbook.tex
@@ 115,17 +115,20 @@ Universit\"at Stuttgart, Paffenwaldring 61, D70569 Stuttgart, Germany}\\
In this chapter we provide a quick start guide to
your first \Dumux experience, including an install script with all necessary instructions
on how to very quickly install the latest release version of \Dumux.
+You should have a recent working Linux environment.
+If you need more information, please have a look at the detailed installation
+instructions in the next chapter \ref{detailedinstall}.
\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}
+\input{3_detailedinstall}
\chapter{Learning to use \Dumux}\label{chp:tutorial}
\input{3_course}
\input{3_furtherpractice}
+\input{4_course}
+\input{4_furtherpractice}
\chapter{Overview and Infrastructure}
This chapter provides an overview of the general structure in \Dumux \ref{sc_structure}
@@ 133,23 +136,24 @@ and gives help for basic work with \Dumux
(\ref{sc_newfoldersetup},\ref{sc_parameterfiles},\ref{sc_restartsimulations}, \ref{sc_developingdumux}).
Further it presents useful external tools \ref{sc_externaltools} and basic
concepts \ref{sc_linearsystem}.
\input{4_structure}
\input{4_newfoldersetup}
\input{4_parameterfiles}
\input{4_restartsimulations}
\input{4_developingdumux}
\input{4_externaltools}
\input{4_assemblinglinearsystem}
+\input{5_structure}
+\input{5_newfoldersetup}
+\input{5_parameterfiles}
+\input{5_restartsimulations}
+\input{5_developingdumux}
+\input{5_externaltools}
+\input{5_assemblinglinearsystem}
\chapter{Advanced \Dumux\  Detailed Instructions}
This chapter contains detailed information for those who are interested
in deeper modifications of underlying \Dumux models, classes, functions, etc.
\input{5_models}
\input{5_spatialdiscretizations}
\input{5_stepsofasimulation}
\input{5_propertysystem}
\input{5_inputoutput}
\input{5_parallel}
+\input{6_basics}
+\input{6_temporaldiscretizations}
+\input{6_spatialdiscretizations}
+\input{6_stepsofasimulation}
+\input{6_propertysystem}
+\input{6_inputoutput}
+\input{6_parallel}
\bibliographystyle{plainnat}
\bibliography{dumuxhandbook}
diff git a/doc/handbook/1_introduction.tex b/doc/handbook/1_introduction.tex
index 370786c3f..705d69242 100644
 a/doc/handbook/1_introduction.tex
+++ b/doc/handbook/1_introduction.tex
@@ 7,7 +7,7 @@ processor systems to highly parallel supercomputers with specialized
hardware architectures.
The means to achieve these somewhat contradictory goals are the
thorough use of object oriented design in conjunction with template
+thorough use of objectoriented design in conjunction with template
programming. These requirements call for \Cplusplus as the implementation
language.
@@ 37,7 +37,7 @@ DUNE's grid interface is independent of the spatial dimension of the
underlying grid. For this purpose, it uses the concept of
codimensional entities. Roughly speaking, an entity of codimension
$0$ constitutes a cell, codimension $1$ entities are faces between
cells, codimension $1$ are edges, and so on until codimension $n$
+cells, codimension $2$ are edges, and so on until codimension $n$
which are the cell's vertices. The \Dune grid interface generally
assumes that all entities are convex polytopes, which means that it
must be possible to express each entity as the convex hull of a set of
@@ 50,7 +50,7 @@ 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. A quick overview of reference elements and the
related numbering can be gotten from the DUNE cheat sheet
+related numbering can be obtained 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}.
@@ 66,7 +66,7 @@ solving the generated systems.
\Dumux comes in form of an additional module \texttt{dumux}.
It depends on the \Dune core modules
\texttt{dunecommon}, \texttt{dunegrid}, \texttt{duneistl}, and on \texttt{dunelocalfunctions}.
+\texttt{dunecommon}, \texttt{dunegrid}, \texttt{duneistl}, and \texttt{dunelocalfunctions}.
The main intention of \Dumux is to provide a framework for an easy and efficient
implementation of new physical models for porous media flow problems,
ranging from problem formulation and the selection of
diff git a/doc/handbook/2_quickinstall.tex b/doc/handbook/2_quickinstall.tex
index b7bf33fb4..668f22ca4 100644
 a/doc/handbook/2_quickinstall.tex
+++ b/doc/handbook/2_quickinstall.tex
@@ 1,9 +1,3 @@
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 the more detailed intructions in the next chapter \ref{detailedinstall}.

\section{Prerequisites} \label{sec:prerequisites}
For this quick start guide the following software packages are required:
\begin{itemize}
@@ 11,16 +5,13 @@ For this quick start guide the following software packages are required:
\item A standard compliant C++ compiler supporting C++11 and the C++14 feature set of GCC 4.9. We support GCC 4.9 or newer and Clang 3.8 or newer.
\item CMake 2.8.12 or newer
\item pkgconfig
\item paraview (to visualize the results)
+\item ParaView (to visualize the results)
\end{itemize}
\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
% It is available after obtaining a download link via \url{http://www.dumux.org/download/} or
% by copying the following lines into a textfile named \texttt{installDumux.sh}:
Copy the following lines into a textfile named \texttt{installDumux.sh}:
+Copy the following lines into a text file named \texttt{installDumux.sh}:
\lstinputlisting[style=DumuxCode, numbersep=5pt, firstline=1, firstnumber=1]{installDumux.sh}
Place the \texttt{installDumux.sh} script in the directory where you want to install \Dumux and \Dune (a single
@@ 34,13 +25,15 @@ More details about the buildsystem can be found in section \ref{buildIt}.
\subsection{A first test run of \Dumux}
When the \texttt{installDumux.sh} script from the subsection above has run successfully, you can execute a second script that
will compile and run a simple onephase ground water flow example and will visualize the result using ParaView.
The test script can be obtained by copying the following lines into a textfile named \texttt{test\_dumux.sh}
+The test script can be obtained by copying the following lines into a text file named \texttt{test\_dumux.sh}
that has to be located in the same directory as the installation script.
\begin{lstlisting}[style=DumuxCode]
cd DUMUX/dumux/buildcmake/test/porousmediumflow/1p/implicit
make B test_1pcctpfa
./test_1pcctpfa test_1pcctpfa.input
+cd DUMUX/dumux/buildcmake/test/porousmediumflow/1p/implicit/isothermal
+make B test_1p_tpfa
+./test_1p_tpfa params.input
paraview *pvd
\end{lstlisting}
The script \texttt{test\_dumux.sh} can be executed by typing into the terminal: \texttt{./test\_dumux.sh}.
If everything works fine, a ParaView window with the result should open automatically.
+If everything works fine, a ParaView window with the result should open automatically, showing the initial
+conditions. Advance ParaView to the next frame (green arrow button) and rescale to data range to admire
+the colorful pressure distribution.
diff git a/doc/handbook/2_detailedinstall.tex b/doc/handbook/3_detailedinstall.tex
similarity index 87%
rename from doc/handbook/2_detailedinstall.tex
rename to doc/handbook/3_detailedinstall.tex
index aa0daddce..8abe54e97 100644
 a/doc/handbook/2_detailedinstall.tex
+++ b/doc/handbook/3_detailedinstall.tex
@@ 1,13 +1,10 @@
% \section{Detailed Installation Instructions}
% \label{install}

Installing \Dumux means that you first unpack \Dune and \Dumux in a root directory,
(section \ref{sc:ObtainingSourceCode}).
In a second step of the installation, all modules are configured with CMake
(section \ref{buildIt}).
After successful installation of \Dumux we guide you to start a test application,
+After successful installation of \Dumux, we guide you to start a test application,
described in section \ref{quickstartguide}.
In section \ref{sec:builddoxydoc} we explain how to build the \Dumux documentation.
+In section \ref{sec:builddoc} we explain how to build the \Dumux documentation.
Lastly, section \ref{sec:externalmoduleslibraries} provides details on optional libraries and modules.
In a technical sense \Dumux is a module of \Dune.
@@ 18,31 +15,28 @@ Details regarding the installation of \Dune are provided on the \Dune website \c
\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.6, comprising the core modules dunecommon, dunegeometry, dunegrid,
duneistl and dunelocalfunctions. For working with \Dumux, these modules are required.
+\Dune release 2.6, comprising the core modules \texttt{dunecommon}, \texttt{dunegeometry},
+\texttt{dunegrid}, \texttt{duneistl} and \texttt{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.
We usually name our root directory \texttt{DUMUX} but an arbitrary name can be chosen.
Source code files for each \Dune module are contained in their own subdirectory within the root directory.
The subdirectories for the modules are named after the module names (depending on how
the modules were obtained a version number is added to the module name).
+the modules were obtained, a version number is added to the module name).
The name of each \Dune module is defined in the file \texttt{dune.module}, which is
in the root directory of the respective module. This should not be changed by the user.
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.
+Secondly, the most recent source code
+(or, more generally, any of its previous revisions) can be obtained by direct access
+to the software repositories of the revision control system. This is described in the second paragraph.
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
@@ 75,7 +69,7 @@ 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.
It is easier to keep up with code changes and to receive important bug fixes.
\Dune and \Dumux use Git for their software repositories. To access them a Git client is needed.
+\Dune and \Dumux use Git for their software repositories. To access them, a Git client is needed.
In the technical language of Git, \emph{cloning a certain software version} means nothing more then fetching
a local copy from the software repository and laying it out in the file system.
@@ 144,7 +138,7 @@ Configuring \Dune and \Dumux is done by the shellcommand \texttt{dunecontrol} w
If you are interested in more details about the build system that is used,
they can be found in the \Dune build system 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,
+If something fails during the execution of \texttt{dunecontrol}, feel free to report it to the \Dune or \Dumux developer mailing list,
but please include error details.
It is possible to compile \Dumux with nearly no explicit options to the build system.
@@ 170,7 +164,7 @@ 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.
The option files above are to be understood more as a starting point
+The option file that comes with the distribution is to be understood more as a starting point
for setting up an own customization than as something which is fixed.
The use of external libraries can make it necessary to add quite many options in an option file.
It can be helpful to give your customized option file its own name, as done above,
@@ 185,9 +179,6 @@ All executables are compiled in the \texttt{build} subdirectories of \Dumux.
If not specified differently in the options file, this is \texttt{buildcmake} as default.
\begin{enumerate}
\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 params.input}
@@ 196,16 +187,16 @@ If not specified differently in the options file, this is \texttt{buildcmake} a
important runtime parameters (like first time step 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{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
+\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$>$.
\item You can display the results using the visualization tool ParaView (or
alternatively VisIt). Just type \texttt{paraview} in the console and open the
 .pvd file. On the left hand side, you can choose the desired parameter to be displayed.
+ PVD file. On the left hand side, you can choose the desired parameter to be displayed.
\end{enumerate}
\section{Building Documentation}

+\label{sec:builddoc}
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}
@@ 213,13 +204,13 @@ in the \texttt{CONFIGURE\_FLAGS} of the building options, see section \ref{build
\subsection{Doxygen}
\label{sec:builddoxydoc}
Doxygen documentation is done by especially formatted comments integrated in the source code,
+Doxygen documentation is done by specifically formatted comments integrated in the source code,
which can get extracted by the program \texttt{doxygen}. Beside extracting these comments,
\texttt{doxygen} builds up a webbrowsable code structure documentation
like class hierarchy of code displayed as graphs, see \url{http://www.stack.nl/~dimitri/doxygen/}.
The Doxygen documentation of a module can be built, if \texttt{doxygen} is installed,
by running \texttt{dunecontrol}, entering the \texttt{build*}directory, and execute
+The Doxygen documentation of a module can be built if \texttt{doxygen} is installed,
+by running \texttt{dunecontrol}, entering the \texttt{build*}directory, and executing
\texttt{make doc}. Then point your web browser to the file
\texttt{MODULE\_BUILD\_DIRECTORY/doc/doxygen/html/index.html} to read the generated documentation.
This should also work for other \Dune modules.
@@ 231,9 +222,9 @@ in \texttt{MODULE\_BUILD\_DIRECTORY/doc/handbook/0\_dumuxhandbook.pdf}.
\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%
+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/}}.
If you are going to use an external \Dune module the website on external modules%
+If you are going to use an external \Dune module, the website on external modules%
\footnote{DUNE: External modules, \url{https://www.duneproject.org/groups/external/}}
can be helpful.
@@ 307,5 +298,5 @@ depending on which modules of \Dune and which external libraries you use.
\item \textbf{Compilers}: Beside \texttt{g++}, \Dune can be built with Clang from the LLVM project and
Intel \Cplusplus compiler. C and Fortran compilers are needed for some external libraries. As code of
 different compilers is linked together they have to be be compatible with each other.
+ different compilers is linked together, they have to be be compatible with each other.
\end{itemize}
diff git a/doc/handbook/3_course.tex b/doc/handbook/4_course.tex
similarity index 100%
rename from doc/handbook/3_course.tex
rename to doc/handbook/4_course.tex
diff git a/doc/handbook/3_furtherpractice.tex b/doc/handbook/4_furtherpractice.tex
similarity index 94%
rename from doc/handbook/3_furtherpractice.tex
rename to doc/handbook/4_furtherpractice.tex
index 30543e92b..d31e227e7 100644
 a/doc/handbook/3_furtherpractice.tex
+++ b/doc/handbook/4_furtherpractice.tex
@@ 5,7 +5,6 @@ If there is a need for further practice, we refer here to the test problems that
are already implemented in \Dumux. Several examples for all models
can be found in the \texttt{test}directory. An overview over the available test
cases can be found in the class documentation \url{http://www.dumux.org/documentation.php}.
% There you also find a \emph{featurelist} for the individual tests.%TODO
Another possibility to gain more experience with \Dumux is the \texttt{dumuxlecture} module
that contains different application examples that are used in the lectures at the
@@ 14,8 +13,6 @@ The \texttt{dumuxlecture} module can be obtained as follows:
\begin{lstlisting}[style=Bash]
$ git clone https://git.iws.unistuttgart.de/dumuxrepositories/dumuxlecture.git
\end{lstlisting}
% TODO: remove again as soon as invalid:
Note that \texttt{dumuxlecture} is currently only compatible with the \Dumux release 2.12.
The module is structured based on the different lectures:
\begin{itemize}
diff git a/doc/handbook/4_assemblinglinearsystem.tex b/doc/handbook/5_assemblinglinearsystem.tex
similarity index 100%
rename from doc/handbook/4_assemblinglinearsystem.tex
rename to doc/handbook/5_assemblinglinearsystem.tex
diff git a/doc/handbook/4_developingdumux.tex b/doc/handbook/5_developingdumux.tex
similarity index 100%
rename from doc/handbook/4_developingdumux.tex
rename to doc/handbook/5_developingdumux.tex
diff git a/doc/handbook/4_externaltools.tex b/doc/handbook/5_externaltools.tex
similarity index 70%
rename from doc/handbook/4_externaltools.tex
rename to doc/handbook/5_externaltools.tex
index a1ec44197..dee059dc1 100644
 a/doc/handbook/4_externaltools.tex
+++ b/doc/handbook/5_externaltools.tex
@@ 1,30 +1,19 @@
\section{External Tools}
\label{sc_externaltools}
\subsection{Eclipse}
There is an Eclipse style file which can be used for \Dumux.
\begin{enumerate}
 \item open in eclipse: \texttt{Window} $\rightarrow$ \texttt{Preferences} $\rightarrow$
 \texttt{C/C++} $\rightarrow$ \texttt{Code Style} $\rightarrow$ \texttt{Formatter}
 \item press the \texttt{Import} button
 \item choose the file \texttt{eclipse\_profile.xml} from your dumuxdevel directory
 \item make sure that now \Dumux is chosen in \texttt{Select a profile}
\end{enumerate}


\subsection{Git}
Git is a version control tool which we use.
The basic Git commands are:
\begin{itemize}
 \item \texttt{git checkout} receive a specified branch from the repository
 \item \texttt{git clone} clone a repository; creates a local copy
 \item \texttt{git diff} to see the actual changes compared to your last commit
 \item \texttt{git pull} pull changes from the repository; synchronizes the
+ \item \texttt{git checkout}: receive a specified branch from the repository
+ \item \texttt{git clone}: clone a repository; creates a local copy
+ \item \texttt{git diff}: to see the actual changes compared to your last commit
+ \item \texttt{git pull}: pull changes from the repository; synchronizes the
repository with your local copy
 \item \texttt{git push} push comitted changes to the repository; synchronizes
+ \item \texttt{git push}: push comitted changes to the repository; synchronizes
your local copy with the repository
 \item \texttt{git status} to check which files/folders have been changed
 \item \texttt{git gui} graphical user interface, helps selecting changes for
+ \item \texttt{git status}: to check which files/folders have been changed
+ \item \texttt{git gui}: graphical user interface, helps selecting changes for
a commit
\end{itemize}
@@ 78,13 +67,13 @@ path where gstat is installed).
\subsection{ParaView}
\paragraph{Reload Button:}
There are scripts to reload \texttt{*.pvd} or series of {\texttt{*.vtu} files since ParaView 4.2.
+There are scripts to reload PVD or series of VTU files since ParaView 4.2.
The scripts can be found
\href{http://markmail.org/message/exxynsgishbvtngg#query:+page:1+mid:rxlwxs7uqrfgibyv+state:results}{\texttt{under this link}}.
Just save the specific code portion in a file and load it via \texttt{Macros} $\rightarrow$ \texttt{Add new macro}.
\paragraph{Guide:}
Since ParaView 4.3.1 The ParaView Guide is partly
+Since ParaView 4.3.1, The ParaView Guide is partly
available for free download, see \url{http://www.paraview.org/documentation/}.
It corresponds to the ParaView book, only without three application chapters.
+It corresponds to the ParaView book, only three application chapters short.
Attention, its size is 180 MiB.
diff git a/doc/handbook/4_newfoldersetup.tex b/doc/handbook/5_newfoldersetup.tex
similarity index 95%
rename from doc/handbook/4_newfoldersetup.tex
rename to doc/handbook/5_newfoldersetup.tex
index 593dbe522..ea26767b4 100644
 a/doc/handbook/4_newfoldersetup.tex
+++ b/doc/handbook/5_newfoldersetup.tex
@@ 18,10 +18,10 @@ The macro can be used with a variable amount of arguments. A simple call could l
\begin{lstlisting}[style=DumuxCode]
dune_add_test(NAME my_test
 SOURCES mainfile.cc
+ SOURCES main.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}.
+Here, we create an executable called \texttt{my\_test} from a source file \texttt{main.cc}.
The name of the test will also be \texttt{my\_test} (has to be unique). The last argument specifies a command  here, we just run the executable \texttt{my\_test} with an input file \texttt{params.input}. For more advanced uses of
the \texttt{add\_dune\_test} macro, have a look at the \texttt{test} directory. A complete documentation is given under \url{https://www.duneproject.org/sphinx/core2.5/}.
diff git a/doc/handbook/4_parameterfiles.tex b/doc/handbook/5_parameterfiles.tex
similarity index 96%
rename from doc/handbook/4_parameterfiles.tex
rename to doc/handbook/5_parameterfiles.tex
index 7bddd051e..f6f615891 100644
 a/doc/handbook/4_parameterfiles.tex
+++ b/doc/handbook/5_parameterfiles.tex
@@ 11,6 +11,8 @@ get the following output at the end of the simulation run
[ Grid ]
Cells = "48 32"
UpperRight = "6 4"
+[ Newton ]
+EnablePartialReassembly = "true"
[ Problem ]
EnableGravity = "true"
Name = "2p"
@@ 21,7 +23,7 @@ LensUpperRight = "4.0 3.0"
DtInitial = "250"
TEnd = "3000"
# Default parameters used:
+# Global default parameters used:
[ Assembly ]
NumericDifferenceMethod = "1"
[ Flux ]
@@ 34,6 +36,7 @@ ResidualReduction = "1e13"
Verbosity = "0"
[ Newton ]
EnableAbsoluteResidualCriterion = "false"
+EnableChop = "false"
EnableResidualCriterion = "false"
EnableShiftCriterion = "true"
MaxAbsoluteResidual = "1e5"
@@ 44,7 +47,6 @@ SatisfyResidualAndShiftCriterion = "false"
TargetSteps = "10"
UseLineSearch = "false"
[ TimeLoop ]
MaxTimeStepDivisions = "10"
MaxTimeStepSize = "1e300"
[ Vtk ]
AddProcessRank = "true"
diff git a/doc/handbook/4_restartsimulations.tex b/doc/handbook/5_restartsimulations.tex
similarity index 98%
rename from doc/handbook/4_restartsimulations.tex
rename to doc/handbook/5_restartsimulations.tex
index fbd12fe9f..80b769da4 100644
 a/doc/handbook/4_restartsimulations.tex
+++ b/doc/handbook/5_restartsimulations.tex
@@ 15,5 +15,5 @@ Unfortunately, writing doubleprecision floating point numbers to VTK files is o
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.
+The restart capabilities will hopefully be improved in future versions of \Dumux3.
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/5_structure.tex
similarity index 96%
rename from doc/handbook/4_structure.tex
rename to doc/handbook/5_structure.tex
index 30f85bfa6..a4146b5af 100644
 a/doc/handbook/4_structure.tex
+++ b/doc/handbook/5_structure.tex
@@ 6,13 +6,14 @@
\item \texttt{bin}: binaries, e.g. used for the automatic testing, postprocessing, installation
\item \texttt{cmake}: the configuration options for building \Dumux
\item \texttt{doc}: files necessary for the Doxygen documentation and this handbook, and various logos
\item \texttt{dumux}: the main folder, containing the source files. see \ref{fig:dumuxstructure}
+\item \texttt{dumux}: the main folder, containing the source files. See \ref{fig:dumuxstructure}
for a visualized structure. For more information on the models have a look at the
Doxygen documentation.
\item \texttt{test}: tests for each numerical model and some functionality.
The structure is equivalent to the \texttt{dumux} folder, the \texttt{references} folder
 contains solutions for the automatic testing. Each test program consist of source
 \texttt{*.cc}, the problem definition \texttt{*problem.hh}, and an input file \texttt{*.input}.
+ contains solutions for the automatic testing. Each test program consist of a main file
+ \texttt{main.cc}, the problem definition \texttt{*problem.hh} (specifying initial and boundary
+ conditions), and an input file \texttt{params.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.
\end{itemize}
diff git a/doc/handbook/5_models.tex b/doc/handbook/6_basics.tex
similarity index 73%
rename from doc/handbook/5_models.tex
rename to doc/handbook/6_basics.tex
index 0d864377e..a6ec76568 100644
 a/doc/handbook/5_models.tex
+++ b/doc/handbook/6_basics.tex
@@ 1,8 +1,9 @@
\section{Models}
+\section{Physical Basics}
Here the basic definitions, the general models concept, and a list of
models available in \Dumux are given. The actual differential equations
can be found in the local residuals (see Doxygen documentation of the
model's \texttt{LocalResidual} class).
+%TODO: Add more physics
\subsection{Basic Definitions and Assumptions}
The basic definitions and assumptions are made, using the example
@@ 202,64 +203,3 @@ A list of all available models can be found
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{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.
The basic idea of the sequential algorithm is to reformulate the
equations of multiphase flow into one equation for
pressure and equations for phase/component/... transport. The pressure equation
is the sum of the mass balance equations and thus considers the total flow of the
fluid system. The new set of equations is considered as decoupled (or weakly coupled)
and can thus be solved sequentially. The most popular sequential model is the
fractional flow formulation for twophase flow which is usually implemented applying
an IMplicit Pressure Explicit Saturation algorithm (IMPES).
In comparison to solving the equations monolithically, the sequential structure allows the use of
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 (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_inputoutput.tex b/doc/handbook/6_inputoutput.tex
similarity index 97%
rename from doc/handbook/5_inputoutput.tex
rename to doc/handbook/6_inputoutput.tex
index 91c9c58d7..33ad270bc 100644
 a/doc/handbook/5_inputoutput.tex
+++ b/doc/handbook/6_inputoutput.tex
@@ 120,9 +120,9 @@ For all available parameters see the Doxygen documentation.
\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
+For every printout step, a single 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 PVD file groups the single 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}
diff git a/doc/handbook/5_parallel.tex b/doc/handbook/6_parallel.tex
similarity index 92%
rename from doc/handbook/5_parallel.tex
rename to doc/handbook/6_parallel.tex
index 10fd57d64..ba4a3580a 100644
 a/doc/handbook/5_parallel.tex
+++ b/doc/handbook/6_parallel.tex
@@ 17,7 +17,7 @@ data from other ranks. The domain decomposition in Dune is handled by the grid m
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
+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.
@@ 62,9 +62,9 @@ submit a job. Check with your cluster administrator how to run parallel applicat
\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.
+During a simulation, one VTU file is written for every output step.
+In the parallel case, one VTU file 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
+after the computation. The parallel VTU files 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/6_propertysystem.tex
similarity index 100%
rename from doc/handbook/5_propertysystem.tex
rename to doc/handbook/6_propertysystem.tex
diff git a/doc/handbook/5_spatialdiscretizations.tex b/doc/handbook/6_spatialdiscretizations.tex
similarity index 99%
rename from doc/handbook/5_spatialdiscretizations.tex
rename to doc/handbook/6_spatialdiscretizations.tex
index fbf9a4f6d..48237edcc 100644
 a/doc/handbook/5_spatialdiscretizations.tex
+++ b/doc/handbook/6_spatialdiscretizations.tex
@@ 1,12 +1,173 @@
\section{Spatial Discretization Schemes}
+\section{Spatial Discretization}
\label{spatialdiscretization}
We discretize space with cellcentered finite volume methods (\ref{cc} ), the box method (\ref{box})
or a staggered grid scheme.
+or a staggered grid scheme (\ref{staggered}).
Grid adaption is available for both box and cellcentered finite volume method.
In general, the spatial parameters, especially the porosity, have to be assigned on
the coarsest level of discretization.
+%
+\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}
+ \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}
+
+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}
+ \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}
+
+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/cctpfa.png}
+\caption{Two neighboring control volumes sharing the face $\sigma$.}
+\label{pc:cctpfa}
+\end{figure}
+
+
+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]{pdf/mpfa_iv.pdf}
+\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$.
+%
+%
\subsection{Box Method  A Short Introduction}\label{box}
The so called box method unites the advantages of the finitevolume (FV) and
@@ 170,170 +331,7 @@ flow and transport equations:
\; \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$.

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

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

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/cctpfa.png}
\caption{Two neighboring control volumes sharing the face $\sigma$.}
\label{pc:cctpfa}
\end{figure}


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]{pdf/mpfa_iv.pdf}
\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

+%
\subsection{Staggered Grid  A Short Introduction}\label{staggered}
\begin{figure}[ht]
diff git a/doc/handbook/5_stepsofasimulation.tex b/doc/handbook/6_stepsofasimulation.tex
similarity index 100%
rename from doc/handbook/5_stepsofasimulation.tex
rename to doc/handbook/6_stepsofasimulation.tex
diff git a/doc/handbook/6_temporaldiscretizations.tex b/doc/handbook/6_temporaldiscretizations.tex
new file mode 100644
index 000000000..fd424205b
 /dev/null
+++ b/doc/handbook/6_temporaldiscretizations.tex
@@ 0,0 +1,62 @@
+\section{Temporal Discretization and Solution Strategies}
+%TODO: Intro sentences
+\subsection{Temporal 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.
+
+\subsection{Solution strategies to solve equations}
+The governing equations of each model can be solved monolithically or sequentially.
+The basic idea of the sequential algorithm is to reformulate the
+equations of multiphase flow into one equation for
+pressure and equations for phase/component/... transport. The pressure equation
+is the sum of the mass balance equations and thus considers the total flow of the
+fluid system. The new set of equations is considered as decoupled (or weakly coupled)
+and can thus be solved sequentially. The most popular sequential model is the
+fractional flow formulation for twophase flow which is usually implemented applying
+an IMplicit Pressure Explicit Saturation algorithm (IMPES).
+In comparison to solving the equations monolithically, the sequential structure allows the use of
+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 (MpfaO method) and mimetic finite differences.
+An $h$adaptive implementation of both sequential algorithms is provided for two dimensions.
diff git a/doc/handbook/CMakeLists.txt b/doc/handbook/CMakeLists.txt
index b9bd427d0..be113ebe7 100644
 a/doc/handbook/CMakeLists.txt
+++ b/doc/handbook/CMakeLists.txt
@@ 2,23 +2,24 @@ set(TEX_INPUTS
0_dumuxhandbook.tex
0_listingstyle.tex
1_introduction.tex
 2_detailedinstall.tex
2_quickinstall.tex
 3_course.tex
 3_furtherpractice.tex
 4_assemblinglinearsystem.tex
 4_developingdumux.tex
 4_externaltools.tex
 4_newfoldersetup.tex
 4_parameterfiles.tex
 4_restartsimulations.tex
 4_structure.tex
 5_inputoutput.tex
 5_models.tex
 5_parallel.tex
 5_propertysystem.tex
 5_spatialdiscretizations.tex
 5_stepsofasimulation.tex
+ 3_detailedinstall.tex
+ 4_course.tex
+ 4_furtherpractice.tex
+ 5_assemblinglinearsystem.tex
+ 5_developingdumux.tex
+ 5_externaltools.tex
+ 5_newfoldersetup.tex
+ 5_parameterfiles.tex
+ 5_restartsimulations.tex
+ 5_structure.tex
+ 6_basics.tex
+ 6_inputoutput.tex
+ 6_parallel.tex
+ 6_propertysystem.tex
+ 6_spatialdiscretizations.tex
+ 6_stepsofasimulation.tex
+ 6_temporaldiscretizations.tex
installDumux.sh)
set(TEX_IMAGES
diff git a/doc/handbook/installDumux.sh b/doc/handbook/installDumux.sh
index 0e84314cc..60295e508 100644
 a/doc/handbook/installDumux.sh
+++ b/doc/handbook/installDumux.sh
@@ 10,25 +10,11 @@ Make sure to be connected to the internet."
echo "*************************************************"
# the core modules
for MOD in common geometry grid localfunctions istl; do
 if [ ! d "dune$MOD" ]; then
 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.6
 cd ..
 fi
+ git clone b releases/2.6 https://gitlab.duneproject.org/core/dune$MOD.git
done
# dumux
if [ ! d "dumux" ]; then
 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 releases/3.0
 cd ..
fi
+git clone b releases/3.0 https://git.iws.unistuttgart.de/dumuxrepositories/dumux.git
if [ $? ne 0 ]; then
echo "*************************************************"

2.22.0