From 332171ba863aa8e62db82e7b493e18a9e019b303 Mon Sep 17 00:00:00 2001
From: Melanie Lipp <melaniel@darth.iws.uni-stuttgart.de>
Date: Tue, 19 Dec 2017 14:05:05 +0100
Subject: [PATCH] [docu] Changes in the documentation of richards, richardsnc
and tracer.
---
dumux/porousmediumflow/richards/indices.hh | 10 ++---
.../richards/volumevariables.hh | 3 ++
dumux/porousmediumflow/richardsnc/indices.hh | 14 +++----
dumux/porousmediumflow/richardsnc/model.hh | 41 +++++++++++++++++++
dumux/porousmediumflow/tracer/indices.hh | 14 ++++---
.../porousmediumflow/tracer/localresidual.hh | 33 +++++++++++----
.../tracer/volumevariables.hh | 28 ++++++++++++-
.../tracer/vtkoutputfields.hh | 7 ++--
8 files changed, 120 insertions(+), 30 deletions(-)
diff --git a/dumux/porousmediumflow/richards/indices.hh b/dumux/porousmediumflow/richards/indices.hh
index 62706a9acf..0bd2cb78ed 100644
--- a/dumux/porousmediumflow/richards/indices.hh
+++ b/dumux/porousmediumflow/richards/indices.hh
@@ -52,13 +52,13 @@ struct RichardsIndices
//////////
// phase indices
//////////
- static constexpr int wPhaseIdx = 0; //! Index of the wetting phase;
- static constexpr int nPhaseIdx = 1; //! Index of the non-wetting phase;
+ static constexpr int wPhaseIdx = 0; //!< Index of the wetting phase;
+ static constexpr int nPhaseIdx = 1; //!< Index of the non-wetting phase;
// present phases (-> 'pseudo' primary variable)
- static constexpr int wPhaseOnly = 1; //! Only the non-wetting phase is present
- static constexpr int nPhaseOnly = 2; //! Only the wetting phase is present
- static constexpr int bothPhases = 3; //! Both phases are present
+ static constexpr int wPhaseOnly = 1; //!< Only the non-wetting phase is present
+ static constexpr int nPhaseOnly = 2; //!< Only the wetting phase is present
+ static constexpr int bothPhases = 3; //!< Both phases are present
};
// \}
diff --git a/dumux/porousmediumflow/richards/volumevariables.hh b/dumux/porousmediumflow/richards/volumevariables.hh
index 81caad7b40..6befa8e4be 100644
--- a/dumux/porousmediumflow/richards/volumevariables.hh
+++ b/dumux/porousmediumflow/richards/volumevariables.hh
@@ -413,6 +413,9 @@ public:
/*!
* \brief Returns the binary diffusion coefficients for a phase in \f$[m^2/s]\f$.
+ *
+ * \param phaseIdx TODO docme!
+ * \param compIdx TODO docme!
*/
Scalar diffusionCoefficient(int phaseIdx, int compIdx) const
{
diff --git a/dumux/porousmediumflow/richardsnc/indices.hh b/dumux/porousmediumflow/richardsnc/indices.hh
index b36c1bb1c7..fd9f255d74 100644
--- a/dumux/porousmediumflow/richardsnc/indices.hh
+++ b/dumux/porousmediumflow/richardsnc/indices.hh
@@ -38,21 +38,21 @@ template <class TypeTag, int PVOffset = 0>
struct RichardsNCIndices
{
- //!< Set the index of the phases for accessing the volvars
+ //! Set the index of the phases for accessing the volvars
static const int wPhaseIdx = 0;
static const int nPhaseIdx = 1;
- //!< Component indices
- static const int compMainIdx = PVOffset + 0; //! main component index
+ //! Component indices
+ static const int compMainIdx = PVOffset + 0; //!< main component index
- //!< primary variable indices
- static const int pressureIdx = PVOffset + 0; //! pressure
+ //! primary variable indices
+ static const int pressureIdx = PVOffset + 0; //!< pressure
//! \note These indices make sense if the first balance is replaced by the
//! total mass balance.
- //!< Equation indices
- static const int conti0EqIdx = PVOffset + 0; //! continuity equation index
+ //! Equation indices
+ static const int conti0EqIdx = PVOffset + 0; //!< continuity equation index
};
// \}
diff --git a/dumux/porousmediumflow/richardsnc/model.hh b/dumux/porousmediumflow/richardsnc/model.hh
index 807ed13c2e..ad3eaf17a7 100644
--- a/dumux/porousmediumflow/richardsnc/model.hh
+++ b/dumux/porousmediumflow/richardsnc/model.hh
@@ -21,6 +21,47 @@
* \ingroup RichardsNCModel
* \brief Base class for all models which use the Richards,
* n-component fully implicit model.
+ *
+ * In the unsaturated zone, Richards' equation
+ *\f{eqnarray}
+ && \frac{\partial (\sum_w \varrho_w X_w^\kappa \phi S_w )}
+ {\partial t}
+ - \sum_w \text{div} \left\{ \varrho_w X_w^\kappa
+ \frac{k_{rw}}{\mu_w} \mbox{\bf K}
+ (\text{grad}\, p_w - \varrho_{w} \mbox{\bf g}) \right\}
+ \nonumber \\ \nonumber \\
+ &-& \sum_w \text{div} \left\{{\bf D_{w, pm}^\kappa} \varrho_{w} \text{grad}\, X^\kappa_{w} \right\}
+ - \sum_w q_w^\kappa = 0 \qquad \kappa \in \{w, a,\cdots \} \, ,
+ w \in \{w, g\}
+ \f}
+ * is frequently used to
+ * approximate the water distribution above the groundwater level.
+ *
+ * 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
+ * is only about \f$1\%\f$ of the viscosity of liquid water.) As a
+ * 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$ 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
+ * saturation is calculated using the inverse of the capillary
+ * pressure, i.e.
+ \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 uniquely inverted, so it is not
+ * possible to set the capillary pressure to zero when using the
+ * Richards model!
*/
#ifndef DUMUX_RICHARDSNC_MODEL_HH
diff --git a/dumux/porousmediumflow/tracer/indices.hh b/dumux/porousmediumflow/tracer/indices.hh
index 54d632ab1b..dbfe144747 100644
--- a/dumux/porousmediumflow/tracer/indices.hh
+++ b/dumux/porousmediumflow/tracer/indices.hh
@@ -18,7 +18,8 @@
*****************************************************************************/
/*!
* \file
- * \brief Defines the primary variable and equation indices used by tracer model
+ * \ingroup TracerModel
+ * \brief Defines the primary variable and equation indices used by the isothermal tracer model.
*/
#ifndef DUMUX_TRACER_INDICES_HH
@@ -30,15 +31,16 @@ namespace Dumux
/*!
* \ingroup TracerModel
- * \ingroup ImplicitIndices
- * \brief The indices for the isothermal tracer model.
+ * \brief Defines the primary variable and equation indices used by the isothermal tracer model.
*/
template <class TypeTag, int PVOffset = 0>
struct TracerIndices
{
- //! Component indices are just numbered by component index
- //! primary variable indices are just numbered by component index
- //! Equation indices
+ /*!
+ * Component indices are just numbered by component index
+ * primary variable indices are just numbered by component index
+ * Equation indices
+ */
static const int transportEqIdx = PVOffset + 0; //!< transport equation index
};
diff --git a/dumux/porousmediumflow/tracer/localresidual.hh b/dumux/porousmediumflow/tracer/localresidual.hh
index 63317e49d3..b416b43d37 100644
--- a/dumux/porousmediumflow/tracer/localresidual.hh
+++ b/dumux/porousmediumflow/tracer/localresidual.hh
@@ -18,7 +18,7 @@
*****************************************************************************/
/*!
* \file
- *
+ * \ingroup TracerModel
* \brief Element-wise calculation of the local residual for problems
* using fully implicit tracer model.
*/
@@ -31,8 +31,7 @@ namespace Dumux
{
/*!
- * \ingroup Implicit
- * \ingroup TracerLocalResidual
+ * \ingroup TracerModel
* \brief Element-wise calculation of the local residual for problems
* using fully implicit tracer model.
*
@@ -72,9 +71,9 @@ public:
* The result should be averaged over the volume (e.g. phase mass
* inside a sub control volume divided by the volume)
*
- * \param scv The sub control volume
- * \param volVars The primary and secondary varaibles on the scv
- * \param useMoles If mole or mass fractions are used
+ * \param problem TODO docme!
+ * \param scv The sub control volume
+ * \param volVars The primary and secondary varaibles on the scv
*/
PrimaryVariables computeStorage(const Problem& problem,
const SubControlVolume& scv,
@@ -106,12 +105,12 @@ public:
* \brief Evaluates the total flux of all conservation quantities
* over a face of a sub-control volume.
*
+ * \param problem TODO docme!
* \param element The element
* \param fvGeometry The finite volume geometry context
* \param elemVolVars The volume variables for all flux stencil elements
* \param scvf The sub control volume face
* \param elemFluxVarsCache The cache related to flux compuation
- * \param useMoles If mole or mass fractions are used
*/
PrimaryVariables computeFlux(const Problem& problem,
const Element& element,
@@ -160,6 +159,16 @@ public:
return flux;
}
+ /*!
+ * \brief TODO docme!
+ *
+ * \param partialDerivatives TODO docme!
+ * \param problem TODO docme!
+ * \param element The element
+ * \param fvGeometry The finite volume geometry context
+ * \param curVolVars TODO docme!
+ * \param scv The sub control volume.
+ */
template<class PartialDerivativeMatrix>
void addStorageDerivatives(PartialDerivativeMatrix& partialDerivatives,
const Problem& problem,
@@ -176,6 +185,16 @@ public:
partialDerivatives[compIdx][compIdx] += d_storage;
}
+ /*!
+ * \brief TODO docme!
+ *
+ * \param partialDerivatives TODO docme!
+ * \param problem TODO docme!
+ * \param element The element
+ * \param fvGeometry The finite volume geometry context
+ * \param curVolVars TODO docme!
+ * \param scv The sub control volume.
+ */
template<class PartialDerivativeMatrix>
void addSourceDerivatives(PartialDerivativeMatrix& partialDerivatives,
const Problem& problem,
diff --git a/dumux/porousmediumflow/tracer/volumevariables.hh b/dumux/porousmediumflow/tracer/volumevariables.hh
index b1771fdd5c..b62ce0c4eb 100644
--- a/dumux/porousmediumflow/tracer/volumevariables.hh
+++ b/dumux/porousmediumflow/tracer/volumevariables.hh
@@ -18,6 +18,7 @@
*****************************************************************************/
/*!
* \file
+ * \ingroup TracerModel
* \brief Quantities required by the tracer model in a control volume
*/
#ifndef DUMUX_TRACER_VOLUME_VARIABLES_HH
@@ -61,7 +62,13 @@ class TracerVolumeVariables : public PorousMediumFlowVolumeVariables<TypeTag>
public:
/*!
- * \copydoc ImplicitVolumeVariables::update
+ * \brief Update all quantities for a given control volume
+ *
+ * \param elemSol A vector containing all primary variables connected to the element
+ * \param problem The object specifying the problem which ought to
+ * be simulated
+ * \param element An element which contains part of the control volume
+ * \param scv The sub-control volume
*/
void update(const ElementSolutionVector &elemSol,
const Problem &problem,
@@ -89,6 +96,8 @@ public:
* \brief Return density \f$\mathrm{[kg/m^3]}\f$ the of the fluid phase.
*
* We always forward to the fluid state with the phaseIdx property (see class description).
+ *
+ * \param pIdx TODO docme!
*/
Scalar density(int pIdx = 0) const
{ return fluidDensity_; }
@@ -98,6 +107,8 @@ public:
*
* This method is here for compatibility reasons with other models. The saturation
* is always 1.0 in a one-phasic context.
+ *
+ * \param pIdx TODO docme!
*/
Scalar saturation(int pIdx = 0) const
{ return 1.0; }
@@ -107,18 +118,24 @@ public:
*
* This method is here for compatibility reasons with other models. The mobility is always 1
* for one-phasic models where the velocity field is given
+ *
+ * \param pIdx TODO docme!
*/
Scalar mobility(int pIdx = 0) const
{ return 1.0; }
/*!
* \brief Return molar density \f$\mathrm{[mol/m^3]}\f$ the of the fluid phase.
+ *
+ * \param pIdx TODO docme!
*/
Scalar molarDensity(int pIdx = 0) const
{ return fluidDensity_/fluidMolarMass_; }
/*!
* \brief Return mole fraction \f$\mathrm{[mol/mol]}\f$ of a component in the phase.
+ *
+ * \param pIdx TODO docme!
* \param compIdx The index of the component
*/
Scalar moleFraction(int pIdx, int compIdx) const
@@ -126,6 +143,8 @@ public:
/*!
* \brief Return mass fraction \f$\mathrm{[kg/kg]}\f$ of a component in the phase.
+ *
+ * \param pIdx TODO docme!
* \param compIdx The index of the component
*/
Scalar massFraction(int pIdx, int compIdx) const
@@ -133,6 +152,8 @@ public:
/*!
* \brief Return concentration \f$\mathrm{[mol/m^3]}\f$ of a component in the phase.
+ *
+ * \param pIdx TODO docme!
* \param compIdx The index of the component
*/
Scalar molarity(int pIdx, int compIdx) const
@@ -140,6 +161,9 @@ public:
/*!
* \brief Return the binary diffusion coefficient \f$\mathrm{[m^2/s]}\f$ in the fluid.
+ *
+ * \param pIdx TODO docme!
+ * \param compIdx The index of the component
*/
Scalar diffusionCoefficient(int pIdx, int compIdx) const
{ return diffCoeff_[compIdx]; }
@@ -157,7 +181,7 @@ public:
{ return porosity_; }
protected:
- Scalar porosity_; //!< Effective porosity within the control volume
+ Scalar porosity_; // Effective porosity within the control volume
Scalar fluidDensity_, fluidMolarMass_;
GlobalPosition dispersivity_;
std::array<Scalar, numComponents> diffCoeff_;
diff --git a/dumux/porousmediumflow/tracer/vtkoutputfields.hh b/dumux/porousmediumflow/tracer/vtkoutputfields.hh
index 109902f8a4..77eb44e2e3 100644
--- a/dumux/porousmediumflow/tracer/vtkoutputfields.hh
+++ b/dumux/porousmediumflow/tracer/vtkoutputfields.hh
@@ -18,7 +18,8 @@
*****************************************************************************/
/*!
* \file
- * \brief Adds vtk output fields specific to the onep model
+ * \ingroup TracerModel
+ * \brief Adds vtk output fields specific to the tracer model
*/
#ifndef DUMUX_TRACER_VTK_OUTPUT_FIELDS_HH
#define DUMUX_TRACER_VTK_OUTPUT_FIELDS_HH
@@ -29,8 +30,8 @@ namespace Dumux
{
/*!
- * \ingroup Tracer, InputOutput
- * \brief Adds vtk output fields specific to the onep model
+ * \ingroup TracerModel
+ * \brief Adds vtk output fields specific to the tracer model
*/
template<class TypeTag>
class TracerVtkOutputFields
--
GitLab