params.md

title: Runtime Parameters

Runtime Parameters

Runtime Parameters

• Configuration at runtime (avoid recompiling)
• We will look at:
  • Parameters in input files
  • Command line parameters
  • Default parameters

Initialize Parameter Tree

• Parameters are initialized by Parameters::init(...)
• Parameters::init(...) constructs a parameter tree singleton from which parameters can be obtained
• The parameter tree stores strings (key-value) and parameter trees (subtrees, groups)

Initialize Parameter Tree

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

Initialize Parameter Tree

Expliticly specify parameter file (default: params.input)

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

Initialize Parameter Tree

Explciticly specify default parameters

#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;
}

Initialize Parameter Tree

Without reading command-line arguments

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

Reading Runtime Parameters

• Read parameters from the parameter tree with getParam (converts std::string to requested type)

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

• Examples:

  bool enableGravity = getParam<bool>("Problem.EnableGravity", true);

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

• Signature without default: throws ParameterException if parameter doesn't exist.

Reading Runtime Parameters

• getParamFromGroup variant traverses the parameter tree

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

• Example

  bool enableGravity = getParamFromGroup<bool>("FreeFlow", "Problem.Gravity");

  • first looks for FreeFlow.Problem.Gravity
  • then looks for Problem.Gravity
• Useful when configuring multiple simulation components or multi-domain problem via the single parameter tree

Reading Runtime Parameters

• Remark: Reading parameters is a slow operation
• Read parameters in constructors of high-level classes
• Never read parameters in functions called for all elements

Checking for Runtime Parameters

• Check: Does parameter exist in the parameter tree?

  if (hasParam("GROUPNAME.PARAMNAME"))
      // do something with parameter

• With group prefix lookup

  if (hasParamInGroup("GROUPNAME","PARAMNAME"))

Parameter tree logs usage

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

Reports unused parameters. Great for detecting typos in configuration file.

Parameter input file

Dune INI syntax ([Group] and Key = Value pairs)

params.input

[Grid]
LowerLeft = 0 0
UpperRight = 60 40
Cells = 24 16

[Problem]
Name = test

[FreeFlow.Problem]
Name = test_ff

Command-line arguments

./executable params.input -Key Value -Key2 Value2 -Key3 "a b c"

Examples:

./executable -Grid.Refinement 2
./executable params_alt.input -Grid.Refinement 2
./executable -Grid.Refinement 2 -Grid.Cells "10 10"

Parameter precedence

1. Command-line arguments overwrite
2. Input file arguments overwrite
3. User-default arguments overwrite
4. Global defaults

Parameter list

An overview of all available parameters can be found in the doxygen documentation.

Excercise

Exercise

• Go to Runtime parameter exercise