Parameter file

Summary

Many functionalities of an AMDiS program can be controlled using a parameter file. This file is passed as first argument to the AMDiS executable. If we want to run the ellipt.2d example using the parameter file init/ellipt.dat.2d we can do so using the following console command in the examples directory:

./ellipt.2d init/ellipt.dat.2d [other arguments]

We will give a list of possible parameters at the end of this document.

Structure of a parameter file

Parameters in the parameter file have keys in the form of strings separated by ->. This allows grouping of parameters that are related to the same things. High-level classes like ProblemStat have a string constructor argument where a name can be provided that relates to an initfile key.

examples/ellipt.cc:
  using Param = LagrangeBasis<Grid, 2>;
  ProblemStat<Param> prob("ellipt");    // make a ProblemStat with the name 'ellipt'

examples/init/ellipt.dat.2d:
  ellipt->mesh: elliptMesh              % name of the mesh created by 'ellipt'
  elliptMesh->num cells: 8 8            % size of the mesh 'elliptMesh'

  ellipt->solver: pcg                   % solver type used by 'ellipt'
  ellipt->solver->max iteration: 10000  % solver parameter related to 'ellipt->solver'

As we saw above, parameters are separated from the keys with the : character and can be strings and numbers. Anything following a % character is considered a comment.

Reading from a parameter file

In the section above we learned that AMDiS classes can be given names that can then be used to specify parameters in the parameter file. In addition to the options AMDiS classes already provide we can add user-defined parameters. For this we simply have to add a key: value pair to the parameter file as we would do with the built-in options and read the value somewhere in our program using the function Parameters::get<T>:

// (1) Overwrites 'value' with the value related to 'key' if found
template <class T>
static void get(std::string const& key, T& value);

// (2) Returns a std::optional containing the value related to 'key' if found
template <class T>
static std::optional<T> get(std::string const& key);

We will now give an example of reading an int parameter called myParameter from an initfile that defaults to 3 if no parameter file containing the key is provided.

// example parameter file entry
myParameter: 42

// using (1)
int i = 3;
Parameters::get("myParameter", i);

// using (2)
int i = Parameters::get<int>("myParameter").value_or(3);

Writing to a parameter file

It is possible to change to value of a parameter given in a parameter file using the function

template <class T>
static void set(std::string const& key, T const& value);

This can be useful if we want to override certain values within our program.

List of parameters and values

In the following section <prefix> denotes a placeholder for the name given to the class instance. <treepath> is a (possibly empty) comma-separated list of integers specifying a TreePath.

ProblemStat

¹Only required when ProblemStat::restore is called
²No marker will be set up if the ->strategy subkey is not specified
³No filewriter will be set up if the ->format subkey is not specified

Markers

¹Only for maximum strategy
²Only for equidistribution strategy
³Only for guaranteed error reduction strategy

Solvers and Preconditioners

Parameters used by the SolverInfo class

PETSc

¹Only for lu preconditioner
²Only for richardson solver
³Only for gmres solver types
⁴Only for BiCGStab_ell solver
⁵Only for GCR solver

^aSee PETSc documentation for Krylov methods
^bSee PETSc documentation for Krylov method tolerances
^cSee PETSc documentation for Krylov method options
^dSee PETSc documentation for preconditioners
^eSee PETSc documentation for preconditioners
^fSee PETSc documentation for preconditioners
^gSee PETSc documentation for GMRes solver
^hSee PETSc documentation for GMRes solver

EIGEN

¹Requires UmfPack
²Requires SuperLU
³Only for gmres solver
⁴Only for dgmres solver
⁵Does not apply to umfpack or superlu solvers
⁶Only for incomplete Choleski factorization
⁷Only for ilu solver

MTL

¹Requires UmfPack
²Does not apply to umfpack solver
³Only umfpack solver
⁴Only bcgsl solver
⁵Only gmres, fgmres and gcr solvers
⁶Only gmres and fgmres solvers
⁷Only idrs solver
⁸Requires Hypre, see amdis/linearalgebra/mtl/HyprePrecon.hpp for subkeys and possible values
⁹Only solver preconditioner, subkeys use the same values as above e.g. <prefix>->precon->solver->max iteration: 500

ISTL

¹Requires dune-istl 2.7
²Requires external solver package
³Only for cg, pcg, fcg, cfcg, bcgs, minres, gmres and fgmres solvers
⁴Only for pcg and gmres solvers
⁵Only for superlu solver
⁶See amdis/linearalgebra/istl/AMGPrecon.hpp for subkeys and possible values
⁷Only solver preconditioner, subkeys use the same values as above e.g. <prefix>->precon->solver->max iteration: 500
⁸Only for bjacobi preconditioner, subkeys use the same values as above e.g. <prefix>->precon->sub precon->iterations: 1
⁹Checks global parameter solver category if not set

Grids

¹If no file name is given a structured grid will be constructed
²Only for structured grid generation
³YaspGrid only

Adaptivity

Parameters used by the AdaptInfo class

¹If this is set to a nonzero value the computation is done number of timesteps times with a fixed time step size

Parameters used by the AdaptInstationary class

Filewriters

¹One filewriter will be set up for each format string in the list
²Requires the dune-vtk module
³Only for vtk format
⁴Only for dune-vtk format
⁵Only for gmsh format
⁶Only for backup format