[Doc] Improve docstrings of transport parameterization

parent 5e1d6c1e
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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.
@}
**/
......@@ -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>;
......
......@@ -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
......
......@@ -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>;
......
......@@ -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
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment