handbook: finish update for the 2.2 release

at least content-wise. there are still quite a few language issues
left to be dealt with...

doc/handbook/ewoms-handbook.bib

@@ -918,21 +918,36 @@
   key = {ALU}
 }
 
+@MISC{GIT-HP,
+  title = {The Website of the Git SCM: \url{http://git-scm.com/}},
+  key = {GIT}
+}
+
 @MISC{APACHE-SUBVERSION-HP,
   title = {The Apache Subversion Website: \url{http://subversion.apache.org/}},
   key = {APACHE-SUBVERSION}
 }
 
 @MISC{DOXYGEN-HP,
-  title = {Doxgen's Homepage: \url{http://www.stack.nl/~dimitri/doxygen/}},
+  title = {The Doxgen website: \url{http://www.stack.nl/~dimitri/doxygen/}},
   key = {DOXYGEN}
 }
 
 @MISC{DUMUX-HP,
-  title = {The {D}umux homepage: \url{http://www.dumux.org/}},
+  title = {The {D}umux website: \url{http://www.dumux.org/}},
   key = {DUMUX}
 }
 
+@MISC{EWOMS-HP,
+  title = {The eWoms website: \url{http://opm-project.org/ewoms}},
+  key = {EWOMS}
+}
+
+@MISC{OPM-HP,
+  title = {The website of the Open Porous Media initiative: \url{http://opm-project.org/}},
+  key = {OPM}
+}
+
 @MISC{DUNE-BS,
   title = {{DUNE} Build System Howto: \url{http://www.dune-project.org/doc/buildsystem/buildsystem.pdf}},
   key = {DUNE-BS}

doc/handbook/ewoms-handbook.tex

@@ -179,12 +179,12 @@
 
 \part{Guides}
 
-\input{structure}
 \input{install}
-\input{guidelines}
+\input{structure}
 \input{new-folder}
-\input{newton-in-a-nutshell}
+\input{guidelines}
 \input{models}
+\input{newton-in-a-nutshell}
 
 \bibliographystyle{plain}
 \bibliography{ewoms-handbook}

doc/handbook/guidelines.tex

@@ -1,4 +1,4 @@
-\section{Guidelines} 
+\chapter{Coding Style Guidelines}
 \label{guidelines}
 
 An important characteristic of source code is that it is written only
@@ -6,49 +6,85 @@ once but usually it is read many times (e.g. when debugging things,
 adding features, etc.). For this reason, good programming frameworks
 always aim to be as readable as possible, even if comes with higher
 effort to write them in the first place. The remainder of this section
-is almost a verbatim copy of the DUNE coding guidelines found at
+is very similar to the \Dune coding guidelines found at the \Dune
-\cite{DUNE-HP}. These guidelines are also recommended for coding with
+website~\cite{DUNE-HP}. These guidelines are also strongly recommended
-\Dumux as developer and user.
+for working with \eWoms. Some of these coding style rules may seem
-
+like splitting hairs to you, but they do make it much easier for
-In order to keep the code maintainable we have decided upon a set of
+everybody to work on code that has not been written by oneself.
-coding rules.  Some of them may seem like splitting hairs to you, but
-they do make it much easier for everybody to work on code that hasn't
-been written by oneself.
 
 \begin{itemize}
 \item Naming: 
 \begin{itemize}
-\item Comments: they are helpful! Please document freely what each part of your code does. 
+\item Comments: They are helpful! Use comments extensively to explain
-\item all comments / documentation is in English
+  what your code does, but please refrain from adding trivial
-\item Variables: Names for variables should only consist of letters and digits. The first letter should be a lower case one. If your variable names consists of several words, then the first letter of each new word should be capital. As we decided on the only exception are the begin and end methods.
+  comments. Trivial comments are, for example comments that only
-\item Variables should be named as self-explaining as possible: especially abbreviations should be avoided (saturation in stead of S)
+  parrot the source code (``this method sets a'' as the comment for a
+  method called \texttt{setA()}), or comments that explain language
+  features (``if b is true then a is c else d'' for the statement
+  \texttt{a = b?c:d}).
+\item All comments, documentation and variable or type names are
+  exclusivly using the English language.
+\item Variables: Names for variables should only feature letters and
+  digits. The first letter should be lower case. If your variable
+  names consists of several words, then the first letter of each new
+  word should be capitalized.
+\item Variables and methods should be named as self-explanatory as
+  possible. Especially, this means abbreviations should be avoided
+  (for example, use 'saturation' in stead of 'S')
 \item Method parameters which are not self-explanatory should always
   have a meaningful comment a at calling sites. Example:
 \begin{lstlisting}[style=eWomsCode]
    localResidual.eval(/*includeBoundaries=*/true);
 \end{lstlisting}
-\item Private Data Variables: Names of private data variables end with an underscore and are the only variables that contain underscores. 
+\item Private attributes: Names of private attributes should end with
-\item Typenames: For typenames, the same rules as for variables apply. The only difference is that the first letter should be a capital one.
+  an underscore and are supposed to be the only variables that contain
-\item Macros: The use of preprocessor macros is strongly discouraged. If you have to use them for whatever reason, please use capital letters only.
+  underscores.
-\item The Exlusive-Access Macro: Every header file traditionally begins with the definition of a preprocessor constant that is used to make sure that each header file is only included once. If your header file is called 'myheaderfile.hh', this constant should be DUNE\_MYHEADERFILE\_HH.
+\item Typenames: For typenames (classes, structures, typedefs, etc),
-\item Files: Filenames should consist of lower case letters exclusively. Header files get the suffix .hh, implementation files the suffix .cc
+  the same rules as for variables apply. The only difference is that
+  the first letter should be a capital one.
+\item Macros: The use of preprocessor macros is strongly
+  discouraged. If you have to use them for whatever reason, please use
+  capital letters only.
+\item Guardian macros: Every header file traditionally begins with the
+  definition of a preprocessor macro that is used to make sure that
+  the header file is only included once. If your header file is
+  called 'myheaderfile.hh', this constant should be named
+  \texttt{DUMUX\_MYHEADERFILE\_HH}.
+\item Files: File names should exclusively consist of lower case
+  letters. Header files get the suffix .hh, implementation files the
+  suffix .cc
 \end{itemize}
-\item Documentation:
+
-      Dune, as any software project of similar complexity, will stand and fall with the quality of its documentation.
+\item Documentation: \eWoms, as any software project of similar
-Therefore it is of paramount importance that you document well everything you do! We use the doxygen system to extract easily-readable documentation from the source code. Please use its syntax everywhere. In particular, please comment \textbf{all}
+  complexity, will stand and fall with the quality of its
+  documentation.  Therefore, it is of paramount importance that you
+  document everything you do well! We use the doxygen system to
+  extract easily-readable documentation from the source code. Please
+  use its syntax everywhere. In particular, please comment
+  \textbf{all}
 \begin{itemize}
-\item Method Parameters (in / out)
+\item Method parameters
-\item Template Parameters
+\item Template parameters
-\item Return Values 
+\item Return values 
 \item Exceptions thrown by a method
  \end{itemize}
-     Since we all know that writing documentation is not well-liked and is frequently defered to some vague 
+ Since we all know that writing documentation is not well-liked and is
-'next week', we herewith proclaim the Doc-Me Dogma . It goes like this: Whatever you do, and in whatever hurry you 
+ frequently defered to some vague 'next week', we herewith proclaim
-happen to be, please document everything at least with a {\verb /** $\backslash$todo Please doc me! */}. That way at least the absence 
+ the Doc-Me Dogma . It goes like this: Whatever you do, and in
-of documentation is documented, and it is easier to get rid of it systematically.
+ whatever hurry you happen to be, please document everything at least
-\item Exceptions:
+ with a {\verb /** $\backslash$todo Please doc me! */}. That way at
-      The use of exceptions for error handling is encouraged. Until further notice, all exceptions thrown are DuneEx.
+ least the absence of documentation is documented, and it is easier to
-\item Debugging Code:
+ get rid of it systematically.
-      Global debugging code is switched off by setting the symbol NDEBUG. In particular, all asserts are 
+\item Exceptions: The use of exceptions for error handling is
-automatically removed. Use those asserts freely!
+  encouraged. Until further notice, all exceptions thrown are derived
+  from \texttt{Dune::Exception}.
+\item Debugging code: Code which is only there to ease the debugging
+  process should always be switched off if the preprocessor macro
+  NDEBUG is defined. In particular, all assertations are automatically
+  removed. Use those assertations freely!
 \end{itemize}
+
+%%% Local Variables: 
+%%% mode: latex
+%%% TeX-master: "ewoms-handbook"
+%%% End: 

doc/handbook/install.tex

@@ -1,60 +1,86 @@
-\chapter{Detailed Installation Instructions} \label{install}
+\chapter{Detailed Installation Instructions}
+\label{install}
+
 \section{Preliminary remarks}
 
-In this section about the installation of \Dumux it is assumed that you work on a Unix or Linux compatible operating system
+In this section about the installation of \eWoms it is assumed that
-and that you are familiar with the use of a command line shell. Installation means that you unpack \Dune together with \Dumux in a certain directory.
+you work on a Unix or Linux compatible operating system and that you
-Then, you compile it in that directory tree in which you do the further work, too. You also should know how to install new software packages
+are familiar with the use of a command line shell. Installation means
-or you should have a person on hand who can give you assistance with that. In section \ref{sec:prerequisites} we list some prerequisites for running \Dune and \Dumux. 
+that you unpack \Dune together with \eWoms in a certain directory.
-Please check in said paragraph whether you can fulfill them. In addition, section \ref{sec:external-modules-libraries} provides some details on optional libraries and modules.
+Then, you compile it in that directory tree in which you do the
+further work, too. You also should know how to install new software
+packages or you should have a person on hand who assist you with
+that. In section \ref{sec:prerequisites} we list some prerequisites
+for running \Dune and \eWoms.  Please make sure to fulfill them before
+you proceed. In addition, section \ref{sec:external-modules-libraries}
+provides some details on optional libraries and modules.
 
-In a technical sense \Dumux is a module of \Dune. 
+In a technical sense \eWoms is a module of \Dune.  Thus, the
-Thus, the installation procedure of \Dumux is the same as that of \Dune. 
+installation procedure of \eWoms is the same as that of \Dune (besides
-Details regarding the installation of \Dune are provided on the \Dune website \cite{DUNE-INST}. 
+using different locations to retieve the source code).  Details
-If you are interested in more details about the build system that is used,
+regarding the installation of \Dune are provided on the \Dune
-they can be found in the {\Dune} Buildsystem Howto \cite{DUNE-BS}.
+website~\cite{DUNE-INST}. If you are interested in more details about
+the build system that is used, they can be found in the {\Dune}
+build system howto \cite{DUNE-BS}.
 
+All \Dune modules, including \eWoms, get extracted into a common
+directory. In the following, we refer to that directory as {\Dune}
+base directory or, in short, as {\Dune}-base.  If it is used as
+directory path of a shell command it is typed as
+\texttt{dune-base}.  For the actual location of the {\Dune} base
+directory on your file system, you may chose any valid directory name for
+which you have write permissions.
 
-All \Dune modules, including \Dumux, get extracted into a common directory, as it is done in an ordinary \Dune installation. 
+Source code files for each \Dune module are contained in their own
-We refer to that directory abstractly as {\Dune} root directory or, in short, as {\Dune}-Root. 
+subdirectory within {\Dune}-base.  We name this directory of a certain
-If it is used as directory's path of a shell command it is typed as \texttt{\Dune-Root}. 
+module \emph{module base directory} or \texttt{module-base}
-For the real {\Dune} root directory on your file system any valid directory name can be chosen.
+if it is a directory path, e.\,g. for the module \texttt{ewoms} these
+names are \emph{ewoms base directory} respective
+\texttt{ewoms-base}.  The real directory names for the
+modules can be chosen arbitrarily. In this manual they are the same as
+the module name or the module name extended by a version number
+suffix.  The name of each \Dune module is defined in the file
+\texttt{dune.module}, which is in the base directory of the respective
+module. This should not be changed by the user.  It is allowed to have
+own files and directories in \Dune-base, which are not related to
+\Dune's needs.
 
-Source code files for each \Dune module are contained in their own subdirectory within {\Dune}-Root.
+After installing source code for all relevant \Dune modules including
-We name this directory of a certain module \emph{module root directory} or \texttt{module-root-directory} if it is a directory path,
+\eWoms, \Dune is being built by the shell-command \texttt{dunecontrol}
-e.\,g. for the module \texttt{dumux} these names are  \emph{dumux root directory} respective \texttt{dumux-root-directory}.
+which is part of the \Dune build system. The \Dune build system is a
-The real directory names for the modules can be chosen arbitrarily. In this manual they are the same as the
+front-end of to the GNU build system adapted to the needs of \Dune.
-module name or the module name extended by a version number suffix.
-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. 
-It is allowed to have own files and directories in \Dune-Root, which are not related to \Dune's needs.
-
-After installing source code for all relevant \Dune modules including \Dumux, \Dune is being built by the shell-command \texttt{dunecontrol} which is part of the \Dune build system. The \Dune build system is a front-end of to the GNU build system adapted to the needs of \Dune.
 
 \section{Prerequisites} \label{sec:prerequisites}
-The GNU tool chain of \texttt{g++}  and the tools of the GNU build system \cite{GNU-BS}, also known as GNU autotools
-(\texttt{autoconf}, \texttt{automake}, \texttt{autogen}, \texttt{libtool}), as well as the GNU variant of \texttt{make}
-called gmake must be available in a recent version. For example Ubuntu Linux provides these tools with the
-packages \texttt{autoconf}, \texttt{automake}, \texttt{libtool}
-and the \Cplusplus compiler \texttt{g++} and \texttt{make} are contained in \texttt{build-essential}.
 
-At the time of writing this manual, it is expected that \texttt{g++} of version $\geqslant$ 4.5.0, \texttt{automake} of version $\geqslant$ 1.9,
+The GNU compiler collection with \Cplusplus support (\texttt{g++}) and
-\texttt{autoconf} of version $\geqslant$ 2.65, \texttt{autogen} of version $\geqslant$ 5.9.7,  \texttt{libtool} of version $\geqslant$ 2.2.6
+the tools of the GNU build system \cite{GNU-BS}, also known as GNU
-and GNU \texttt{make} version $\geqslant$ 3.81 should do their job for building \Dumux.
+autotools (\texttt{autoconf}, \texttt{automake}, \texttt{autogen},
+\texttt{libtool}), as well as the GNU variant of \texttt{make} called
+gmake must be available in a recent enough version. For example Ubuntu
+Linux provides these tools by means of the packages \texttt{autoconf},
+\texttt{automake}, \texttt{libtool} and the  package 
+\texttt{build-essential} includes the \Cplusplus compiler
+\texttt{g++} and \texttt{make}.
 
-The building of included documentation like this handbook requires \LaTeX\  and auxiliary tools
+At the time of writing this manual, the minumum version required for
-like \texttt{dvipdf} and \texttt{bibtex}. One usually chooses a \LaTeX\  distribution like \texttt{texlive} for this purpose.
+\texttt{g++} is 4.4.0, \texttt{automake}  the documentation by setting the switch
-It is possible to switch off the building of the documentation by setting the switch \texttt{--disable-documentation} 
+\texttt{--disable-documentation} in the \texttt{CONFIGURE\_FLAGS} of
-in the \texttt{CONFIGURE\_FLAGS} of the building options (see Chapter \ref{buildIt}).
+the building options (see Chapter \ref{buildIt}).  Additional parts of
-Additional parts of documentation are contained within the source code files as special formatted comments.
+documentation are contained within the source code files as specially
-Extracting them can be done using \texttt{doxygen} (version $\geqslant$ 1.7.2 works). 
+formatted comments.  Extracting them can be done using the tool
-See for this optional step Section \ref{sec:build-doxy-doc}.
+\texttt{doxygen} (version $\geqslant$ 1.8.2 works).  See for this
+optional step section \ref{sec:build-doxy-doc}.
 
-Depending on whether you are going to use external libraries and modules for additional \Dune features, 
+Depending on whether you are going to use external libraries and
-additional software packages may be required. Some hints on that are given in Section \ref{sec:external-modules-libraries}.
+modules for additional \Dune features, additional software packages
+may be required. Some hints on that are given in Section
+\ref{sec:external-modules-libraries}.
 
-For the extraction of the content of tar files, the GNU version of \texttt{tar} is used.
+For the extraction of the content of tar files, the GNU version of
-The subversion (svn) software repositories can be accessed with help of a subversion client. We recommend the Apache Subversion command-line client \texttt{svn}
+\texttt{tar} is used.  To access the git or subversion software
-contained in Apache Subversion of version $\geqslant$ 1.6.0 \cite{APACHE-SUBVERSION-HP}.
+repositories, a git and subversion clients are required. We recommend
+to use the git command-line client \texttt{git} version 1.7.12 or
+newer with the subversion integration plugin \texttt{git-svn} enabled~\cite{GIT-HP}.
 
 \begin{table}
 \centering
@@ -63,18 +89,18 @@ contained in Apache Subversion of version $\geqslant$ 1.6.0 \cite{APACHE-SUBVERS
 \toprule
 \textbf{purpose} & \textbf{package names} \\
 \midrule
-general: & subversion & git & libtool \\
+general: & git & git-svn & libtool \\
 & automake & build-essential & libboost-all-dev \\
 & texlive-latex-base & doxygen & csh\\
-& gfortran & ? libpthread-stubs0 ?\\
+& gfortran & \\
 \midrule
 for alberta: & freeglut3-dev &  \\
 \midrule
 for parallel use: & openmpi-common & mpi-default-bin & mpi-default-dev \\
 \midrule
-for ug parallel: & flex & bison & \\
+for parallel UG: & flex & bison & \\
 \midrule
-for alberta parallel: & libblas-dev &\\
+for parallel alberta: & libblas-dev &\\
 \midrule
 for debugging: & valgrind &\\
 \bottomrule
@@ -82,293 +108,258 @@ for debugging: & valgrind &\\
 \label{tbl:ubuntu-pkg}
 \end{table}
 
-\section{Obtaining source code for \Dune and \Dumux}
+\section{Obtaining source code for \Dune and \eWoms}
-As stated above, the \Dumux release 2.1.0 and trunk (developer tree) are based on the \Dune release 2.1.1, 
-comprising the core modules \texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl} and \texttt{dune-localfunctions}.
-% and the external dune module \texttt{dune-pdelab}.
-For working with \Dumux, these modules are required.
 
-Two possibilities exist to get the source code of \Dune and \Dumux.
+As stated above, the \eWoms is based on the \Dune release 2.2,
-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.
+comprising the core modules \texttt{dune-common},
-Secondly, a method to obtain the most recent source code (or, more generally, any of its previous revisions) by direct access 
+\texttt{dune-geometry}, \texttt{dune-grid}, \texttt{dune-istl} and
-via Internet to the software repositories of the revision control system is described in the subsequent part. 
+\texttt{dune-localfunctions}.  For working with \eWoms, these modules
+are required.
 
-However, if a user does not want to use the most recent version,
+Two possibilities exist to get the source code of \Dune and \eWoms.
-certain version tags (i.\,e. special names), version numbers and even software branches are means 
+Firstly, released versions \Dune and \eWoms can be downloaded as tar
-of the software revision control system to provide access to different versions of the software.
+files from the \Dune and \eWoms websites. They have to be extracted as
+described in the next paragraph.  Secondly, the most recent source
+code can be obtained by directly downloading it from its respective
+source-code repository. This method is described in the subsequent
+section.
 
 \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 within these archives.
+
-The extraction from the tar files is done as follows: 
+The slightly old-fashionedly named tape-archive-file, shortly named
-Download the tarballs from the respective \Dune (version 2.2.0) and \Dumux websites to a certain folder in your file system.
+tar file or tarball, is a common file format for distributing
-Create the {\Dune} root directory, named DUMUX in the example below. Then extract the content of the tar files, e.\,g. with the command-line program \texttt{tar}.
+collections of files contained within these archives.  The extraction
-This can be achieved by the following shell commands. Replace \texttt{path\_to\_tarball} with the directory name where the downloaded files are actually located.
+from the tar files is done as follows: Download the tarballs from the
-After extraction, the actual name of the \emph{dumux root directory} is \texttt{dumux-2.2}. 
+respective \Dune~\cite{DUNE-HP} (version 2.2.0) and
+\eWoms~\cite{EWOMS-HP} websites.  Then, create the {\Dune} base
+directory, named \texttt{~/src} in the example below. Then, extract the
+content of the tar files, e.\,g. with the command-line program
+\texttt{tar}.  This can be achieved by the following shell
+commands. Replace \texttt{path\_to\_tarball} with the directory name
+where the downloaded files are actually located.  After extraction,
+the actual name of the \emph{ewoms base directory} is
+\texttt{ewoms-2.2}.
 
 \begin{lstlisting}[style=Bash]
-$ mkdir DUMUX
+$ mkdir ~/src
-$ cd DUMUX
+$ cd ~/src
 $ tar xzvf path_to_tarball_of/dune-common-2.2.0.tar.gz 
 $ tar xzvf path_to_tarball_of/dune-grid-2.2.0.tar.gz 
 $ tar xzvf path_to_tarball_of/dune-geometry-2.2.0.tar.gz 
 $ tar xzvf path_to_tarball_of/dune-istl-2.2.0.tar.gz 
 $ tar xzvf path_to_tarball_of/dune-localfunctions-2.2.0.tar.gz 
-$ tar xzvf path_to_tarball_of/dumux-2.2.tar.gz
+$ tar xzvf path_to_tarball_of/ewoms-2.2.0.tar.gz
 \end{lstlisting}
 
-Furthermore, if you wish to install the optional \Dune Grid-Howto which provides a tutorial on the Dune grid interface:
+\paragraph{Obtaining \Dune and \eWoms from software repositories} 
+
+Direct access to a software repositories for downloading code can be
+convenient to always follow the changes of done to the software
+project. Usually, source code repositories are structured in
+branches. One of these branches is commonly used to include the latest
+features of the software, and there is normally one branch for each
+release which only receives fixes for bug which have been discovered
+after the software was released. The following text describes how to
+retrieve the source code of \Dune and \eWoms from such release
+branches.
+
+The \Dune project uses Apache Subversion~\cite{APACHE-SUBVERSION-HP}
+to manage its software repositories, while \eWoms -- being part of the
+open porous media project -- opted to use the git source code
+management system~\cite{GIT-HP}. Fortunately, git ships with a
+subversion plugin, so all modules can be managed using git.
+
+In the technical language of Apache Subversion \emph{cloning a certain
+  software repository} means nothing more then fetching a local copy
+of the software repository and placing it on the local file system.
+In addition to the software some more files for the use of the
+software revision control system itself are created. They are kept in
+a directory named \texttt{.git} at the base directory of the cloned
+software repository.
+
+The installation procedure is structured as follows: Create a {\Dune} base
+directory (named \texttt{~/src} in the lines below).  Then, enter the
+previously created directory and check out the desired modules.  As
+you see below, the check-out uses two different servers for getting
+the sources, one for \Dune and one for \eWoms.  The \Dune modules of
+the stable 2.2 release branch are cloned similarly as described on the
+\Dune website~\cite{DUNE-DOWNLOAD-SVN}:
 
 \begin{lstlisting}[style=Bash]
-$ tar xzvf path_to_tarball_of/dune-grid-howto-2.2.0.tar.gz
+mkdir ~/src
+cd ~/src
+for DUNE_MODULE in common geometry grid istl localfunctions; do
+  git svn clone \
+   https://svn.dune-project.org/svn/dune-$DUNE_MODULE/branches/release-2.2 \
+   dune-$DUNE_MODULE
+done
 \end{lstlisting}
 
-\paragraph{Obtaining \Dune and \Dumux from software repositories} 
+The newest and maybe unstable developments are also provided in these
+repositories in a folder called \emph{trunk}. Please check the \Dune
+website \cite{DUNE-DOWNLOAD-SVN} for further information. However, the
+current \eWoms release is based on the stable 2.2 \Dune release and it
+might misbehave using the the newest version of \Dune.
 
-Direct access to a software revision control system for downloading code can be of advantage for the user later on. 
+The \eWoms module is checked out as described below (see also the
-It can be easier for him to keep up with code changes and to receive important bug fixes using the update command of the revision control system. 
+\eWoms website \cite{EWOMS-HP}).  Its source tree has to be created in
-\Dune and \Dumux use Apache Subversion for their software repositories. To access them a certain program is needed which is referred to here shortly as subversion client. 
+the \Dune-base directory, where the \Dune modules have also been
-In our description, we use the subversion client of the Apache Subversion software itself, which is a command-line tool named \texttt{svn}. 
+cloned into. Subsequently, the next command is executed there,
-It is available for most Linux and Unix distributions as software package.
+too. The directory which holds the \eWoms module is called
-
+\texttt{ewoms} here.
-In the technical language of Apache Subversion \emph{checking out a certain software version} means nothing more then fetching 
-a local copy from the software repository and laying it out in the file system.  In addition to the software some more files for the use of the software revision control system itself are created. They are kept in directories named \texttt{.svn} and can be found in each subfolder which is under version control.
-If you have developer access to \Dumux, it is also possible to do the opposite, i.\,e. to load up a modified revision of software into the software repository. This is usually termed as \emph{software commit}.
-
-The installation procedure is done as follows:
-Create a  {\Dune} root directory, named \texttt{DUMUX} in the lines below.
-Then, enter the previously created directory and check out the desired modules. 
-As you see below, the check-out uses two different servers for getting the sources, one for \Dune and one for {\Dumux}.
-The \Dune modules of the stable 2.2 release branch are checked out as described on the \Dune website \cite{DUNE-DOWNLOAD-SVN}:
 
 \begin{lstlisting}[style=Bash]
-$ mkdir DUMUX
+cd ~/src
-$ cd DUMUX
+git clone git://github.com/OPM/ewoms.git ewoms
-$ svn checkout https://svn.dune-project.org/svn/dune-common/branches/release-2.2 dune-common
-$ svn checkout https://svn.dune-project.org/svn/dune-istl/branches/release-2.2 dune-istl
-$ svn checkout https://svn.dune-project.org/svn/dune-grid/branches/release-2.2 dune-grid
-$ svn checkout https://svn.dune-project.org/svn/dune-geometry/branches/release-2.2 dune-geometry
-$ svn checkout https://svn.dune-project.org/svn/dune-localfunctions/branches/release-2.2 dune-localfunctions
 \end{lstlisting}
 
-The newest and maybe unstable developments are also provided in these repositories in a folder called \emph{trunk}. Please check the \Dune website \cite{DUNE-DOWNLOAD-SVN} for further information. However, the current \Dumux release is based on the stable 2.1 release and it might not compile without further adaptations using the the newest versions of \Dune.
+\section{Building the doxygen documentation}
+\label{sec:build-doxy-doc}
 
-The additional module \texttt{dune-grid-howto} is a tutorial which provides information about the \Dune grid interface.
+Doxygen documentation is done by especially formatted comments
-It may give you an idea of how some abstractions in \Dune are done.
+integrated in the source code, which can get extracted by the program
-The installation of \texttt{dune-grid-howto} is optional and is not required by \Dumux. It is done by: 
+\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 \cite{DOXYGEN-HP}.
+
+Building the doxygen documentation of a module is done as follows,
+provided the program \texttt{doxygen} is installed: Set in building
+options the \texttt{--enable-doxygen} switch.  This is either
+accomplished by adding it in \texttt{dunecontrol} options-file to
+\texttt{CONFIGURE\_FLAGS}, or by adding it to \texttt{dunecontrol}'s
+command-line-argument \texttt{--configure-opts}.  After running
+\texttt{dunecontrol} enter in module's base directory the subdirectory
+\texttt{doc/doxygen}.  You then run the command \texttt{doxygen}
+within that directory. Point your web browser to the file
+\texttt{module-base-directory/doc/doxygen/html/index.html} to read the
+generated documentation.  For all \Dune-modules that described here,
+the doxygen documentation can be generated analogously.
 
 \begin{lstlisting}[style=Bash]
-$ svn checkout https://svn.dune-project.org/svn/dune-grid-howto/branches/release-2.2 dune-grid-howto
+cd ~/src/ewoms/doc/doxygen
+doxygen
+firefox html/index.html
 \end{lstlisting}
 
-The \texttt{dumux} module is checked out as described below (see also the \Dumux website \cite{DUMUX-HP}).
+\section{Building the \eWoms handbook}
-Its file tree has to be created in the \Dune-Root directory, where the \Dune modules have also been checked out to. Subsequently, the next command
-is executed there, too. The dumux root directory is called \texttt{dumux} here.
-
-\begin{lstlisting}[style=Bash]
-$ # make sure you are in DUNE-Root
-$ svn checkout --username=anonymous --password='' svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux
-\end{lstlisting}
-
-\paragraph{Hints for \Dumux-Developers}
-If you also want to actively participate in the development of \Dumux, you can apply either for full developer
-access or for developer access on certain parts of \Dumux. Granted developer access means that
-you are allowed to commit own code and that you can access the \texttt{dumux-devel} module.
-This enhances \texttt{dumux} by providing maybe unstable code from the developer group.
-A developer usually checks out non-anonymously the modules \texttt{dumux} and \texttt{dumux-devel}. 
-\texttt{Dumux-devel} itself makes use of the stable part \texttt{dumux}. Hence, the two parts have to be checked out together.
-This is done using the commands below. But \texttt{joeuser} needs to be replaced by
-the actual user name of the developer for accessing the software repository. 
-One can omit the \texttt{--username} option in the commands above if the user name for the repository access is
-identical to the one for the system account.
-
-\begin{lstlisting}[style=Bash]
-$ svn co --username=joeuser svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux
-$ svn co --username=joeuser svn://svn.iws.uni-stuttgart.de/DUMUX/dune-mux/trunk dumux-devel
-\end{lstlisting}
-
-Please choose either not to store the password by subversion in an insecure way or
-choose to store it by subversion in a secure way, e.\,g. together with KDE's KWallet or GNOME Keyring.
-Check the documentation of Subversion for info on how this is done.
-A leaked out password can be used by evil persons to abuse a software repository.
-
-\section{Patching \Dune or external libraries}
-Patching of \Dune modules in order to work together with \Dumux can be necessary for several reasons.
-Software like a compiler or even a standard library
-changes at times. But, for example, a certain release of a software component that we depend on, may not reflect that change and thus it has to be modified.
-In the dynamic developing process of software which depends on other modules it is not always feasible 
-to adapt everything to the most recent version of each module. Consequently, patches exist or they will be brought into existence. They may fix problems with a certain module
-of a certain release without introducing too much structural change. It can also happen 
-that a release gets amendments (updates) and a formerly useful patch becomes obsolete.
-
-\Dumux contains patches and documentation about their usage and application within the directory \texttt{dumux/patches}.
-Please check the README file in that directory for recent information. 
-In general, a patch can be applied as follows (the exact command or the used parameters may be slightly different).
-We include here an example of a patch against 2.0 release of \Dune for \Dumux release 2.0 for purpose of showing how a patch gets applied. Note this patch is no longer necessary for \Dune 2.2 releases.
-
-\begin{lstlisting}[style=Bash]
-$ # make sure you are in DUNE-Root
-$ cd dune-istl
-$ patch -p1 < ../dumux/patches/dune-istl-2.0.patch
-\end{lstlisting}
-
-It can be removed by 
-\begin{lstlisting}[style=Bash]
-$ path -p1 -R < ../dumux/patches/dune-istl-2.0.patch
-\end{lstlisting}
-
-The \texttt{checkout-dumux} script also applies patches, if not explicitly requested not to do so.
-
-
-\section{Building doxygen documentation} \label{sec:build-doxy-doc}
-
-Doxygen documentation is done by especially formatted comments integrated in the source code, which can get extracted by the program 
-\texttt{doxygen}. Beside extracting these comments, \texttt{doxygen} builds up a web-browsable code structure documentation
-like class hierarchy of code displayed as graphs, see \cite{DOXYGEN-HP}.
-
-Building the doxygen documentation of a module is done as follows, provided the program \texttt{doxygen} is installed:
-Set in building options the \texttt{--enable-doxygen} switch.
-This is either accomplished by adding it in \texttt{dunecontrol} options-file to  \texttt{CONFIGURE\_FLAGS}, or by adding
-it to  \texttt{dunecontrol}'s command-line-argument \texttt{--configure-opts}. 
-After running \texttt{dunecontrol} enter in module's root directory the subdirectory \texttt{doc/doxygen}.
-You then run the command \texttt{doxygen} within that directory. Point your web browser to the file 
-\texttt{module-root-directory/doc/doxygen/html/index.html} to read the generated documentation.
-All  \Dune-modules that are used here except \texttt{dune-grid-howto}  including also \texttt{dumux} contain some doxygen documentation, which can be extracted as
-described in the following lines. The external library UG has also a \texttt{doc/doxygen} directory for building its doxygen documentation.
-
-\begin{lstlisting}[style=Bash]
-$ # change before next command your directory to DUNE-Root
-$ cd dumux/doc/doxygen
-$ doxygen
-$ firefox html/index.html
-\end{lstlisting}
-
-\section{Building documentation of other \Dune modules}
 
 If the \texttt{--enable-documentation} switch has been set in the configure flags of
-\texttt{dunecontrol}, this does not necessarily mean that for every 
+\texttt{dunecontrol}, watch for a summary line of the build script that reads
-\Dune module the documentation is being built.
-However, at least Makefiles for building the documentation are generated.
-Provided you run \texttt{dunecontrol} with the option above,
-it should be possible to build documentation if available.
-Check the targets you can build in \texttt{module-root-directory/doc/Makefile.am}.
-For example in the module \texttt{dune-istl} you can build the documentation \texttt{istl.pdf} by typing the following into the console, when you are in the \Dune-Root:
-
 \begin{lstlisting}[style=Bash]
-$ # change before next command your directory to DUNE-Root
+Build eWoms handbook....: yes
-$ cd dune-istl/doc
-$ make istl.pdf
 \end{lstlisting}
 
-Or for module \texttt{dune-grid-howto} the documentation can be build by: 
+If this is the case, the handbook should be automatically build by
+\texttt{dunecontrol} and can be found at
+\texttt{\$EWOMS\_BASE/doc/handbook/ewoms-handbook.pdf}.
 
-\begin{lstlisting}[style=Bash]
+If the summary line says that the handbook is not going to be build,
-$ # change before next command your directory to DUNE-Root
+then you usually have to install additional \LaTeX packages.
-$ cd dune-grid-howto/doc
-$ make grid-howto.pdf
-\end{lstlisting}
 
-This applies for \Dumux, too. Rebuilding the handbook can be done as follows:
+\section{External libraries and modules}
+\label{sec:external-modules-libraries}
 
-\begin{lstlisting}[style=Bash]
+The libraries described below provide additional functionality but are
-$ cd dumux/doc/handbook
+not generally required to use \eWoms.  If you are going to use an
-$ make ewoms-handbook.pdf
+external library, also check the information provided on the \Dune
-\end{lstlisting}
+website~\cite{DUNE-EXT-LIB} for additional hints.  If you are going to
+use an external \Dune module, the website listing external
+modules~\cite{DUNE-EXT-MOD} can also be helpful.
 
+Some external libraries have additional dependencies which can also be
+used by \Dune.  Also, some libraries, such as BLAS or MPI might have
+multiple versions installed on the system.  To avoid problems, you
+should make sure that all external libraries use the same dependencies
+as \Dune.
 
-%As of writing this, no general method of building documentation contained in \Dune's modules is known to the author.
+In the following list, you can find some external modules and external
-
+libraries, and some more libraries and tools which are prerequisites
-%Alternatively, the tool CMake can be used to build \Dumux. Please check the file \texttt{INSTALL.cmake} for details.
+for their use.
-
-\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 \cite{DUNE-EXT-LIB}.
-If you are going to use an external \Dune module the website on external modules \cite{DUNE-EXT-MOD} can be helpful.
-
-Installing an external library can require additional libraries which are also used by \Dune. 
-For some libraries, such as BLAS or MPI, multiple versions can be installed on the system.
-Make sure that it uses the same library as \Dune when configuring the external library.
-
-In the following list, you can find some external modules and external libraries, and some more libraries and tools which are prerequisites for their use.
 
 \begin{itemize}
-\item \textbf{ALBERTA}: External library for use as grid. Adaptive multi Level finite element toolbox using Bisectioning refinement and Error control by Residual Techniques for scientific Applications. Building it requires a Fortran compiler \texttt{gfortran}. Download: \texttt{\url{http://www.alberta-fem.de}}.
+\item \textbf{ALBERTA}: External library which can be used as an
+  additional grid manager. ALBERTA stands for ``\textbf{A}daptive multi \textbf{L}evel finite element toolbox
+  using \textbf{B}isectioning refinement and \textbf{E}rror control by \textbf{R}esidual
+  \textbf{T}echniques for scientific \textbf{A}pplications''. Building it requires a
+  Fortran compiler, for example \texttt{gfortran}. It can be downloaded at:
+  \texttt{\url{http://www.alberta-fem.de}}.
 
-\item \textbf{ALUGrid}: External library for use as grid. ALUGrid is built by a \Cplusplus compiler like \texttt{g++}. If you want to build a parallel version, you will need \texttt{MPI}. It was successfully run with \texttt{openmpi}. The parallel version needs also a graph partitioner, such as \texttt{METIS}. It was run successfully in combination with \Dune using \texttt{METIS}. \\
+\item \textbf{ALUGrid}: External library for use as grid. ALUGrid
-Download: \texttt{\url{http://aam.mathematik.uni-freiburg.de/IAM/Research/alugrid}}
+  requires by a \Cplusplus compiler like \texttt{g++} to be build. If
+  you want to build a parallel version, you will need an MPI library
+  like, for example \texttt{openmpi}, installed on your system. The
+  parallel version needs also a graph partitioner, such as
+  \texttt{METIS}.
 
-\item \textbf{\Dune-multidomaingrid}: External module. If you going to run on the same grid different domains or subdomains,
+  Download:
-this can be the package of choice. This is done by providing a meta grid. It can be useful for multi-physics approaches or domain decomposition methods. Download: \texttt{\url{http://gitorious.org/dune-multidomaingrid}}. 
+  \texttt{\url{http://aam.mathematik.uni-freiburg.de/IAM/Research/alugrid}}
-%Furthermore, the external module \textbf{\Dune-multidomain} can be useful for solving heterogenous problems on spatial subdomains. These subdomains are managed using another DUNE module called dune-multidomaingrid.
 
-\item \textbf{\Dune-PDELab}: External module to write more easily discretizations. PDELab provides already a sound number of discretizations like FEM or discontinuous Galerkin methods. Download: \texttt{\url{http://www.dune-project.org/pdelab}}. 
+\item \textbf{SuperLU}: External library for solving linear
+  equations. SuperLU is a general purpose library for the direct
+  solution of large, sparse, non-symmetric systems of linear
+  equations.
 
-\item \textbf{PARDISO}: External library for solving linear equations. The package PARDISO is a thread-safe, high-performance, robust, memory efficient and easy to use software for solving large sparse symmetric and asymmetric linear systems of equations on shared memory multiprocessors. The precompiled binary can be downloaded after personal registration from the PARDISO website (\texttt{\url{http://www.pardiso-project.org}}).
+  Download:
+  \texttt{\url{http://crd.lbl.gov/~xiaoye/SuperLU}}.
 
-\item \textbf{SuperLU}: External library for solving linear equations. SuperLU is a general purpose library for the direct solution of large, sparse, non-symmetric systems of linear equations. Be aware that the version 4.3 is not supported by \Dune prior to 2.1.0. \\ (\texttt{\url{http://crd.lbl.gov/~xiaoye/SuperLU}}).
+\item \textbf{UG}: External library which can be used as an additional
+  grid manager. UG is a toolbox for \textbf{U}nstructured
+  \textbf{G}rids: For \eWoms it has to be build by GNU buildsystem and
+  a \Cplusplus compiler. That's why \Dune specific patches need
+  applied before use. Building it makes use of the tools
+  \texttt{lex}/\texttt{yacc} or the GNU variants
+  \texttt{flex}/\texttt{bison}.
 
-\item \textbf{UG}: External library for use as grid. UG is a toolbox for Unstructured Grids: For \Dumux it has to be build by GNU buildsystem and a \Cplusplus compiler. That's why \Dune specific patches need applied before use. Building it makes use of the tools \texttt{lex}/\texttt{yacc} or the GNU variants \texttt{flex}/\texttt{bison}. 
+  Website:
+  \texttt{\url{http://atlas.gcsc.uni-frankfurt.de/~ug/}}\\
+  Further information:
+  \texttt{\url{http://www.dune-project.org/external_libraries/install_ug.html}}\\
 
 \end{itemize}
 
-The following are dependencies of some of the used libraries. You will need them depending on which modules of \Dune and which external libraries you use.
+The following are dependencies of some of the external libraries. You
+will need them depending on which modules of \Dune and which external
+libraries you use.
 
 \begin{itemize}
-\item \textbf{MPI}: The parallel version of \Dune and also some of the external dependencies need MPI when they are going to be built for parallel computing. \texttt{Openmpi} version $\geqslant$ 1.4.2 and \texttt{MPICH} in a recent version have been reported to work. 
+\item \textbf{MPI}: The parallel version of \Dune and also some of the
+  external dependencies need MPI when they are going to be built for
+  parallel computing. \texttt{Openmpi} version $\geqslant$ 1.4.2 and
+  \texttt{MPICH} in a recent version have been reported to work.
 
-\item \textbf{lex/yacc} or \textbf{flex/bison}: These are quite common developing tools, code generators for lexical analyzers and parsers. This is a prerequisite for UG.
+\item \textbf{lex/yacc} or \textbf{flex/bison}: These are quite common
+  developing tools, code generators for lexical analyzers and
+  parsers. This is a prerequisite for compiling UG.
 
-\item \textbf{BLAS}: Alberta makes use of BLAS. Thus install GotoBLAS2, ATLAS, non-optimized BLAS or BLAS provided by a chip manufacturer. Take care that the installation scripts select the intended version of BLAS. See \texttt{\url{http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms}}.
+\item \textbf{BLAS}: Alberta makes use of BLAS (acronym for
+  ``\textbf{B}asic \textbf{L}inear \textbf{A}lgebra
+  \textbf{S}ubprograms). Thus install GotoBLAS2, ATLAS,
+  non-optimized BLAS or a BLAS library provided by a computer
+  vendor. Take care that the installation scripts select the intended
+  version of BLAS. For further information, see
+  \texttt{\url{http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms}}.
 
-\item \textbf{GotoBLAS2}: This is an optimized version of BLAS. It covers not  all processors of the day, but quite a broad range. Its license is now very open.  A Fortran compiler like \texttt{gfortran} is needed to compile it.\\
+\item \textbf{GotoBLAS2}: This is an optimized BLAS library. It does
-Available by \texttt{\url{http://www.tacc.utexas.edu/tacc-projects/gotoblas2/}}.
+  not provide optimized routines for all modern processors, but quite
+  a broad range. Also, its license is now open. A Fortran compiler
+  like \texttt{gfortran} is needed to compile it.
 
-\item \textbf{METIS}: This is a dependency of ALUGrid, if you are going to run it parallel.
+  Available at
+  \texttt{\url{http://www.tacc.utexas.edu/tacc-projects/gotoblas2/}}.
 
-\item \textbf{Compilers}: Beside \texttt{g++} it has been reported that \Dune was successfully built with \texttt{Clang++} from the LLVM project and the Intel \Cplusplus compiler. 
+\item \textbf{METIS}: This is a dependency of ALUGrid, if you are
-C and Fortran compiler is needed for some external libraries. As code of different compilers is linked together they have to be be compatible with each other. A good choice is the GNU compiler suite \texttt{gcc}, \texttt{g++} and \texttt{gfortran}.
+  going to run it parallel.
+  
+  Available for non-commercial use at
+  \texttt{\url{http://glaros.dtc.umn.edu/gkhome/metis/metis/overview}}
 
-\item \textbf{libgomp}: External libraries, such as ALUGrid, can make use of OpenMP when used together with METIS. For that purpose it can be necessary to install the \texttt{libgomp} library.
+\item \textbf{Compilers}: Besides \texttt{g++} \Dune and \eWoms can
-% http://openmp.org/
+  also be built with the \texttt{clang++} compiler originating from
-
+  the LLVM project. If you try other compilers, be aware that in addition to a
-%\item \textbf{libgmp}: The Gnu Multiple Precision Arithmetic Library (GMP) is also a prerequisite for \Dune. It may be necessary to install it.
+  \Cplusplus compiler, C and Fortran compilers are needed to compile
-% http://gmplib.org/
+  some external libraries.
 \end{itemize}
 
-\section{Hints for Users from IWS}
-We provide some features to make life a little bit easier for
-users from the Institute for Modelling Hydraulic and Environmental Systems, University of Stuttgart.
-
-There exists internally a SVN repository made for several external libraries.
-If you are allowed to access it, go to the {\Dune}-Root, then the following.
-
-Prepared external directory:
-\begin{lstlisting}[style=Bash]
-$ # Make sure you are in DUNE-Root
-$ svn checkout svn://svn.iws.uni-stuttgart.de/DUMUX/external/trunk external
-\end{lstlisting}
-
-This directory \texttt{external} contains a script to install external libraries, such as 
-ALBERTA, ALUGrid, UG, METIS and GotoBLAS2:
-\begin{lstlisting}[style=Bash]
-$ cd external
-$ ./installExternal.sh all
-\end{lstlisting}
-
-It is also possible to install only the actually needed external libraries:
-\begin{lstlisting}[style=Bash]
-$ ./installExternal.sh -h      # show, what options this script provide
-$ ./installExternal.sh --parallel alu
-\end{lstlisting}
-
-The libraries are then compiled within that directory and are not installed in a different place. 
-A \Dune build may need to know their location. Thus, one may have to refer to them as options for \texttt{dunecontrol}, 
-for example via the options file \texttt{my-debug.opts}. Make sure you compile the required external libraries before 
-you run \texttt{dunecontrol}.
-
-
-
-
 %%% Local Variables: 
 %%% mode: latex
 %%% TeX-master: "ewoms-handbook"

doc/handbook/intro.tex

@@ -1,6 +1,6 @@
 \chapter{Introduction}
 
-\eWoms aims to be a generic framework for the simulation of multiphase
+\eWoms~\cite{EWOMS-HP} aims to be a generic framework for the simulation of multi-phase
 fluid flow and transport processes in porous media using continuum
 mechanical approaches.  At the same time, \eWoms aims to deliver
 top-notch computational performance, high flexibility, a sound
@@ -8,6 +8,16 @@ software architecture and the ability to run on anything from single
 processor systems to highly parallel supercomputers with specialized
 hardware architectures.
 
+\eWoms is an integral part of the open porous media
+initiative~\cite{OPM-HP} where it provides the fully-implicit
+models. \eWoms is based on the source code of the
+\Dumux~\cite{DUMUX-HP} simulation framework and aims to be a proper
+superset of \Dumux when it comes to features, while at the same time
+it aims to deliver better performance and quality of the source
+code. To ease porting features from \Dumux to \eWoms and vice-versa,
+all classes provided by \eWoms are currently located in the namespace
+\texttt{Dumux}.
+
 The means to achieve these somewhat contradictory goals are the
 thorough use of object oriented design in conjunction with template
 programming. These requirements motivated the decision to use

doc/handbook/new-folder.tex

@@ -1,54 +1,87 @@
-\section{Setup of a New Folder}
+\chapter{Creating a new directory for source code}
 
-In this section setting up a new folder is described. In fact it is very easy to create a new folder, but getting \Dumux to know the new folder takes some steps which will be explained in more detail below:
+In this section, we describe how setting up a new directory for source
+code. In fact, it is very easy to create a new directory, but getting
+\Dune build system to recognize the new folder takes some steps which
+will be explained in more detail below:
 
 \begin{itemize}
- \item create new folder with content
+\item Create new directory with content. Quite often an existing
- \item adapt \verb+Makefile.am+
+  directory can be used as a base for the new one.
- \item insert new folder in \verb+Makefile.am+ of the directory above
+\item Adapt \texttt{Makefile.am} in the new directory and add this
- \item adapt \verb+configure.ac+ in the \verb+$DUMUX_ROOT+ (the directory you checked out, probably dumux)
+  direcory to the \texttt{SUBDIRS} list of the \texttt{Makefile.am} in
- \item newly compile \Dumux
+  the directory above the one which you just created.
+\item Adapt \texttt{configure.ac} in the \eWoms base directory (the
+  directory to which you checked out or unpacked the \eWoms source
+  code, probably \texttt{ewoms})
+\item Run the command \texttt{automake} in the \eWoms base directory.
+\item Re-compile \eWoms by typing \texttt{make} in the \eWoms base
+  directory.
 \end{itemize}
 
 \noindent In more detail:
 
-\textbf{First} of all, the new folder including all relevant files needs to be created (see Section \ref{tutorial-coupled} and \ref{tutorial-decoupled} for description of a problem). 
+\textbf{First} of all, the new directory including all relevant files
+needs to be created (see section \ref{tutorial-coupled} and
+\ref{tutorial-decoupled} for description of how to define problems).
 
-\textbf{Second}, a new \verb+Makefile.am+ for the new Folder needs to be created. It is good practice to simply copy an existing file. For example the file \verb+$DUMUX_ROOT/test/2p/Makefile.am+ looks as follows:
+\textbf{Second}, a new \texttt{Makefile.am} for the new directory
+needs to be created. It is good practice to simply copy and modify an
+existing file. For example, the file \texttt{tutorial/Makefile.am}
+looks as follows:
 \begin{verbatim}
-bin_PROGRAMS = test_2p
+# programs just to build when "make check" is used
+check_PROGRAMS = tutorial_decoupled tutorial_coupled
 
-test_2p_SOURCES = test_2p.cc
+noinst_HEADERS= *.hh
-test_2p_CXXFLAGS = $(MPI_CPPFLAGS) 
+EXTRA_DIST = CMakeLists.txt
-test_2p_LDADD = $(MPI_LDFLAGS) 
+
+tutorial_coupleddir = $(datadir)/dumux/tutorial
+tutorial_coupled_SOURCES = tutorial_coupled.cc
+tutorial_coupled_DATA = $(tutorial_coupled_SOURCES)
 
 include $(top_srcdir)/am/global-rules
 \end{verbatim}
 
-All occurrences of \verb+test_2p+ need to be replaced by the name of the new project, e.g. \verb+New_Project+. At least if the name of the source file as well as the name of the new project are \verb+New_Project+.
+All occurrences of \texttt{tutorial\_coupled} need to be replaced by
+the name of the new project, e.g. \texttt{new\_project}. At least if
+the name of the source file as well as the name of the new project are
+\texttt{new\_project}.
 
-\textbf{Third}: In the directory above your new Project there is also a \verb+Makefile.am+ . In this file the subdirectories are listed. As you introduced a new subdirectory, it needs to be included here. In this case the name of the new Folder is \verb+New_Project+ . Don't forget the trailing backslash.
+\textbf{Third}: In the parent directory of the directory which you
+created, there is also a \texttt{Makefile.am}. In this file the
+sub-directories are listed. As you introduced a new sub-directory, it
+needs to be included there. In this case, the name of the new
+directory is \texttt{new\_project}.
 
 \begin{verbatim}
- SUBDIRS = . \
+...
-	  1p \
+SUBDIRS = doc dumux m4 test tutorial new_project
-	  1p2c \
-	  2p \
-	  2p2c \
-	  2p2cni \
-	  2pni \
-	New_Project \
 ...
 \end{verbatim}
 
-\textbf{Fourth}: In \verb+$DUMUX_ROOT+ there is a file \verb+configure.ac+. In this file, the respective Makefiles are listed. After a line reading
+\textbf{Fourth}: In \eWoms base directory there is a file
+\texttt{configure.ac}. In this file, the respective Makefiles are
+listed. After a line reading
 
- \verb+AC_CONFIG_FILES([Makefile+ 
+ \texttt{AC\_CONFIG\_FILES([Makefile} 
 
- \noindent a line, declaring a new Makefile, needs to be included. The Makefile itself will be generated automatically. For keeping track of the included files, inserting in alphabetical order is good practice. The new line could read: \verb+test/New_Project/Makefile+ 
+ \noindent a line, declaring a new Makefile, needs to be added. The
-
+ Makefile itself will be generated automatically from the
-\textbf{Fifth}: Compile \Dumux as described in Section \ref{install}.
+ \texttt{Makefile.am} file which you just generated. For keeping track
+ of the included files, it is adviced to insert new Makefiles in
+ alphabetical order. The new line could read:
+ \texttt{new\_project/Makefile}
 
+ \textbf{Fifth}: Run the command \texttt{automake} in the \eWoms base
+ directory.
+
+ \textbf{Sixth}: Re-compile \eWoms as described in Section \ref{install}.
+
+%%% Local Variables: 
+%%% mode: latex
+%%% TeX-master: "ewoms-handbook"
+%%% End: 
 
 
 

doc/handbook/newton-in-a-nutshell.tex

@@ -1,64 +1,72 @@
-\chapter{Newton in a Nutshell}
+\chapter{The Newton-Raphson method}
 
-For the isothermal immiscible multi-phase model for flow in porous
+For the isothermal immiscible multi-phase model, the following mass
-media, the following mass conservation equation needs to be solved:
+conservation equation needs to be solved:
 \begin{align}
 \underbrace{
-  \phi \frac{\partial \varrho_\alpha S_\alpha}{\partial t}
+  \frac{\partial \phi \varrho_\alpha S_\alpha}{\partial t}
  -
  \text{div} \left\{
  \varrho_\alpha \frac{k_{r\alpha}}{\mu_\alpha} \mbox{\bf K} \left(\text{grad}\, p_\alpha - \varrho_{\alpha} \mbox{\bf g} \right)
  \right\} - q_\alpha} _
-{\textbf{f}(\textbf{u}^r)}
+{\textbf{f}(\textbf{u})}
 = 0 \; .
 \end{align}
 
-Because of the nonlinear dependencies (even in this comparativly simple equation) in there, this is a really difficult task. However, for finding roots of of difficult equations there is a really handy method out there: \textsc{Newton}'s method. 
+Because of the nonlinear dependencies even solving this comparatively
+simple equation is a quite challenging task. However, for
+finding roots of non-linear systems equations the
+\textsc{Newton}-\textsc{Raphson} method can be used.
 
-When using a fully coupled numerical model, one timestep essentially consists of the application of the \textsc{Newton} algorithm to solve the nonlinear system.
+When using a fully-implicit numerical model, each time step essentially
+consists of the application of the \textsc{Newton} algorithm to solve
+the nonlinear system.
 
-One step of the \textsc{Newton} method can be formalized as follows:
+The idea of this algorithm is to linearize the non-linear system of
+equation at a given solution, and then solving the resulting linear
+system of equations. The hope is, that the solution of this linear
+system is closer to the root of the non-linear system of
+equations. This process is repeated until either convergence is
+reached (a pre-determined accuracy is reached), or divergence of the
+algorithm is detected (either by trespassing the maximum number of
+iterations or by failure to linearize). This method can be formalized
+as follows:
 
-\textsc{Newton} method: 
 \begin{subequations}
 \begin{align}
 \label{NewtonGen}
-\textbf{u}^{r+1} &= \textbf{u}^r -  \left(\textbf{f}^\prime (\textbf{u}^r) \right)^{-1} \textbf{f}(\textbf{u}^r) \\
+\textbf{u}^{r+1} &= \textbf{u}^r + \Delta \textbf{u}^r \\
-\Leftrightarrow {\textbf{f}^{\prime}(\textbf{u}^r)}  ( \textbf{u}^{r+1}-\textbf{u}^r) &= -\textbf{f}(\textbf{u}^r) \\
+\Delta \textbf{u}^r & = - \left\{\text{grad}\,\textbf{f} (\textbf{u}^r) \right\}^{-1} \textbf{f}(\textbf{u}^r) \\
-\Leftrightarrow \underbrace{\textbf{f}^{\prime}(\textbf{u}^r)}_{\textnormal{Jacobian}} ( \textbf{u}^r - \textbf{u}^{r+1}) &= \textbf{f}(\textbf{u}^r) \label{NewtonAsUsed}
 \end{align}
 \end{subequations}
 
 \noindent with
 \begin{itemize}
+\item $\textbf{u}$: Vector of unknowns
+\item $\textbf{f}(\textbf{u}^r)$: Residual (Function of the vector of unknowns which ought to be set to $0$)
 \item $\phantom{a}^r$: last iteration, $\phantom{a}^{r+1}$: current iteration,
-\item $\phantom{a}^\prime$: derivative
+\item $\text{grad}\,\phantom{a}$: \textsc{Jacobian} matrix of
-\item $\textbf{u}$: vector of unknowns, the actual primary variables
+  $\textbf{f}$, i.e. matrix of the derivatives of \textbf{f} regarding
-\item $\textbf{f}(\textbf{u}^r)$: function of vector of unknowns
+  all components of $\textbf{u}$
 \end{itemize}
 
-1-D example with slope $m$:
+The value of $\textbf{u}$ for which $\textbf{f}$ becomes zero is
-\begin{equation}
+searched for. Bringing \eqref{NewtonGen} into the form used the linear
- m= \frac{y(u^{r+1})-y(u^{r})}{u^{r+1}-u^{r}} \textnormal{ for a root of a function: } m= - \frac{y(u^{r})}{u^{r+1}-u^{r}}
+solvers
-\end{equation}
-The value of u (generally a vector of unknowns) for which f becomes zero is searched for. Therefore the quantity of interest is $\textbf{u}^{r+1}$.
-
-But the (BiCGSTAB / Pardiso / ...) linear solver solves systems of the form:
 \begin{equation}
 \label{GenSysEq}
- A\textbf{x} = \textbf{b} .
+ \textbf{A}\textbf{x} - \textbf{b} = 0 
 \end{equation}
-
+leads to
-Comparing (\ref{GenSysEq}) with (\ref{NewtonAsUsed}) leads to:
 \begin{itemize}
-\item $\textbf{b} = \textbf{f}(\textbf{u}^r)$ r.h.s. as it is known from the last iteration. Here, $\textbf{f}(\textbf{u}^r)$ is called residual. It is obtained by evaluating the balance equations with the primary variables, as obtained from the last iteration step.
+\item $\textbf{A} = \text{grad}\,\textbf{f} (\textbf{u}^r)$
-\item $A=\textbf{f}^{\prime}(\textbf{u}^r)$ coefficient matrix or \textsc{Jacobian}. It is obtained by numerical differentiation. Evaluating the balance equations at the last solution + eps, then evaluating the balance equations at the last solution - eps, division by 2eps: numerical differentiation complete.
+\item $\textbf{x} = \textbf{u}^{r} - \textbf{u}^{r+1}$
-\item $\textbf{x} = (\textbf{u}^{r+1} - \textbf{u}^{r})$ this is what the linear solver finds as an solution. 
+\item $\textbf{b} = \textbf{f}(\textbf{u}^{r})$
 \end{itemize}
 
-This is equivalent to stating that the implemented algorithm solves for the change of the solution. Or in other words: until the $\textbf{u}$ does not change with one more \textsc{Newton-}iteration (do not confuse with timestep!).
+Once $\textbf{u}^{r} - \textbf{u}^{r+1}$ has been calculated, \eWoms
-
+updates the current solution in \texttt{NewtonController::update()}
-In the rest of Dumux (everywhere besides in the solver), not the change of the solution is looked for, but the actual solution is used. Therefore the outcome of the linear solver needs to be reformulated as done in \verb+updateMethod.update(*this, u, *uOld, model);+. In this function the ``change in solution'' is changed to ``solution''. Afterwards the quantity \verb+*u+ stands for the solution.
+and starts the next iteration if the scheme has not yet converged.
 
 %%% Local Variables: 
 %%% mode: latex

doc/handbook/structure.tex

@@ -1,25 +1,23 @@
-\chapter{Structure, Guidelines, New Folder Setup}
+\chapter{Directory structure}
 
-\section{Directory Structure}
+We briefly describe the directory structure of \eWoms in terms 
-
-We briefly describe the directory structure of \Dumux in terms 
 of subdirectories, source files, and tests. For more details, 
 the Doxygen documentation should be considered. 
-\Dumux comes in form of a DUNE module \texttt{dumux}. 
+\eWoms comes in form of a DUNE module \texttt{dumux}. 
 It has a similar structure as other DUNE modules like \texttt{dune-grid}. 
 The following subdirectories are within the module's root directory, 
 from now on assumed to be \texttt{/}: 
 \begin{itemize} 
 \item \texttt{CMake}: the configuration options 
-for building \Dumux using CMake. See the file \texttt{INSTALL.cmake} in 
+for building \eWoms using CMake. See the file \texttt{INSTALL.cmake} in 
-the root directory of \texttt{dumux} for details. Of course, 
+the root directory of the \eWoms distribution for details. Of course, 
 it is also possible to use the DUNE buildsystem just like for the other 
 DUNE modules.
 \item \texttt{doc}: contains the Doxygen documentation in \texttt{doxygen}, 
-this handbook in \texttt{handbook}, and the \Dumux logo in various formats in 
+this handbook in \texttt{handbook}, and the \eWoms logo in various formats in 
 \texttt{logo}. The html documentation produced by Doxygen can be accessed as usual, 
 namely, by opening \texttt{doc/doxygen/html/index.html} with a web browser. 
-\item \texttt{dumux}: the \Dumux source files. See Section \ref{sec:dumux} for details. 
+\item \texttt{dumux}: the \eWoms source files. See Section \ref{sec:dumux} for details. 
 \item \texttt{test}: tests for each numerical model and the property system. 
 See Section \ref{sec:test} for details. 
 \item \texttt{tutorial}: contains the tutorials described in Chapter \ref{chp:tutorial}. 
@@ -28,91 +26,91 @@ See Section \ref{sec:test} for details.
 
 \subsection{The \texttt{dumux} directory}\label{sec:dumux}
 
-The directory \texttt{dumux} contains the \Dumux source files. It consists of the following subdirectories (see Figure \ref{fig:dumux-structure}): 
+The directory \texttt{dumux} contains the \eWoms source files. It consists of the following subdirectories (see Figure \ref{fig:dumux-structure}): 
 
 \begin{itemize} 
 
-\item \texttt{boxmodels}:
+\item \texttt{boxmodels}: The fully implicit vertex-centered finite
-the general fully implicit box method is contained in the subdirectory 
+  volume (box) method. This directory features the following
-\texttt{common}, while each of the other subdirectories contains 
+  sub-directories
-a derived specific numerical model. The subdirectory \texttt{common} also contains the file \texttt{boxfvelementgeometry.hh} employed by the box method to extract the dual mesh geometry information out of the primal one. 
+  \begin{itemize} 
-% The files \texttt{pdelabboxassembler.hh} and \texttt{pdelabboxlocaloperator.hh} allow the use of the DUNE module \texttt{dune-pdelab}. 
+  \item \texttt{common}: The infrastructural code shared by all box
+    models; For example it contains the file
+    \texttt{boxfvelementgeometry.hh} which is used by the box scheme to
+    construct the dual grid out of the primal one.
+  \item \texttt{modules}: This directory features parts which can be
+    re-used by multiple models, like a generic plug-in for the energy
+    equation, models for determining the filter velocity, or plugins
+    describing molecular diffusion.
+  \item Each of the other subdirectories contains 
+    a physical numerical model which uses the box discretization.
+  \end{itemize}
 
-\item \texttt{common}:
+\item \texttt{common}: General stuff like the \eWoms property system
-general stuff like the property system and the time management for the 
+  and classes for managing time which are shared by the fully-implicit
-fully coupled as well as the decoupled models, 
+  and the semi-implicit models.  For example it features the file
-% the interface for the Pardiso direct solver library \cite{Pardiso}, 
+  \texttt{start.hh} which provides the default way for starting a
-and the \texttt{start.hh} file that includes the common routine for starting a model called in the main function. 
+  simulation.
 
 \item \texttt{decoupled}:
- numerical models to solve the pressure equation as part of the fractional flow formulation. The specific models are contained 
+ Numerical models to solve the pressure equation as part of the fractional flow formulation. The specific models are contained 
- in corresponding subdirectories. In each model folder are subdirectories for the implicit pressure equation sorted by the employed discretization method, and for the explicit transport equation. The general decoupled formulation for the implicit pressure explicit transport formulation can be found in the subdirectory \texttt{common}.
+ in corresponding subdirectories. In each model folder are subdirectories for the implicit pressure equation sorted by the employed discretization method, and for the explicit transport equation. The general semi-implicit formulation for the implicit pressure, explicit transport formulation can be found in the subdirectory \texttt{common}.
 
-% \item \texttt{fractionalflow}:
+\item \texttt{io}: Additional classes that provide in-/output routines
-% the (non-compositional) fractional flow model, which utilizes the IMPES method 
+  like writing and reading restart files (often called 'checkpoint'
-% contained in the subdirectory \texttt{impes}.
+  files) and for writing a series of VTK files.
 
-% \item \texttt{functions}:
+\item \texttt{material}: Everything related to material parameters and
-% the Crouzeix--Raviart function implemented in the style of \texttt{dune-disc}'s P1 function. 
+  constitutive equations. For example, the properties of a pure
+  chemical substance (e.g. water) or pseudo substance (e.g. air) can
+  be found in the subdirectory \texttt{components} with the base class
+  \texttt{components/component.hh}. Fluid systems are located in the
+  sub-folder \texttt{fluidsystems}, while capillary pressure/relative
+  permeability laws are located in the sub-folder
+  \texttt{fluidmatrixinteractions}. Furthermore, the classes computing
+  binary coefficients like the Henry coefficient or binary diffusion
+  coefficients are held by the sub-folder \texttt{binarycoefficients}.
 
-% \item \texttt{fvgeometry}:
+\item \texttt{nonlinear}: This folder contains an implementation of
-% employed by the box method to extract the dual mesh geometry information out of the 
+  the Newton-Raphson method for solving non-linear systems of
-% primal one. 
+  equations.
 
-\item \texttt{io}: additional in-/output possibilities like restart files 
+\item \texttt{linear}: This folder features code which is required to
-and a VTKWriter extension. 
+  parallelize the linear solvers, as well as back-ends for these
-
+  solvers. For example it contains classes to calculate an overlap
-\item \texttt{material}: everything related to material parameters and 
+  given the distributed matrix of the linear system, and provides
-constitutive equations. The properties of a pure chemical substance (e.g. water) or pseudo substance (e.g. air) can be found in the subdirectory \texttt{components} with the base class \texttt{components/component.hh}. The fluidsytem in the folder \texttt{fluidsystems} collects the information from the respective component and binary coefficients files, and contains the fluid characteristics of phases (e.g. viscosity, density, enthalpy, diffusion coefficients) for compositional or non-compositional multi-phase flow. 
+  classes which use this overlap to provide overlapping matrices,
-
+  vectors, linear operators and scalar products.
-The base class for all spatially dependend variables -- like permeability and porosity  -- 
-can be found in \texttt{spatialparameters}. The base class in \texttt{boxspatialparameters.hh} 
-also provides spatial averaging routines. All other spatial properties are specified in the specific
- files of the respective models. Furthermore, the constitutive relations -- e.g. $p_c(S_w) $ -- are in \texttt{fluidmatrixinteractions}, 
-while the necessary binary coefficients like the Henry coefficient or binary diffusion coefficients are definded in
- \texttt{binarycoefficients}.
-
-
-\item \texttt{nonlinear}: Newton's method.
-
-
-% \item \texttt{operators}: based on \texttt{dune-disc}, assembly operators for Crouzeix--Raviart 
-% elements and mimetic finite differences. 
-% 
-% 
-% \item \texttt{pardiso}: interface to the Pardiso direct solver library, \cite{Pardiso}. 
-% 
-% 
-% \item \texttt{shapefunctions}:  Crouzeix--Raviart element shape functions. 
-% 
-% 
-% \item \texttt{timedisc}: time discretization for the decoupled models. 
-% 
-% 
-% \item \texttt{transport}: numerical models to solve the pressure equation 
-% as part of the fractional flow formulation analogous to the \texttt{diffusion} 
-% directory. Moreover, the compositional decoupled models are included here. 
 
+\item \texttt{istl}: This folder contains a copy of slightly modified
+  linear solvers from the ISTL \Dune module. The reason why they where
+  copied is to provide linear solvers with better performance and
+  stability without being held back by the \Dune developers.
 
+\item \texttt{parallel}: Contains some helper classes useful for
+  programming MPI parallel code. For example this folder contains a
+  simple MPI buffer class, and various commonly used \Dune
+  data-handles.
 \end{itemize}
 
-
-
 \subsection{The directory \texttt{test}}\label{sec:test}
 
-
+The directory \texttt{test} contains at least one test/example for
-The directory \texttt{test} contains a test for each numerical model and for 
+each numerical model and for each important aspect of the common
-the property system. The tests for the property system can be found in \texttt{common}. 
+\eWoms infrastructure. The directory \texttt{common} contains a test
-The subfolder \texttt{boxmodels} contains tests for the fully 
+for the property system.  The sub-directory \texttt{boxmodels}
-coupled models (\texttt{1p},  \texttt{1p2c},  \texttt{2p},  \texttt{2p2c},  
+contains test applications for the fully-implicit models (where each
-\texttt{2p2cni},  \texttt{2pni}, \texttt{3p3c},  \texttt{3p3cni},  \texttt{mpnc} and \texttt{richards}), while the subdirectory \texttt{decoupled} corresponds to the decoupled models. 
+test is named according to the scheme \texttt{PROBLEMNAME\_MODDEL}),
-Each subdirectory contains one or more program files \texttt{test\_*.cc}, where \texttt{*} usually is the 
+while the subdirectory \texttt{decoupled} features tests for the
-name of the folder. Moreover, the problem definitions can be found 
+semi-implicit models.  Each subdirectory contains one or more program
-in the \texttt{*problem.hh} files and the definition of the spatially dependent parameters in \texttt{*spatialparameters.hh}. Simply executing the tests should either run the 
+files \texttt{*.cc} which contain the main function for the
-full test or give a list of required command line arguments. After test execution, 
+test. Moreover, the problem definitions can be found in the
-VTK output files should have been generated. 
+\texttt{*problem.hh} files. Simply executing the tests should either
-For more detailed descriptions of the tests, the problem definitions and their corresponding 
+run the full test or give a list of required command line
-Doxygen documentation should be considered. 
+arguments. After test execution, VTK output files are generated by
+most tests.  For more detailed descriptions of the tests, the problem
+definitions and their corresponding Doxygen documentation should be
+considered.
 
 \begin{landscape}
 \begin{figure}[hbt]
@@ -120,7 +118,7 @@ Doxygen documentation should be considered.
   \includegraphics[width=\linewidth, keepaspectratio]{EPS/ewoms_structure.eps}
   \caption{
     \label{fig:dumux-structure}
-    Structure of the \eWoms source tree.
+    Structure \texttt{dumux} sub-directory of the \eWoms source tree.
   }
 \end{figure}
 \end{landscape}

doc/handbook/tutorial-decoupled.tex

@@ -1,13 +1,6 @@
-\section[Decoupled model]{Solving a problem using a Decoupled Model}\label{tutorial-decoupled}
+\section[Semi-implicit model]{Solving a problem using a Semi-implicit Model}\label{tutorial-decoupled}
-The process of solving a problem using \Dumux can be roughly divided into four parts: 
-\begin{enumerate}
- \item The geometry of the problem and correspondingly a grid have to be defined.
- \item Material properties and constitutive relationships have to be defined.
- \item Boundary conditions as well as initial conditions have to be defined.
- \item A suitable model has to be chosen.
-\end{enumerate}
 
-In contrast to the last section, we now apply a decoupled solution procedure, a
+In contrast to the last section, we now apply a semi-implicit solution procedure, a
 so-called \textit{IMPET} (\textit{IM}plicit \textit{P}ressure \textit{E}xplicit 
 \textit{T}ransport) algorithm. This means that the pressure equation is first 
 solved using an implicit method. The resulting velocities are then used to solve
@@ -16,8 +9,8 @@ In this tutorial, pure fluid phases are solved with a finite volume discretizati
 of both pressure- and transport step. Primary variables, according to default
 settings of the model, are the pressure and the saturation of the wetting phase.
 
-The problem which is solved in this tutorial is illustrated in figure 
+The problem which is solved in this tutorial is the same as for the previous tutorial and is illustrated in figure 
-\ref{tutorial-decoupled:problemfigure}. A rectangular domain with no flow 
+\ref{tutorial-decoupled:problemfigure}: A rectangular domain with no flow 
 boundaries on the top and at the bottom, which is initially saturated with oil, 
 is considered. Water infiltrates from the left side into the domain. Gravity 
 effects are neglected.
@@ -39,46 +32,46 @@ effects are neglected.
 \caption{Geometry of the tutorial problem with initial and boundary conditions.}\label{tutorial-decoupled:problemfigure}
 \end{figure}
 
-Listing \ref{tutorial-decoupled:mainfile} shows how the main file, which has to be executed, has to be set up, if the problem described above is to be solved using a decoupled model. This main file can be found in the directory \texttt{/tutorial} of the stable part of \Dumux.
+Listing \ref{tutorial-decoupled:mainfile} shows how the main file, which has to be executed, has to be set up, if the problem described above is to be solved using a semi-implicit model. This main file can be found in the directory \texttt{/tutorial} below the \eWoms base directory.
 
 \begin{lst}[File tutorial/tutorial\_decoupled.cc]\label{tutorial-decoupled:mainfile} \mbox{}
-\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=24, firstnumber=24]{../../tutorial/tutorial_decoupled.cc}
+\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=26, firstnumber=26]{../../tutorial/tutorial_decoupled.cc}
 \end{lst}
 
 First, from line \ref{tutorial-decoupled:include-begin} to line
-\ref{tutorial-decoupled:include-end} the \Dune and \Dumux files containing
+\ref{tutorial-decoupled:include-end} the \Dune and \eWoms files containing
 essential functions and classes are included.
 
 At line \ref{tutorial-decoupled:set-type-tag} the type tag of the
 problem which is going to be simulated is set. All other data types
-can be retrieved by the \Dumux property system and only depend on this
+can be retrieved by the \eWoms property system and only depend on this
 single type tag. For an introduction to the
 property system, see section \ref{sec:propertysystem}.
 
-After this \Dumux' default startup routine \texttt{Dumux::start()} is
+After this, \eWoms' default startup routine \texttt{Dumux::start()} is
 called in line \ref{tutorial-decoupled:call-start}. This function deals
-with parsing the command line arguments, reading the parameter file,
+with parsing the command line arguments, 
 setting up the infrastructure necessary for \Dune, loading the grid, and
 starting the simulation. All parameters can
 be either specified by command line arguments of the form
-(\texttt{--ParameterName=ParameterValue}), in the file specified by the
+(\texttt{--ParameterName=ParameterValue}), or in the file specified by the
 \texttt{--ParameterFile=filename.ini} argument. If a parameter is
 specified on the command line as well as in the parameter file, the
-values provided in the command line have
+values provided in the command line takes
 precedence.
 
 \subsection{The problem class} \label{decoupled_problem}
 
-When solving a problem using \Dumux, the most important file is the
+When solving a problem using \eWoms, the most important file is the
 so-called \textit{problem file} as shown in listing
 \ref{tutorial-decoupled:problemfile} of
 \texttt{tutorialproblem\_decoupled.hh}.
 
 \begin{lst}[File tutorial/tutorialproblem\_decoupled.hh]\label{tutorial-decoupled:problemfile} \mbox{}
-\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=24, firstnumber=24]{../../tutorial/tutorialproblem_decoupled.hh}
+\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=27, firstnumber=27]{../../tutorial/tutorialproblem_decoupled.hh}
 \end{lst}
 
-First, both \Dune  grid handlers and the decoupled model of \Dumux 
+First, both \Dune  grid handlers and the semi-implicit model of \eWoms 
 have to be included. Then, a new type tag is created for the problem 
 in line \ref{tutorial-decoupled:create-type-tag}.  In this case, the 
 new type tag inherits all properties defined for the \texttt{DecoupledTwoP} 
@@ -88,13 +81,13 @@ is chosen as discretization scheme (defined via the include in line
 a problem class is attached to the new type tag, while the grid which
 is going to be used is defined in line \ref{tutorial-decoupled:set-grid-type} --
 in this case an \texttt{YaspGrid} is created. Since there's no uniform mechanism to
-allocate grids in \Dune, \Dumux features the concept of grid creators.
+allocate grids in \Dune, \eWoms features the concept of grid creators.
 In this case the generic \texttt{CubeGridCreator} (line \ref{tutorial-decoupled:set-gridcreator}) which creates a
 structured hexahedron grid of a specified size and resolution. For
 this grid creator the  physical domain of the grid is specified via the
-run-time parameters \texttt{Grid.upperRightX},
+run-time parameters \texttt{DomanSizeX},
-\texttt{Grid.upperRightY}, \texttt{Grid.numberOfCellsX} and
+\texttt{DomanSizeY}, \texttt{CellsX} and
-\texttt{Grid.numberOfCellsY}. These parameters can be specified via
+\texttt{CellsY}. These parameters can be specified via
 the command-line or in a parameter file.
 For more information about the \Dune grid interface, the different grid types 
 that are supported and the generation of different grids consult 
@@ -102,45 +95,45 @@ the \textit{Dune Grid Interface HOWTO} \cite{DUNE-HP}.
 
 Next, we select the material of the simulation: In the case of a pure two-phase
 model, each phase is a bulk fluid, and the complex (compositional) fluidsystems
-do not need to be used. However, they can be used (see exercise 1 \ref{dec-ex1-fluidsystem}). 
+do not need to be used. However, they can be used (see exercise 1e). 
-Instead, we use a simplified fluidsystem container that provides classes 
+Instead, we use a simplified fluidsystem that wraps pure component classes 
-for liquid and gas phases, line \ref{tutorial-decoupled:2p-system-start} to 
+for the liquid and gas phases. This is done from line \ref{tutorial-decoupled:2p-system-start} to 
-\ref{tutorial-decoupled:2p-system-end}. These are linked to the appropriate 
+\ref{tutorial-decoupled:2p-system-end}. These components represent fluids made of pure 
-chemical species in line \ref{tutorial-decoupled:wettingPhase} and 
+chemical species, but given the fact, that a even pure chemical species can assume two phases, only their respective liquid phase is selected on lines \ref{tutorial-decoupled:wettingPhase} and 
 \ref{tutorial-decoupled:nonwettingPhase}. For all parameters that depend 
 on space, such as the properties of the soil, the specific spatial parameters 
 for the problem of interest are specified in line
 \ref{tutorial-decoupled:set-spatialparameters}. 
 
-Now we arrive at some model parameters of the applied two-phase decoupled 
+Now we arrive at some model parameters of the applied two-phase semi-implicit 
-model. First, in line  \ref{tutorial-decoupled:cflflux} a flux function for the evaluation of the cfl-criterion is defined. This is optional as there exists also a default flux function. The choice depends on the problem which has to be solved. For cases which are not advection dominated the one chosen here is more reasonable.
+model. First, in line  \ref{tutorial-decoupled:cflflux} a flux function for the evaluation of the CFL-criterion is defined. This is optional as there exists also a default flux function. The choice depends on the problem which has to be solved. For cases which are not advection dominated, the one chosen here is more reasonable.
 Line \ref{tutorial-decoupled:cflfactor} assigns the CFL-factor to be used in the
-simulation run, which scales the time step size (kind of security factor). The last property in line \ref{tutorial-decoupled:gravity} 
+simulation run, which scales the time step size (kind of security factor). The next property, defined on line \ref{tutorial-decoupled:gravity} 
-is optional and tells the model not to use gravity.
+is optional and tells the model to disregard gravity.
+Finally, the default dimensions of the size of the physical and temporal
+domains are defined on lines
+\ref{tutorial-decoupled:domain-defaults-begin} to
+\ref{tutorial-decoupled:domain-defaults-end}.
 
-After all necessary information is written into the property system and 
+After all necessary properties are defined and 
-its namespace is closed in line \ref{tutorial-decoupled:propertysystem-end},
+its \texttt{Properties} namespace is closed in line \ref{tutorial-decoupled:propertysystem-end},
 the problem class is defined in line \ref{tutorial-decoupled:def-problem}. 
 As its property, the problem class itself is also derived from a parent, 
-\texttt{IMPESProblem2P}. The class constructor (line 
+\texttt{IMPESProblem2P}.
-\ref{tutorial-decoupled:constructor-problem}) is able to hold two vectors,
-which is not needed in this tutorial.
 
-Beside the definition of the boundary and initial conditions (discussed in 
+Beside the definition of the boundary and initial conditions, the problem class also provides
-subsection \label{decoupled-problem:boundary}), the problem class also contains
+general information about the current simulation. First, the name used by for the
-general information about the current simulation. First, the name used by
+resulting VTK output files is defined by the \texttt{name()} method of line
-the \texttt{VTK-writer} to generate output is defined in the method of line
 \ref{tutorial-decoupled:name}, and line \ref{tutorial-decoupled:restart} indicates
-whether restart files are written. As decoupled schemes usually feature small 
+when and whether restart files are written. As semi-implicit schemes usually feature small 
-timesteps, it can be usefull to set an output interval larger than 1. The respective function is called in line \ref{tutorial-decoupled:outputinterval}, which gets the output interval as argument.
+timesteps, it can be useful to set an output interval larger than 1. The respective function is called in line \ref{tutorial-decoupled:outputinterval}, which gets the output interval as argument.
 
 The following methods all have in common that they may be dependent on space.
 Hence, they all have either an \texttt{element} or an \texttt{intersection} as their
 function argument: Both are \Dune entities, depending on whether the parameter of the method is defined in an element, such as 
-    initial values, or on an intersection, such as a boundary condition. As it may be sufficient to return values only based on a position, \Dumux models can also access functions in the problem with the form \mbox{\texttt{...AtPos(GlobalPosition\& globalPos)}}, without an \Dune entity, as one can see in line \ref{tutorial-decoupled:bctype}.
+    initial values, or on an intersection, such as a boundary condition. As it may be sufficient to return values only based on a position, \eWoms models can also access functions in the problem with the form \mbox{\texttt{...AtPos(GlobalPosition\& globalPos)}}, without an \Dune entity, as one can see in line \ref{tutorial-decoupled:bctype}.
 
-There are the methods for general parameters, source- or
+There are also methods for terms of the partial differential equations which must be provided such as the source term, boundary conditions (lines \ref{tutorial-decoupled:bctype} to
-sinkterms, boundary conditions (lines \ref{tutorial-decoupled:bctype} to
 \ref{tutorial-decoupled:neumann}) and initial values for the transported
 quantity in line \ref{tutorial-decoupled:initial}. For more information
 on the functions, consult the documentation in the code.
@@ -151,16 +144,17 @@ Listing \ref{tutorial-decoupled:spatialparametersfile} shows the file
 \verb+tutorialspatialparams_decoupled.hh+:
 
 \begin{lst}[File tutorial/tutorialspatialparams\_decoupled.hh]\label{tutorial-decoupled:spatialparametersfile} \mbox{}
-\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=24, firstnumber=24]{../../tutorial/tutorialspatialparams_decoupled.hh}
+\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=27, firstnumber=27]{../../tutorial/tutorialspatialparams_decoupled.hh}
 \end{lst}
-The argument list here is the same as for the problem 
+The argument list for its methods here is the same as for the problem 
 functions: Either an \texttt{element}, or only the global position if the function is called \texttt{...AtPos(...)}.
 
 \subsection{Exercises}
 \label{tutorial-deoucpled:exercises}
-The following exercises will give you the opportunity to learn how you can change 
+The following exercises will give you the opportunity to learn how you
-soil parameters, boundary conditions and fluid properties in \Dumux and to play along 
+can change soil parameters, boundary conditions and fluid properties
-with the decoupled modelling framework.
+in \eWoms and is intended to give you an opportunity to play with the
+semi-implicit modelling framework.
 
 \subsubsection{Exercise 1}
 \renewcommand{\labelenumi}{\alph{enumi})}
@@ -168,33 +162,71 @@ For Exercise 1 you only have to make some small changes in the tutorial files.
 \begin{enumerate}
 \item \textbf{Altering output}
 
-To get an impression what the results should look like you can first run the original version of the decoupled tutorial model by typing  \texttt{./tutorial\_decoupled}. The runtime parameters which are set printed at the start of the simulation. If the input file has the same name than the main file (e.g. \texttt{tutorial\_decoupled.cc} and \texttt{tutorial\_decoupled.input}), it is automatically chosen. If the name differs the program has to be started typing \texttt{./tutorial\_decoupled -parameterFile <filename>.input}. For more options you can also type \texttt{./tutorial\_decoupled -h}. For the visualisation with paraview please refer to \ref{quick-start-guide}.\\
+  To get an impression what the results should look like, you can run
-As you can see, the simulation creates many output files. To reduce these in order to perform longer simulations, change the method responsible for output (line \ref{tutorial-decoupled:outputinterval} in the file \texttt{tutorialproblem\_decoupled}) as to write an output only every 20 timesteps. Compile the main file by typing \texttt{make tutorial\_decoupled} and run the model. Now, run the simulation for 5e5 seconds.
+  the unmodified version of the semi-implicit tutorial problem by
+  typing \texttt{./tutorial\_decoupled}. The runtime parameters which
+  are set printed at the start of the simulation. You may either
+  specify values for them on the command line by passing the program
+  \texttt{--ParameterName=Value} arguments, or by putting parameters
+  into a filie and instructing the program to load it by adding the
+  command line option \texttt{--ParameterFile=filename}. For a
+  description of the available parameters options you add the
+  \texttt{--help} command line argument to the program. For the
+  visualizing the output using paraview please refer to
+  \ref{quick-start-guide}.
 
-\item \textbf{Changing the Model Domain and the Boundary Conditions} \\
+  As you can see, the simulation creates many output files. To reduce
+  these in order to perform longer simulations, change the method
+  responsible for output (line \ref{tutorial-decoupled:outputinterval}
+  in the file \texttt{tutorialproblem\_decoupled}) so that it only
+  writes an output file every 20 time steps. Re-compile the program by
+  typing \texttt{make tutorial\_decoupled} and run it again. Now, run
+  the simulation for $500\;000$ seconds.
+
+\item \textbf{Changing the Model Domain} \\
 Change the size of the model domain so that you get a rectangle
 with edge lengths of x = 300 m \\  and y = 300 m and with discretisation lengths of  $\Delta \text{x} = 20$ m and $\Delta \text{y} = 10$ m. \\
+
+
+\item \textbf{Changing the Boundary Conditions} \\
 Change the boundary conditions in the file \texttt{tutorialproblem\_decoupled.hh} so that water enters from the bottom and oil flows out at the top boundary. The right and the left boundary should be closed for water and oil fluxes. The Neumannn Boundary conditions are multiplied by the normal (pointing outwards), so an influx is negative, an outflux always positive. Such information can easily be found in the documentation of the functions (also look into base classes).
 
 \item \textbf{Changing Fluids} \\
-Now you can change the fluids. Use DNAPL instead of Oil and Brine instead of Water. To do that you have to select different components via the property system in the problem file:
+Now change the fluids: Use DNAPL instead of LNAPL and brine instead of water. To do that you have to select different components:
 \begin{enumerate}
- \item Brine: The class \texttt{Dumux::Brine} acts as an adapter to the fluid system that alters a pure water class by adding some salt. Hence, the class \texttt{Dumux::Brine} uses a pure water class, such as \texttt{Dumux::H2O}, as a second template argument after the data type \texttt{<Scalar>} as a template argument (be sure to use the complete water class with its own template parameter).
+ \item Brine: First, you need to add an \texttt{\#include} directive for \texttt{brine.hh}. The class \texttt{Dumux::Brine} is an adapter class that slightly adapts the thermodynamic properties of pure water by adding some salt. Hence, the class \texttt{Dumux::Brine} uses a pure water class, such as \texttt{Dumux::H2O}, as a second template argument after the data type \texttt{<Scalar>} as a template argument.
- \item DNAPL: A standard set of chemical substances, such as Water and Brine, is already included (via a list of \texttt{\#include ..} commandos) and hence easily accessible by default. This is not the case for the class \texttt{Dumux::SimpleDNAPL}, however, which is located in the folder \texttt{dumux/material/components/}. Try to include the file as well as select the component via the property system.
+ \item DNAPL: First, you need to change \texttt{\#include} directive from \texttt{lnapl.hh} to \texttt{dnapl.hh}. Then change the fluid used for the non-wetting phase from \texttt{LNAPL<Scalar>} to \texttt{DNAPL<Scalar>}
 \end{enumerate}
-If you want to take a closer look at how the fluid classes are defined and which substances are already available please browse through the files in the directory
+If you want to take a closer look at how the fluid classes are defined and which substances are already available you may browse the files in the directory
 \texttt{/dumux/material/components}.
 
-\item \textbf{Use the \Dumux fluid system}\label{dec-ex1-fluidsystem} \\
+\item \textbf{Use an \eWoms fluid system}\label{dec-ex1-fluidsystem} \\
-\Dumux usually organizes fluid mixtures via a \texttt{fluidsystem}, see also chapter \ref{sec:fluidframework}. In order to include a fluidsystem you first have to comment the lines \ref{tutorial-coupled:2p-system-start} to \ref{tutorial-coupled:2p-system-end} in the problem file. If you use eclipse, this can easily be done by pressing \textit{str + shift + 7} -- the same as to cancel the comment later on.\\
+\eWoms usually organizes fluid mixtures via a \textit{fluid system}, see also chapter \ref{sec:fluidframework}. In order to include a fluid system you first have to comment the lines \ref{tutorial-coupled:2p-system-start} to \ref{tutorial-coupled:2p-system-end} in the problem file.\\
-Now include the file \texttt{fluidsystems/h2oairsystem.hh} in the material folder, and set a property \texttt{FluidSystem} with the appropriate type, \texttt{Dumux::H2OAirFluidSystem<TypeTag>}. However, this rather complicated fluidsystem uses tabularized fluid data, which need to be initialized (i.e. the tables need to be filled with values) in the constructor body of the current problem by adding \texttt{GET\_PROP\_TYPE(TypeTag, FluidSystem)::init();}. Remember that the constructor function always has the same name as the respective class, i.e. \texttt{TutorialProblemDecoupled(..)}.\\
+
-To avoid the initialization, use the simpler version of water \texttt{Dumux::SimpleH2O} or a non-tabulated version \texttt{Dumux::H2O}. This can be done by setting the property \texttt{Components} type \texttt{H2O},
+Now include the file \texttt{fluidsystems/h2oairsystem.hh} in the
-as is done in all the test problems of the decoupled 2p2c model.\\
+material folder, and set a property \texttt{FluidSystem} with the
-The density of the gas is magnitudes smaller than that of oil, so please decrease the injection rate to $q_n = -3 \times 10^{-4}$ $\left[\frac{\textnormal{kg}}{\textnormal{m}^2 \textnormal{s}}\right]$. Also reduce the simulation duration to 2e4 seconds.\\
+appropriate type,
-Please reverse the changes of this example, as we still use bulk phases and hence do not need such an extensive fluid system.
+\texttt{Dumux::FluidSystems::H2OAir<Scalar>}. However, this rather
+complicated fluidsystem uses tabularized fluid data, which need to be
+initialized at startup (i.e. the tables need to be filled with values)
+in the constructor body of the current problem by adding
+\texttt{GET\_PROP\_TYPE(TypeTag, FluidSystem)::init();}. Remember that
+the constructor function always has the same name as the respective
+class, i.e. \texttt{TutorialProblemDecoupled(..)}.
+
+The density of the gas is magnitudes smaller than that of oil, so it
+is advisable to decrease the injection rate to $q_n = -3 \cdot 10^{-4}
+\frac{\text{kg}}{\text{m}^2 \text{s}}$. Also reduce the simulation
+duration to $20\;000$ seconds.
+
+Before you proceed, please revert the changes made in this exercise,
+as we still use bulk phases and hence do not need such an extensive
+fluid system.
  
 \item \textbf{Heterogeneities}  \\
-Set up a model domain with the soil properties given in Figure \ref{tutorial-deoucpled:exercise1_d}. Adjust the boundary conditions so that water is again flowing from left to right.
+  Set up a model domain with the soil properties given in Figure
+  \ref{tutorial-deoucpled:exercise1_d}. Adjust the boundary conditions
+  so that water is again flowing from left to right.
 \begin{figure}[ht]
 \psfrag{K1 =}{K $= 10^{-8}\text{ m}^2$}
 \psfrag{phi1 =}{$\phi = 0.15$}
@@ -232,7 +264,7 @@ After this, change the domain size (parameter input file) to match the domain de
 by figure \ref{tutorial-decoupled:ex2_Domain}. Adapt the problem class
 so that the boundary conditions are consistent with figure
 \ref{tutorial-decoupled:ex2_BC}. Initially, the domain is fully saturated
-with water and the pressure is $p_w = 2 \times 10^5 \text{Pa}$ . Oil
+with water and the pressure is $p_w = 2 \cdot 10^5 \text{Pa}$ . Oil
 infiltrates from the left side. Create a grid with $20$ cells in
 $x$-direction and $10$ cells in $y$-direction. The simulation time
 should be set to $2e4 \text{s}$.
@@ -279,24 +311,15 @@ compile the program.
  \item Further increase the CFL-factor to 2 and investigate the saturation.
 \end{itemize}
 
-\subsubsection{Exercise 3: Parameter file input.}
+\subsubsection{Exercise 3}
-As you have experienced, compilation takes quite some time. Therefore, \Dumux 2.1 provides a simple method to read in parameters (such as simulation end time or modelling parameters) via \texttt{Paramter Input Files}. The tests in the Test-folder \texttt{/test/} already use this system.\\
-If you look at the Application in \texttt{/test/boxmodels/2p/}, you see that the main file looks rather empty: The parameter file \texttt{test\_2p.input} is read by a standard start procedure, which is called in the main function. This should be adapted for your problem at hand. The program run has to be called with the parameter file as argument. As this is a basic \Dumux feature, the procedure is the equivalent in the decoupled as in the box models.
-In the code, parameters can be read via the macro \texttt{GET\_RUNTIME\_PARAM(TypeTag, Scalar, MyWonderfulGroup.MyWonderfulParameter);}. In \texttt{test\_2p}, \texttt{MyWonderfulGroup} is the group \texttt{SpatialParams} - any type of groups is applicable, if the group definition in the parameter file is enclosed in square brackets. The parameters are then listed thereafter. Try and use as much parameters as possible via the input file, such as lens dimension, grid resolution, soil properties etc. In addition, certain parameters that are specific to the model, such as the \texttt{CFL}-factor, can be assigned in the parameter file without any further action.
-
-\subsubsection{Exercise 4}
 Create a new file for benzene called \texttt{benzene.hh} and implement
-a new fluid system. (You may get a hint by looking at existing fluid 
+a new component. (You may get a hint by looking at existing components
-systems in the directory \verb+/dumux/material/fluidsystems+.)
+in the directory \verb+/dumux/material/components+.)
 
 Use benzene as a new fluid and run the model of Exercise 2 with water
 and benzene. Benzene has a density of $889.51 \, \text{kg} / \text{m}^3$
 and a viscosity of $0.00112 \, \text{Pa} \; \text{s}$. 
 
-
-\subsubsection{Exercise 5}
-If both the coupled and the decoupled tutorial are completed, one should have noticed that the function arguments in the problem function differ slighty, as the numerical models differ. However, both are functions that depend on space, so both models can also work with functions based ond \mbox{\texttt{...AtPos(GlobalPosition \& globalPos)}}, no matter if we model coupled or decoupled. Try to formulate a spatial parameters file that works with both problems, the coupled and the decoupled. Therein, only use functions at the position.
-
 %%% Local Variables: 
 %%% mode: latex
 %%% TeX-master: "ewoms-handbook"

examples/tutorialproblem_coupled.hh

@@ -28,7 +28,7 @@
 // The numerical model
 #include <dumux/boxmodels/immiscible/immisciblemodel.hh>
 
-// The components that are used
+// The chemical species that are used
 #include <dumux/material/components/h2o.hh>
 #include <dumux/material/components/lnapl.hh>
 
@@ -64,11 +64,13 @@ SET_TYPE_PROP(TutorialProblemCoupled, GridCreator, Dumux::CubeGridCreator<TypeTa
 
 // Set the wetting phase /*@\label{tutorial-coupled:2p-system-start}@*/
 SET_TYPE_PROP(TutorialProblemCoupled, WettingPhase,   /*@\label{tutorial-coupled:wettingPhase}@*/
-              Dumux::LiquidPhase<typename GET_PROP_TYPE(TypeTag, Scalar), Dumux::H2O<Scalar> >); 
+              Dumux::LiquidPhase<typename GET_PROP_TYPE(TypeTag, Scalar),
+              Dumux::H2O<typename GET_PROP_TYPE(TypeTag, Scalar)> >); 
 
 // Set the non-wetting phase
 SET_TYPE_PROP(TutorialProblemCoupled, NonwettingPhase,  /*@\label{tutorial-coupled:nonwettingPhase}@*/
-              Dumux::LiquidPhase<typename GET_PROP_TYPE(TypeTag, Scalar), Dumux::LNAPL<Scalar> >);  /*@\label{tutorial-coupled:2p-system-end}@*/
+              Dumux::LiquidPhase<typename GET_PROP_TYPE(TypeTag, Scalar), 
+              Dumux::LNAPL<typename GET_PROP_TYPE(TypeTag, Scalar)> >);  /*@\label{tutorial-coupled:2p-system-end}@*/
 
 // Set the material law
 SET_PROP(TutorialProblemCoupled, MaterialLaw)

examples/tutorialproblem_decoupled.hh

@@ -96,7 +96,7 @@ SET_SCALAR_PROP(TutorialProblemDecoupled, ImpetCflFactor, 0.95); /*@\label{tutor
 // Disable gravity
 SET_BOOL_PROP(TutorialProblemDecoupled, EnableGravity, false); /*@\label{tutorial-decoupled:gravity}@*/
 
-// define how long the simulation should run [s]
+// define how long the simulation should run [s] /*@\label{tutorial-decoupled:domain-defaults-begin}@*/
 SET_SCALAR_PROP(TutorialProblemDecoupled, EndTime, 100e3);
 
 // define the properties required by the cube grid creator
@@ -106,7 +106,7 @@ SET_SCALAR_PROP(TutorialProblemDecoupled, DomainSizeZ, 0.0);
 
 SET_INT_PROP(TutorialProblemDecoupled, CellsX, 100);
 SET_INT_PROP(TutorialProblemDecoupled, CellsY, 1);
-SET_INT_PROP(TutorialProblemDecoupled, CellsZ, 0);
+SET_INT_PROP(TutorialProblemDecoupled, CellsZ, 0); /*@\label{tutorial-decoupled:domain-defaults-end}@*/
 } /*@\label{tutorial-decoupled:propertysystem-end}@*/
 
 /*! \ingroup DecoupledProblems