From aace6f1b9df7ad6b649366ec2bfe6fd88290380d Mon Sep 17 00:00:00 2001
From: melaniel <melanie.lipp@iws.uni-stuttgart.de>
Date: Wed, 2 Oct 2019 10:41:46 +0200
Subject: [PATCH] [doc][handbook] Include examples in handbook.
---
doc/handbook/0_dumux-handbook.tex | 13 ++
doc/handbook/4_course.tex | 12 +-
doc/handbook/4_examples.tex | 10 +
doc/handbook/4_furtherpractice.tex | 2 +-
doc/handbook/5_structure.tex | 1 +
doc/handbook/6_basics.tex | 202 ++++++++++++++++++++-
doc/handbook/6_temporaldiscretizations.tex | 3 +-
doc/handbook/dumux-handbook.bib | 28 +++
8 files changed, 257 insertions(+), 14 deletions(-)
create mode 100644 doc/handbook/4_examples.tex
diff --git a/doc/handbook/0_dumux-handbook.tex b/doc/handbook/0_dumux-handbook.tex
index 59d04dabe7..fc6aeb20c9 100644
--- a/doc/handbook/0_dumux-handbook.tex
+++ b/doc/handbook/0_dumux-handbook.tex
@@ -11,6 +11,7 @@
\usepackage{enumerate}
\usepackage{hyperref}
\usepackage{graphicx}
+\usepackage{mhchem}
\usepackage{listings}
\usepackage[square,numbers]{natbib}
@@ -124,7 +125,19 @@ how to build the documentation and about external libraries and modules.
\input{3_detailedinstall}
\chapter{Learning to use \Dumux}\label{chp:tutorial}
+So, you've downloaded your very own copy of \Dumux and its dependencies.
+You've run dunecontrol, and your example ``test$\_$dumux" not only compiles,
+but it even shows a nice simulation in ParaView.
+Maybe you've read through parts of the handbook, and even started looking
+through the Doxygen documentation.
+Well done. What now? \par
+%
+\textit{``How on earth is this going to help me solve my multi-(phase, component,
+ scale, physics) flow and transport problems in porous media systems?''}, you begin to wonder.
+Don't panic! In order to best ease our prospective users and developers into the
+wonderful \Dumux simulation environment, we've prepared a \Dumux course and extensively-documented examples.
\input{4_course}
+\input{4_examples}
\input{4_furtherpractice}
\chapter{Overview and Infrastructure}
diff --git a/doc/handbook/4_course.tex b/doc/handbook/4_course.tex
index c3dbee42f7..6074db9a26 100644
--- a/doc/handbook/4_course.tex
+++ b/doc/handbook/4_course.tex
@@ -1,14 +1,4 @@
-So, you've downloaded your very own copy of \Dumux and its dependencies.
-You've run dunecontrol, and your example ``test$\_$dumux" not only compiles,
-but it even shows a nice simulation in ParaView.
-Maybe you've read through parts of the handbook, and even started looking
-through the Doxygen documentation.
-Well done. What now? \par
-%
-\textit{``How on earth is this going to help me solve my multi-(phase, component,
-scale, physics) flow and transport problems in porous media systems?''}, you begin to wonder.
-Don't panic! In order to best ease our prospective users and developers into the
-wonderful \Dumux simulation environment, we've prepared a \Dumux course.
+\section{Hands-on \Dumux experience -- the \Dumux course}
This course is offered once a year over a period of 3 days at the University of Stuttgart.
If you're looking for information on attending, subscribe to the \Dumux mailing list
and stay tuned for updates:
diff --git a/doc/handbook/4_examples.tex b/doc/handbook/4_examples.tex
new file mode 100644
index 0000000000..24a8f08299
--- /dev/null
+++ b/doc/handbook/4_examples.tex
@@ -0,0 +1,10 @@
+\section{Experience \Dumux by reading -- the \Dumux examples}
+As an alternative to going through exercises, you can have a look at our well-documented \Dumux examples. They show how to apply \Dumux to typical physical problems. In the \texttt{README.md} files, the setup is explained, the used code is presented and documented and images resulting from the simulation are included. The \texttt{README.md} files are located directly in the subfolders of \texttt{examples} and can be displayed by web browsers.
+
+We currently have the examples
+\begin{itemize}
+ \item \texttt{1ptracer}: one-phase groundwater flow including a tracer
+ \item \texttt{2pinfiltration}: two-phase infiltration problem
+ \item \texttt{shallowwaterfriction}: steady subcritical shallow water flow including bottom friction
+\end{itemize}
+The number of examples is continuously growing.
\ No newline at end of file
diff --git a/doc/handbook/4_furtherpractice.tex b/doc/handbook/4_furtherpractice.tex
index d31e227e73..0d49b97db8 100644
--- a/doc/handbook/4_furtherpractice.tex
+++ b/doc/handbook/4_furtherpractice.tex
@@ -39,7 +39,7 @@ contained in the \texttt{dumux-lecture} module:
\item \texttt{co2plume}: Analysis of the influence of the gravitational number on the $\text{CO}_2$ plume
\item \texttt{columnxylene}: A VEGAS experiment
\item \texttt{convectivemixing}: A test case related to CO$_2$ storage
-\item \texttt{fuelcell}%TODO
+\item \texttt{fuelcell}: Water management in PEM fuel cells
\item \texttt{heatpipe}: A show case for two-phase two-component flow with heat fluxes
\item \texttt{heavyoil}: Steam assisted gravity drainage (SAGD)
\item \texttt{henryproblem}: A show case related to salt water intrusion
diff --git a/doc/handbook/5_structure.tex b/doc/handbook/5_structure.tex
index a4146b5afc..a184e8a843 100644
--- a/doc/handbook/5_structure.tex
+++ b/doc/handbook/5_structure.tex
@@ -9,6 +9,7 @@
\item \texttt{dumux}: the main folder, containing the source files. See \ref{fig:dumux-structure}
for a visualized structure. For more information on the models have a look at the
Doxygen documentation.
+\item \texttt{examples}: well-documented examples of applying \Dumux to typical physical problems. In the \texttt{README.md} files, the setup is explained, the used code is presented and documented and images resulting from the simulation are included. The \texttt{README.md} files are located directly in the subfolders of \texttt{examples} and can be displayed by web browsers.
\item \texttt{test}: tests for each numerical model and some functionality.
The structure is equivalent to the \texttt{dumux} folder, the \texttt{references} folder
contains solutions for the automatic testing. Each test program consist of a main file
diff --git a/doc/handbook/6_basics.tex b/doc/handbook/6_basics.tex
index a6ec76568a..691a07f19f 100644
--- a/doc/handbook/6_basics.tex
+++ b/doc/handbook/6_basics.tex
@@ -3,7 +3,6 @@ Here the basic definitions, the general models concept, and a list of
models available in \Dumux are given. The actual differential equations
can be found in the local residuals (see Doxygen documentation of the
model's \texttt{LocalResidual} class).
-%TODO: Add more physics
\subsection{Basic Definitions and Assumptions}
The basic definitions and assumptions are made, using the example
@@ -125,6 +124,207 @@ $\boldsymbol{v}_\alpha$ & velocity (Darcy or free flow)& & \\
\label{fig:phaseMassEnergyTransfer}
\end{figure}
+\subsection[Scale]{Scale\footnote{\label{foot:hommel}This subsection is taken from \cite{hommel2016modeling} in a slightly adapted form.}}
+
+Depending on the scale of interest, physical and chemical processes and properties can be described
+using different approaches.
+On the molecular scale, the properties and interactions of individual molecules are described,
+which is only feasible for a restricted number of molecules.
+For larger systems, a continuum approach is used, where properties are averaged over
+groups of similar molecules, assuming continuous matter. This upscaling by averaging
+from the molecular scale results in the micro-scale, on which the system is described by
+the pore geometry and the distribution of distinct fluid phases within the pores.
+However, for larger laboratory or field-scale applications, the micro-scale is still
+computationally prohibitively expensive and system descriptions on the macro-scale
+are used for calculations. The macro-scale description is obtained by averaging over the
+micro-scale properties within a representative elementary volume (REV),
+which needs to be large enough to ensure that the averaged properties are independent of the REV size
+or position. However, it should in turn be much smaller than the entire domain size \citep{helmig1997multiphase}. %(Bear 1988)
+The detailed pore-geometry and phase-distribution information of the micro-scale is lost
+on the macro-scale and replaced by volume average quantities,
+such as porosity, permeability and phase saturation,
+and relations like the Darcy's law.
+The macro-scale is also called the REV (or Darcy) scale and is the scale of the
+models available in \Dumux.
+
+\subsection[Porous medium properties]{Porous medium properties\footref{foot:hommel}}
+\subsubsection{Porosity}
+The porosity $\phi$ is defined as the fraction of the volume occupied by fluids in an REV $V_\mathrm{fluid}$
+divided by the total volume of the REV $V_\mathrm{total}$.
+
+\begin{equation}\label{eq:def_poro}
+\phi=\frac{V_\mathrm{fluid}}{V_\mathrm{total}}=1-\frac{V_\mathrm{solid}}{V_\mathrm{total}}.
+\end{equation}
+
+
+\subsubsection{Intrinsic permeability}
+The intrinsic permeability is a measure on the REV scale of the ease of fluid flow through porous media.
+It relates the potential gradient and the resulting flow velocity in the Darcy equation.
+As the porous medium may have a structure leading to preferential flow in certain directions,
+intrinsic permeability is in general a tensorial quantity $\mathbf{K}$.
+For isotropic porous media, it can be reduced to a scalar quantity $K$.
+
+% \begin{equation}
+% \mathbf{v}=
+% \end{equation}
+
+\newpage
+\subsection[Phases and components]{Phases and components\footref{foot:hommel}}\label{sec:phases_components}
+A phase is defined as a continuum having distinct properties (e.g. density and viscosity). If phases are miscible, they contain dissolved portions of the substance of the other phase.
+Fluid and solid phases are distinguished. The fluid phases have different affinities to the solid phases. The phase, which has a higher affinity to the solid phases is referred to as the (more) wetting phase. In the case of two phases, the less wetting one is called the non-wetting phase.
+
+The fluid phases may be composed of several components, while the solid phases are assumed to consist exclusively of a single component. Components are distinct chemical species or a group of chemical species.
+The composition of the components in a phase can influence the phase properties.
+
+\subsubsection{Mass fraction, mole fraction}\label{sec:mole_frac_molality}
+The composition of a phase is described by mass or mole fractions of the components.
+The mole fraction $x^\kappa_\alpha$ of component $\kappa$ in phase $\alpha$ is defined as:
+
+\begin{equation}\label{eq:def_molefrac}
+x^\kappa_\alpha = \frac{n^\kappa_\alpha}{\sum_i n^i_\alpha},
+\end{equation}
+
+where $n^\kappa_\alpha$ is the number of moles of component $\kappa$ in phase $\alpha$.
+The mass fraction $X^\kappa_\alpha$ is defined similarly
+using the mass of component $\kappa$ in phase $\alpha$ instead of $n^\kappa_\alpha$,
+$X^\kappa_\alpha = \nicefrac{\mathrm{mass^\kappa_\alpha}}{\mathrm{mass^{total}_\alpha}}$.
+% as:
+%
+% \begin{equation}\label{eq:def_massfrac}
+% X^\kappa_\alpha = \frac{m^\kappa_\alpha}{\sum_i m^i_\alpha},
+% \end{equation}
+%
+% where $m^\kappa_\alpha$ is the mass of component $\kappa$ in phase $\alpha$.
+The molar mass $M^\kappa$ of the component $\kappa$ relates the mass fraction
+to the mole fraction and vice versa.
+
+\subsection[Fluid properties]{Fluid properties\footref{foot:hommel}}\label{sec:fluid_properties}
+The most important fluid properties to describe fluid flow on the REV scale are density and viscosity.
+
+\subsubsection{Density}\label{sec:density}
+The density $\rho_\alpha$ of a fluid phase $\alpha$ is defined as the ratio of its mass to its volume
+$(\rho_\alpha = \nicefrac{\mathrm{mass_\alpha}}{\mathrm{volume_\alpha}})$ while
+the molar density $\rho_{\mathrm{mol},\alpha}$ is defined as the ratio of the number of moles per volume
+$(\rho_{\mathrm{mol},\alpha} = \nicefrac{\mathrm{moles_\alpha}}{\mathrm{volume_\alpha}})$.
+
+\subsubsection{Viscosity}\label{sec:viscosity}
+The dynamic viscosity $\mu_\alpha$ characterizes the resistance of a fluid to flow.
+As density, it is a fluid phase property.
+For Newtonian fluids, it relates the shear stress $\tau_\mathrm{s}$ to the
+velocity gradient $\nicefrac{d v_{\alpha,\,x}}{d y}$:
+
+\begin{equation}\label{eq:def_viscosity}
+\tau_\mathrm{s} = \mu_\alpha \frac{d v_{\alpha,\,x}}{d y}.
+\end{equation}
+
+Density and viscosity are both dependent on pressure, temperature and phase composition.
+
+\subsection[Fluid phase interactions in porous media]{Fluid phase interactions in porous media\footref{foot:hommel}}\label{sec:fluid_interact}
+If more than a single fluid is present in the porous medium, the fluids interact with each other and the solids, which leads to additional properties for multi-phase systems.
+
+\subsubsection{Saturation}\label{sec:saturation}
+The saturation $S_\alpha$ of a phase $\alpha$ is defined as the ratio of the volume occupied
+by that phase to the total pore volume within an REV.
+As all pores are filled with some fluid, the sum of the saturations of all present phases is equal to one.
+
+\subsubsection{Capillary pressure}\label{sec:pc}
+Immiscible fluids form a sharp interface as a result of differences in their intermolecular forces
+translating into different adhesive and cohesive forces at the fluid-fluid and fluid-fluid-solid interfaces
+creating interfacial tension on the microscale.
+From the mechanical equilibrium which has also to be satisfied at the interface,
+a difference between the pressures of the fluid phases results defined as
+the capillary pressure $p_\mathrm{c}$:
+
+\begin{equation}\label{eq:pc-pn_pw}
+p_\mathrm{c} = p_\mathrm{n} - p_\mathrm{w}.
+\end{equation}
+
+On the microscale, $p_\mathrm{c}$ can be calculated from the surface tension
+according to the Laplace equation \citep[see][]{helmig1997multiphase}.
+
+On the REV scale, however, capillary pressure needs to be defined by quantities of that scale.
+Several empirical relations provide expressions to link $p_\mathrm{c}$ to the wetting-phase saturation $S_\mathrm{w}$.
+An example is the relation given by \citet{brooks1964hydrau} %, Corey1994}
+to determine $p_\mathrm{c}$ based on
+$S_\mathrm{e}$, which is the effective wetting-phase saturation,
+the entry pressure $p_\mathrm{d}$, and the parameter $\lambda$ describing the pore-size distribution:
+
+\begin{equation}\label{eq:pc-Sw}
+p_\mathrm{c} = p_\mathrm{d} S_\mathrm{e}^{-\frac{1}{\lambda}},
+\end{equation}
+
+with
+
+\begin{equation}\label{eq:Se}
+S_\mathrm{e} = \frac{S_\mathrm{w}-S_\mathrm{w,r}}{1-S_\mathrm{w,r}},
+\end{equation}
+
+where $S_\mathrm{w,r}$ is the residual wetting phase saturation which cannot be displaced
+by another fluid phase and remains in the porous medium.
+
+\subsubsection{Relative permeability}\label{sec:kr}
+The presence of two fluid phases in the porous medium reduces the space available for flow
+for each of the fluid phases.
+This increases the resistance to flow of the phases, which is accounted for by the means of
+the relative permeability $k_\mathrm{r,\alpha}$, which scales the intrinsic permeability.
+It is a value between zero and one, depending on the saturation.
+The relations describing the relative permeabilities of the wetting and non-wetting phase are different
+as the wetting phase predominantly occupies small pores and the edges of larger pores while the
+non-wetting phases occupies large pores.
+The relative permeabilities for the wetting phase $k_\mathrm{r,w}$ and the non-wetting phase are calculated as:
+
+\begin{equation}\label{eq:krw}
+k_\mathrm{r,w} = S_\mathrm{e}^{\frac{2+3\lambda}{\lambda}}
+\end{equation}
+and
+\begin{equation}\label{eq:krn}
+k_\mathrm{r,n} = \left( 1- S_\mathrm{e}\right)^2 \left( 1- S_\mathrm{e}^{\frac{2+\lambda}{\lambda}}\right).
+\end{equation}
+
+\subsection[Transport processes in porous media]{Transport processes in porous media \footref{foot:hommel}}\label{sec:tipm}
+On the macro-scale, the transport of mass can be grouped according to the driving force of the
+transport process. Pressure gradients result in the advective transport of a fluid phase
+and all the components constituting the phase,
+while concentration gradients result in the diffusion of a component within a phase.
+
+\subsubsection{Advection}\label{sec:Advection}
+Advective transport is determined by the flow field.
+On the macro-scale, the velocity $\mathbf{v}$ is calculated using the Darcy equation
+depending on the potential gradient $(\nabla p_\alpha - \rho_\alpha \mathbf{g})$,
+accounting for both pressure difference and gravitation,
+the intrinsic permeability of the porous medium,
+and the viscosity $\mu$ of the fluid phase:
+
+\begin{equation} \label{eq:Darcy1p}
+\mathbf{v}=-\frac{\mathbf{K}}{\mu}(\nabla p - \rho \mathbf{g}).
+\end{equation}
+
+$\mathbf{v}$ is proportional to $(\nabla p - \rho \mathbf{g})$ with the proportional factor $\nicefrac{\mathbf{K}}{\mu}$.
+This equation can be extended to calculate the velocity $\mathbf{v}_{\alpha}$ of phase $\alpha$ in the case of
+two-phase flow by considering the relative permeability $k_\mathrm{r,\alpha}$ (Section~\ref{sec:kr}):
+
+\begin{equation} \label{eq:Darcy2p}
+\mathbf{v}_{\alpha}=-\frac{k_\mathrm{r,\alpha}\mathbf{K}}{\mu_{\alpha}}(\nabla p_{\alpha} - \rho_{\alpha} \mathbf{g})
+\end{equation}
+
+\subsubsection{Diffusion}\label{sec:Diffusion}
+Molecular diffusion is a process determined by the concentration gradient.
+It is commonly modeled as Fickian diffusion following Fick's first law:
+
+\begin{equation} \label{eq:Diffusion}
+\mathbf{j_d}=-\rho_{\mathrm{mol},\alpha} D^\kappa_\alpha \nabla x^\kappa_\alpha,
+\end{equation}
+
+where $D^\kappa_\alpha$ is the molecular diffusion coefficient of component $\kappa$ in phase $\alpha$.
+In a porous medium, the actual path lines are tortuous due to the impact of the solid matrix.
+This tortuosity and the impact of the presence of multiple fluid phases
+is accounted for by using an effective diffusion coefficient $D^\kappa_\mathrm{pm, \alpha}$:
+
+\begin{equation} \label{eq:diffusion_coeff_pm}
+D^\kappa_\mathrm{pm, \alpha}= \phi \tau_\alpha S_\alpha D^\kappa_\alpha,
+\end{equation}
+
+where $\tau_\alpha$ is the tortuosity of phase $\alpha$.
\subsection{Gas mixing laws}
Prediction of the $p-\varrho-T$ behavior of gas mixtures is typically based on two (contradicting) concepts: Dalton's law or Amagat's law.
diff --git a/doc/handbook/6_temporaldiscretizations.tex b/doc/handbook/6_temporaldiscretizations.tex
index fd424205bd..f3fdb36492 100644
--- a/doc/handbook/6_temporaldiscretizations.tex
+++ b/doc/handbook/6_temporaldiscretizations.tex
@@ -1,5 +1,6 @@
\section{Temporal Discretization and Solution Strategies}
-%TODO: Intro sentences
+In this section, the temporal discretization as well as solution strategies (monolithic/sequential) are presented.
+
\subsection{Temporal discretization}
Our systems of partial differential equations are discretized in space and in time.
diff --git a/doc/handbook/dumux-handbook.bib b/doc/handbook/dumux-handbook.bib
index 169292f207..88860ce45f 100644
--- a/doc/handbook/dumux-handbook.bib
+++ b/doc/handbook/dumux-handbook.bib
@@ -1854,3 +1854,31 @@ year={1999}
year={1993},
publisher={John Wiley \& Sons}
}
+
+@phdthesis{hommel2016modeling,
+ author = {Hommel, Johannes},
+ isbn = {978-3-942036-48-1},
+ month = {2},
+ school = {Universität Stuttgart, TASK},
+ title = {Modeling biogeochemical and mass transport processes in the subsurface: Investigation of microbially induced calcite precipitation},
+ type = {Promotionsschrift},
+ url = {https://elib.uni-stuttgart.de/handle/11682/8787},
+ volume = 244,
+ year = 2016
+}
+
+@book{helmig1997multiphase,
+ title={Multiphase flow and transport processes in the subsurface: a contribution to the modeling of hydrosystems.},
+ author={Helmig, Rainer and others},
+ year={1997},
+ publisher={Springer-Verlag}
+}
+
+@article{brooks1964hydrau,
+ title={HYDRAU uc properties of porous media},
+ author={Brooks, R and Corey, T},
+ journal={Hydrology Papers, Colorado State University},
+ volume={24},
+ pages={37},
+ year={1964}
+}
--
GitLab