---
title: The DuMuX property system
subtitle: Flexible compile-time parameters
---
# Parameters vs. properties
## Parameters vs. properties
- <span style="color:#3498DB">Parameters</span> are set at __run-time__
<p>A default value may be used if the user does not provide one at run-time</p>
- <span style="color:#3498DB">Properties</span> are known and set at __compile-time__
<p>
Can be used e.g. as template parameters (__types__ or values with `constexpr` specifier);
No run-time penalty, enable compiler to optimize
</p>
## Template parameters
- C++ supports _generic programming_ via __templates__
- e.g. classes defined in terms of other types
- concrete versions of templates are stamped out upon compilation
- __Flexible__: implementation not restricted to _concrete types_
- __Efficient__: decisions made at compile-time
## Template parameters
An example - `std::vector`
```cpp
// Declaration of the class template, usable with any
// `T` that fulfills the requirements that `vector` poses on it.
template<typename T, typename A = std::allocator<T>>
class vector;
// Instantiation of a concrete vector - a vector of ints.
// The compiler will define this concrete type for us,
// using the definition of the class template.
std::vector<int> v;
```
## Template specializations
Template implementations can be specialized for concrete types
```cpp
template<typename T>
class MyVector
{
// Generic implementation for any T
};
template<>
class MyClass<int>
{
// specialized implementation for `int`
};
```
## Too many template parameters
For some classes, providing all template parameters can be very cumbersome and error-prone.
```cpp
// Example from dune-pdelab. 9 template parameters!
using GOF0 = Dune::GridOperator<
GFS, GFS, LOP, MBE,
RF, RF, RF,
CF, CF
>;
DGGO2 dggo2(gfs, cd, gfs, cf, lop, mbe);
```
## Traits classes
A usual way to group template parameters
```cpp
struct MyGridOperatorTraits{
using FromGFS = ...;
// ...
};
using GOF0 = Dune::PDELab::GridOperator<MyGridOperatorTraits>;
```
## Inheriting from traits classes
Inheritance may lead to unexpected results
```cpp
struct MyBaseTraits
{
using Scalar = int;
using Vector = std::vector<Scalar>;
};
struct MyDoubleTraits : public MyBaseTraits
{
using Scalar = double;
};
// this is a vector of ints!
typename MyDoubleTraits::vector v{1.14142, 1.73205};
```
## Type traits
Based on template specialization
```cpp
// Trait class template declaration
template<typename T> struct ValueType;
// Specialization for vectors of T
template<typename T, typename Allocator>
struct ValueType<std::vector<T, Allocator>> { using type = T; };
// Specialization for Dune::FieldVector
template<typename T, int size>
struct ValueType<Dune::FieldVector<T, size>> { using type = T; };
```
## Type traits
A usage example
```cpp
template<typename Container>
void someFunction(const Container& c) {
using V = typename ValueType<Container>::type;
// do something with V
// ...
}
```
# The DuMuX Property System
## Property System Design
- Based on __C++ template specialization__ (_type traits_)
- From a __type tag__, one can extract __properties__ defined for it
- A __property tag__ is a trait class definition (or default implementation)
- A __property__ is exported from a __property tag__ specialization for a __type tag__
- (The property system also supports definitions of traits classes - see later)
## Property System Design
A simplified example to illustrate the idea
```cpp
// myproperties.hh
namespace TTag { struct MyTypeTag {}; }
namespace Properties {
// some property tag
template<typename TypeTag> struct SomeTag;
// property definition for MyTypeTag
template<>
struct SomeTag<MyTypeTag>
{ using type = /*the actual property*/; };
} // namespace Properties
```
## Property System Design
A simplified example to illustrate the idea
```cpp
template<class TypeTag>
class GenericClass
{
using PropA = typename Properties::Tag<TypeTag>::type;
using PropB = typename Properties::OtherTag<TypeTag>::type;
// ...
// A property could be, for instance, a fluid system
using FS = typename Properties::FluidSystem<TypeTag>::type;
};
```
## Property System Design
Issues with this simplified example
- Composition of __type tags__ via inheritance bears the same issue as in the previous example (with traits classes)
- We would like to define properties in base __type tags__ dependent on property definitions in derived ones
## Actual Design
- A hierarchy of nodes -- called __type tags__ -- is defined (via inheritance)
- __Properties__ are defined for the appropriate nodes in this hierarchy.
- The definition of __properties__ may _depend on_ arbitrary other properties, which may be _overwritten_ at any higher node of the hierarchy
- The only requirement for properties is that they may not exhibit __cyclic dependencies__
## Actual Design
Let's implement the `Vector` example using the property system
```cpp
namespace TTag { struct BaseTag; }
// specialization of the Scalar property for BaseTag
template<class TypeTag>
struct Scalar<TypeTag, TTag::BaseTag> { using type = int; };
// specialization of the Vector property for BaseTag
template<class TypeTag>
struct Vector<TypeTag, TTag::BaseTag>
{
using type = std::vector<
GetPropType<TypeTag, Properties::Scalar>
>;
};
```
## Actual Design
Let's implement the `Vector` example using the property system
```cpp
struct DoubleTag { using InheritsFrom = std::tuple<BaseTag>; };
// Specialization of the Scalar property for DoubleTag
template<class TypeTag>
struct Scalar<TypeTag, TTag::DoubleTag>
{ using type = double; };
```
```cpp
// using the property
using Vector = GetPropType<DoubleTag, Properties::Vector>;
Vector v{1.41421, 1.73205}; // v is a std::vector<double>!
```
## Using __type tags__ as traits classes
```cpp
struct BaseTag
{
using Scalar = double;
// Important: do not directly use Scalar here as it would
// break the possibility to overwrite it in a child node
template<typename TypeTag>
using Vector = std::vector<
GetPropType<TypeTag, Properties::Scalar>
>;
};
```
## Configure a model at compile time
- The DuMu<sup>x</sup> way $\leftrightarrow$ <span style="color:blue">Properties</span>
- A so-called <span style="color:blue">TypeTag</span> bundles all necessary information $\leftrightarrow$ only ONE template parameter
- <span style="color:blue">Properties</span> (data types and values) can be retrieved via the property system.
```cpp
template <class TypeTag>
class InjectionProblemTwoP
{
using VolumeVariables = GetPropType<
TypeTag, Properties::VolumeVariables
>;
constexpr auto useIFS = getPropValue<
TypeTag, Properties::EnableBoxInterfaceSolver
>();
};
```
## The DuMu<sup>x</sup> property system
- Extension $\leftrightarrow$ tree of so called TypeTag nodes
- Each TypeTag is associated with Properties
## The DuMu<sup>x</sup> property system
- Hierarchy / Inheritance
- TypeTags can inherit properties from other TypeTags
- Properties with the same name are overwritten
## How to use I
Creating new <span style="color:blue">TypeTag</span> nodes
```cpp
namespace Dumux::Properties::TTag {
struct MyTypeTag;
struct MyOtherTypeTag
{ using InheritsFrom = std::tuple<MyTypeTag>; }
} // end namespace Dumux::Properties::TTag
```
## How to use II
Creating new <span style="color:blue">property tags</span> (empty, unset properties) $\leftrightarrow$ Property names are unique!
```cpp
namespace Dumux::Properties {
DUMUX_DEFINE_PROPERTY(Problem)
} // end namespace Dumux::Properties
```
## How to use III
Setting **type** properties for a specific type tag `MyTypeTag`
```cpp
namespace Properties {
template<class TypeTag>
struct Problem<TypeTag, TTag::MyTypeTag>
{ using type = Dumux::MyProblem<TypeTag>; };
} // end namespace Properties
```
## How to use III (alternative)
Alternatively, using **type** alias properties for a specific type tag `MyTypeTag`
```cpp
namespace Properties::TTag {
struct MyTypeTag {
...
template<class TypeTag>
using Problem = Dumux::MyProblem<TypeTag>;
...
};
} // end namespace Properties
```
## How to use IV
Setting **value** properties for a specific type tag `MyTypeTag`
```cpp
namespace Properties{
template<class TypeTag>
struct EnableBoxInterfaceSolver<TypeTag, TTag::MyTypeTag>
{ static constexpr bool value = true; }
} // end namespace Properties
```
## How to use IV (alternative)
Setting **value** for a alias property for a specific type tag `MyTypeTag`
```cpp
namespace Properties {
struct MyTypeTag {
...
using EnableBoxInterfaceSolver = std::true_type;
...
};
} // end namespace Properties
```
## How to use V
Getting the property type set for a `TypeTag`
```cpp
namespace Dumux{
template <class TypeTag>
class Problem
{
using Scalar = GetPropType<TypeTag, Properties::Scalar>;
};
} // end namespace Dumux
```
## Summary
- "Top-level" classes in DuMu<sup>x</sup> depend on a __type tag__ and use the property system to obtain other types
- Setting a property for your __type tag__ will affect all classes using the same __type tag__
- Each model defines a set of properties grouped in a __type tag__
* e.g. <span style="color:blue">TwoP, TwoPTwoC, TwoPNI</span>
- By deriving your __type tag__ from those, your problem inherits all type information needed to set up the model at compile time!
- Example: see Exercise