Commit 5c3615ca authored by Lukas Riedel's avatar Lukas Riedel

Improve documentation of new parameterization features

* Add formulae for functions implemented
* Add doxygen subgroups Parameterization and Interpolators
* Add author and date information
parent b1e7d9f5
......@@ -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
......
......@@ -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
{
......
......@@ -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();
......
......@@ -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.
@}
**/
......@@ -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
{
......
......@@ -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
......@@ -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
{
......
......@@ -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
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