OilfieldToolsNet/opm-simulators
4
0
Fork 0
mirror of https://github.com/OPM/opm-simulators.git synced 2024-11-24 18:20:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

handbook: finish update for the 2.2 release

Browse Source 
at least content-wise. there are still quite a few language issues
left to be dealt with...
This commit is contained in:
Andreas Lauser 2012-10-17 15:48:43 +02:00
parent eaf7d9cea5
commit 9aad4c3a7e
11 changed files with 658 additions and 542 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
doc/handbook/ewoms-handbook.bib
View File

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

6
doc/handbook/ewoms-handbook.tex
View File

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

102
doc/handbook/guidelines.tex
View File

@ -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
\cite{DUNE-HP}. These guidelines are also recommended for coding with
\Dumux as developer and user.
In order to keep the code maintainable we have decided upon a set of
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.
is very similar to the \Dune coding guidelines found at the \Dune
website~\cite{DUNE-HP}. These guidelines are also strongly recommended
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
everybody to work on code that has not 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 all comments / documentation is in English
\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.
\item Variables should be named as self-explaining as possible: especially abbreviations should be avoided (saturation in stead of S)
\item Comments: They are helpful! Use comments extensively to explain
what your code does, but please refrain from adding trivial
comments. Trivial comments are, for example comments that only
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 Typenames: For typenames, 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 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 Files: Filenames should consist of lower case letters exclusively. Header files get the suffix .hh, implementation files the suffix .cc
\item Private attributes: Names of private attributes should end with
an underscore and are supposed to be the only variables that contain
underscores.
\item Typenames: For typenames (classes, structures, typedefs, etc),
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.
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}
\item Documentation: \eWoms, as any software project of similar
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 Template Parameters
\item Return Values
\item Method parameters
\item Template parameters
\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
'next week', we herewith proclaim the Doc-Me Dogma . It goes like this: Whatever you do, and in whatever hurry you
happen to be, please document everything at least with a {\verb /** $\backslash$todo Please doc me! */}. That way at least the absence
of documentation is documented, and it is easier to get rid of it systematically.
\item Exceptions:
The use of exceptions for error handling is encouraged. Until further notice, all exceptions thrown are DuneEx.
\item Debugging Code:
Global debugging code is switched off by setting the symbol NDEBUG. In particular, all asserts are
automatically removed. Use those asserts freely!
Since we all know that writing documentation is not well-liked and is
frequently defered to some vague 'next week', we herewith proclaim
the Doc-Me Dogma . It goes like this: Whatever you do, and in
whatever hurry you happen to be, please document everything at least
with a {\verb /** $\backslash$todo Please doc me! */}. That way at
least the absence of documentation is documented, and it is easier to
get rid of it systematically.
\item Exceptions: The use of exceptions for error handling is
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:

547
doc/handbook/install.tex
View File

