Parameter

Handling Parameters, i.e., values that can be set after compilation, in dune-fem is extremely easy. Just add

Dune::Fem::MPIManager::initialize( argc, argv );
Dune::Fem::Parameter::append( argc, argv );

at the head of your main function. Parameters are strings of the format "key: value". Any command line argument containing a colon will thus be interpreted as a parameter.

Note

All parameter keys are case sensitive.

Found parameters are removed from the command line.

There are 8 static methods in Parameter to obtain the value of a parameter. They are divided by the following criteria:

• Default Value: The methods taking a default value will return the default, if the parameter has not been specified by the user. Additionally, they will add "\e key : \e value" to the database. The methods not taking a default value will throw an exception, if the parameter could not be found in the database.
• Return Value: For convenience, there is always a method (called getValue) returning the value of the parameter. If you do not want to rely on return value optimization, use the method (called get) taking a reference to the return variable as an argument.
• Validation: It is often necessary to make sure the value satisfies certain constraints. For this purpose, some methods take a validator as an argument.

Of course, you don't have to pass every parameter on the command line. They can also be gathered in files. Parameter provides a kind of include mechanism. Whenever a parameter with key "paramfile" is encountered, the value is interpreted as a paramter file to include.

Fem parameters can also be appended to the parameter list via an DGF file. The method

appendDGF( "macrogrid.dgf" );

reads in the DGF-block:

FemParameter
 
#

from file "macrogrid.dgf". All parameters defined within this block are appended to the parameter list.

If a parameter is defined multiply, the first definition is added to the database. All later definitions are ignored. Therefore it is important to know the exact behaviour of the "paramfile" parameter:

• All parameters in the current file (or the command line) are added first.
• If there were includes, they are processed in the order of appearance.
• Should an included file have includes, they are added depth-first, i.e., The includes of one included file are parsed down to the last file included, before the includes of the next included file are considered.

All parameter names defined by dune-fem should conform to the following naming convention:

fem.<group>.<parameter>

The group name can be omitted if necessary.

An example is the parameter

fem.verboserank

This can beused throughout the the program; by calling:

Parameter::verbose()

If verbose is set, information concerning the parameters read will be output to stdout.

Parameter Substitution: Parameter can consist of parts of other parameters. In order to resolve this dependency, the substituted parameter is put into brackets. A smale example for this is

N: 128
parameter1: macrogrid_$(N).dgf

results in

parameter1: macrogrid_128.dgf

This can be used when on parameter controls several other parameters, such like the number of cells in the macrogrid.

Shell Program executions:Out of the Parameter file shell scripts/commands can be called in order to calculate the value of a parameter. The object which should be executed has to be put into $[command] brackets.

parameter1: $[ ./script.sh]

with the script.sh

#!/bin/bash
echo 'HalloWorld';

This smale example resolves the parameter to have the value 'HalloWorld'

If $ is used explicite in a parameter value, $$ kills the substitution of the parameter.

Here is an example usage:

#include <dune/fem/io/parameter.hh>
 
int globalFlag;
 
int main ( int argc, char **argv )
{
  Dune::Fem::MPIManager::initialize( argc, argv );
  Dune::Fem::Parameter::append( argc, argv );
 
  // get parameters
  double startTime = Parameter::getValue< double >( "starttime", 0.0 );
  auto validator = [ startTime ]( double time ) { return time > startTime; };
  double endTime = Parameter::getValidValue< double >( "endtime", validator );
 
  Dune::Fem::Parameter::get( "flag", 0, globalFlag );
 
  if( Dune::Fem::Parameter::verbose() )
    std::cout << "Computing from " << startTime << " to " << endTime << std::endl;
 
  // ...
 
  std::ofstream results( Dune::Fem::Parameter::outputPrefix() + "/results" );
 
  // ...
 
  Dune::Fem::Parameter::write( "parameter.log" );
}

Parameter deprecation Sometimes parameter names are changed and it can be difficult to find all occurrences of the old parameter in the code. To help with the transition it is possible to deprecate parameters by adding the line

deprecated: old_name

This will cause an exception to be thrown by any attempt in the code to access the value of the parameter using the old name.