From 4ff969b25a63a1d2537973fc84c428da8dc22e93 Mon Sep 17 00:00:00 2001
From: Beatrix Becker <beatrix.becker@iws.uni-stuttgart.de>
Date: Thu, 20 Dec 2018 14:13:15 +0100
Subject: [PATCH] [handbook] cleanup, restructure discretization
---
doc/handbook/0_dumux-handbook.tex | 7 +-
doc/handbook/1_introduction.tex | 8 +-
doc/handbook/2_detailedinstall.tex | 53 ++--
doc/handbook/2_quickinstall.tex | 25 +-
doc/handbook/3_furtherpractice.tex | 3 -
doc/handbook/4_externaltools.tex | 31 +-
doc/handbook/4_newfoldersetup.tex | 4 +-
doc/handbook/4_parameterfiles.tex | 6 +-
doc/handbook/4_restartsimulations.tex | 2 +-
doc/handbook/4_structure.tex | 7 +-
doc/handbook/{5_models.tex => 5_basics.tex} | 64 +---
doc/handbook/5_inputoutput.tex | 4 +-
doc/handbook/5_parallel.tex | 8 +-
doc/handbook/5_spatialdiscretizations.tex | 330 ++++++++++----------
doc/handbook/5_temporaldiscretizations.tex | 62 ++++
doc/handbook/CMakeLists.txt | 3 +-
16 files changed, 298 insertions(+), 319 deletions(-)
rename doc/handbook/{5_models.tex => 5_basics.tex} (73%)
create mode 100644 doc/handbook/5_temporaldiscretizations.tex
diff --git a/doc/handbook/0_dumux-handbook.tex b/doc/handbook/0_dumux-handbook.tex
index 7d8185ce93..b8bf6d986b 100644
--- a/doc/handbook/0_dumux-handbook.tex
+++ b/doc/handbook/0_dumux-handbook.tex
@@ -115,6 +115,10 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 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 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 next chapter \ref{detailed-install}.
\input{2_quickinstall}
\chapter{Detailed Installation, Documentation, and Externals}\label{detailed-install}
@@ -144,7 +148,8 @@ concepts \ref{sc_linearsystem}.
\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_basics}
+\input{5_temporaldiscretizations}
\input{5_spatialdiscretizations}
\input{5_stepsofasimulation}
\input{5_propertysystem}
diff --git a/doc/handbook/1_introduction.tex b/doc/handbook/1_introduction.tex
index 370786c3f5..705d692420 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 object-oriented 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
co-dimensional entities. Roughly speaking, an entity of co-dimension
$0$ constitutes a cell, co-dimension $1$ entities are faces between
-cells, co-dimension $1$ are edges, and so on until co-dimension $n$
+cells, co-dimension $2$ are edges, and so on until co-dimension $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.dune-project.org/pdf/dune-cheat-sheet.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{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, and on \texttt{dune-localfunctions}.
+\texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, and \texttt{dune-localfunctions}.
The main intention of \Dumux is to provide a framework for an easy and efficient
implementation of new physical models for porous media flow problems,
ranging from problem formulation and the selection of
diff --git a/doc/handbook/2_detailedinstall.tex b/doc/handbook/2_detailedinstall.tex
index aa0daddce1..8abe54e971 100644
--- a/doc/handbook/2_detailedinstall.tex
+++ b/doc/handbook/2_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{quick-start-guide}.
-In section \ref{sec:build-doxy-doc} we explain how to build the \Dumux documentation.
+In section \ref{sec:build-doc} we explain how to build the \Dumux documentation.
Lastly, section \ref{sec:external-modules-libraries} 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 dune-common, dune-geometry, dune-grid,
-dune-istl and dune-localfunctions. For working with \Dumux, these modules are required.
+\Dune release 2.6, comprising the core modules \texttt{dune-common}, \texttt{dune-geometry},
+\texttt{dune-grid}, \texttt{dune-istl} and \texttt{dune-localfunctions}.
+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 sub-directory within the root directory.
The sub-directories 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{dumux-devel} or the external libraries from \texttt{dumux-external} 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 old-fashionedly named tape-archive-file, 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 shell-command \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.dune-project.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} sub-directories of \Dumux.
If not specified differently in the options file, this is \texttt{build-cmake} as default.
\begin{enumerate}
-\item Go to the directory \texttt{build-cmake/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{build-cmake} a
important run-time 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:build-doc}
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{--disable-documentation}
@@ -213,13 +204,13 @@ in the \texttt{CONFIGURE\_FLAGS} of the building options, see section \ref{build
\subsection{Doxygen}
\label{sec:build-doxy-doc}
-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 web-browsable code structure documentation
like class hierarchy of code displayed as graphs, see \url{http://www.stack.nl/~dimitri/doxygen/}.
-The Doxygen documentation of a module can be built, if \texttt{doxygen} is installed,
-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\_dumux-handbook.pdf}.
\section{External Libraries and Modules} \label{sec:external-modules-libraries}
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.dune-project.org/doc/external-libraries/}}.
-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.dune-project.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/2_quickinstall.tex b/doc/handbook/2_quickinstall.tex
index b7bf33fb45..b6c71a337f 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{detailed-install}.
-
\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 pkg-config
-\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 shell-script \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 text-file named \texttt{installDumux.sh}:
-Copy the following lines into a text-file 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 build-system 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 one-phase ground water flow example and will visualize the result using ParaView.
-The test script can be obtained by copying the following lines into a text-file 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/build-cmake/test/porousmediumflow/1p/implicit
-make -B test_1pcctpfa
-./test_1pcctpfa test_1pcctpfa.input
+cd DUMUX/dumux/build-cmake/test/porousmediumflow/1p/implicit/stationary
+make -B test_1p_compressible_stationary_tpfa
+./test_1p_compressible_stationary_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/3_furtherpractice.tex b/doc/handbook/3_furtherpractice.tex
index 30543e92ba..d31e227e73 100644
--- a/doc/handbook/3_furtherpractice.tex
+++ b/doc/handbook/3_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{feature-list} for the individual tests.%TODO
Another possibility to gain more experience with \Dumux is the \texttt{dumux-lecture} module
that contains different application examples that are used in the lectures at the
@@ -14,8 +13,6 @@ The \texttt{dumux-lecture} module can be obtained as follows:
\begin{lstlisting}[style=Bash]
$ git clone https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-lecture.git
\end{lstlisting}
-% TODO: remove again as soon as invalid:
-Note that \texttt{dumux-lecture} 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_externaltools.tex b/doc/handbook/4_externaltools.tex
index a1ec441975..dee059dc1d 100644
--- a/doc/handbook/4_externaltools.tex
+++ b/doc/handbook/4_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 dumux-devel 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/4_newfoldersetup.tex
index 593dbe5223..ea26767b48 100644
--- a/doc/handbook/4_newfoldersetup.tex
+++ b/doc/handbook/4_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.dune-project.org/sphinx/core-2.5/}.
diff --git a/doc/handbook/4_parameterfiles.tex b/doc/handbook/4_parameterfiles.tex
index 7bddd051ed..f6f615891e 100644
--- a/doc/handbook/4_parameterfiles.tex
+++ b/doc/handbook/4_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 = "1e-13"
Verbosity = "0"
[ Newton ]
EnableAbsoluteResidualCriterion = "false"
+EnableChop = "false"
EnableResidualCriterion = "false"
EnableShiftCriterion = "true"
MaxAbsoluteResidual = "1e-5"
@@ -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/4_restartsimulations.tex
index fbd12fe9f9..80b769da42 100644
--- a/doc/handbook/4_restartsimulations.tex
+++ b/doc/handbook/4_restartsimulations.tex
@@ -15,5 +15,5 @@ Unfortunately, writing double-precision 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 \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 30f85bfa69..a4146b5afc 100644
--- a/doc/handbook/4_structure.tex
+++ b/doc/handbook/4_structure.tex
@@ -6,13 +6,14 @@
\item \texttt{bin}: binaries, e.g. used for the automatic testing, post-processing, installation
\item \texttt{cmake}: the configuration options for building \Dumux
\item \texttt{doc}: files necessary for the Doxygen documentation and this handbook, and various logos
-\item \texttt{dumux}: the main folder, containing the source files. see \ref{fig:dumux-structure}
+\item \texttt{dumux}: the main folder, containing the source files. See \ref{fig:dumux-structure}
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/5_basics.tex
similarity index 73%
rename from doc/handbook/5_models.tex
rename to doc/handbook/5_basics.tex
index 0d864377eb..a6ec76568a 100644
--- a/doc/handbook/5_models.tex
+++ b/doc/handbook/5_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/doxygen-stable/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 vector-valued quantities $u$, $m$, $q$ and a tensor-valued flux $\mathbf{f}$.
-For the sake of simplicity, we assume scalar quantities $u$, $m$, $q$ and a vector-valued
-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 multi-phase 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 two-phase 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 cell-centered finite volume method. Further schemes,
-so far only available for the two-phase pressure equation, are cell-centered finite
-volumes with multi-point flux approximation (Mpfa-O 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/5_inputoutput.tex
index 91c9c58d77..33ad270bcb 100644
--- a/doc/handbook/5_inputoutput.tex
+++ b/doc/handbook/5_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 print-out step, a single \texttt{*.vtu} file is created. For parallel simulations one file
+For every print-out step, a single VTU file is created. For parallel simulations one file
per print-out 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/5_parallel.tex
index 10fd57d646..ba4a3580a2 100644
--- a/doc/handbook/5_parallel.tex
+++ b/doc/handbook/5_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 AMG-preconditioned
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 vtu-files as default output format.
-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.
+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 vtu-files 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_spatialdiscretizations.tex b/doc/handbook/5_spatialdiscretizations.tex
index fbf9a4f6da..48237edcc2 100644
--- a/doc/handbook/5_spatialdiscretizations.tex
+++ b/doc/handbook/5_spatialdiscretizations.tex
@@ -1,12 +1,173 @@
-\section{Spatial Discretization Schemes}
+\section{Spatial Discretization}
\label{spatialdiscretization}
We discretize space with cell-centered 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 cell-centered 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}
+Cell-centered 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 finite-volume 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 cell-centered finite-volume formulation.
+Finite-volume 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 co-normal direction $\mathbf{\Lambda}_K\mathbf{n}$.
+In the following, the main ideas of the two-point flux approximation and the multi-point flux approximation methods are briefly described. Hereby, we restrict the discussion to the two-dimensional 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 finite-volume 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 two-point flux approximation is a simple but robust cell-centered finite-volume scheme, which is commonly used in commercial software.
+This scheme can be derived by using the co-normal 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 so-called K-orthogonal 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 Mpfa-O method. The graphic on the right illustrates how the sub-control volume $L^v$ and face $\sigma^v_2$ are embedded in cell $L$. Note that the face stencils for all sub-control volume faces in the depicted interaction region are $\mathcal{S}_{\sigma^v_i} = \{ K,L,M \}$, meaning that the fluxes over the sub-control 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 finite-volume 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 multi-point flux approximation method (Mpfa-O 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 sub-control volumes $K^v$. Analogously, each face is sub-divided into sub-control 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 sub-control volume $K^v$).
+In the following, we restrict our discussion to the two-dimensional 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 sub-control 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 cell-centered scheme, the introduced face unknowns $u_{\sigma^v_i}$ have to be eliminated. This is done by enforcing flux continuity for each sub-control 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 sub-control volume face $\sigma^v_i$.
+%
+%
\subsection{Box Method -- A Short Introduction}\label{box}
The so called box method unites the advantages of the finite-volume (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}
-Cell-centered 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 finite-volume 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 cell-centered finite-volume formulation.
-Finite-volume 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 co-normal direction $\mathbf{\Lambda}_K\mathbf{n}$.
-In the following, the main ideas of the two-point flux approximation and the multi-point flux approximation methods are briefly described. Hereby, we restrict the discussion to the two-dimensional 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 finite-volume 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 two-point flux approximation is a simple but robust cell-centered finite-volume scheme, which is commonly used in commercial software.
-This scheme can be derived by using the co-normal 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 so-called K-orthogonal 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 Mpfa-O method. The graphic on the right illustrates how the sub-control volume $L^v$ and face $\sigma^v_2$ are embedded in cell $L$. Note that the face stencils for all sub-control volume faces in the depicted interaction region are $\mathcal{S}_{\sigma^v_i} = \{ K,L,M \}$, meaning that the fluxes over the sub-control 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 finite-volume 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 multi-point flux approximation method (Mpfa-O 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 sub-control volumes $K^v$. Analogously, each face is sub-divided into sub-control 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 sub-control volume $K^v$).
-In the following, we restrict our discussion to the two-dimensional 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 sub-control 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 cell-centered scheme, the introduced face unknowns $u_{\sigma^v_i}$ have to be eliminated. This is done by enforcing flux continuity for each sub-control 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 sub-control 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_temporaldiscretizations.tex b/doc/handbook/5_temporaldiscretizations.tex
new file mode 100644
index 0000000000..e0a5542b8b
--- /dev/null
+++ b/doc/handbook/5_temporaldiscretizations.tex
@@ -0,0 +1,62 @@
+\section{Temporal Discretization and Algorithms}
+%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 vector-valued quantities $u$, $m$, $q$ and a tensor-valued flux $\mathbf{f}$.
+For the sake of simplicity, we assume scalar quantities $u$, $m$, $q$ and a vector-valued
+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{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 multi-phase 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 two-phase 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 cell-centered finite volume method. Further schemes,
+so far only available for the two-phase pressure equation, are cell-centered finite
+volumes with multi-point flux approximation (Mpfa-O 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 b9bd427d00..c5e180fe3f 100644
--- a/doc/handbook/CMakeLists.txt
+++ b/doc/handbook/CMakeLists.txt
@@ -13,12 +13,13 @@ set(TEX_INPUTS
4_parameterfiles.tex
4_restartsimulations.tex
4_structure.tex
+ 5_basics.tex
5_inputoutput.tex
- 5_models.tex
5_parallel.tex
5_propertysystem.tex
5_spatialdiscretizations.tex
5_stepsofasimulation.tex
+ 5_temporaldiscretizations.tex
installDumux.sh)
set(TEX_IMAGES
--
GitLab