@ -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
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.
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 can give you assistance with that. In section \ref{sec:prerequisites} we list some prerequisites for running \Dune and \Dumux.
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.
In this section about the installation of \eWoms it is assumed that
you work on a Unix or Linux compatible operating system and that you
are familiar with the use of a command line shell. Installation means
that you unpack \Dune together with \eWoms in a certain directory.
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.
Thus, the installation procedure of \Dumux is the same as that of \Dune.
Details regarding the installation of \Dune are provided on the \Dune website \cite{DUNE-INST}.
If you are interested in more details about the build system that is used,
they can be found in the {\Dune} Buildsystem Howto \cite{DUNE-BS}.
In a technical sense \eWoms is a module of \Dune. Thus, the
installation procedure of \eWoms is the same as that of \Dune (besides
using different locations to retieve the source code). Details
regarding the installation of \Dune are provided on the \Dune
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.
We refer to that directory abstractly as {\Dune} root directory or, in short, as {\Dune}-Root.
If it is used as directory's path of a shell command it is typed as \texttt{\Dune-Root}.
For the real {\Dune} root directory on your file system any valid directory name can be chosen.
Source code files for each \Dune module are contained in their own
subdirectory within {\Dune}-base. We name this directory of a certain
module \emph{module base directory} or \texttt{module-base}
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.
We name this directory of a certain module \emph{module root directory} or \texttt{module-root-directory} if it is a directory path,
e.\,g. for the module \texttt{dumux} these names are \emph{dumux root directory} respective \texttt{dumux-root-directory}.
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 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.
After installing source code for all relevant \Dune modules including
\eWoms, \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,
\texttt{autoconf} of version $\geqslant$ 2.65, \texttt{autogen} of version $\geqslant$ 5.9.7, \texttt{libtool} of version $\geqslant$ 2.2.6
and GNU \texttt{make} version $\geqslant$ 3.81 should do their job for building \Dumux.
The GNU compiler collection with \Cplusplus support (\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 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
like \texttt{dvipdf} and \texttt{bibtex}. One usually chooses a \LaTeX\ distribution like \texttt{texlive} for this purpose.
It is possible to switch off the building of the documentation by setting the switch \texttt{--disable-documentation}
in the \texttt{CONFIGURE\_FLAGS} of the building options (see Chapter \ref{buildIt}).
Additional parts of documentation are contained within the source code files as special formatted comments.
Extracting them can be done using \texttt{doxygen} (version $\geqslant$ 1.7.2 works).
See for this optional step Section \ref{sec:build-doxy-doc}.
At the time of writing this manual, the minumum version required for
\texttt{g++} is 4.4.0, \texttt{automake} the documentation by setting the switch
\texttt{--disable-documentation} in the \texttt{CONFIGURE\_FLAGS} of
the building options (see Chapter \ref{buildIt}). Additional parts of
documentation are contained within the source code files as specially
formatted comments. Extracting them can be done using the tool
\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,
additional software packages may be required. Some hints on that are given in Section \ref{sec:external-modules-libraries}.
Depending on whether you are going to use external libraries and
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.
The subversion (svn) software repositories can be accessed with help of a subversion client. We recommend the Apache Subversion command-line client \texttt{svn}
contained in Apache Subversion of version $\geqslant$ 1.6.0 \cite{APACHE-SUBVERSION-HP}.
For the extraction of the content of tar files, the GNU version of
\texttt{tar} is used. To access the git or subversion software
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}
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.
\section{Obtaining source code for \Dune and \eWoms}
Two possibilities exist to get the source code of \Dune and \Dumux.
Firstly, \Dune and \Dumux can be downloaded as tar files from the respective \Dune and \Dumux website. They have to be extracted as described in the next paragraph.
Secondly, a method to obtain the most recent source code (or, more generally, any of its previous revisions) by direct access
via Internet to the software repositories of the revision control system is described in the subsequent part.
As stated above, the \eWoms is based on the \Dune release 2.2,
comprising the core modules \texttt{dune-common},
\texttt{dune-geometry}, \texttt{dune-grid}, \texttt{dune-istl} and
\texttt{dune-localfunctions}. For working with \eWoms, these modules
are required.
However, if a user does not want to use the most recent version,
certain version tags (i.\,e. special names), version numbers and even software branches are means
of the software revision control system to provide access to different versions of the software.
Two possibilities exist to get the source code of \Dune and \eWoms.
Firstly, released versions \Dune and \eWoms can be downloaded as tar
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:
Download the tarballs from the respective \Dune (version 2.2.0) and \Dumux websites to a certain folder in your file system.
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}.
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{dumux root directory} is \texttt{dumux-2.2}.
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: Download the tarballs from the
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
$ cd DUMUX
$ mkdir ~/src
$ 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.
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.
\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.
In our description, we use the subversion client of the Apache Subversion software itself, which is a command-line tool named \texttt{svn}.
It is available for most Linux and Unix distributions as software package.
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}:
The \eWoms module is checked out as described below (see also the
\eWoms website \cite{EWOMS-HP}). Its source tree has to be created in
the \Dune-base directory, where the \Dune modules have also been
cloned into. Subsequently, the next command is executed there,
too. The directory which holds the \eWoms module is called
\texttt{ewoms} here.
\begin{lstlisting}[style=Bash]
$ mkdir DUMUX
$ cd DUMUX
$ 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
cd ~/src
git clone git://github.com/OPM/ewoms.git ewoms
\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.
It may give you an idea of how some abstractions in \Dune are done.
The installation of \texttt{dune-grid-howto} is optional and is not required by \Dumux. It is done by:
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 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}).
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}
\section{Building the \eWoms handbook}
If the \texttt{--enable-documentation} switch has been set in the configure flags of
\texttt{dunecontrol}, this does not necessarily mean that for every
\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:
\texttt{dunecontrol}, watch for a summary line of the build script that reads
\begin{lstlisting}[style=Bash]
$ # change before next command your directory to DUNE-Root
$ cd dune-istl/doc
$ make istl.pdf
Build eWoms handbook....: yes
\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]
$ # change before next command your directory to DUNE-Root
$ cd dune-grid-howto/doc
$ make grid-howto.pdf
\end{lstlisting}
If the summary line says that the handbook is not going to be build,
then you usually have to install additional \LaTeX packages.
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]
$ cd dumux/doc/handbook
$ make ewoms-handbook.pdf
\end{lstlisting}
The libraries described below provide additional functionality but are
not generally required to use \eWoms. If you are going to use an
external library, also check the information provided on the \Dune
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.
%Alternatively, the tool CMake can be used to build \Dumux. Please check the file \texttt{INSTALL.cmake} for details.
\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.
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}. \\
Download: \texttt{\url{http://aam.mathematik.uni-freiburg.de/IAM/Research/alugrid}}
\item \textbf{ALUGrid}: External library for use as grid. 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,
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}}.
%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.
Download:
\texttt{\url{http://aam.mathematik.uni-freiburg.de/IAM/Research/alugrid}}
\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.\\
Available by \texttt{\url{http://www.tacc.utexas.edu/tacc-projects/gotoblas2/}}.
\item \textbf{GotoBLAS2}: This is an optimized BLAS library. It does
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.
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}.
\item \textbf{METIS}: This is a dependency of ALUGrid, if you are
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.
% http://openmp.org/
%\item \textbf{libgmp}: The Gnu Multiple Precision Arithmetic Library (GMP) is also a prerequisite for \Dune. It may be necessary to install it.
% http://gmplib.org/
\item \textbf{Compilers}: Besides \texttt{g++} \Dune and \eWoms can
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
\Cplusplus compiler, C and Fortran compilers are needed to compile
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"

12
doc/handbook/intro.tex
View File

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

89
doc/handbook/new-folder.tex
View File

@ -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 adapt \verb+Makefile.am+
\item insert new folder in \verb+Makefile.am+ of the directory above
\item adapt \verb+configure.ac+ in the \verb+$DUMUX_ROOT+ (the directory you checked out, probably dumux)
\item newly compile \Dumux
\item Create new directory with content. Quite often an existing
directory can be used as a base for the new one.
\item Adapt \texttt{Makefile.am} in the new directory and add this
direcory to the \texttt{SUBDIRS} list of the \texttt{Makefile.am} in
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
test_2p_CXXFLAGS = $(MPI_CPPFLAGS)
test_2p_LDADD = $(MPI_LDFLAGS)
noinst_HEADERS= *.hh
EXTRA_DIST = CMakeLists.txt
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 \
1p2c \
2p \
2p2c \
2p2cni \
2pni \
New_Project \
...
SUBDIRS = doc dumux m4 test tutorial 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+
\textbf{Fifth}: Compile \Dumux as described in Section \ref{install}.
\noindent a line, declaring a new Makefile, needs to be added. The
Makefile itself will be generated automatically from the
\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:

70
doc/handbook/newton-in-a-nutshell.tex
View File

@ -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
media, the following mass conservation equation needs to be solved:
For the isothermal immiscible multi-phase model, the following mass
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) \\
\Leftrightarrow {\textbf{f}^{\prime}(\textbf{u}^r)} ( \textbf{u}^{r+1}-\textbf{u}^r) &= -\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}
\textbf{u}^{r+1} &= \textbf{u}^r + \Delta \textbf{u}^r \\
\Delta \textbf{u}^r & = - \left\{\text{grad}\,\textbf{f} (\textbf{u}^r) \right\}^{-1} \textbf{f}(\textbf{u}^r) \\
\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 $\textbf{u}$: vector of unknowns, the actual primary variables
\item $\textbf{f}(\textbf{u}^r)$: function of vector of unknowns
\item $\text{grad}\,\phantom{a}$: \textsc{Jacobian} matrix of
$\textbf{f}$, i.e. matrix of the derivatives of \textbf{f} regarding
all components of $\textbf{u}$
\end{itemize}
1-D example with slope $m$:
\begin{equation}
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}}
\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:
The value of $\textbf{u}$ for which $\textbf{f}$ becomes zero is
searched for. Bringing \eqref{NewtonGen} into the form used the linear
solvers
\begin{equation}
\label{GenSysEq}
A\textbf{x} = \textbf{b} .
\textbf{A}\textbf{x} - \textbf{b} = 0
\end{equation}
Comparing (\ref{GenSysEq}) with (\ref{NewtonAsUsed}) leads to:
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 $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+1} - \textbf{u}^{r})$ this is what the linear solver finds as an solution.
\item $\textbf{A} = \text{grad}\,\textbf{f} (\textbf{u}^r)$
\item $\textbf{x} = \textbf{u}^{r} - \textbf{u}^{r+1}$
\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!).
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.
Once $\textbf{u}^{r} - \textbf{u}^{r+1}$ has been calculated, \eWoms
updates the current solution in \texttt{NewtonController::update()}
and starts the next iteration if the scheme has not yet converged.
%%% Local Variables:
%%% mode: latex

