Commit e2089181 authored by Bernd Flemisch's avatar Bernd Flemisch
Browse files

inlcuded handbook in stable

git-svn-id: svn:// 2fb0f335-1f38-0410-981e-8018bf24f1b0
parent 887acdfb
......@@ -6,6 +6,14 @@ AM_INIT_AUTOMAKE
AC_CHECK_PROGS([TEX4HT], [tex4ht], [true])
AC_CHECK_PROGS([MK4HT], [mk4ht], [true])
AC_CHECK_PROGS([T4HT], [t4ht], [true])
AM_CONDITIONAL([TEX4HT], [test "x$TEX4HT" != xtrue])
AC_CHECK_PROGS([CONVERT], [convert], [false])
AM_CONDITIONAL([CONVERT], [test "x$CONVERT" != xfalse])
AM_CONDITIONAL([BUILD_HANDBOOK], [test -a "stamp-vc"])
AC_MSG_WARN([valgrind/memcheck.h not found]))
SUBDIRS = doxygen
SUBDIRS = doxygen handbook
CURDIR = doc
This diff is collapsed.
# $id: $
#EPS_FILES = EPS/tutorial-problemconfiguration.eps
......@@ -12,17 +12,17 @@ if WML
WMLDOCS = index.html
#if TEX4HT
HTDOCS = navigation.html css.html dumux-handbook.html
EXTRA_DIST = dumux-handbook.pdf
......@@ -37,20 +37,20 @@ CLEANFILES = *.aux *.bbl *.blg *.log *.out *.toc *.dvi *.ps
CLEANFILES += *.4ct *.4tc *.css *.idv *.idx *.lg *.tid *.tmp *.tms *.xref
CLEANFILES += dumux-handbook*.html dumux-handbook*.png
%.eps: $(srcdir)/%.jpg
convert $< $@
dumux-handbook.tex: $(EPS_FILES)
#dumux-handbook.html: $(DOCSOURCE) dune.cfg tex4ht.env
# $(MAKE) dumux-handbook.dvi
# $(MK4HT) htlatex dumux-handbook.tex "dune"; \
# $(MK4HT) htlatex dumux-handbook.tex "dune"; \
# $(T4HT) dumux-handbook.tex
# $(TEX) dumux-handbook.tex
dumux-handbook.html: $(DOCSOURCE) dune.cfg tex4ht.env
$(MAKE) dumux-handbook.dvi
$(MK4HT) htlatex dumux-handbook.tex "dune"; \
$(MK4HT) htlatex dumux-handbook.tex "dune"; \
$(T4HT) dumux-handbook.tex
$(TEX) dumux-handbook.tex
# mkdir ModelDescriptions
......@@ -78,4 +78,4 @@ EXTRA_TEXINPUTS=$(top_srcdir)
include $(top_srcdir)/am/global-rules
include $(top_srcdir)/am/latex
\chapter{Newton in an Nutshell}
When using a fully coupled numerical model, one timestep essentially consists of the applicaiotn of the \textsc{Newton} algorith to0 sole the nonlinear system.
One step of the \textsc{Newton} method can be formalized as follows:
\textsc{Newton} method:
\textbf{u}^{r+1} &= \textbf{u}^r - \left(\textbf{f}^\prime (\textbf{u}^r) \right)^{-1} \textbf{f}(\textbf{u}^r) \\
\Leftrightarrow ( \textbf{u}^{r+1}-\textbf{u}^r) {\textbf{f}^{\prime}(\textbf{u}^r)} &= -\textbf{f}(\textbf{u}^r) \\
\Leftrightarrow ( \textbf{u}^r - \textbf{u}^{r+1}) \underbrace{\textbf{f}^{\prime}(\textbf{u}^r)}_{\textnormal{Jacobian}} &= \textbf{f}(\textbf{u}^r) \label{NewtonAsUsed}
\noindent with
\item $\phantom{a}^r$: last iteration, $\phantom{a}^{r+1}$: current iteration,
\item $\phantom{a}^\prime$: derivative
\item $\textbf{u}$: vector of unknowns
\item $\textbf{f}(\textbf{u}^r)$: function of vector of unknowns
1-D example with slope $m$:
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}}
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:
A\textbf{x} = \textbf{b} .
Comparing (\ref{GenSysEq}) with (\ref{NewtonAsUsed}) leads to:
\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.
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 iteration.
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.
\HCode{<link rel="stylesheet" type="text/css" href="$(ROOT)/dune.css" />}
This diff is collapsed.
\lstset{language=C++, basicstyle=\ttfamily,
keywordstyle=\color{black}\bfseries, tabsize=4, stringstyle=\ttfamily,
commentstyle=\it, extendedchars=true, escapeinside={/*@}{@*/}}
\DeclareGraphicsExtensions{.eps, .jpg}
\newcommand{\Dune}{{\sf\bfseries DUNE}}
\newcommand{\Dumux}{DuMu$^\text{x}$ }
% a new counter
% you can give a label to it and thus reference it
% syntax: \numberThis{printedTextToBeLabeled}{label}
% if you wanted a \newline after a numbered thing, you could just add a empty line after ``\label{#2}''
\thethingCounter.\ #1 \label{#2}
%The theorems
{\Huge Handbook}
{\normalsize Lehrstuhl f\"ur Hydromechanik und Hydrosystemmodellierung, \\
Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\
{\normalsize \texttt{\url{}}}\\
\chapter{Getting started}
We first describe the steps which are necessary for installing DuMu$^\text{x}$
and then provide a quick start guide for the first DuMu$^\text{x}$ experience.
We conclude this chapter with a copy of the DUNE coding guidelines.
This section quotes the DUNE coding guidelines found at \cite{DUNE-HP}.
These guidelines also should be followed by every \Dumux 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.
\item Naming:
\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 Private Data Variables: Names of private data variables end with an underscore.
\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 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 all
\item Method Parameters
\item Template Parameters
\item Return Values
\item Exceptions thrown by a method
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!"
For the installation of DuMu$^\text{x}$, the following steps have to be performed.
\paragraph{Checkout of the core modules}
Since we always want to be up to date with the latest changes in DUNE,
we decided to use the developers version of the core modules
\texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, and \texttt{dune-disc}.
First, create a directory where all the DUNE modules will be stored in. Then, enter the previously created folder.
The checkout has to be performed as described on
the DUNE webpage, \cite{DUNE-HP}:
\item \texttt{svn checkout dune-common}
\item \texttt{svn checkout dune-grid}
\item \texttt{svn checkout dune-istl}
\item \texttt{svn checkout dune-disc}
The \Dumux webpage \cite{dumux-hp} contains the revision numbers of the core modules
for which compatibility to \Dumux can be guaranteed.
Additionally, it is highly recommended that you also checkout the \texttt{dune-grid} HOWTO
\texttt{svn checkout dune-grid-howto}
and work yourself through that tutorial in order to get an understanding of
the Dune grid interface.
\paragraph{Checkout of DuMu$^\text{x}$ and external modules}
If you obtained a \Dumux tarball, you should just extract the tarball as usual
and can skip this part.
First of all, you need to ask one of the IWS system administrators to
add your account to the group \texttt{svndune}.
If you are working on a LH2 computer, you then can checkout DuMu$^\text{x}$
and the external modules via
\item \texttt{svn checkout svn+ssh://luftig/home/svn/DUMUX/dune-mux/trunk dumux}
\item \texttt{svn checkout svn+ssh://luftig/home/svn/DUMUX/dune-subgrid/trunk dune-subgrid}
\item \texttt{svn checkout svn+ssh://luftig/home/svn/DUMUX/external/trunk external}
If you want to checkout from outside LH2, you first need to establish a tunnel.
To this end, you need to add once
\texttt{ssht = ssh -p 2022 -l login -o}
with \texttt{login} replaced
by your actual IWS login name, to the section \texttt{[tunnels]} of the
file \texttt{\$HOME/} \texttt{.subversion/config},
The tunnel then needs to be initialized every time you want
to connect to the repository by
\texttt{ssh -Nf -L}.
Then, you can checkout everything as described above, if you replace \texttt{luftig}
by \texttt{localhost}.
%Moreover, the possibility to checkout a read-only version from outside exists. Therefor, no IWS-account is needed. The following commands can be used for an anonymous checkout:
%\item \texttt{svn checkout svn:// dumux}
%\item \texttt{svn checkout svn:// external}
%\item \texttt{svn checkout svn:// dune-subgrid}
\paragraph{Build the external modules}
If you obtained a \Dumux tarball, you should skip this part.
The external modules have to be built first. They consist of Alberta, ALUGrid, UG, and METIS.
To install them all, execute the install script in the folder \texttt{external}:
\texttt{./ all}
If you like to only install some of the external software, you can choose one of the
corresponding options instead of \texttt{all}: \texttt{alberta, alu, metis, ug}.
Please also refer to the DUNE webpage for additional details, \cite{DUNE-HP}.
\paragraph{Build DUNE and DuMu$^\text{x}$}
Type in the folder \texttt{DUMUX}:
\texttt{./dune-common/bin/dunecontrol --opts=\$DUMUX\_ROOT/debug.opts all}
This uses the DUNE buildsystem. If it does not work, please consider
the file \texttt{INSTALL} in the \Dumux root directory (if you use
SVN, this \texttt{\$DUMUX\_ROOT} is usually \texttt{dumux}, if you use
a released version it is usually \texttt{dumux-VERSION}). You can also
find more information in the DUNE Buildsystem HOWTO located at the
DUNE webpage, \cite{DUNE-HP}. Alternatively, the tool CMake can be
used to build \Dumux. Please check the file \texttt{INSTALL.cmake} for
Since creating, refining and managing grids in general is a very
complex topic which has severe effects on computational efficiency and
for which no generic and efficient approach exists, our simulation
framework is build on top of DUNE, the \textbf{D}istributed and \textbf{U}nified
\textbf{N}umerics \textbf{E}nvironment~\cite{DUNE-HP}. DUNE provides a generic interface to many
grid management libraries such as UG~\cite{UG-HP}, ALBERTA~\cite{ALBERTA-HP},
ALU-Grid~\cite{ALUGRID-HP} and a few more. DUNE extensively uses templates in
order to achieve maximum efficiency to access the actual grid
libraries\footnote{In fact, the performance penalty resulting from the
use of DUNE's grid interface is usually negligible~\cite{BURRI2006}.}.
\includegraphics[width=.5\linewidth, keepaspectratio]{EPS/dunedesign}
A high-level overview on DUNE's design as available on the project's
web site~\cite{DUNE-HP}.
DUNE's grid interface is independent of the spatial dimension of the
underlying grid. For this purpose, it uses the concept of
co-dimensional entities. Roughly speaking, an entity of co-dimension
$0$ constitutes a cell, co-dimension $1$ entities are faces between
cells, co-dimension $1$ are edges, and so on until co-dimension $n$
which are the cell's vertices. The DUNE grid interface generally
assumes that all entities are convex polytopes, which means that it
must be possible to express each entity as the convex hull of a set of
vertices. For efficiency, all entities are further expressed in terms
of so-called reference elements which are transformed to the actual
spatial incarnation within the grid by a so-called geometry
function\footnote{The same approach is also used by \texttt{dune-disc} for
finite element shape functions.}. Here, a reference element for an
entity can be thought of as a prototype for the actual grid
entity. For example, if we used at a grid that used hexahedrons as cells,
the reference element for each cell would be the unit cube $[0, 1]^3$
and the geometry function would scale and translate the cube so that
it matches the grid's cell. For a more thorough description of DUNE's
grid definition, see~\cite{BASTIAN2008}.
In addition to the grid interface, DUNE also provides quite a few additional
modules, of which the \texttt{dune-disc} and \texttt{dune-istl} modules are the most
relevant in the context of this handbook. \texttt{dune-disc} provides a toolbox for
discretization and includes a set of generic finite element shape
functions, matrix assemblers for translating local stiffness matrices
into global linear systems of equations and much more. \texttt{dune-istl} is the
\textbf{I}terative \textbf{S}olver \textbf{T}emplate \textbf{L}ibrary
and provides generic, highly optimized linear algebra routines for solving
the generated systems.
\Dumux comes in form of an additional module \texttt{dumux}.
It inherits functionality from the DUNE core modules
\texttt{dune-common}, \texttt{dune-grid}, and \texttt{dune-istl}, as well as from
the discretization module \texttt{dune-disc}. Some numerical models
also depend on the \texttt{dune-subgrid} module, \cite{subgrid}.
The main intention of \Dumux is to provide a framework for easy and efficient
implementation of models from porous media flow problems,
ranging from problem formulation, the selection of
spatial and temporal discretization schemes, as well as nonlinear solvers,
up to general concepts for model coupling.
Moreover, \Dumux includes ready to use numerical models and example applications.
\chapter[Models]{Physical and numerical models}
\section{Physical and mathematical description}
Characteristic of compositional multiphase models is that the phases
are not only matter of a single chemical substance. Instead, their
composition in general includes several species, and for the mass transfer,
the component behavior is quite different from the phase behavior. In the following, we
give some basic definitions and assumptions that are required for the
formulation of the model concept below. As an example, we take a
three-phase three-component system water-NAPL-gas
\cite{A3:class:2002a}. The modification for other multicomponent
systems is straightforward and can be found, e.\ g., in
\subsection{Basic Definitions and Assumptions for the Compositional
Model Concept}
The term {\it component} stands for constituents of the phases which
can be associated with a unique chemical species, or, more generally, with
a group of species exploiting similar physical behavior. In this work, we
assume a water-gas-NAPL system composed of the phases water (subscript
$\text{w}$), gas ($\text{g}$), and NAPL ($\text{n}$). These phases are
composed of the components water (superscript $\text{w}$), air
($\text{a}$), and the organic contaminant ($\text{c}$) (see Fig.\
\caption{Mass and energy transfer between the phases}
For the nonisothermal multiphase processes in porous media under
consideration, we state that the assumption of local thermal
equilibrium is valid since flow velocities are small. We neglect
chemical reactions and biological decomposition and assume chemical
equilibrium. Mechanical equilibrium is not valid in a porous medium,
since discontinuities in pressure can occur across a fluid-fluid
interface due to capillary effects.
\textbf{Notation:} The index $\alpha \in \{\text{w}, \text{n}, \text{g}\}$ refers
to the phase, while the index $\kappa \in \{\text{w}, \text{a}, \text{c}\}$ refers
to the component. \\
$p_\alpha$ & phase pressure & $\phi$ & porosity \\
$T$ & temperature & $K$ & absolute permeability tensor \\
$S_\alpha$ & phase saturation & $\tau$ & tortuosity \\
$x_\alpha^\kappa$ & mole fraction of component $\kappa$ in phase $\alpha$ & $\boldsymbol{g}$ & gravitational acceleration \\
$X_\alpha^\kappa$ & mass fraction of component $\kappa$ in phase $\alpha$ & $q^\kappa_\alpha$ & volume source term of $\kappa$ in $\alpha$ \\
$\varrho_{\text{mol},\alpha}$ & molar density of phase $\alpha$ & $u_\alpha$ & specific internal energy \\
$\varrho_{\alpha}$ & mass density of phase $\alpha$ & $h_\alpha$ & specific enthalpy \\
$k_{\text{r}\alpha}$ & relative permeability & $c_\text{s}$ & specific heat enthalpy \\
$\mu_\alpha$ & phase viscosity & $\lambda_\text{pm}$ & heat conductivity \\
$D_\alpha^\kappa$ & diffusivity of component $\kappa$ in phase $\alpha$ & $q^h$ & heat source term \\
$v_\alpha$ & Darcy velocity & $v_{a,\alpha}$ & advective velocity
\subsection{Balance Equations}
For the balance equations for multicomponent systems, it is in many
cases convenient to use a molar formulation of the continuity
equation. Considering the mass conservation for each component allows
us to drop source/sink terms for describing the mass transfer between
phases. Then, the
molar mass balance can be written as:
&& \phi \frac{\partial (\sum_\alpha \varrho_{\text{mol}, \alpha}
x_\alpha^\kappa S_\alpha )}{\partial t} \nonumber
- \sum\limits_\alpha \Div \left( \frac{k_{\text{r}
\alpha}}{\mu_\alpha} \varrho_{\text{mol}, \alpha}
x_\alpha^\kappa K (\grad p_\alpha -
\varrho_{\alpha} \boldsymbol{g}) \right) \nonumber \\
\nonumber \\
&& - \sum\limits_\alpha \Div \left( \tau \phi S_\alpha D_\alpha^\kappa \varrho_{\text{mol},
\alpha} \grad x_\alpha^\kappa \right) \nonumber
- q^\kappa = 0, \qquad \kappa \in \{\text{w,a,c}\}.
The component mass balance can also be written in terms of mass fractions
by replacing molar densities by mass densities and mole by mass fractions.
To obtain a single conserved quantity in the temporal derivative, the total
concentration, representing the mass of one component per unit volume, is defined as
C^\kappa = \sum_\alpha \phi S_\alpha \varrho_{\text{mass},\alpha} X_\alpha^\kappa \; .
Using this definition, the component mass balance is written as:
&& \frac{\partial C^\kappa}{\partial t} =
\sum\limits_\alpha \Div \left( \frac{k_{\text{r}
\alpha}}{\mu_\alpha} \varrho_{\text{mass}, \alpha}
X_\alpha^\kappa K (\grad p_\alpha +
\varrho_{\text{mass}, \alpha} \boldsymbol{g}) \right) \nonumber \\
\nonumber \\
&& + \sum\limits_\alpha \Div \left( \tau \phi S_\alpha D_\alpha^\kappa \varrho_{\text{mass},
\alpha} \grad X_\alpha^\kappa \right) \nonumber
+ q^\kappa = 0, \qquad \kappa \in \{\text{w,a,c}\}.
In the case of non-isothermal systems, we further have to balance the
thermal energy. We assume fully reversible processes, such that entropy
is not needed as a model parameter. Furthermore, we neglect
dissipative effects and the heat transport due to molecular
diffusion. The heat balance can then be
formulated as:
&& \phi \frac{\partial \left( \sum_\alpha \varrho_{\alpha}
u_\alpha S_\alpha \right)}{\partial t} + \left( 1 -
\phi \right) \frac{\partial \varrho_{\text{s}} c_{\text{s}}
T}{\partial t} \nonumber
- \Div \left( \lambda_{\text{pm}} \grad T \right)
\nonumber \\
\nonumber \\
&& - \sum\limits_\alpha \Div \left( \frac{k_{\text{r}
\alpha}}{\mu_\alpha} \varrho_{\alpha} h_\alpha
K \left( \grad p_\alpha - \varrho_{\alpha}
\boldsymbol{g} \right) \right) \nonumber
- q^h \; = \; 0.
In order to close the system, supplementary constraints for capillary pressure, saturations and mole
fractions are needed, \cite{A3:helmig:1997}.
According to the Gibbsian phase rule, the number of degrees of freedom
in a non-isothermal compositional multiphase system is equal to the
number of components plus one. This means we need as many independent
unknowns in the system description. The
available primary variables are, e.\ g., saturations, mole/mass
fractions, temperature, pressures, etc.
\section{Available models}
The following description of the available models is automatically extracted