From 3d737c29526d0e036875f88b07d1edb75c2b651c Mon Sep 17 00:00:00 2001
From: Andreas Lauser <Andreas.Lauser@iws.uni-stuttgart.de>
Date: Wed, 3 Nov 2010 13:52:57 +0000
Subject: [PATCH] handbook: Add automatically extracted model desctiptions for
 the fully coupled models

also improve the description of the richards model so that it is ready
for the handbook
---
 doc/handbook/Makefile.am                      | 10 ----------
 .../ModelDescriptions/1p2cboxmodel.tex        | 17 ++++++++++++++++
 doc/handbook/ModelDescriptions/1pboxmodel.tex |  9 +++++++++
 .../ModelDescriptions/2p2cboxmodel.tex        | 20 +++++++++++++++++++
 .../ModelDescriptions/2p2cniboxmodel.tex      | 18 +++++++++++++++++
 doc/handbook/ModelDescriptions/2pboxmodel.tex | 13 ++++++++++++
 .../ModelDescriptions/2pniboxmodel.tex        | 13 ++++++++++++
 .../ModelDescriptions/richardsboxmodel.tex    | 13 ++++++++++++
 8 files changed, 103 insertions(+), 10 deletions(-)
 create mode 100644 doc/handbook/ModelDescriptions/1p2cboxmodel.tex
 create mode 100644 doc/handbook/ModelDescriptions/1pboxmodel.tex
 create mode 100644 doc/handbook/ModelDescriptions/2p2cboxmodel.tex
 create mode 100644 doc/handbook/ModelDescriptions/2p2cniboxmodel.tex
 create mode 100644 doc/handbook/ModelDescriptions/2pboxmodel.tex
 create mode 100644 doc/handbook/ModelDescriptions/2pniboxmodel.tex
 create mode 100644 doc/handbook/ModelDescriptions/richardsboxmodel.tex

diff --git a/doc/handbook/Makefile.am b/doc/handbook/Makefile.am
index a3e431d13..2e713e712 100644
--- a/doc/handbook/Makefile.am
+++ b/doc/handbook/Makefile.am
@@ -53,16 +53,6 @@ dumux-handbook.html:  $(DOCSOURCE) dune.cfg tex4ht.env
 	$(TEX) dumux-handbook.tex
 
 dumux-handbook.pdf: 
-#	mkdir ModelDescriptions
-	cat ../doxygen/latex/classDune_1_1OnePBoxModel.tex | ../../util/scripts/extractDetailedDescription.py >ModelDescriptions/1pboxmodel.tex
-	cat ../doxygen/latex/classDune_1_1OnePTwoCBoxModel.tex | ../../util/scripts/extractDetailedDescription.py >ModelDescriptions/1p2cboxmodel.tex
-	cat ../doxygen/latex/classDune_1_1RichardsBoxModel.tex | ../../util/scripts/extractDetailedDescription.py >ModelDescriptions/richardsboxmodel.tex
-	cat ../doxygen/latex/classDune_1_1TwoPBoxModel.tex | ../../util/scripts/extractDetailedDescription.py >ModelDescriptions/2pboxmodel.tex
-	cat ../doxygen/latex/classDune_1_1TwoPNIBoxModel.tex | ../../util/scripts/extractDetailedDescription.py >ModelDescriptions/2pniboxmodel.tex
-	cat ../doxygen/latex/classDune_1_1TwoPTwoCBoxModelBase.tex | ../../util/scripts/extractDetailedDescription.py >ModelDescriptions/2p2cboxmodel.tex
-	cat ../doxygen/latex/classDune_1_1TwoPTwoCNIBoxModel.tex | ../../util/scripts/extractDetailedDescription.py >ModelDescriptions/2p2cniboxmodel.tex
-	cat ../doxygen/latex/classDune_1_1IMPES.tex | ../../util/scripts/extractDetailedDescription.py >ModelDescriptions/2pdecoupledmodel.tex
-	cat ../doxygen/latex/classDune_1_1Decoupled2p2c.tex | ../../util/scripts/extractDetailedDescription.py >ModelDescriptions/decoupled2p2c.tex
 	latex dumux-handbook.tex
 	bibtex dumux-handbook
 	latex dumux-handbook.tex
