parameters.md

Runtime Parameters

Runtime simulation parameters can be parsed to the program via a parameter file, via the command line, or can be initialized programmatically. We discuss all three approaches. Moreover, most parameters have default values as explained below. Runtime parameters are a configuration mechanism at program runtime (avoiding recompilation).

Initializing the parameter tree

The parameter tree is initialized by Dumux::Parameters::init. This constructs a parameter tree singleton from which parameters can be retrieved via accessor functions. The parameter tree can stores key-value pairs of type string. Values can also be other parameter trees (subtrees, groups). A simple program only initializing the parameter tree looks like this

#include <dumux/common/parameters.hh>
int main(int argc, char** argv)
{
    Dumux::Parameters::init(argc, argv);
    return 0;
}

We can also specify a parameter file (default: params.input) to be parsed (the expected INI file format is described below):

#include <dumux/common/parameters.hh>
int main(int argc, char** argv)
{
    Dumux::Parameters::init(argc, argv, "params.input");
    return 0;
}

Default parameters can explicitly be set upon initialization

#include <dune/common/parametertree.hh>
#include <dumux/common/parameters.hh>
int main(int argc, char** argv)
{
    Dumux::Parameters::init(argc, argv, [](Dune::ParameterTree& p){
        p["key"] = "value";
        p["group.key"] = "value2";
        ...
    });
    return 0;
}

The following variant omits reading command-line arguments and only parsing the specified input parameter file params.input:

#include <dumux/common/parameters.hh>
int main(int argc, char** argv)
{
    Dumux::Parameters::init("params.input");
    return 0;
}

Reading Runtime Parameters

Runtime parameters can be read from the parameter tree with the functions Dumux::getParam (converts string to requested type)

paramname_ = getParam<TYPE>("GROUPNAME.PARAMNAME", default);

where the specified default value is expected to be convertible to the type TYPE. Some examples are

  bool enableGravity = getParam<bool>("Problem.EnableGravity", true);
  auto upperRight = getParam<Dune::FieldVector<double, 3>>("FreeFlow.Grid.UpperRight");

Not specifying a default parameter causes the function to throws a Dumux::ParameterException if parameter doesn't exist in the parameter tree.

The function Dumux::getParamFromGroup traverses the parameter tree

paramname_ = getParamFromGroup<TYPE>("GROUPNAME", "PARAMNAME", default);

for example