[handbook] cleanup, restructure discretization

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}

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

doc/handbook/2_detailedinstall.tex

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

doc/handbook/2_quickinstall.tex

-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.

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}

doc/handbook/4_externaltools.tex

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

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/}.

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"

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).

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}

doc/handbook/5_models.tex → doc/handbook/5_basics.tex

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

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}

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.

doc/handbook/5_temporaldiscretizations.tex

+\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.

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