diff --git a/doc/handbook/ModelDescriptions/1p2cboxmodel.tex b/doc/handbook/ModelDescriptions/1p2cboxmodel.tex
new file mode 100644
index 000000000..73b3afc7a
--- /dev/null
+++ b/doc/handbook/ModelDescriptions/1p2cboxmodel.tex
@@ -0,0 +1,17 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% This file has been autogenerated from the LaTeX part of the   %
+% doxygen documentation; DO NOT EDIT IT! Change the model's .hh %
+% file instead!!                                                %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+Adaption of the BOX scheme to the one-\/phase two-\/component flow model. This model implements an one-\/phase flow of an incompressible fluid, that consists of two components, using a standard Darcy approach (neglecting gravitation) as the equation for the conservation of momentum: \[ v_{D} = - \frac{K}{\mu} \left(\text{grad} p - \varrho g \right) \]
+
+By inserting this into the continuity equation, one gets \[ - \text{div} \left\{ \varrho \frac{K}{\mu} \left(\text{grad} p - \varrho g \right) \right\} = q \;, \]
+
+The transport of the components is described by the following equation: \[ \Phi \varrho \frac{ \partial x}{\partial t} - \text{div} \left( \varrho \frac{K x}{\mu} \left( \text{grad} p - \varrho g \right) + \varrho \tau \Phi D \text{grad} x \right) = q. \]
+
+All equations are discretized using a fully-\/coupled vertex centered finite volume (box) scheme as spatial and the implicit Euler method as time discretization.
+
+The primary variables are the pressure $p$ and the mole fraction of dissolved component $x$.
+
diff --git a/doc/handbook/ModelDescriptions/1pboxmodel.tex b/doc/handbook/ModelDescriptions/1pboxmodel.tex
new file mode 100644
index 000000000..91b93512e
--- /dev/null
+++ b/doc/handbook/ModelDescriptions/1pboxmodel.tex
@@ -0,0 +1,9 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% This file has been autogenerated from the LaTeX part of the   %
+% doxygen documentation; DO NOT EDIT IT! Change the model's .hh %
+% file instead!!                                                %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+Adaption of the BOX scheme to the single phase isothermal flow model. Single phase compressible isothermal flow model, \begin{align*} \phi \frac{\partial \varrho}{\partial t} + \vec{\nabla} \cdot (- \varrho \frac{\bar{\bar{K}}}{\mu} ( \nabla p -\varrho \vec{g})) = q, \end{align*} discretized using a vertex centered finite volume (box) scheme as spatial and the implicit Euler method as time discretization. Of course, the model can also be used for incompressible single phase flow modeling, if in the problem file a fluid with constant density is chosen.
+
diff --git a/doc/handbook/ModelDescriptions/2p2cboxmodel.tex b/doc/handbook/ModelDescriptions/2p2cboxmodel.tex
new file mode 100644
index 000000000..e0f5bad76
--- /dev/null
+++ b/doc/handbook/ModelDescriptions/2p2cboxmodel.tex
@@ -0,0 +1,20 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% This file has been autogenerated from the LaTeX part of the   %
+% doxygen documentation; DO NOT EDIT IT! Change the model's .hh %
+% file instead!!                                                %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+Adaption of the BOX scheme to the two-\/phase two-\/component flow model. This model implements two-\/phase two-\/component flow of two compressible and partially miscible fluids $\alpha \in \{ w, n \}$ composed of the two components $\kappa \in \{ w, a \}$. The standard multiphase Darcy approach is used as the equation for the conservation of momentum: \[ v_\alpha = - \frac{k_{r\alpha}}{\mu_\alpha} K \left(\text{grad} p_\alpha - \varrho_{\alpha} \boldsymbol{g} \right) \]
+
+By inserting this into the equations for the conservation of the components, one gets one transport equation for each component \begin{eqnarray*} && \phi \frac{\partial (\sum_\alpha \varrho_\alpha X_\alpha^\kappa S_\alpha )} {\partial t} - \sum_\alpha \nabla \cdot \left\{ \varrho_\alpha X_\alpha^\kappa \frac{k_{r\alpha}}{\mu_\alpha} \mbox{\bf K} ({\bf \nabla} p_\alpha - \varrho_{\alpha} \mbox{\bf g}) \right\} \nonumber \\ \nonumber \\ &-& \sum_\alpha \nabla \cdot \left\{{\bf D_{pm}^\kappa} \varrho_{\alpha} {\bf \nabla} X^\kappa_{\alpha} \right\} - \sum_\alpha q_\alpha^\kappa = \quad 0 \qquad \kappa \in \{w, a\} \, , \alpha \in \{w, g\} \end{eqnarray*}
+
+This is discretized using a fully-\/coupled vertex centered finite volume (box) scheme as spatial and the implicit Euler method as temporal discretization.
+
+By using constitutive relations for the capillary pressure $p_c = p_n - p_w$ and relative permeability $k_{r\alpha}$ and taking advantage of the fact that $S_w + S_n = 1$ and $X^\kappa_w + X^\kappa_n = 1$, the number of unknowns can be reduced to two. The used primary variables are, like in the two-\/phase model, either $p_w$ and $S_n$ or $p_n$ and $S_w$. The formulation which ought to be used can be specified by setting the {\ttfamily Formulation} property to either TwoPTwoCIndices::pWsN or TwoPTwoCIndices::pNsW. By default, the model uses $p_w$ and $S_n$. Moreover, the second primary variable depends on the phase state, since a primary variable switch is included. The phase state is stored for all nodes of the system. Following cases can be distinguished:
+\begin{itemize}
+\item Both phases are present: The saturation is used (either $S_n$ or $S_w$, dependent on the chosen {\ttfamily Formulation}), as long as $ 0 < S_\alpha < 1$.
+\item Only wetting phase is present: The mass fraction of, e.g., air in the wetting phase $X^a_w$ is used, as long as the maximum mass fraction is not exceeded ($X^a_w<X^a_{w,max}$)
+\item Only non-\/wetting phase is present: The mass fraction of, e.g., water in the non-\/wetting phase, $X^w_n$, is used, as long as the maximum mass fraction is not exceeded ($X^w_n<X^w_{n,max}$)
+\end{itemize}
+
diff --git a/doc/handbook/ModelDescriptions/2p2cniboxmodel.tex b/doc/handbook/ModelDescriptions/2p2cniboxmodel.tex
new file mode 100644
index 000000000..c86e44dfa
--- /dev/null
+++ b/doc/handbook/ModelDescriptions/2p2cniboxmodel.tex
@@ -0,0 +1,18 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% This file has been autogenerated from the LaTeX part of the   %
+% doxygen documentation; DO NOT EDIT IT! Change the model's .hh %
+% file instead!!                                                %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+Adaption of the BOX scheme to the non-\/isothermal two-\/phase two-\/component flow model. This model implements a non-\/isothermal two-\/phase flow of two compressible and partly miscible fluids $\alpha \in \{ w, n \}$. Thus each component $\kappa \{ w, a \}$ can be present in each phase. Using the standard multiphase Darcy approach a mass balance equation is solved: \begin{eqnarray*} && \phi \frac{\partial (\sum_\alpha \varrho_\alpha X_\alpha^\kappa S_\alpha )}{\partial t} - \sum_\alpha \text{div} \left\{ \varrho_\alpha X_\alpha^\kappa \frac{k_{r\alpha}}{\mu_\alpha} \mbox{\bf K} (\text{grad} p_\alpha - \varrho_{\alpha} \mbox{\bf g}) \right\}\\ &-& \sum_\alpha \text{div} \left\{{\bf D_{\alpha, pm}^\kappa} \varrho_{\alpha} \text{grad} X^\kappa_{\alpha} \right\} - \sum_\alpha q_\alpha^\kappa = \quad 0 \qquad \kappa \in \{w, a\} \, , \alpha \in \{w, n\} \end{eqnarray*} For the energy balance, local thermal equilibrium is assumed which results in one energy conservation equation for the porous solid matrix and the fluids: \begin{eqnarray*} && \phi \frac{\partial \left( \sum_\alpha \varrho_\alpha u_\alpha S_\alpha \right)}{\partial t} + \left( 1 - \phi \right) \frac{\partial (\varrho_s c_s T)}{\partial t} - \sum_\alpha \text{div} \left\{ \varrho_\alpha h_\alpha \frac{k_{r\alpha}}{\mu_\alpha} \mathbf{K} \left( \text{grad}\: p_\alpha - \varrho_\alpha \mathbf{g} \right) \right\} \\ &-& \text{div} \left( \lambda_{pm} \text{grad} \: T \right) - q^h \qquad = \quad 0 \qquad \alpha \in \{w, n\} \end{eqnarray*}
+
+This is discretized using a fully-\/coupled vertex centered finite volume (box) scheme as spatial and the implicit Euler method as temporal discretization.
+
+By using constitutive relations for the capillary pressure $p_c = p_n - p_w$ and relative permeability $k_{r\alpha}$ and taking advantage of the fact that $S_w + S_n = 1$ and $X^\kappa_w + X^\kappa_n = 1$, the number of unknowns can be reduced to two. If both phases are present the primary variables are, like in the nonisothermal two-\/phase model, either $p_w$, $S_n$ and temperature or $p_n$, $S_w$ and temperature. The formulation which ought to be used can be specified by setting the {\ttfamily Formulation} property to either {\ttfamily TwoPTwoIndices::pWsN} or {\ttfamily TwoPTwoCIndices::pNsW}. By default, the model uses $p_w$ and $S_n$. In case that only one phase (nonwetting or wetting phase) is present the second primary variable represents a mass fraction. The correct assignment of the second primary variable is performed by a phase state dependent primary variable switch. The phase state is stored for all nodes of the system. The following cases can be distinguished:
+\begin{itemize}
+\item Both phases are present: The saturation is used (either$S_n$ or $S_w$, dependent on the chosen formulation).
+\item Only wetting phase is present: The mass fraction of air in the wetting phase $X^a_w$ is used.
+\item Only non-\/wetting phase is present: The mass fraction of water in the non-\/wetting phase, $X^w_n$, is used.
+\end{itemize}
+
diff --git a/doc/handbook/ModelDescriptions/2pboxmodel.tex b/doc/handbook/ModelDescriptions/2pboxmodel.tex
new file mode 100644
index 000000000..e7256ef01
--- /dev/null
+++ b/doc/handbook/ModelDescriptions/2pboxmodel.tex
@@ -0,0 +1,13 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% This file has been autogenerated from the LaTeX part of the   %
+% doxygen documentation; DO NOT EDIT IT! Change the model's .hh %
+% file instead!!                                                %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+Adaption of the BOX scheme to the twophase flow model. This model implements two-\/phase flow of two completely immiscible fluids $\alpha \in \{ w, n \}$ using a standard multiphase Darcy approach as the equation for the conservation of momentum: \[ v_\alpha = - \frac{k_{r\alpha}}{\mu_\alpha} K \left(\text{grad} p_\alpha - \varrho_{\alpha} \boldsymbol{g} \right) \]
+
+By inserting this into the equation for the conservation of the phase mass, one gets \[ \phi \frac{\partial \varrho_\alpha S_\alpha}{\partial t} - \text{div} \left\{ \varrho_\alpha \frac{k_{r\alpha}}{\mu_\alpha} K \left(\text{grad} p_\alpha - \varrho_{\alpha} \boldsymbol{g} \right) \right\} = q_\alpha \;, \] discretized by a fully-\/coupled vertex centered finite volume (box) scheme as spatial and the implicit Euler method as time discretization.
+
+By using constitutive relations for the capillary pressure $p_c = p_n - p_w$ and relative permeability $k_{r\alpha}$ and taking advantage of the fact that $S_w + S_n = 1$, the number of unknowns can be reduced to two. Currently the model supports choosing either $p_w$ and $S_n$ or $p_n$ and $S_w$ as primary variables. The formulation which ought to be used can be specified by setting the {\ttfamily Formulation} property to either {\ttfamily TwoPCommonIndices::pWsN} or {\ttfamily TwoPCommonIndices::pNsW}. By default, the model uses $p_w$ and $S_n$.
+
diff --git a/doc/handbook/ModelDescriptions/2pniboxmodel.tex b/doc/handbook/ModelDescriptions/2pniboxmodel.tex
new file mode 100644
index 000000000..ab80ee9a0
--- /dev/null
+++ b/doc/handbook/ModelDescriptions/2pniboxmodel.tex
@@ -0,0 +1,13 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% This file has been autogenerated from the LaTeX part of the   %
+% doxygen documentation; DO NOT EDIT IT! Change the model's .hh %
+% file instead!!                                                %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+Adaption of the BOX scheme to the non-\/isothermal twophase flow model. This model implements a non-\/isothermal two-\/phase flow of two completely immiscible fluids $\alpha \in \{ w, n \}$. Using the standard multiphase Darcy approach, the mass conservation equations for both phases can be described as follows: \begin{eqnarray*} && \phi \frac{\partial (\varrho_\alpha S_\alpha )}{\partial t} - \text{div} \left\{ \varrho_\alpha \frac{k_{r\alpha}}{\mu_\alpha} \mbox{\bf K} (\text{grad} p_\alpha - \varrho_{\alpha} \mbox{\bf g}) \right\} - q_\alpha^\kappa = \quad 0 \qquad \alpha \in \{w, n\} \end{eqnarray*} For the energy balance, local thermal equilibrium is assumed which results in one energy conservation equation for the porous solid matrix and the fluids: \begin{eqnarray*} && \phi \frac{\partial \left( \sum_\alpha \varrho_\alpha u_\alpha S_\alpha \right)}{\partial t} + \left( 1 - \phi \right) \frac{\partial (\varrho_s c_s T)}{\partial t} - \sum_\alpha \text{div} \left\{ \varrho_\alpha h_\alpha \frac{k_{r\alpha}}{\mu_\alpha} \mathbf{K} \left( \text{grad} \: p_\alpha - \varrho_\alpha \mathbf{g} \right) \right\} \\ &-& \text{div} \left( \lambda_{pm} \text{grad} \: T \right) - q^h \qquad = \quad 0, \qquad \alpha \in \{w, n\}. \end{eqnarray*}
+
+The equations are discretized using a fully-\/coupled vertex centered finite volume (box) scheme as spatial and the implicit Euler method as time discretization.
+
+Currently the model supports choosing either $p_w$, $S_n$ and $T$ or $p_n$, $S_w$ and $T$ as primary variables. The formulation which ought to be used can be specified by setting the {\ttfamily Formulation} property to either {\ttfamily TwoPNIIndices::pWsN} or {\ttfamily TwoPIndices::pNsW}. By default, the model uses $p_w$, $S_n$ and $T$.
+
diff --git a/doc/handbook/ModelDescriptions/richardsboxmodel.tex b/doc/handbook/ModelDescriptions/richardsboxmodel.tex
new file mode 100644
index 000000000..836705751
--- /dev/null
+++ b/doc/handbook/ModelDescriptions/richardsboxmodel.tex
@@ -0,0 +1,13 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% This file has been autogenerated from the LaTeX part of the   %
+% doxygen documentation; DO NOT EDIT IT! Change the model's .hh %
+% file instead!!                                                %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+This model implements a variant of the Richards equation for quasi-\/twophase flow. In the unsaturated zone, Richards' equation is frequently used to calculate the water distribution above the groundwater level. It can be derived from the twophase equations, i.e. \[ \frac{\partial\;\phi S_\alpha \rho_\alpha}{\partial t} - \mathbf{div} \left\{ \frac{k_{r\alpha}}{\mu_\alpha}\;K \mathbf{grad}\left[ p_\alpha - g\rho_\alpha \right] \right\} = q_\alpha, \] where $\alpha \in \{w, n\}$ is the fluid phase, $\rho_\alpha$ is the fluid density, $S_\alpha$ is the fluid saturation, $\phi$ is the porosity of the soil, $k_{r\alpha}$ is the relative permeability for the fluid, $\mu_\alpha$ is the fluid's dynamic viscosity, $K$ is the intrinsic permeability, $p_\alpha$ is the fluid pressure and $g$ is the potential of the gravity field.
+
+In contrast to the full twophase model, the Richards model assumes gas as the non-\/wetting fluid and that it exhibits a much lower viscosity than the (liquid) wetting phase. (For example at atmospheric pressure and at room temperature, the viscosity of air is only about $1\%$ of the viscosity of liquid water.) As a consequence, the $\frac{k_{r\alpha}}{\mu_\alpha}$ term typically is much larger for the gas phase than for the wetting phase. For this reason, the Richards model assumes that $\frac{k_{rn}}{\mu_n}$ tends to infinity. This implies that the pressure of the gas phase is equivalent to a static pressure and can thus be specified externally and that therefore, mass conservation only needs to be considered for the wetting phase.
+
+The model thus choses the absolute pressure of the wetting phase $p_w$ as its only primary variable. The wetting phase saturation is calculated using the inverse of the capillary pressure, i.e. \[ S_w = p_c^{-1}(p_n - p_w) \] holds, where $p_n$ is a given reference pressure. Nota bene that the last step is assumes that the capillary pressure-\/saturation curve can be inverted uniquely, so it is not possible to set the capillary pressure to zero when using the Richards model!
+