156
doc/handbook/structure.tex
View File

@ -1,25 +1,23 @@
\chapter{Structure, Guidelines, New Folder Setup}
\chapter{Directory structure}
\section{Directory Structure}
We briefly describe the directory structure of \Dumux in terms
We briefly describe the directory structure of \eWoms 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
the root directory of \texttt{dumux} for details. Of course,
for building \eWoms using CMake. See the file \texttt{INSTALL.cmake} in
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}:
the general fully implicit box method is contained in the subdirectory
\texttt{common}, while each of the other subdirectories contains
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.
% The files \texttt{pdelabboxassembler.hh} and \texttt{pdelabboxlocaloperator.hh} allow the use of the DUNE module \texttt{dune-pdelab}.
\item \texttt{boxmodels}: The fully implicit vertex-centered finite
volume (box) method. This directory features the following
sub-directories
\begin{itemize}
\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}:
general stuff like the property system and the time management for the
fully coupled as well as the decoupled models,
% the interface for the Pardiso direct solver library \cite{Pardiso},
and the \texttt{start.hh} file that includes the common routine for starting a model called in the main function.
\item \texttt{common}: General stuff like the \eWoms property system
and classes for managing time which are shared by the fully-implicit
and the semi-implicit models. For example it features the file
\texttt{start.hh} which provides the default way for starting a
simulation.
\item \texttt{decoupled}:
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}.
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 semi-implicit formulation for the implicit pressure, explicit transport formulation can be found in the subdirectory \texttt{common}.
% \item \texttt{fractionalflow}:
% the (non-compositional) fractional flow model, which utilizes the IMPES method
% contained in the subdirectory \texttt{impes}.
\item \texttt{io}: Additional classes that provide in-/output routines
like writing and reading restart files (often called 'checkpoint'
files) and for writing a series of VTK files.
% \item \texttt{functions}:
% the Crouzeix--Raviart function implemented in the style of \texttt{dune-disc}'s P1 function.
\item \texttt{material}: Everything related to material parameters and
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}:
% employed by the box method to extract the dual mesh geometry information out of the
% primal one.
\item \texttt{nonlinear}: This folder contains an implementation of
the Newton-Raphson method for solving non-linear systems of
equations.
\item \texttt{io}: additional in-/output possibilities like restart files
and a VTKWriter extension.
\item \texttt{material}: everything related to material parameters and
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.
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{linear}: This folder features code which is required to
parallelize the linear solvers, as well as back-ends for these
solvers. For example it contains classes to calculate an overlap
given the distributed matrix of the linear system, and provides
classes which use this overlap to provide overlapping matrices,
vectors, linear operators and scalar products.
\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 a test for each numerical model and for
the property system. The tests for the property system can be found in \texttt{common}.
The subfolder \texttt{boxmodels} contains tests for the fully
coupled models (\texttt{1p}, \texttt{1p2c}, \texttt{2p}, \texttt{2p2c},
\texttt{2p2cni}, \texttt{2pni}, \texttt{3p3c}, \texttt{3p3cni}, \texttt{mpnc} and \texttt{richards}), while the subdirectory \texttt{decoupled} corresponds to the decoupled models.
Each subdirectory contains one or more program files \texttt{test\_*.cc}, where \texttt{*} usually is the
name of the folder. Moreover, the problem definitions can be found
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
full test or give a list of required command line arguments. After test execution,
VTK output files should have been generated.
For more detailed descriptions of the tests, the problem definitions and their corresponding
Doxygen documentation should be considered.
The directory \texttt{test} contains at least one test/example for
each numerical model and for each important aspect of the common
\eWoms infrastructure. The directory \texttt{common} contains a test
for the property system. The sub-directory \texttt{boxmodels}
contains test applications for the fully-implicit models (where each
test is named according to the scheme \texttt{PROBLEMNAME\_MODDEL}),
while the subdirectory \texttt{decoupled} features tests for the
semi-implicit models. Each subdirectory contains one or more program
files \texttt{*.cc} which contain the main function for the
test. Moreover, the problem definitions can be found in the
\texttt{*problem.hh} files. Simply executing the tests should either
run the full test or give a list of required command line
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}

