diff --git a/doc/handbook/box.tex b/doc/handbook/box.tex
new file mode 100644
index 0000000000000000000000000000000000000000..0ce70c7c4c0000d1428bce304116dca2215c07c8
--- /dev/null
+++ b/doc/handbook/box.tex
@@ -0,0 +1,123 @@
+\section{Box method - A short introduction}\label{box}
+
+For the spatial discretization the so called BOX-method is used which unites the advantages of the finite-volume (FV) and finite-element (FE) methods.
+
+First, the model domain $G$ is discretized with a FE mesh consisting of nodes i and corresponding elements $E_k$. Then, a secondary FV mesh is constructed by connecting the midpoints and barycenters of the elements surrounding node i creating a box $B_i$ around node i (see Figure \ref{pc:box}a).
+
+\begin{figure} [h]
+\includegraphics[width=0.8\linewidth,keepaspectratio]{EPS/box_disc}
+\caption{\label{pc:box} Discretization of the BOX-method}
+\end{figure}
+
+The FE mesh divides the box $B_i$ into subcontrolvolumes (scv's) $b^k_i$ (see Figure \ref{pc:box}b). Figure \ref{pc:box}c shows the finite element $E_k$ and the scv's $b^k_i$ inside $E_k$, which belong to four different boxes $B_i$. Also necessary for the discretization are the faces of the subcontrolvolumes (scvf's) $e^k_{ij}$ between the scv's $b^k_i$ and $b^k_j$, where $|e^k_{ij}|$ is the length of the scvf. The integration points $x^k_{ij}$ on $e^k_{ij}$ and the outer normal vector $\mathbf n^k_{ij}$ are also to be defined (see Figure \ref{pc:box}c).
+
+The advantage of the FE method is that unstructured grids can be used, while the FV method is mass conservative. The idea is to apply the FV method (balance of fluxes across the interfaces) to each FV box $B_i$ and to get the fluxes across the interfaces $e^k_{ij}$ at the integration points $x^k_{ij}$ from the FE approach. Consequently, at each scvf the following expression results:
+
+\begin{equation}
+ f(\tilde u(x^k_{ij})) \cdot \mathbf n^k_{ij} \: |e^k_{ij}| \qquad \textrm{with} \qquad \tilde u(x^k_{ij}) = \sum_i N_i(x^k_{ij}) \cdot \hat u_i .
+\end{equation}
+
+In the following, the discretization of the balance equation is going to be derived. From the \textsc{reynolds}s transport theorem follows the general balance equation:
+
+\begin{equation}
+ \underbrace{\int_G \frac{\partial}{\partial t} \: u \: dG}_{1} + \underbrace{\int_{\partial G} (\mathbf{v} u + \mathbf w) \cdot \textbf n \: d\varGamma}_{2} = \underbrace{\int_G q \: dG}_{3}
+\end{equation}
+
+\begin{equation}
+ f(u) = \int_G \frac{\partial u}{\partial t} \: dG + \int_{G} \nabla \cdot \underbrace{\left[ \mathbf{v} u + \mathbf w(u)\right] }_{F(u)} \: dG - \int_G q \: dG = 0
+\end{equation}
+
+where term 1 describes the changes of entity $u$ within a control volume over time, term 2 the advective, diffusive and dispersive fluxes over the interfaces of the control volume and term 3 is the source and sink term. $G$ denotes the model domain and $F(u) = F(\mathbf v, p) = F(\mathbf v(x,t), p(x,t))$.\\
+
+Like the FE method, the BOX-method follows the principle of weighted residuals. In the function $f(u)$ the unknown $u$ is approximated by discrete values at the nodes of the FE mesh $\hat u_i$ and linear basis functions $N_i$ yielding an approximate function $f(\tilde u)$. For $u\in \lbrace \mathbf v, p, x^\kappa \rbrace$ this means
+
+\begin{minipage}[b]{0.5\textwidth}
+\begin{equation}
+\label{eq:p}
+ \tilde p = \sum_i N_i \hat{p_i}
+\end{equation}
+\begin{equation}
+\label{eq:v}
+ \tilde{\mathbf v} = \sum_i N_i \hat{\mathbf v}
+\end{equation}
+\begin{equation}
+\label{eq:x}
+ \tilde x^\kappa = \sum_i N_i \hat x^\kappa
+\end{equation}
+\end{minipage}
+\hfill
+\begin{minipage}[b]{0.5\textwidth}
+\begin{equation}
+\label{eq:dp}
+ \nabla \tilde p = \sum_i \nabla N_i \hat{p_i}
+\end{equation}
+\begin{equation}
+\label{eq:dv}
+ \nabla \tilde{\mathbf v} = \sum_i \nabla N_i \hat{\mathbf v}
+\end{equation}
+\begin{equation}
+\label{eq:dx}
+ \nabla \tilde x^\kappa = \sum_i \nabla N_i \hat x^\kappa .
+\end{equation}
+\end{minipage}
+
+Due to the approximation with node values and basis functions the differential equations are not exactly fulfilled anymore but a residual $\varepsilon$ is produced.
+
+\begin{equation}
+ f(u) = 0 \qquad \Rightarrow \qquad f(\tilde u) = \varepsilon
+\end{equation}
+
+Application of the principle of weighted residuals, meaning the multiplication of the residual $\varepsilon$ with a weighting function $W_j$ and claiming that this product has to vanish within the whole domain,
+
+\begin{equation}
+ \int_G W_j \cdot \varepsilon \: \overset {!}{=} \: 0 \qquad \textrm{with} \qquad \sum_j W_j =1
+\end{equation}
+
+yields the following equation:
+
+\begin{equation}
+ \int_G W_j \frac{\partial \tilde u}{\partial t} \: dG + \int_G W_j \cdot \left[ \nabla \cdot F(\tilde u) \right] \: dG - \int_G W_j \cdot q \: dG = \int_G W_j \cdot \varepsilon \: dG \: \overset {!}{=} \: 0 .
+\end{equation}
+
+Then, the chain rule and the \textsc{green-gaussian} integral theorem are applied.
+
+\begin{equation}
+ \int_G W_j \frac{\partial \sum_i N_i \hat u_i}{\partial t} \: dG + \int_{\partial G} \left[ W_j \cdot F(\tilde u)\right] \cdot \mathbf n \: d\varGamma_G + \int_G \nabla W_j \cdot F(\tilde u) \: dG - \int_G W_j \cdot q \: dG = 0
+\end{equation}
+
+A mass lumping technique is applied by assuming that the storage capacity is reduced to the nodes. This means that the integrals $M_{i,j} = \int_G W_j \: N_i \: dG$ are replaced by the mass lumping term $M^{lump}_{i,j}$ which is defined as:
+
+\begin{equation}
+ M^{lump}_{i,j} =\begin{cases} \int_G W_j \: dG = \int_G N_i \: dG = V_i &i = j\\
+ 0 &i \neq j\\
+ \end{cases}
+\end{equation}
+
+where $V_i$ is the volume of the FV box $B_i$ associated with node i. The application of this assumption in combination with $\int_G W_j \:q \: dG = V_i \: q$ yields
+
+\begin{equation}
+ V_i \frac{\partial \hat u_i}{\partial t} + \int_{\partial G} \left[ W_j \cdot F(\tilde u)\right] \cdot \mathbf n \: d\varGamma_G + \int_G \nabla W_j \cdot F(\tilde u) \: dG- V_i \cdot q = 0
+\end{equation}
+
+Defining the weighting function $W_j$ to be piecewisely constant over a control volume box $B_i$
+
+\begin{equation}
+ W_j(x) = \begin{cases}
+ 1 &x \in B_i \\
+ 0 &x \notin B_i\\
+ \end{cases}
+\end{equation}
+
+causes $\nabla W_j = 0$:
+
+\begin{equation}
+\label{eq:disc1}
+ V_i \frac{\partial \hat u_i}{\partial t} + \int_{\partial B_i} \left[ W_j \cdot F(\tilde u)\right] \cdot \mathbf n \; d{\varGamma}_{B_i} - V_i \cdot q = 0 .
+\end{equation}
+
+The consideration of the time discretization and inserting $W_j = 1$ finally lead to the discretized form which will be applied to the mathematical flow and transport equations:
+
+\begin{equation}
+\label{eq:discfin}
+ V_i \frac{\hat u_i^{n+1} - \hat u_i^{n}}{\Delta t} + \int_{\partial B_i} F(\tilde u^{n+1}) \cdot \mathbf n \; d{\varGamma}_{B_i} - V_i \: q^{n+1} \: = 0
+\end{equation}
diff --git a/doc/handbook/dumux-handbook.tex b/doc/handbook/dumux-handbook.tex
index 55bcb837e9f713ceaa3921a035c9086de6eb5ef7..3904c88bdcf5d2dbe749f8972ff3bdefe4e53390 100644
--- a/doc/handbook/dumux-handbook.tex
+++ b/doc/handbook/dumux-handbook.tex
@@ -142,15 +142,15 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\
\input{intro}
\input{getting-started}
-\input{designpatterns}
-\input{propertysystem}
\input{tutorial}
\input{structure}
+\input{designpatterns}
+\input{propertysystem}
\input{models}
\input{DumuxFlow}
\input{NewtonInANutshell}
\input{TipsNTricks}
-
+\input{install}
\bibliographystyle{plain}
\bibliography{dumux-handbook}
diff --git a/doc/handbook/getting-started.tex b/doc/handbook/getting-started.tex
index 743a5f07f33c61aa6858674d5f97dbe46179cbc2..93ba070734e3178031ec108785e7eb53df6759fd 100644
--- a/doc/handbook/getting-started.tex
+++ b/doc/handbook/getting-started.tex
@@ -1,8 +1,7 @@
\chapter{Getting started}
-First, we describe the prerequisites and the steps which are necessary for the installation of \Dumux. Then a quick start guide for the first \Dumux experience is provided. We conclude this chapter with a copy of the \Dune coding guidelines.
+First, we describe a quick installation procedure.
+Then a quick start guide for the first \Dumux experience is provided.
-\input{install}
+\input{quick-install}
\input{quickstart-guide}
-\input{guidelines}
-\input{newFolder}
diff --git a/doc/handbook/install.tex b/doc/handbook/install.tex
index ccd13d2f04d0a2465b264882ca7323d23e25fba0..9426411c7f90e938d6b59d15ca475f3f88e1aa3f 100644
--- a/doc/handbook/install.tex
+++ b/doc/handbook/install.tex
@@ -1,5 +1,5 @@
-\section{Installation of \Dumux} \label{install}
-\subsection{Preliminary remarks}
+\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.
@@ -30,7 +30,7 @@ It is allowed to have own files and directories in \Dune-Root, which are not rel
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.
-\subsection{Prerequisites} \label{sec:prerequisites}
+\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}
must be available in a recent version. For Ubuntu Linux, e.g., these are contained in the
@@ -59,7 +59,7 @@ For the extraction of the content of tar-files, the GNU version of \texttt{tar}
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}.
-\subsection{Obtaining source code for \Dune and \Dumux}
+\section{Obtaining source code for \Dune and \Dumux}
As stated above, the \Dumux release 2.0.2 and trunk (developer tree) is based on the \Dune release 2.1.0,
comprising the core modules \texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, \texttt{dune-localfunctions}
and the external dune module \texttt{dune-pdelab}. Thus, for a proper \Dumux installation these modules are required.
@@ -174,18 +174,7 @@ choose to store it by subversion in a secure way, e.g. together with \texttt{kwa
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.
-\paragraph{checkout-dumux script}
-The shell-script \texttt{checkout-dumux} facilitates setting up a {\Dune}/{\Dumux} directory tree (currently for the trunk version).
-It is contained in the download section of the \Dumux web page \cite{DUMUX-HP}.
-For example the second line below will check out the required \Dune modules and \texttt{dumux}, \texttt{dumux-devel} and the \texttt{external} folder, which contains some useful external software and libraries.
-Again, \texttt{joeuser} needs to be replaced by the actual user name.
-
-\begin{lstlisting}[style=Bash]
-$ checkout-dumux -h # show help,
-$ checkout-dumux -gme -u joeuser -p password -d DUMUX
-\end{lstlisting}
-
-\subsection{Patching \Dune or external libraries}
+\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
@@ -213,60 +202,8 @@ $ path -p1 -R < ../dumux/patches/dune-istl-2.0.patch
The \texttt{checkout-dumux} script also applies patches, if not explicitly requested not to do so.
-\subsection{Build of \Dune and \Dumux}
-\label{buildIt}
-Building of \Dune and \Dumux is done by the command-line script \texttt{dunecontrol} as described in \Dune Installation Notes \cite{DUNE-INST}
-and in much more comprehensive form in the \Dune Buildsystem Howto \cite{DUNE-BS}.
-If something fails during the execution of \texttt{dunecontrol} feel free to report it to the \Dune or \Dumux developer mailing list,
-but also try to include error details.\\
-
-It is possible to compile \Dumux with nearly no explicit options to the build system.
-%, but experience showed that the code quality through all parts of \Dune is not yet high enough to give the compiler full
-%freedom for allowing certain kinds of optimizations.
-However, for the successful compilation of \Dune and \Dumux, it is currently necessary to pass the
-%As options, switches for the optimization can be set in parts
-%build system for code by default, it is safer to pass
-the option \texttt{-fno-strict-aliasing} to the C++-compiler
-\cite{WIKIPED-ALIASING}, which is done here via a command-line argument to \texttt{dunecontrol}:
-
-
-\begin{lstlisting}[style=Bash]
-$ # make sure you are in the directory DUNE-Root
-$ ./dune-common/bin/dunecontrol --configure-opts="CXXFLAGS=-fno-strict-aliasing" all
-\end{lstlisting}
-
-Too many options can make life hard. That's why usually option-files are being used together with dunecontrol and its sub-tools.
-Larger sets of options are kept in them. If you are going to compile with options suited for debugging the code, the following
-can be a starting point:
-
-%Below in command-line make sure to insert the right name of dumux' root directory, which is in the case of installation from tar-files \texttt{dumux-2.0} or in the case of installation from subversion just \texttt{dumux}. For a developer it is also possible to take the options file from \texttt{dumux-devel}.
-
-\begin{lstlisting}[style=Bash]
-$ # make sure you are in the directory DUNE-Root
-$ cp dumux/debug.opts my-debug.opts # create a personal version
-$ gedit my-debug.opts # optional editing the options file
-$ ./dune-common/bin/dunecontrol --opts=my-debug.opts all
-\end{lstlisting}
-
-More optimized code, which is typically not usable for standard debugging tasks, can be produced by
-
-\begin{lstlisting}[style=Bash]
-$ cp dumux/optim.opts my-optim.opts
-$ ./dune-common/bin/dunecontrol --opts=my-optim.opts all
-\end{lstlisting}
-
-Sometimes it is necessary to have additional options which
-are specific to a package set of an operating system or
-sometimes you have your own preferences.
-Feel free to work with your own set of options, which may evolve over time.
-The option files above are to be understood more as a starting point
-for setting up an own customization than as something which is fixed.
-The use of external libraries can make it necessary to add quite many options in an option-file.
-It can be helpful to give your customized option file its own name, as done above.
-One avoids confusing it with the option files which came out of the distribution
-and which can be possibly updated by subversion later on.
-\subsection{Building doxygen documentation} \label{sec:build-doxy-doc}
+\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
@@ -289,7 +226,7 @@ $ doxygen
$ firefox html/index.html
\end{lstlisting}
-\subsection{Building documentation of other \Dune modules}
+\section{Building documentation of other \Dune modules}
If the \texttt{--enable-documentation} switch has been set in the configure flags of
\texttt{dunecontrol}, this does not necessarily mean that for every
@@ -326,7 +263,7 @@ $ make dumux-handbook.pdf
%Alternatively, the tool CMake can be used to build \Dumux. Please check the file \texttt{INSTALL.cmake} for details.
-\subsection{External libraries and modules} \label{sec:external-modules-libraries}
+\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}.
@@ -382,7 +319,7 @@ C and Fortran compiler is needed for some external libraries. As code of differe
% http://gmplib.org/
\end{itemize}
-\subsection{Hints for Users from IWS}
+\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.
diff --git a/doc/handbook/models.tex b/doc/handbook/models.tex
index 7081ae9cde2f057fabe32eb33592de2e497e1199..c117929653b1f18abcb72a96faa139fff1565167 100644
--- a/doc/handbook/models.tex
+++ b/doc/handbook/models.tex
@@ -142,7 +142,7 @@ unknowns in the system description. The
available primary variables are, e.\ g., saturations, mole/mass
fractions, temperature, pressures, etc.
-
+\input{box}
\section{Available models}
diff --git a/doc/handbook/quick-install.tex b/doc/handbook/quick-install.tex
new file mode 100644
index 0000000000000000000000000000000000000000..3af9477e095a0a2312c8409d03e1036582e43357
--- /dev/null
+++ b/doc/handbook/quick-install.tex
@@ -0,0 +1,75 @@
+\section{Quick Installation of \Dumux} \label{quick-install}
+
+This only provides one quick way of installing \Dumux.
+You should have a recent working Linux environment, no \Dune core modules should be installed.
+If you need more information,
+have \Dune already installed, please have a look at the detailed installation
+instructions in Section \ref{install}.
+
+\subsection{Obtaining the code with the script \texttt{checkout-dumux}}
+
+The shell-script \texttt{checkout-dumux} facilitates setting up a {\Dune}/{\Dumux} directory tree (currently for the trunk version).
+It is contained in the download section of the \Dumux web page \cite{DUMUX-HP}.
+For example the second line below will check out the required \Dune modules and \texttt{dumux},
+\texttt{dumux-devel} and the \texttt{external} folder, which contains some useful external software and libraries.
+Again, \texttt{joeuser} needs to be replaced by the actual user name.
+
+\begin{lstlisting}[style=Bash]
+$ checkout-dumux -h # show help,
+$ checkout-dumux -gme -u joeuser -p password -d DUMUX
+\end{lstlisting}
+
+
+\subsection{Build of \Dune and \Dumux}
+\label{buildIt}
+Building of \Dune and \Dumux is done by the command-line script \texttt{dunecontrol} as described in \Dune Installation Notes \cite{DUNE-INST}
+and in much more comprehensive form in the \Dune Buildsystem Howto \cite{DUNE-BS}.
+If something fails during the execution of \texttt{dunecontrol} feel free to report it to the \Dune or \Dumux developer mailing list,
+but also try to include error details.\\
+
+It is possible to compile \Dumux with nearly no explicit options to the build system.
+%, but experience showed that the code quality through all parts of \Dune is not yet high enough to give the compiler full
+%freedom for allowing certain kinds of optimizations.
+However, for the successful compilation of \Dune and \Dumux, it is currently necessary to pass the
+%As options, switches for the optimization can be set in parts
+%build system for code by default, it is safer to pass
+the option \texttt{-fno-strict-aliasing} to the C++-compiler
+\cite{WIKIPED-ALIASING}, which is done here via a command-line argument to \texttt{dunecontrol}:
+
+
+\begin{lstlisting}[style=Bash]
+$ # make sure you are in the directory DUNE-Root
+$ ./dune-common/bin/dunecontrol --configure-opts="CXXFLAGS=-fno-strict-aliasing" all
+\end{lstlisting}
+
+Too many options can make life hard. That's why usually option-files are being used together with dunecontrol and its sub-tools.
+Larger sets of options are kept in them. If you are going to compile with options suited for debugging the code, the following
+can be a starting point:
+
+%Below in command-line make sure to insert the right name of dumux' root directory, which is in the case of installation from tar-files \texttt{dumux-2.0} or in the case of installation from subversion just \texttt{dumux}. For a developer it is also possible to take the options file from \texttt{dumux-devel}.
+
+\begin{lstlisting}[style=Bash]
+$ # make sure you are in the directory DUNE-Root
+$ cp dumux/debug.opts my-debug.opts # create a personal version
+$ gedit my-debug.opts # optional editing the options file
+$ ./dune-common/bin/dunecontrol --opts=my-debug.opts all
+\end{lstlisting}
+
+More optimized code, which is typically not usable for standard debugging tasks, can be produced by
+
+\begin{lstlisting}[style=Bash]
+$ cp dumux/optim.opts my-optim.opts
+$ ./dune-common/bin/dunecontrol --opts=my-optim.opts all
+\end{lstlisting}
+
+Sometimes it is necessary to have additional options which
+are specific to a package set of an operating system or
+sometimes you have your own preferences.
+Feel free to work with your own set of options, which may evolve over time.
+The option files above are to be understood more as a starting point
+for setting up an own customization than as something which is fixed.
+The use of external libraries can make it necessary to add quite many options in an option-file.
+It can be helpful to give your customized option file its own name, as done above.
+One avoids confusing it with the option files which came out of the distribution
+and which can be possibly updated by subversion later on.
+
diff --git a/doc/handbook/structure.tex b/doc/handbook/structure.tex
index a744290209702bdf889e545fcd3f66f657a1613e..90197e4c3481dbea5f3a5b5898bc91a420c3fcc0 100644
--- a/doc/handbook/structure.tex
+++ b/doc/handbook/structure.tex
@@ -1,4 +1,6 @@
-\chapter{Directory Structure}
+\chapter{Structure, Guidelines, New Folder Setup}
+
+\section{Directory Structure}
We briefly describe the directory structure of \Dumux in terms
of subdirectories, source files, and tests. For more details,
@@ -25,7 +27,7 @@ See Section \ref{sec:test} for details.
-\section{The directory \texttt{dumux}}\label{sec:dumux}
+\subsection{The directory \texttt{dumux}}\label{sec:dumux}
The directory \texttt{dumux} contains the \Dumux source files. It consists of the following subdirectories (see Figure \ref{fig:dumux-structure}):
@@ -94,7 +96,7 @@ while the necessary binary coefficients like the Henry coefficient or binary dif
-\section{The directory \texttt{test}}\label{sec:test}
+\subsection{The directory \texttt{test}}\label{sec:test}
The directory \texttt{test} contains a test for each numerical model and for
@@ -120,3 +122,6 @@ Doxygen documentation should be considered.
}
\end{figure}
\end{landscape}
+
+\input{guidelines}
+\input{newFolder}
diff --git a/doc/handbook/tutorial-coupled.tex b/doc/handbook/tutorial-coupled.tex
index 37aa108afef2b0979b55b481a875ac6ba1f87d14..71fa19077aefa054b5d0b16c6951d9cfe5449b6c 100644
--- a/doc/handbook/tutorial-coupled.tex
+++ b/doc/handbook/tutorial-coupled.tex
@@ -1,127 +1,3 @@
-\section{Box method - A short introduction}\label{box}
-
-For the spatial discretization the so called BOX-method is used which unites the advantages of the finite-volume (FV) and finite-element (FE) methods.
-
-First, the model domain $G$ is discretized with a FE mesh consisting of nodes i and corresponding elements $E_k$. Then, a secondary FV mesh is constructed by connecting the midpoints and barycenters of the elements surrounding node i creating a box $B_i$ around node i (see Figure \ref{pc:box}a).
-
-\begin{figure} [h]
-\includegraphics[width=0.8\linewidth,keepaspectratio]{EPS/box_disc}
-\caption{\label{pc:box} Discretization of the BOX-method}
-\end{figure}
-
-The FE mesh divides the box $B_i$ into subcontrolvolumes (scv's) $b^k_i$ (see Figure \ref{pc:box}b). Figure \ref{pc:box}c shows the finite element $E_k$ and the scv's $b^k_i$ inside $E_k$, which belong to four different boxes $B_i$. Also necessary for the discretization are the faces of the subcontrolvolumes (scvf's) $e^k_{ij}$ between the scv's $b^k_i$ and $b^k_j$, where $|e^k_{ij}|$ is the length of the scvf. The integration points $x^k_{ij}$ on $e^k_{ij}$ and the outer normal vector $\mathbf n^k_{ij}$ are also to be defined (see Figure \ref{pc:box}c).
-
-The advantage of the FE method is that unstructured grids can be used, while the FV method is mass conservative. The idea is to apply the FV method (balance of fluxes across the interfaces) to each FV box $B_i$ and to get the fluxes across the interfaces $e^k_{ij}$ at the integration points $x^k_{ij}$ from the FE approach. Consequently, at each scvf the following expression results:
-
-\begin{equation}
- f(\tilde u(x^k_{ij})) \cdot \mathbf n^k_{ij} \: |e^k_{ij}| \qquad \textrm{with} \qquad \tilde u(x^k_{ij}) = \sum_i N_i(x^k_{ij}) \cdot \hat u_i .
-\end{equation}
-
-In the following, the discretization of the balance equation is going to be derived. From the \textsc{reynolds}s transport theorem follows the general balance equation:
-
-\begin{equation}
- \underbrace{\int_G \frac{\partial}{\partial t} \: u \: dG}_{1} + \underbrace{\int_{\partial G} (\mathbf{v} u + \mathbf w) \cdot \textbf n \: d\varGamma}_{2} = \underbrace{\int_G q \: dG}_{3}
-\end{equation}
-
-\begin{equation}
- f(u) = \int_G \frac{\partial u}{\partial t} \: dG + \int_{G} \nabla \cdot \underbrace{\left[ \mathbf{v} u + \mathbf w(u)\right] }_{F(u)} \: dG - \int_G q \: dG = 0
-\end{equation}
-
-where term 1 describes the changes of entity $u$ within a control volume over time, term 2 the advective, diffusive and dispersive fluxes over the interfaces of the control volume and term 3 is the source and sink term. $G$ denotes the model domain and $F(u) = F(\mathbf v, p) = F(\mathbf v(x,t), p(x,t))$.\\
-
-Like the FE method, the BOX-method follows the principle of weighted residuals. In the function $f(u)$ the unknown $u$ is approximated by discrete values at the nodes of the FE mesh $\hat u_i$ and linear basis functions $N_i$ yielding an approximate function $f(\tilde u)$. For $u\in \lbrace \mathbf v, p, x^\kappa \rbrace$ this means
-
-\begin{minipage}[b]{0.5\textwidth}
-\begin{equation}
-\label{eq:p}
- \tilde p = \sum_i N_i \hat{p_i}
-\end{equation}
-\begin{equation}
-\label{eq:v}
- \tilde{\mathbf v} = \sum_i N_i \hat{\mathbf v}
-\end{equation}
-\begin{equation}
-\label{eq:x}
- \tilde x^\kappa = \sum_i N_i \hat x^\kappa
-\end{equation}
-\end{minipage}
-\hfill
-\begin{minipage}[b]{0.5\textwidth}
-\begin{equation}
-\label{eq:dp}
- \nabla \tilde p = \sum_i \nabla N_i \hat{p_i}
-\end{equation}
-\begin{equation}
-\label{eq:dv}
- \nabla \tilde{\mathbf v} = \sum_i \nabla N_i \hat{\mathbf v}
-\end{equation}
-\begin{equation}
-\label{eq:dx}
- \nabla \tilde x^\kappa = \sum_i \nabla N_i \hat x^\kappa .
-\end{equation}
-\end{minipage}
-
-Due to the approximation with node values and basis functions the differential equations are not exactly fulfilled anymore but a residual $\varepsilon$ is produced.
-
-\begin{equation}
- f(u) = 0 \qquad \Rightarrow \qquad f(\tilde u) = \varepsilon
-\end{equation}
-
-Application of the principle of weighted residuals, meaning the multiplication of the residual $\varepsilon$ with a weighting function $W_j$ and claiming that this product has to vanish within the whole domain,
-
-\begin{equation}
- \int_G W_j \cdot \varepsilon \: \overset {!}{=} \: 0 \qquad \textrm{with} \qquad \sum_j W_j =1
-\end{equation}
-
-yields the following equation:
-
-\begin{equation}
- \int_G W_j \frac{\partial \tilde u}{\partial t} \: dG + \int_G W_j \cdot \left[ \nabla \cdot F(\tilde u) \right] \: dG - \int_G W_j \cdot q \: dG = \int_G W_j \cdot \varepsilon \: dG \: \overset {!}{=} \: 0 .
-\end{equation}
-
-Then, the chain rule and the \textsc{green-gaussian} integral theorem are applied.
-
-\begin{equation}
- \int_G W_j \frac{\partial \sum_i N_i \hat u_i}{\partial t} \: dG + \int_{\partial G} \left[ W_j \cdot F(\tilde u)\right] \cdot \mathbf n \: d\varGamma_G + \int_G \nabla W_j \cdot F(\tilde u) \: dG - \int_G W_j \cdot q \: dG = 0
-\end{equation}
-
-A mass lumping technique is applied by assuming that the storage capacity is reduced to the nodes. This means that the integrals $M_{i,j} = \int_G W_j \: N_i \: dG$ are replaced by the mass lumping term $M^{lump}_{i,j}$ which is defined as:
-
-\begin{equation}
- M^{lump}_{i,j} =\begin{cases} \int_G W_j \: dG = \int_G N_i \: dG = V_i &i = j\\
- 0 &i \neq j\\
- \end{cases}
-\end{equation}
-
-where $V_i$ is the volume of the FV box $B_i$ associated with node i. The application of this assumption in combination with $\int_G W_j \:q \: dG = V_i \: q$ yields
-
-\begin{equation}
- V_i \frac{\partial \hat u_i}{\partial t} + \int_{\partial G} \left[ W_j \cdot F(\tilde u)\right] \cdot \mathbf n \: d\varGamma_G + \int_G \nabla W_j \cdot F(\tilde u) \: dG- V_i \cdot q = 0
-\end{equation}
-
-Defining the weighting function $W_j$ to be piecewisely constant over a control volume box $B_i$
-
-\begin{equation}
- W_j(x) = \begin{cases}
- 1 &x \in B_i \\
- 0 &x \notin B_i\\
- \end{cases}
-\end{equation}
-
-causes $\nabla W_j = 0$:
-
-\begin{equation}
-\label{eq:disc1}
- V_i \frac{\partial \hat u_i}{\partial t} + \int_{\partial B_i} \left[ W_j \cdot F(\tilde u)\right] \cdot \mathbf n \; d{\varGamma}_{B_i} - V_i \cdot q = 0 .
-\end{equation}
-
-The consideration of the time discretization and inserting $W_j = 1$ finally lead to the discretized form which will be applied to the mathematical flow and transport equations:
-
-\begin{equation}
-\label{eq:discfin}
- V_i \frac{\hat u_i^{n+1} - \hat u_i^{n}}{\Delta t} + \int_{\partial B_i} F(\tilde u^{n+1}) \cdot \mathbf n \; d{\varGamma}_{B_i} - V_i \: q^{n+1} \: = 0
-\end{equation}
-
\section[Fully-coupled model]{Solving a problem using a Fully-Coupled Model}\label{tutorial-coupled}
The process of solving a problem using \Dumux can be roughly divided into four parts: