Improve documentation of new parameterization features

* Add formulae for functions implemented
* Add doxygen subgroups Parameterization and Interpolators
* Add author and date information

dune/dorie/common/groups.dox

@@ -12,9 +12,24 @@
   @todo document models
 @}
 
+@defgroup Interpolators Interpolators
+@{
+  @ingroup Common
+  @brief Interpolation of structured data for evaluation on any point
+      inside the grid.
+
+  ## Overview
+
+  Interpolators have the task to store input data and evaluate it for global
+  positions on the grid. The data is not shared or scattered across processes,
+  but exists independently on every process. Therefore, using these structures
+  is only efficient in a setup process. Interpolators should not be used to
+  retrieve data repeatedly, especially not from a PDE solver.
+@}
+
 @defgroup Models Models
 
-@defgroup LocalOperators Local operators
+@defgroup LocalOperators Local Operators
 @{
   Local operators are in many senses the heart of dorie; in them, we transform
   finite element basis into a vector of residuals and a mass matrix taking into

dune/dorie/common/interpolator.hh

@@ -16,6 +16,12 @@ namespace Dune {
 namespace Dorie {
 
 /// An abstract interpolator. Stores all data necessary for evaluation.
+/**
+ *  \see InterpolatorFactory for conveniently creating derived objects
+ *  \ingroup Interpolators
+ *  \author Lukas Riedel
+ *  \date 2018
+ */
 template<typename T, typename Traits>
 class Interpolator
 {
@@ -95,6 +101,8 @@ public:
 /** This interpolator iterprets its data like *cell*-data.
  *  When using a dataset with three values across the extensions of two,
  *  the data values shange at positions 2/3 and 4/3.
+ *
+ *  \ingroup Interpolators
  */
 template<typename T, typename Traits>
 class NearestNeighborInterpolator: public Interpolator<T, Traits>
@@ -155,6 +163,12 @@ public:
 };
 
 /// Factory for creating interpolators
+/**
+ *  \see Interpolator for the base class of created objects
+ *  \ingroup Interpolators
+ *  \author Lukas Riedel
+ *  \date 2018
+ */
 template<typename Traits>
 struct InterpolatorFactory
 {

dune/dorie/model/richards/flow_parameters.hh

@@ -20,20 +20,32 @@
 namespace Dune {
 namespace Dorie {
 
-/// Top-level parameterization interface.
-/** This class stores the parameters, maps them to grid entities, and provides
- *  functions to access the parameterization. For doing so, the
+/// Top-level parameterization interface for the local operator.
+/** This class loads and stores the parameters, maps them to grid entities,
+ *  and provides functions to access the parameterization. For doing so, the
  *  FlowParameters::bind function has to be called first to cache the
  *  parameters of the given grid entity. Parameters are only stored for entities
  *  of codim 0.
  *
- *  \detail The parameterization consists of three structures:
+ *  \details The parameterization consists of three structures:
  *      - This top-level class serves as interface and storage. It also casts to
  *          data types used by the DUNE operators
  *      - The Dorie::RichardsParameterization interface that provides strong
  *          data types for the base parameters and purely virtual functions that
  *          need to be defined by derived parameterizations
  *      - The actual parameterization defining all parameters and functions
+ *
+ *  \warning Load-balancing the grid *after* this object has been instantiated
+ *      is currently not supported.
+ *
+ *  \todo Make this object support load-balancing. This would require a global
+ *      ID mapper and communicating the data in the _param storage. The latter
+ *      is rather involved because of non-standard data types like maps and
+ *      Dorie::ScalingFactors
+ *
+ *  \author Lukas Riedel
+ *  \date 2018
+ *  \ingroup RichardsParam
  */
 template <typename Traits>
 class FlowParameters
@@ -90,7 +102,7 @@ private:
     }
 
 public:
-    /// Constructor.
+    /// Create this object and load the data.
     /** Create a level grid view of level 0, create a mapper on it, and store
      *  the config tree.
      *  \param config Configuration file tree
@@ -128,6 +140,9 @@ public:
     template <class Entity>
     void bind (Entity entity) const
     {
+        static_assert(Entity::codimension == 0,
+                      "Parameters are mapped to codim 0 entities only!");
+
         // retrieve index of top father element of chosen entity
         while(entity.hasFather()) {
             entity = entity.father();

dune/dorie/model/richards/groups.dox

@@ -13,4 +13,69 @@
     @todo document richards model
 @}
 
+@defgroup RichardsParam Parameterization
+@{
+@ingroup RichardsModel
+
+@brief Representing hydraulic properties of the porous medium
+
+## Overview
+
+The parameterization condenses the subscale physics from below the
+REV scale and represents the statistics and structural configuration of
+the porous medium. It is the main source of non-linearity in the Richards
+equation.
+
+In the Richards regime conductivity, water saturation, and water content
+may vary discontinuously. These singularities can impose strong numeric
+instabilities. DG methods can explicitly incorporate such singularities if
+they occur across grid cell interfaces. The Parameterization module provides
+a fast access to soil parameters and scaling factors by mapping these values
+to grid elements on the coarsest level. This way it is ensured that
+singularities do not occur inside a grid element.
+
+A parameterization must supply the following functional relations between
+state variables and parameters:
+
+@f{align*}{
+    \Theta & \mapsto \theta \\
+    h_m & \mapsto \Theta(h_m) \\
+    \Theta & \mapsto K(\Theta)
+@f}
+
+Storing this data, providing grid-to-data mappings, and access to this data
+are tasks of the Dune::Dorie::FlowParameters interface, that is directly used
+in the @ref LocalOperators.
+
+## Scaling
+
+The parameterizations implemented with the
+Dune::Dorie::RichardsParameterization interface are envisaged to be constant
+throughout a single medium layer. However, one typically finds small-scale
+variations at the scale of interest. To account for these heterogeneities,
+several scaling schemes have been developed.
+
+We implement scaling by storing a set of scaling factors for every grid cell on
+the coarsest level. Unlike the parameterization objects, these do not map
+to a certain medium but only the cell itself (and its child cells). The scaling
+factors are stored inside instances of Dune::Dorie::ScalingFactors.
+
+For evaluating scaling factor data, the Dune::Dorie::ScalingAdapter interface
+is used, which internally uses the Interpolator interface. These structures are
+discarded as soon as the data is loaded for every grid cell on the processor.
+
+In practice, we store three independent scaling values
+@f$ \xi_{h_m}, \xi_{K}, \xi_{\phi} @f$
+which are applied to the parameterization functions as follows:
+
+@f{align*}{
+    \Theta &= \Theta(h_m \cdot \xi_{h_m}) \\
+    \phi &= \theta_s + \xi_{\phi} \\
+    K &= K(\Theta) \cdot \xi_K^2
+@f}
+
+Here, @f$ \phi @f$ denotes the (scaled) porosity of the medium.
+
+@}
+
 **/

dune/dorie/model/richards/parameterization/interface.hh

@@ -8,7 +8,20 @@
 namespace Dune {
 namespace Dorie {
 
-/// Class defining the interface for parameterizations of Richards equation
+/// Interface for parameterizations of Richards equation.
+/** Defines the basic parameters and the relation between water content
+ *  and saturation
+ *  @f{align*}{
+ *      \phi &:= \theta_s \\
+ *      \theta (\Theta) &= \Theta \left[ \phi - \theta_r \right] + \theta_r
+ *  @f}
+ *  where \f$ \phi \f$ is the porosity, which might be scaled with a
+ *  ScalingFactors::scale_por.
+ *
+ *  \see FlowParameters stores one instance of a derived class for every
+ *      medium layer.
+ *  \ingroup RichardsParam
+ */
 template <typename Traits>
 class RichardsParameterization
 {

dune/dorie/model/richards/parameterization/mualem_van_genuchten.hh

@@ -10,15 +10,17 @@
 namespace Dune {
 namespace Dorie {
 
-/// Class specifying the Mualem–van Genuchten parameterization
-/** Implements the following parameters which need to be specified in the
- *  respective parameter file:
- *  * RichardsParameterization::ResidualWaterContent "theta_r"
- *  * RichardsParameterization::SaturatedWaterContent "theta_s"
- *  * RichardsParameterization::SaturatedConductivity "k0"
- *  * Alpha "alpha"
- *  * N "n"
- *  * Tau "tau"
+/// Representation of the Mualem–van Genuchten parameterization
+/** Implements the following relations:
+ *  @f{align*}{
+ *      m &:= 1 - 1/n \\
+ *      \Theta (h_m) &= \left[ 1 + \left[ \alpha h_m \right]^n \right]^{-m} \\
+ *      K (\Theta) &= K_0 \Theta^\tau
+ *                      \left[ 1 - \left[ 1 - \Theta^{1/m} \right]^m \right]^2
+ *  @f}
+ *  \ingroup RichardsParam
+ *  \author Lukas Riedel
+ *  \date 2018
  */
 template <typename Traits>
 class MualemVanGenuchtenParameterization :
@@ -144,4 +146,4 @@ public:
 } // namespace Dune
 } // namespace Dorie
 
-#endif // DUNE_DORIE_PARAM_MVG_HH
\ No newline at end of file
+#endif // DUNE_DORIE_PARAM_MVG_HH

dune/dorie/model/richards/parameterization/scaling.hh

@@ -19,6 +19,8 @@ namespace Dorie {
 /** The variables are initialized to their default values
  *  (no effective scaling).
  *  \tparam RF Numeric type of scaling factors
+ *  \see ScalingAdapter returns this object when evaluated at a certain position
+ *  \ingroup RichardsParam
  */
 template<typename RF>
 struct ScalingFactors
@@ -27,12 +29,19 @@ struct ScalingFactors
     RF scale_head = 1.0;
     //! Scaling factor of conductivity
     RF scale_cond = 1.0;
-    //! Scaling factor of saturation
+    //! Scaling factor of porosity (a summand, actually!)
     RF scale_por = 0.0;
 };
 
 /// Abstract base class for scaling adapters. Provides the interface.
-/** \tparam Traits Type traits of this adapter
+/** A ScalingAdapter implements the evaluate method which returns a set of
+ *  ScalingFactors.
+ *
+ *  \tparam Traits Type traits of this adapter.
+ *  \ingroup RichardsParam
+ *  \author Lukas Riedel
+ *  \date 2018
+ *  \see ScalingAdapterFactory conveniently creates derived objects
  */
 template<typename Traits>
 class ScalingAdapter
@@ -108,7 +117,32 @@ protected:
     }
 };
 
-/// A ScalingAdapter implementing Miller scaling
+/// A ScalingAdapter implementing Miller scaling.
+/** Miller scaling assumes geometric similarity and only varies the local
+ *  length scale of the porous medium.
+ *
+ *  The scaled values of matric head \f$ h_m \f$ and the conducitivity
+ *  \f$ K \f$ with respect to the reference values \f$ h_m^* \f$ and
+ *  \f$ K^* \f$ are calculated by applying the Miller scaling factor
+ *  \f$ \xi \f$, which indicates a local length scale with respect to the
+ *  reference length scale of the medium.
+ *
+ *  \f{align*}{
+ *      h_m &= h_m^* \cdot \xi \\
+ *      K &= K^* \cdot \xi^2
+ *  \f}
+ *
+ *  When entering data, the single dataset is used as Miller scaling factor
+ *  \f$ \xi \f$. This scaling adapter effectively sets
+ *
+ *  \f{align*}{
+ *      \xi_{h_m} = \xi_K = \xi
+ *  \f}
+ *
+ *  \ingroup RichardsParam
+ *  \author Lukas Riedel
+ *  \date 2018
+ */
 template<typename Traits>
 class MillerScalingAdapter : public ScalingAdapter<Traits>
 {
@@ -139,7 +173,15 @@ public:
     ~MillerScalingAdapter () override = default;
 };
 
-/// A scaling adapter that does not implement any scaling
+/// A ScalingAdapter that does not implement any scaling.
+/** This adapter returns a default-initialized instance of ScalingFactors
+ *  when evaluated.
+ *
+ *  \see ScalingFactors
+ *  \ingroup RichardsParam
+ *  \author Lukas Riedel
+ *  \date 2018
+ */
 template<typename Traits>
 class DummyScalingAdapter : public ScalingAdapter<Traits>
 {
@@ -169,6 +211,12 @@ public:
 
 
 /// Factory class for creating ScalingAdapters.
+/**
+ *  \ingroup RichardsParam
+ *  \author Lukas Riedel
+ *  \date 2018
+ *  \see ScalingAdapter is the base class of instances created by this factory
+ */
 template<typename Traits>
 struct ScalingAdapterFactory
 {

dune/dorie/test/test-grid-creation.hh

@@ -49,4 +49,4 @@ void create_grid_and_test_mapping (const Dune::ParameterTree& config,
     }
 }
 
-#endif // TEST_GRID_CREATION_HH
\ No newline at end of file
+#endif // TEST_GRID_CREATION_HH