187
doc/handbook/tutorial-decoupled.tex
View File

@ -1,13 +1,6 @@
\section[Decoupled model]{Solving a problem using a Decoupled 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}
\section[Semi-implicit model]{Solving a problem using a Semi-implicit Model}\label{tutorial-decoupled}
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
\ref{tutorial-decoupled:problemfigure}. A rectangular domain with no flow
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
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},
\texttt{Grid.upperRightY}, \texttt{Grid.numberOfCellsX} and
\texttt{Grid.numberOfCellsY}. These parameters can be specified via
run-time parameters \texttt{DomanSizeX},
\texttt{DomanSizeY}, \texttt{CellsX} and
\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}).
Instead, we use a simplified fluidsystem container that provides classes
for liquid and gas phases, line \ref{tutorial-decoupled:2p-system-start} to
\ref{tutorial-decoupled:2p-system-end}. These are linked to the appropriate
chemical species in line \ref{tutorial-decoupled:wettingPhase} and
do not need to be used. However, they can be used (see exercise 1e).
Instead, we use a simplified fluidsystem that wraps pure component classes
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 components represent fluids made of pure
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
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.
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.
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}
is optional and tells the model not to use 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 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
its namespace is closed in line \ref{tutorial-decoupled:propertysystem-end},
After all necessary properties are defined and
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
\ref{tutorial-decoupled:constructor-problem}) is able to hold two vectors,
which is not needed in this tutorial.
\texttt{IMPESProblem2P}.
Beside the definition of the boundary and initial conditions (discussed in
subsection \label{decoupled-problem:boundary}), the problem class also contains
general information about the current simulation. First, the name used by
the \texttt{VTK-writer} to generate output is defined in the method of line
Beside the definition of the boundary and initial conditions, the problem class also provides
general information about the current simulation. First, the name used by for the
resulting VTK output files is defined by the \texttt{name()} 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
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.
when and whether restart files are written. As semi-implicit schemes usually feature small
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
sinkterms, boundary conditions (lines \ref{tutorial-decoupled:bctype} to
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
\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
soil parameters, boundary conditions and fluid properties in \Dumux and to play along
with the decoupled modelling framework.
The following exercises will give you the opportunity to learn how you
can change soil parameters, boundary conditions and fluid properties
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}.\\
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.
To get an impression what the results should look like, you can run
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 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 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: 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} \\
\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.\\
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},
as is done in all the test problems of the decoupled 2p2c model.\\
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.\\
Please reverse the changes of this example, as we still use bulk phases and hence do not need such an extensive fluid system.
\item \textbf{Use an \eWoms fluid system}\label{dec-ex1-fluidsystem} \\
\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::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.}
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}
\subsubsection{Exercise 3}
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
systems in the directory \verb+/dumux/material/fluidsystems+.)
a new component. (You may get a hint by looking at existing components
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"

8
examples/tutorialproblem_coupled.hh
View File

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

4
examples/tutorialproblem_decoupled.hh
View File

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