[Doc] Improve docstrings of transport parameterization

dune/dorie/model/richards/adapters/conductivity.hh

@@ -9,7 +9,8 @@ namespace Dune{
     /*---------------------------------------------------------------------*//**
      * @brief      Converts a parametrization P that contains conductivity
      *             information into a grid function (in PDELab sense)
-     *
+     * @ingroup    RichardsParam
+     * 
      * @tparam     T     BasicTraits with information about the function domain
      * @tparam     P     Parametrization class with saturated conductivity
      *                   information

dune/dorie/model/richards/adapters/saturation.hh

@@ -10,7 +10,8 @@ namespace Dune{
      * @brief      Converts a parametrization P that contains saturation
      *             information and a matric head grid function GF into a grid
      *             function (in PDELab sense) of saturation.
-     *
+     * @ingroup    RichardsParam
+     * 
      * @tparam     T     BasicTraits with information about the function domain
      * @tparam     P     Parametrization class with saturation information
      * @tparam     GF    Grid function of the matric head

dune/dorie/model/richards/adapters/water_content.hh

@@ -10,7 +10,8 @@ namespace Dune{
      * @brief      Converts a parametrization P that contains conductivity
      *             information and a matric head grid function GF into a grid
      *             function (in PDELab sense) of water content.
-     *
+     * @ingroup    RichardsParam
+     * 
      * @tparam     T     BasicTraits with information about the function domain
      * @tparam     P     Parametrization class with conductivity information
      * @tparam     GF    Grid function of the matric head

dune/dorie/model/richards/adapters/water_flux.hh

@@ -11,7 +11,8 @@ namespace Dune{
      * @brief      Converts an grid function space GFS and some particular
      *             coefficients for such space X to match the water flux
      *             equation with a GridFunctionInterface.
-     *
+     * @ingroup    RichardsParam
+     * 
      * @tparam     GFS   Grid Function Space
      * @tparam     X     Coefficients for the GFS
      * @tparam     P     Parameters

dune/dorie/model/transport/adapters/effective_hydrodynamic_dispersion.hh

@@ -11,7 +11,8 @@ namespace Dorie{
  * @details    For a given paramaterization, water flux and water content, this
  *             class returns the hydrodynamic dispersion tensor (od dimension
  *             dimRange) in an aliased vector.
- *
+ * @ingroup    TransportParam
+ * 
  * @tparam     T               The base traits
  * @tparam     Parameter       The transport parameter class
  * @tparam     GFWaterFlux     The water flux grid function class

dune/dorie/model/transport/adapters/peclet.hh

@@ -8,6 +8,7 @@ namespace Dorie{
 
 /**
  * @brief      Converts an interface to match a microscopic peclet number.
+ * @ingroup    TransportParam
  * 
  * @tparam     T               The base traits
  * @tparam     Parameter       The transport parameter class

dune/dorie/model/transport/modules.dox

@@ -43,13 +43,82 @@
 
 ## Overview
 
-...
+The parameterization condenses the subscale physics from below the
+REV scale and represents the effective dispersion process in the far-field 
+regimme of the transport process. The main task of the parameterization in DORiE
+is to estimate the hydrodynamic dispersion tensor. However, it also estimates 
+the microscopic péclet number. Several options (and their combinations) are 
+available.
+
+### Parameterization
+
+The microscopic peclet number is directly implemented in the base class of the 
+parameterization Dune::Dorie::Parameterization::Transport::peclet_f().
+
+The hydrodynamic dispersion tensor is implemented as a polyphormic object in 
+Dune::Dorie::Parameterization::Transport. It can take the form of three 
+different parameterizations:
+
+  1. **Constant hydrodynamic dispersion tensor**
+    As the name reveals, it simply requires a constant tensor 
+    Dune::Dorie::Parameterization::ConstHydrodynamicDispersion.
+
+  2. **Power Law**
+    In this case, the diagonal of the tensor depends on the microscopic peclet
+    number, the molecular diffusion, and two user-dependent parameters
+    Dune::Dorie::Parameterization::PowerLawDispersion.
+
+  3. **Superposition**
+    The superposition case assumes that the linear combination of different 
+    dispersion processes lead to the desired hydrodynamic dispersion tensor.
+    Since the concept is not tied to any particular parameterization, the 
+    individual processes are implemented as well as polyphormic objects. 
+    In this case, there are implemented the two most fundamental processes at
+    pore scale 
+    Dune::Dorie::Parameterization::HydrodynamicDispersionSuperposition:
+
+    a. *Effective diffusion coefficient*
+      Dune::Dorie::Parameterization::EffectiveDiffusion
+        
+      + Constant coefficient 
+        Dune::Dorie::Parameterization::ConstEffectiveDiffusion
+      + Milligtong Quirk I 
+        Dune::Dorie::Parameterization::MillingtonQuirk1
+      + Milligtong Quirk II 
+        Dune::Dorie::Parameterization::MillingtonQuirk2
+
+    b. *Effective hydromechanic dispersion tensor*
+      Dune::Dorie::Parameterization::EffectiveHydromechanicDispersion
+
+      + Constant effective hydromechanic dispersion tensor
+        Dune::Dorie::Parameterization::ConstEffectiveHydromechanicDispersion
+      + Hydromechanic dispersion for isotropic media
+        Dune::Dorie::Parameterization::IsotropicEffectiveHydromechanicDispersion
 
 Storing this data, providing grid-to-data mappings, and access to this data
 are tasks of the Dune::Dorie::TransportParameters interface, that is directly 
 used in the @ref LocalOperators.
 
+Special care has to be taken when modifying repeated parameters (e.g. molecular
+diffusion) or when storing shared pointers in polyhpromic objects. If not 
+treated carefully, some parameters may be not reachable anymore with the 
+parameters() methods or be doubly created when using the method clone(). 
+
+@todo       Add scaling factors to porosity values
+
+### Adapters
+
+The adapter for the hydrodynamic dispersion tensor is rather specific: 
 
++ Visualization of glyph tensors in Paraview is only avaiable for 9 component 
+  data (3D tensor).
++ The VTK writer of dune-grid can only write data that is indexable once. H
+  Hence, the 3x3 tensor has to be flattened.
++ The usual Grid Function to VTK Function adapter in dune-pdelab does not allow
+  to write more than 3 components of data. Hence we write our own Grid Function 
+  to dune-function adapter (Dune::Dorie::VTKGridFunctionAdapter) which is 
+  natively accepted by the current vtk writers.
+  
 @}
 
 **/

dune/dorie/model/transport/parameterization/hydrodynamic_dispersion/eff_hydromechanic_dispersion/longitudinal/const.hh

@@ -11,6 +11,15 @@ namespace Dune {
 namespace Dorie {
 namespace Parameterization {
 
+/*-------------------------------------------------------------------------*//**
+ * @brief      Class for constant longitudinal dispersivity.
+ *
+ * @ingroup    TransportParam
+ * @author     Santiago Ospina
+ * @date       2019
+ *
+ * @tparam     Traits  the base traits
+ */
 template <class Traits>
 class ConstLongitudinalDispersivity 
     : public LongitudinalDispersivity<Traits>
@@ -18,12 +27,13 @@ class ConstLongitudinalDispersivity
 private:
     using Base = LongitudinalDispersivity<Traits>;
     using RangeField = typename Traits::RF;
+
 public:
     using WaterFluxType = typename Base::WaterFluxType;
     using WaterContentType = typename Base::WaterContentType;
-
     using LongitudinalDispersivityType = typename Base::LongitudinalDispersivityType;
 
+    /// Parameter defining the constant longitudinal dispersivity
     struct ConstLongitudinalDispersivityType
     {
         RangeField value;
@@ -35,10 +45,19 @@ public:
 
     ConstLongitudinalDispersivityType _lambda_l;
 
+public:
+
+    /// Construct with default-initialized parameters
+    /** \param name The name associated with this soil layer
+     */
     ConstLongitudinalDispersivity (const std::string name) 
         :   Base(name)
     { }
 
+    /// Construct from a tuple of parameters
+    /** \param name The name associated with this soil layer
+     *  \param parameters Tuple of parameters to use in this parameterization
+     */
     template<typename... Args>
     ConstLongitudinalDispersivity (
             const std::string name,
@@ -47,11 +66,12 @@ public:
         _lambda_l(std::get<ConstLongitudinalDispersivityType>(parameters))
     { }
 
+    /// Add default destructor to clarify override
     ~ConstLongitudinalDispersivity () override = default;
 
-    const std::string& get_name() const { return _name; }
-
-
+    /// Return the longitudinal dispersivity
+    /** {WaterFlux,WaterContent} -> LongitudinalDispersivity
+     */
     std::function<
         LongitudinalDispersivityType(const WaterFluxType, const WaterContentType)> 
             longitudinal_dispersivity_f () const override
@@ -61,16 +81,25 @@ public:
         };
     }
 
+    /// Return a map of parameter names and values for manipulation
+    /** \return Map: Parameter name, parameter value in this object
+     */
     std::multimap<std::string, double&> parameters () override
     {
         return {{ConstLongitudinalDispersivityType::name,_lambda_l.value}};
     }
 
+    /// Return a map of parameter names and values for manipulation
+    /** \return Map: Parameter name, parameter value in this object
+     */
     std::multimap<std::string, const double&> parameters () const override
     {
         return {{ConstLongitudinalDispersivityType::name,_lambda_l.value}};
     }
 
+    /// Return a map of parameter names and values for manipulation
+    /** \return Map: Parameter name, parameter value in this object
+     */
     std::unique_ptr<LongitudinalDispersivity<Traits>> clone () const override
     {
         using ThisType = ConstLongitudinalDispersivity<Traits>;

dune/dorie/model/transport/parameterization/hydrodynamic_dispersion/eff_hydromechanic_dispersion/longitudinal/interface.hh

@@ -12,6 +12,15 @@ namespace Parameterization {
 template<class Traits>
 class IsotropicEffectiveHydromechanicDispersion;
 
+/*-------------------------------------------------------------------------*//**
+ * @brief      Class for longitudinal dispersivity.
+ *
+ * @ingroup    TransportParam
+ * @author     Santiago Ospina
+ * @date       2019
+ *
+ * @tparam     Traits  the base traits
+ */
 template <class Traits>
 class LongitudinalDispersivity
 {
@@ -22,31 +31,58 @@ public:
 
     using WaterFluxType = typename BaseP::WaterFluxType;
     using WaterContentType = typename BaseP::WaterContentType;
-    
+    using LongitudinalDispersivityType = typename BaseP::LongitudinalDispersivityType;
+
+    //! The name of this parameterization instance, associated with the layer.
+    const std::string _name;
+
+    /// Construct with default-initialized parameters
+    /** \param name The name associated with this soil layer
+     */
     LongitudinalDispersivity (const std::string name) 
         :   _name(name)
     { }
 
+    /// Construct from a tuple of parameters
+    /** \param name The name associated with this soil layer
+     *  \param parameters Tuple of parameters to use in this parameterization
+     */
+    template<typename... Args>
+    LongitudinalDispersivity (
+            const std::string name,
+            const std::tuple<Args...> parameters)
+        :   _name(name)
+    { }
+
+    /// Default constructor (virtual).
     virtual ~LongitudinalDispersivity () = default;
 
+    /// Return the name of this parameterization instance.
     const std::string& get_name() const { return _name; }
 
-    using LongitudinalDispersivityType = typename BaseP::LongitudinalDispersivityType;
-
+    /// Return a bound version of the longitudinal dispersivity
+    /** \return Function: {Water Flux, Water Content} -> Longitudinal Dispersivity
+     */
     virtual std::function<
         LongitudinalDispersivityType(const WaterFluxType, const WaterContentType)> 
             longitudinal_dispersivity_f () const = 0;
 
+    /// Return a map referecing all parameters by their names.
+    /** \return Map. Key: Name of parameter (string).
+     *      Value: Value of parameter (double&)
+     */
     virtual std::multimap<std::string, double&> parameters () = 0;
+
+    /// Return a map referecing all parameters by their names.
+    /** \return Map. Key: Name of parameter (string).
+     *      Value: Value of parameter (const double&)
+     */    
     virtual std::multimap<std::string, const double&> parameters () const = 0;
 
-    /// Return a clone of this object
-    /** \return a unique pointer with a copy of this object.
+    /// Clone the plymorphic class
+    /** \return unique pointer to the cloned object
      */
     virtual std::unique_ptr<LongitudinalDispersivity<Traits>> clone () const = 0;
-
-private:
-    const std::string _name;
 };
 
 } // namespace Parameterization

dune/dorie/model/transport/parameterization/hydrodynamic_dispersion/eff_hydromechanic_dispersion/transverse/const.hh

@@ -11,6 +11,15 @@ namespace Dune {
 namespace Dorie {
 namespace Parameterization {
 
+/*-------------------------------------------------------------------------*//**
+ * @brief      Class for constant transverse dispersivity.
+ *
+ * @ingroup    TransportParam
+ * @author     Santiago Ospina
+ * @date       2019
+ *
+ * @tparam     Traits  the base traits
+ */
 template <class Traits>
 class ConstTransverseDispersivity 
     : public TransverseDispersivity<Traits>
@@ -22,9 +31,9 @@ private:
 public:
     using WaterFluxType = typename Base::WaterFluxType;
     using WaterContentType = typename Base::WaterContentType;
-
     using TransverseDispersivityType = typename Base::TransverseDispersivityType;
 
+    /// Parameter defining the constant transverse dispersivity
     struct ConstTransverseDispersivityType
     {
         RangeField value;
@@ -36,10 +45,19 @@ public:
 
     ConstTransverseDispersivityType _lambda_t;
 
+public:
+
+    /// Construct with default-initialized parameters
+    /** \param name The name associated with this soil layer
+     */
     ConstTransverseDispersivity (const std::string name) 
         :   Base(name)
     { }
 
+    /// Construct from a tuple of parameters
+    /** \param name The name associated with this soil layer
+     *  \param parameters Tuple of parameters to use in this parameterization
+     */
     template<typename... Args>
     ConstTransverseDispersivity (
             const std::string name,
@@ -48,11 +66,12 @@ public:
         _lambda_t(std::get<ConstTransverseDispersivityType>(parameters))
     { }
 
+    /// Add default destructor to clarify override
     ~ConstTransverseDispersivity () override = default;
 
-    const std::string& get_name() const { return _name; }
-
-
+    /// Return the transverse dispersivity
+    /** {WaterFlux,WaterContent} -> TransverseDispersivity
+     */
     std::function<
         TransverseDispersivityType(const WaterFluxType, const WaterContentType)> 
             transverse_dispersivity_f () const override
@@ -62,16 +81,25 @@ public:
         };
     }
 
+    /// Return a map of parameter names and values for manipulation
+    /** \return Map: Parameter name, parameter value in this object
+     */
     std::multimap<std::string, double&> parameters () override
     {
         return {{ConstTransverseDispersivityType::name,_lambda_t.value}};
     }
 
+    /// Return a map of parameter names and values for manipulation
+    /** \return Map: Parameter name, parameter value in this object
+     */
     std::multimap<std::string, const double&> parameters () const override
     {
         return {{ConstTransverseDispersivityType::name,_lambda_t.value}};
     }
 
+    /// Return a map of parameter names and values for manipulation
+    /** \return Map: Parameter name, parameter value in this object
+     */
     std::unique_ptr<TransverseDispersivity<Traits>> clone () const override
     {
         using ThisType = ConstTransverseDispersivity<Traits>;

dune/dorie/model/transport/parameterization/hydrodynamic_dispersion/eff_hydromechanic_dispersion/transverse/interface.hh

@@ -12,6 +12,15 @@ namespace Parameterization {
 template<class Traits>
 class IsotropicEffectiveHydromechanicDispersion;
 
+/*-------------------------------------------------------------------------*//**
+ * @brief      Class for transverse dispersivity.
+ *
+ * @ingroup    TransportParam
+ * @author     Santiago Ospina
+ * @date       2019
+ *
+ * @tparam     Traits  the base traits
+ */
 template <class Traits>
 class TransverseDispersivity
 {
@@ -22,31 +31,58 @@ public:
 
     using WaterFluxType = typename BaseP::WaterFluxType;
     using WaterContentType = typename BaseP::WaterContentType;
-    
+    using TransverseDispersivityType = typename BaseP::TransverseDispersivityType;
+
+    //! The name of this parameterization instance, associated with the layer.
+    const std::string _name;
+
+    /// Construct with default-initialized parameters
+    /** \param name The name associated with this soil layer
+     */
     TransverseDispersivity (const std::string name) 
         :   _name(name)
     { }
 
+    /// Construct from a tuple of parameters
+    /** \param name The name associated with this soil layer
+     *  \param parameters Tuple of parameters to use in this parameterization
+     */
+    template<typename... Args>
+    TransverseDispersivity (
+            const std::string name,
+            const std::tuple<Args...> parameters)
+        :   _name(name)
+    { }
+
+    /// Default constructor (virtual).
     virtual ~TransverseDispersivity () = default;
 
+    /// Return the name of this parameterization instance.
     const std::string& get_name() const { return _name; }
 
-    using TransverseDispersivityType = typename BaseP::TransverseDispersivityType;
-
+    /// Return a bound version of the transverse dispersivity
+    /** \return Function: {Water Flux, Water Content} -> Transverse Dispersivity
+     */
     virtual std::function<
         TransverseDispersivityType(const WaterFluxType, const WaterContentType)> 
             transverse_dispersivity_f () const = 0;
 
+    /// Return a map referecing all parameters by their names.
+    /** \return Map. Key: Name of parameter (string).
+     *      Value: Value of parameter (double&)
+     */
     virtual std::multimap<std::string, double&> parameters () = 0;
+
+    /// Return a map referecing all parameters by their names.
+    /** \return Map. Key: Name of parameter (string).
+     *      Value: Value of parameter (const double&)
+     */    
     virtual std::multimap<std::string, const double&> parameters () const = 0;
 
     /// Return a clone of this object
     /** \return a unique pointer with a copy of this object.
      */
     virtual std::unique_ptr<TransverseDispersivity<Traits>> clone () const = 0;
-
-private:
-    const std::string _name;
 };
 
 } // namespace Parameterization