From c89340fd14ab13a76d288a3fc9228edca7d458ec Mon Sep 17 00:00:00 2001
From: Andreas Lauser <and@poware.org>
Date: Wed, 22 Feb 2012 10:07:10 +0000
Subject: [PATCH] documentation: update model descriptions for 1p, 2p, 2pni,
richards and Mp-Nc models
git-svn-id: svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk@7854 2fb0f335-1f38-0410-981e-8018bf24f1b0
---
README | 12 ++--
doc/handbook/models.tex | 7 ++-
dumux/boxmodels/1p/1pmodel.hh | 18 +++---
dumux/boxmodels/2p/2pmodel.hh | 17 +++---
dumux/boxmodels/2pni/2pnimodel.hh | 72 ++++++++++++++---------
dumux/boxmodels/mpnc/mpncmodel.hh | 36 ++++++------
dumux/boxmodels/richards/richardsmodel.hh | 33 ++++++-----
7 files changed, 110 insertions(+), 85 deletions(-)
diff --git a/README b/README
index 0bbc291930..b4737e1bb1 100644
--- a/README
+++ b/README
@@ -30,12 +30,12 @@ Public License (GPL) version 2 or - at your option - any later
version. The GPL can be read online [3], or in the LICENSE file
provided in the topmost directory of the DuMuX source code tree.
-Please note that DuMuX is - unlike DUNE - NOT licensed under the
-Lesser General Public License with a template exception. This means
-that you must publish any source code which uses any of the DuMuX
-header files if you want to redistribute your program to any third
-parties. If this is unacceptable to you, please contact us [4, 5]
-for a commercial license.
+Please note that DuMuX's license, unlike DUNE, does NOT feature a
+template exception to the GNU General Public License. This means that
+you must publish any source code which uses any of the DuMuX header
+files if you want to redistribute your program to third parties. If
+this is unacceptable to you, please contact us [4, 5] for a commercial
+license.
Links
diff --git a/doc/handbook/models.tex b/doc/handbook/models.tex
index a16f19f4b9..d1851d6962 100644
--- a/doc/handbook/models.tex
+++ b/doc/handbook/models.tex
@@ -150,7 +150,12 @@ The following description of the available models is automatically extracted
from the Doxygen documentation.
% \textbf{TODO}: Unify notation.
-\subsection{Fully coupled models}
+\subsection{Fully-implicit models}
+
+The fully-implicit models described in this section are using the box
+scheme as described in~\ref{box} for spatial and the implicit euler
+method as temporal discretization. The models itself are located in
+subdirectories of \texttt{dumux/boxmodels} of the \Dumux distribution.
\subsubsection{The single-phase model: OnePBoxModel}
\input{ModelDescriptions/1pboxmodel}
diff --git a/dumux/boxmodels/1p/1pmodel.hh b/dumux/boxmodels/1p/1pmodel.hh
index 67f0745c7c..5634957c24 100644
--- a/dumux/boxmodels/1p/1pmodel.hh
+++ b/dumux/boxmodels/1p/1pmodel.hh
@@ -40,16 +40,16 @@ namespace Dumux
{
/*!
* \ingroup OnePBoxModel
- * \brief Adaption of the BOX scheme to the single-phase isothermal flow model.
+ * \brief A single-phase, isothermal flow model using the box scheme.
*
- * Single-phase compressible isothermal flow model,
- * \f{align*}
- * \phi \frac{\partial \varrho}{\partial t} + \text{div} (- \varrho \frac{\textbf K}{\mu} ( \text{grad}\, p -\varrho {\textbf g})) = q,
- * \f}
- * 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 a fluid with constant density is chosen in the problem file.
+ * Single-phase, isothermal flow model, which solves the mass
+ * continuity equation
+ * \f[
+ \phi \frac{\partial \varrho}{\partial t} + \text{div} (- \varrho \frac{\textbf K}{\mu} ( \textbf{grad}\, p -\varrho {\textbf g})) = q,
+ * \f]
+ * discretized using a vertex-centered finite volume (box) scheme as
+ * spatial and the implicit Euler method as time discretization. The
+ * model supports compressible as well as incompressible fluids.
*/
template<class TypeTag >
class OnePBoxModel : public BoxModel<TypeTag>
diff --git a/dumux/boxmodels/2p/2pmodel.hh b/dumux/boxmodels/2p/2pmodel.hh
index 82f88311a8..94b157a6f3 100644
--- a/dumux/boxmodels/2p/2pmodel.hh
+++ b/dumux/boxmodels/2p/2pmodel.hh
@@ -39,14 +39,14 @@ namespace Dumux
/*!
* \ingroup TwoPBoxModel
- * \brief Adaption of the BOX scheme to the twophase flow model.
+ * \brief A two-phase, isothermal flow model using the box scheme.
*
- * This model implements two-phase flow of two completely immiscible fluids
+ * This model implements two-phase flow of two immiscible fluids
* \f$\alpha \in \{ w, n \}\f$ using a standard multiphase Darcy
- * approach as the equation for the conservation of momentum:
+ * approach as the equation for the conservation of momentum, i.e.
\f[
v_\alpha = - \frac{k_{r\alpha}}{\mu_\alpha} \textbf{K}
- \left(\text{grad}\, p_\alpha - \varrho_{\alpha} {\textbf g} \right)
+ \left(\textbf{grad}\, p_\alpha - \varrho_{\alpha} {\textbf g} \right)
\f]
*
* By inserting this into the equation for the conservation of the
@@ -55,12 +55,13 @@ namespace Dumux
\phi \frac{\partial \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)
+ \varrho_\alpha \frac{k_{r\alpha}}{\mu_\alpha} \mbox{\bf K} \left(\textbf{grad}\, p_\alpha - \varrho_{\alpha} \mbox{\bf g} \right)
\right\} - q_\alpha = 0 \;,
\f]
- * discretized by a fully-coupled vertex
- * centered finite volume (box) scheme as spatial and
- * the implicit Euler method as time discretization.
+ *
+ * This equations are 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 \f$p_c =
* p_n - p_w\f$ and relative permeability \f$k_{r\alpha}\f$ and taking
diff --git a/dumux/boxmodels/2pni/2pnimodel.hh b/dumux/boxmodels/2pni/2pnimodel.hh
index 22233737f0..b45f6bf12c 100644
--- a/dumux/boxmodels/2pni/2pnimodel.hh
+++ b/dumux/boxmodels/2pni/2pnimodel.hh
@@ -34,38 +34,56 @@ namespace Dumux {
/*!
* \ingroup TwoPNIBoxModel
- * \brief Adaption of the BOX scheme to the non-isothermal twophase flow model.
+ * \brief A two-phase, non-isothermal flow model using the box scheme.
+ *
+ * This model implements a non-isothermal two-phase flow for two
+ * immiscible fluids \f$\alpha \in \{ w, n \}\f$. Using the standard
+ * multiphase Darcy approach, the mass conservation equations for both
+ * phases can be described as follows:
+ * \f[
+ \phi \frac{\partial \phi \varrho_\alpha S_\alpha}{\partial t}
+ -
+ \text{div}
+ \left\{
+ \varrho_\alpha \frac{k_{r\alpha}}{\mu_\alpha} \mathrm{K}
+ \left( \textrm{grad}\, p_\alpha - \varrho_{\alpha} \mathbf{g} \right)
+ \right\}
+ -
+ q_\alpha = 0 \qquad \alpha \in \{w, n\}
+ \f]
*
- * This model implements a non-isothermal two-phase flow of two completely immiscible fluids
- * \f$\alpha \in \{ w, n \}\f$.
- * Using the standard multiphase Darcy approach, the mass conservation equations for both phases can
- * be described as follows:
- * \f{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 = 0 \qquad \alpha \in \{w, n\}
- * \f}
- * For the energy balance, local thermal equilibrium is assumed which results in one
- * energy conservation equation for the porous solid matrix and the fluids:
- * \f{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} \mbox{\bf K} \left( \text{grad} \, p_\alpha
- - \varrho_\alpha \mbox{\bf g} \right) \right\} \\
- &-& \text{div} \left( \lambda_{pm} \text{grad} \, T \right)
- - q^h = 0, \qquad \alpha \in \{w, n\}.
+ * For the energy balance, local thermal equilibrium is assumed. This
+ * results in one energy conservation equation for the porous solid
+ * matrix and the fluids:
+
+ \f{eqnarray*}
+ \frac{\partial \phi \sum_alpha \varrho_\alpha u_\alpha S_\alpha}{\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( \textbf{grad}\,p_\alpha - \varrho_\alpha \mbox{\bf g} \right)
+ \right\} \ \
+ & - \text{div} \left(\lambda_{pm} \textbf{grad} \, T \right)
+ - q^h = 0, \qquad \alpha \in \{w, n\} \;,
\f}
+ * where \f$h_\alpha\f$ is the specific enthalpy of a fluid phase
+ * \f$\alpha\f$ and \f$u_\alpha = h_\alpha -
+ * p_\alpha/\varrho_\alpha\f$ is the specific internal energy of the
+ * phase.
*
- * The equations are discretized using a fully-coupled vertex
- * centered finite volume (box) scheme as spatial and the implicit Euler method
+ * 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 \f$p_w\f$, \f$S_n\f$ and \f$T\f$ or \f$p_n\f$,
- * \f$S_w\f$ and \f$T\f$ as primary variables. The formulation which ought to be used can be
- * specified by setting the <tt>Formulation</tt> property to either <tt>TwoPNIIndices::pWsN</tt> or <tt>TwoPIndices::pNsW</tt>. By
+ * Currently the model supports choosing either \f$p_w\f$, \f$S_n\f$
+ * and \f$T\f$ or \f$p_n\f$, \f$S_w\f$ and \f$T\f$ as primary
+ * variables. The formulation which ought to be used can be specified
+ * by setting the <tt>Formulation</tt> property to either
+ * <tt>TwoPNIIndices::pWsN</tt> or <tt>TwoPIndices::pNsW</tt>. By
* default, the model uses \f$p_w\f$, \f$S_n\f$ and \f$T\f$.
*/
template<class TypeTag>
diff --git a/dumux/boxmodels/mpnc/mpncmodel.hh b/dumux/boxmodels/mpnc/mpncmodel.hh
index 2eaa053944..20be9020ea 100644
--- a/dumux/boxmodels/mpnc/mpncmodel.hh
+++ b/dumux/boxmodels/mpnc/mpncmodel.hh
@@ -32,7 +32,8 @@ namespace Dumux
{
/*!
* \ingroup MPNCModel
- * \brief A vertex centered fully implicit model for M-phase, N-component flow
+ * \brief A fully implicit model for M-phase, N-component flow using
+ * vertex centered finite volumes.
*
* This model implements a \f$M\f$-phase flow of a fluid mixture
* composed of \f$N\f$ chemical species. The phases are denoted by
@@ -50,7 +51,8 @@ namespace Dumux
\f]
*
* By inserting this into the equations for the conservation of the
- * components, one gets one transport equation for each component \f$\kappa\f$
+ * mass of each component, one gets one mass-continuity equation for
+ * each component \f$\kappa\f$
* \f[
\sum_{\kappa} \left(
\phi \frac{\partial \varrho_\alpha x_\alpha^\kappa S_\alpha}{\partial t}
@@ -64,34 +66,36 @@ namespace Dumux
\right)
= q^\kappa
\f]
- * with \f$\overline M_\alpha\f$ being the average molar mass of the phase \f$\alpha\f$:
- * \f[ \overline M_\alpha = \sum_\kappa M^\kappa \; x_\alpha^\kappa \f]
+ * with \f$\overline M_\alpha\f$ being the average molar mass of the
+ * phase \f$\alpha\f$: \f[ \overline M_\alpha = \sum_\kappa M^\kappa
+ * \; x_\alpha^\kappa \f]
*
* For the missing \f$M\f$ model assumptions, the model assumes that
* if a fluid phase is not present, the sum of the mole fractions of
- * this fluid phase is smaller than \f$1\f$, i.e.
- * \f[ \forall \alpha: S_\alpha = 0 \implies \sum_\kappa x_\alpha^\kappa \leq 1 \f]
+ * this fluid phase is smaller than \f$1\f$, i.e.
+ * \f[
+ * \forall \alpha: S_\alpha = 0 \implies \sum_\kappa x_\alpha^\kappa \leq 1
+ * \f]
*
* Also, if a fluid phase may be present at a given spatial location
* its saturation must be positive:
* \f[ \forall \alpha: \sum_\kappa x_\alpha^\kappa = 1 \implies S_\alpha \geq 0 \f]
*
* Since at any given spatial location, a phase is always either
- * present or not present, the one of the strict equallities on the
+ * present or not present, the one of the strict equalities on the
* right hand side is always true, i.e.
* \f[ \forall \alpha: S_\alpha \left( \sum_\kappa x_\alpha^\kappa - 1 \right) = 0 \f]
* always holds.
*
* These three equations constitute a non-linear complementarity
- * problem, which can be solved using a so-called non-linear
- * complementarity function \f$\Phi(a, b)\f$ which has the property
+ * problem, which can be solved using so-called non-linear
+ * complementarity functions \f$\Phi(a, b)\f$ which have the property
* \f[\Phi(a,b) = 0 \iff a \geq0 \land b \geq0 \land a \cdot b = 0 \f]
*
* Several non-linear complementarity functions have been suggested,
* e.g. the Fischer-Burmeister function
* \f[ \Phi(a,b) = a + b - \sqrt{a^2 + b^2} \;. \f]
- *
- * Though this model uses
+ * This model uses
* \f[ \Phi(a,b) = \min \{a, b \}\;, \f]
* because of its piecewise linearity.
*
@@ -100,9 +104,9 @@ namespace Dumux
* spatial discretization and the implicit Euler method as temporal
* discretization.
*
- * The model assumes thermodynamic equilibrium and uses the following
- * primary variables:
- * - The componentfugacities \f$f^1, \dots, f^{N}\f$
+ * The model assumes local thermodynamic equilibrium and uses the
+ * following primary variables:
+ * - The component fugacities \f$f^1, \dots, f^{N}\f$
* - The pressure of the first phase \f$p_1\f$
* - The saturations of the first \f$M-1\f$ phases \f$S_1, \dots, S_{M-1}\f$
* - Temperature \f$T\f$ if the energy equation is enabled
@@ -118,14 +122,10 @@ class MPNCModel : public BoxModel<TypeTag>
typedef typename GridView::template Codim<0>::Iterator ElementIterator;
typedef typename GET_PROP_TYPE(TypeTag, PrimaryVariables) PrimaryVariables;
-
-
typedef typename GET_PROP_TYPE(TypeTag, SolutionVector) SolutionVector;
-
typedef Dumux::MPNCVtkWriter<TypeTag> MPNCVtkWriter;
-
enum {
enableEnergy = GET_PROP_VALUE(TypeTag, EnableEnergy),
enableDiffusion = GET_PROP_VALUE(TypeTag, EnableDiffusion),
diff --git a/dumux/boxmodels/richards/richardsmodel.hh b/dumux/boxmodels/richards/richardsmodel.hh
index e31c2f9245..e5e497701f 100644
--- a/dumux/boxmodels/richards/richardsmodel.hh
+++ b/dumux/boxmodels/richards/richardsmodel.hh
@@ -39,18 +39,18 @@ namespace Dumux
/*!
* \ingroup RichardsModel
*
- * \brief This model implements a variant of the Richards equation for
- * quasi-twophase flow.
+ * \brief This model which 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.
+ * approximate the water distribution above the groundwater level. It
+ * can be derived from the two-phase equations, i.e.
\f[
\frac{\partial\;\phi S_\alpha \rho_\alpha}{\partial t}
-
\text{div} \left\{
- \rho_\alpha \frac{k_{r\alpha}}{\mu_\alpha}\; {\textbf K}
- \text{grad}\left[
+ \rho_\alpha \frac{k_{r\alpha}}{\mu_\alpha}\; \mathbf{K}
+ \textbf{grad}\left[
p_\alpha - g\rho_\alpha
\right]
\right\}
@@ -61,11 +61,11 @@ namespace Dumux
* \f$\rho_\alpha\f$ is the fluid density, \f$S_\alpha\f$ is the fluid
* saturation, \f$\phi\f$ is the porosity of the soil,
* \f$k_{r\alpha}\f$ is the relative permeability for the fluid,
- * \f$\mu_\alpha\f$ is the fluid's dynamic viscosity, \f$K\f$ is the
+ * \f$\mu_\alpha\f$ is the fluid's dynamic viscosity, \f$\mathbf{K}\f$ is the
* intrinsic permeability, \f$p_\alpha\f$ is the fluid pressure and
* \f$g\f$ is the potential of the gravity field.
*
- * In contrast to the full twophase model, the Richards model assumes
+ * In contrast to the full two-phase 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
@@ -73,10 +73,10 @@ namespace Dumux
* consequence, the \f$\frac{k_{r\alpha}}{\mu_\alpha}\f$ term
* typically is much larger for the gas phase than for the wetting
* phase. For this reason, the Richards model assumes that
- * \f$\frac{k_{rn}}{\mu_n}\f$ 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.
+ * \f$\frac{k_{rn}}{\mu_n}\f$ is infinitly large. This implies that
+ * the pressure of the gas phase is equivalent to the static pressure
+ * distribution 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
* \f$p_w\f$ as its only primary variable. The wetting phase
@@ -85,10 +85,11 @@ namespace Dumux
\f[
S_w = p_c^{-1}(p_n - p_w)
\f]
- * holds, where \f$p_n\f$ 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!
+ * holds, where \f$p_n\f$ is a given reference pressure. Nota bene,
+ * that the last step is assumes that the capillary
+ * pressure-saturation curve can be uniquely inverted, so it is not
+ * possible to set the capillary pressure to zero when using the
+ * Richards model!
*/
template<class TypeTag >
class RichardsModel : public BoxModel<TypeTag>
--
GitLab