Configuration File Guide

File Syntax

The Parameter File follows a simple syntax derived from the DUNE ParameterTree Parser:

heading ::=  '[', key, { '.', key }, ']'
line    ::=  key, { '.', key }, '=', { value }
key     ::=  string | int
value   ::=  string | { double } | { int }

A set of rules defines this syntax:

  • Every key (or every set of keys, respectively) must be unique

  • Empty lines and (remnants of) lines following a hash (#) are ignored

  • Keys must not contain spaces

  • For vector values, the vector entries are separated by spaces.

  • String valued entries may not contain spaces or have to be contained by quotes ("). However, doing the latter is not recommended.

  • Keys can be nested and are separated by dots (.)

  • Headings can be nested within their heading declaration and last until the next heading declaration.

  • When parsed, headings are placed in front of the actual keys, i.e.

    [heading1.heading2]
    key1.key2 = value
    key1.key3 = value
    

    is equivalent with

    heading1.heading2.key1.key2 = value
    heading1.heading2.key1.key3 = value
    

Cheat Sheets

These cheat sheets are automatically generated by the Parameter Scraper. The configuration files are used for the Parameter Field Generator module and the main simulation routine. They are executed by dorie pfg <config> and dorie run <config>, respectively, see the CLI documentation.

Parameter Field Generator

Category: [general]

outputFile

Output file path of the parameter field array.

Possible values

path

Default value

field.h5

Queried at

dataset

The dataset name inside the outputFile.

New in version 2.0.0.

Possible values

path

Default value

None

Queried at

converter

Identifier of the random field converter. The converter is applied after the random field is created and modifies it.

Use exponential for creating a suitable Miller scaling field.

New in version 2.0.0.

Possible values

none, binary, exponential

Default value

binary

Queried at

tempDir

Temporary output directory of the dune-randomfield module. Note that this only accepts a folder (file names are fixed).

Changed in version 2.0.0: Renamed from generator.fft.outputPath.

Possible values

path

Default value

/tmp/fft_generator/

Queried at

Category: [grid]

dimensions

Physical dimensions of the field.

Changed in version 2.0.0: Renamed from generator.dimensions.

Possible values

2, 3

Default value

2

Queried at

extensions

Physical extensions of the created random field. This information is not used by DORiE but required for meaningful correlation lengths (see grid.corrLength below).

New in version 2.0.0.

Possible values

int × int (× int)

Default value

1 1

Queried at

cells

Resolution (in grid cells) of the created random field.

Changed in version 2.0.0: Renamed from generator.fft.N.

Possible values

int × int (× int)

Default value

100 100

Queried at

Category: [stochastic]

seed

Seed of all random number generators involved. The same seed will lead to the same random field, if the application is used with the same settings (compiler, number of parallel processes, …)

Changed in version 2.0.0: Renamed from generator.fft.seed.

Possible values

int

Default value

1

Queried at

variance

Variance of the resulting field.

New in version 2.0.0.

Possible values

float

Default value

0.2

Queried at

corrLength

Physical correlation lengths for axiparallel anisotropy. Specify one value for each dimension of the field.

Changed in version 2.0.0: Renamed from generator.fft.correlationLenghts.

Possible values

float × float (× float)

Default value

.1 .05

Queried at

covariance

Defines which variogram function should be used to create the random field.

Changed in version 2.0.0: Renamed from generator.fft.covariance.

Possible values

exponential, gaussian, spherical, whiteNoise

Default value

gaussian

Queried at

Category: [converter.binary]

indices

Binary values A and B to transform the field into. The field will be set to A where its value is less equal 0, and B where its value is greater 0.

New in version 2.0.0.

Possible values

int

Default value

0 1

Queried at

Category: [converter.exponential]

varianceScaling

Substract the variance from the random field values before applying the exponential. For a random field with gaussian covariance, this will result in a conductivity field with the same macroscopic properties that a homogeneous field, in the sense that average water flux is the same (Roth 1995).

New in version 2.0.0.

Possible values

bool

Default value

true

Queried at

Main Routine

Depending on the simulation.mode, the respective model categories will be read. The parameters without model prefix are always evaluated.

New in version 2.0.0: Added transport model parameters.

Changed in version 2.0.0: Split parameters into default and richards model parameters.

Category: [simulation]

mode

Sets the simulation mode of DORiE. (richards) mode calculates the matric head with a DG scheme and produce water fluxes with Raviart Thomas reconstruction. (richards+transport) mode calculates (richards) mode and use the generated water flux and saturation at each step to calculate the solute transport model for unsaturated media with a DG scheme.

New in version 2.0.0.

Possible values

richards, richards+transport

Default value

richards

Queried at

Category: [grid]

gridType

Grid geometry. The grid can either be structured rectangular / cubic (rectangular) or unstructured triangular / tetrahedral (gmsh).

For rectangular grids, the grid extensions, the number of cells, and the [grid.mapping] must be specified. These keys are ignored for gmsh grids, where the mesh file contains all associated information.

Possible values

rectangular, gmsh

Default value

rectangular

Queried at

dimensions

Dimensionality of the domain.

Possible values

2, 3

Default value

2

Queried at

gridFile

Path to the gmsh file containing the grid if gridType is set to gmsh. If a rectangular grid is built, this value is ignored.

Possible values

path

Default value

None

Queried at

extensions

Physical extensions of the domain in meters. Given in x, then y, then z-direction. If a mesh file is imported, these values are ignored.

Possible values

float × float (× float)

Default value

1 1

Queried at

cells

Initial number of cells in each dimension (x, then y, then z) if gridType is set to rectangular. This represents the coarsest level of the grid (i.e., refinement level 0). If a mesh file is imported, these values are ignored.

Possible values

int × int (× int)

Default value

100 100

Queried at

initialLevel

Initial level of refinement of the grid. 0 means no refinement.

Possible values

int

Default value

0

Queried at

Category: [grid.mapping]

file

The H5 file containing all mapping datasets. Leave empty or set to None for global mappings. All values in this section are ignored if a mesh file is imported.

New in version 2.0.0.

Possible values

path

Default value

None

Queried at

volume

The H5 dataset containing the mapping from cell to medium index. May specify a global index for the entire volume if its value can be parsed as int.

New in version 2.0.0.

Possible values

path or int

Default value

0

Queried at

boundaryLower

The H5 dataset mapping the lower boundary faces to boundary condition indices. May specify a global index for the boundary if its value can be parsed as int.

New in version 2.0.0.

Possible values

path or int

Default value

0

Queried at

boundaryUpper

The H5 dataset mapping the upper boundary faces to boundary condition indices. May specify a global index for the boundary if its value can be parsed as int.

New in version 2.0.0.

Possible values

path or int

Default value

1

Queried at

boundaryLeft

The H5 dataset mapping the left boundary faces to boundary condition indices. May specify a global index for the boundary if its value can be parsed as int.

New in version 2.0.0.

Possible values

path or int

Default value

2

Queried at

boundaryRight

The H5 dataset mapping the right boundary faces to boundary condition indices. May specify a global index for the boundary if its value can be parsed as int.

New in version 2.0.0.

Possible values

path or int

Default value

3

Queried at

boundaryFront

The H5 dataset mapping the front boundary faces to boundary condition indices (3D only). May specify a global index for the boundary if its value can be parsed as int.

New in version 2.0.0.

Possible values

path or int

Default value

4

Queried at

boundaryBack

The H5 dataset mapping the back boundary faces to boundary condition indices (3D only). May specify a global index for the boundary if its value can be parsed as int.

New in version 2.0.0.

Possible values

path or int

Default value

5

Queried at

Category: [adaptivity]

policy

Switches the target policy to do adaptive grid refinement (h-adaptivity). If enabled, an unstructured grid manager with higher computational cost is used when using rectangular / cubic grids.

New in version 2.0.0: Replaces useAdaptivity.

Possible values

none, waterFlux

Default value

none

Queried at

maxLevel

The maximum refinement level kept in the grid. This is a useful tool to prevent over-refinement. If this value is high, the grid can be refined to an arbitrary degree, leading to an evenly distributed error across the grid. Make sure you avoid refinement levels which imply grid cell sizes beyond the Richards continuum scale.

Possible values

int

Default value

10

Queried at

minLevel

Minimum refinement level of the grid. Grid cells will not get coarsened below this level.

Possible values

int

Default value

0

Queried at

markingStrategy

Marking strategy used in order to find the grid cells that should be refined / coarsened.

  • elementFraction: Of the N elements in the sorted list of local errors, the first αN elements are refined while the last βN elements are being coarsened.

  • errorFraction: Refine (coarse) as many elements as necessary, such that the total relative contribution of all refined (coarsened) cells to the global error is α (β), starting with the most (least) contributing element. The total number of affected entities can vary greatly between different iterations, and (with α = β) much more elements are coarsened than refined.

  • threshold: All elements with a local error η > α are being refined once. Coarsening occurs for all elements that carry an error smaller than β.

Changed in version 2.0.0: Option targetTolerance removed.

Possible values

elementFraction, errorFraction, threshold

Default value

elementFraction

Queried at

refinementFraction

The value of α for the chosen markingStrategy.

Possible values

float

Default value

0.1

Queried at

coarseningFraction

The value of β for the chosen markingStrategy.

Possible values

float

Default value

0.2

Queried at

threshold

Grid refinement is skipped entirely for the given time step if all grid elements carry an error lower than this value. This is to only make the grid as fine as necessary.

Possible values

float

Default value

1E-8

Queried at

Category: [output]

logLevel

Logging level of the core functions.

Possible values

trace, debug, info, warning, error, critical

Default value

info

Queried at

Category: [misc]

debugMode

Switches debug mode on (true) or off (false). In debug mode, the execution of DORiE stops immediately until a developer hooks into the process with a debugger and sets the variable i to a value > 0. Only intended for use by developers.

Possible values

true, false

Default value

false

Queried at

Category: [richards.output]

logLevel

Logging level of the Richards solver.

New in version 2.0.0.

Possible values

trace, debug, info, warning, error, critical

Default value

info

Queried at

outputPath

Path to the directory where most of the outputs are stored. DORiE will attempt to create it if it does not exist.

Possible values

path

Default value

output_richards

Queried at

fileName

Base file name for VTK output.

Possible values

string

Default value

output_richards

Queried at

vertexData

Plot vertex based (true) or cell-centered (false) data into VTK files. Prefer vertex over cell data for full-precision output. System tests and plotting functions (dorie plot) require cell- centered data.

Possible values

true, false

Default value

true

Queried at

policy

Policy when to write the data. none disables output for this model.

New in version 2.0.0.

Possible values

endOfRichardsStep, none

Default value

endOfRichardsStep

Queried at

subsamplingLevel

Plot VTK files with virtually refined grids. VTK only supports bilinear triangulations and displays higher-order solutions inappropriately. Use level 0 for order 1, and level N for order N. For level > 0, the printed grid does not resemble the actual grid. This parameter defaults to 0 if not given in the config file. Notice that subsampling significantly increases the output file size!

Possible values

int

Default value

0

Queried at

asciiVtk

Defines whether VTK files should be written as ASCII (true) or binary (false). ASCII is easier to parse in case you want to write your own post-processing, but takes a lot more space on your hard drive.

Possible values

true, false

Default value

false

Queried at

Category: [richards.boundary]

file

Path to the YAML boundary condition data file.

Changed in version 2.0.0: Expects a YAML file now.

Possible values

path

Default value

richards_bc.yml

Queried at

Category: [richards.initial]

type

The data type representing the initial condition. Either an HDF datafile (data), analytic equations (analytic), or a solution of the stationary flow problem (stationary).

New in version 2.0.0.

Possible values

data, analytic, stationary

Default value

analytic

Queried at

quantity

The physical quantity represented by the initial condition data or equation.

New in version 2.0.0.

Possible values

matricHead, waterContent

Default value

matricHead

Queried at

equation

Equation for the initial condition

New in version 2.0.0.

Possible values

equation [x,y,z,h]

Default value

-h

Queried at

file

Path to the initial condition data file (data type only). DORiE currently only supports H5 files with file extension .h5.

New in version 2.0.0.

Possible values

path

Default value

None

Queried at

dataset

Dataset to use as initial condition (data type only).

New in version 2.0.0.

Possible values

string

Default value

None

Queried at

interpolation

Interpolation type used for the data (data type only).

New in version 2.0.0.

Possible values

nearest, linear

Default value

linear

Queried at

Category: [richards.time]

start

Starting time in seconds.

Possible values

float

Default value

0

Queried at

end

Ending time in seconds.

Possible values

float

Default value

1E6

Queried at

minTimestep

Minimum time step that is allowed before DORiE stops running. with an error, in seconds.

Possible values

float

Default value

0.1

Queried at

startTimestep

Value of the first time step in seconds.

Possible values

float

Default value

10

Queried at

maxTimestep

Largest allowed time step in seconds. Use this to control the density of your output.

Possible values

float

Default value

1E5

Queried at

minIterations

Minimum number of Newton iterations of the solver per time step. At maxTimestep, the Newton solver is not allowed to calculate more than this number of iterations.

Possible values

int

Default value

1

Queried at

maxIterations

Maximum number of Newton iterations of the solver per time step. At minTimestep, the Newton solver is not allowed to calculate more than this number of iterations.

Possible values

int

Default value

12

Queried at

timestepIncreaseFactor

Factor the current time step is multiplied with when increasing the time step.

Possible values

float > 1

Default value

1.5

Queried at

timestepDecreaseFactor

Factor the current time step is multiplied with when decreasing the time step.

Possible values

float < 1

Default value

0.5

Queried at

Category: [richards.parameters]

file

YAML file containing the parameter definitions.

Possible values

path

Default value

richards_param.yml

Queried at

Category: [richards.numerics]

FEorder

Polynomial order of the DG method used. Setting this value to 0 (zero) selects the finite volume (FV) solver (only compatible to structured rectangular grids).

Changed in version 2.0.0: Renamed from grid.FEorder.

Possible values

0, 1, 2, 3

Default value

1

Queried at

upwinding

Upwinding method for skeleton terms. Upwinding typically increases numeric stability while reducing accuracy.

  • semiUpwind: Apply upwinding to conductivity factor (only).

  • fullUpwind: Apply upwinding to conductivity. Not recommended for DG, but for FV.

Changed in version 2.0.0: Renamed from dg.experimental.upwinding.

Possible values

none, semiUpwind, fullUpwind

Default value

none

Queried at

DGMethod

DG discretization method for skeleton terms.

  • SIPG: Symmetric Interior Penalty

  • NIPG: Non-Symmetric Interior Penalty

  • OBB: Oden, Babuska, Baumann: no penalty term

  • IIP: Incomplete Interior Penalty: no symmetry term

Changed in version 2.0.0: Renamed from dg.experimental.method.

Possible values

SIPG, NIPG, OBB, IIP

Default value

SIPG

Queried at

DGWeights

Apply harmonic weighting to skeleton term contributions in DG.

Changed in version 2.0.0: Renamed from dg.experimental.weights.

Possible values

true, false

Default value

true

Queried at

penaltyFactor

Penalty factor to be used in the Discontinuous Galerkin scheme

Changed in version 2.0.0: Renamed from dg.penaltyFactor.

Possible values

float

Default value

10

Queried at

Category: [richards.fluxReconstruction]

enable

Apply the flux reconstruction method to the solved matric head and obtain conservative gradients. It always computes (internally) the local lifting independent whether the lifting keyword is active or not.

New in version 2.0.0.

Possible values

true, false

Default value

true

Queried at

checkJumps

Check that flux reconstruction engine is creating conforming normal fluxes up to jumpTol. ProTip: Setting warnings together with a very low tolerance will let you track the changes on the quality of the flux reconstruction.

New in version 2.0.0.

Possible values

none, warn, error

Default value

none

Queried at

checkTol

Whenever checkJumps is activated, it check that flux reconstruction engine is creating conforming normal fluxes up to jumpTol.

New in version 2.0.0.

Possible values

float > 0

Default value

1E-10

Queried at

Category: [richards.NewtonParameters]

ForceIteration

Force the Newton solver to calculate at least one iteration, even if the initial defect is below AbsoluteLimit. This ensures that dynamics cannot be ‘skipped’ at very small time steps.

Possible values

true, false

Default value

false

Queried at

AbsoluteLimit

Absolute error tolerance of the Newton solver. Reduce this value to increase precision.

Possible values

1E-11 < float < 1E-8

Default value

1E-10

Queried at

Reduction

Relative error tolerance of the Newton solver. Reduce this value to increase precision.

Possible values

float

Default value

1E-4

Queried at

ReassembleThreshold

If the ratio between last and current calculation defect exceeds this value, the linear operator matrix is reassembled to ensure convergence.

Possible values

float

Default value

5E-2

Queried at

LineSearchMaxIterations

Maximum iteration count of linear searches performed to deduce the optimal damping factor for reducing the defect.

Possible values

int

Default value

10

Queried at

MinLinearReduction

Required defect reduction of the linear solver. The Newton solver calculates the required linear reduction for second order Newton convergence automatically and chooses the smaller value of both.

Possible values

float

Default value

1E-3

Queried at

Category: [transport.output]

logLevel

Logging level of the Richards solver.

Possible values

trace, debug, info, warning, error, critical

Default value

info

Queried at

outputPath

Path to the directory where most of the outputs are stored. DORiE will attempt to create it if it does not exist.

Possible values

path

Default value

output_transport

Queried at

fileName

Base file name for VTK output.

Possible values

string

Default value

output_transport

Queried at

vertexData

Plot vertex based (true) or cell-centered (false) data into VTK files. Vertex based data might render sharp parameterization boundaries inappropriately. System tests and plotting functions (dorie plot) require cell-centered data.

Possible values

true, false

Default value

true

Queried at

policy

Policy when to write the data. none disables output for this model.

Possible values

endOfTransportStep, endOfRichardsStep, none

Default value

endOfRichardsStep

Queried at

writeDispersionTensor

Defines whether VTK files should include the hydrodynamic dispersion tensor. Tensors are written in 3D and have 9 componentents independently of the world dimension. This can be easily be visualizated in Paraview with the Tensor Glyph filter.

Possible values

true, false

Default value

false

Queried at

subsamplingLevel

Plot VTK files with virtually refined grids. VTK only supports bilinear triangulations and displays higher-order solutions inappropriately. Use level 0 for order 1, and level N for order N. For level > 0, the printed grid does not resemble the actual grid. This parameter defaults to 0 if not given in the config file. Notice that subsampling significantly increases the output file size!

Possible values

int

Default value

0

Queried at

asciiVtk

Defines whether VTK files should be written as ASCII (true) or binary (false). ASCII is easier to parse in case you want to write your own post-processing, but takes a lot more space on your hard drive.

Possible values

true, false

Default value

false

Queried at

Category: [transport.boundary]

file

Path to the YAML boundary condition data file.

Possible values

path

Default value

transport_bc.yml

Queried at

Category: [transport.initial]

type

The data type representing the initial condition. Either an HDF datafile (data), or analytic equations (analytic).

Possible values

data, analytic

Default value

analytic

Queried at

quantity

The physical quantity represented by the initial condition data.

  • soluteConcentration: Solute concentration in the water phase.

Possible values

soluteConcentration

Default value

soluteConcentration

Queried at

equation

Equation for the initial condition

Possible values

equation [x,y,z,h]

Default value

0

Queried at

file

Path to the initial condition data file (data type only). DORiE currently only supports H5 files with file extension .h5.

Possible values

path

Default value

None

Queried at

dataset

Dataset to use as initial condition (data type only).

Possible values

string

Default value

None

Queried at

interpolation

Interpolation type used for the data (data type only).

Possible values

nearest, linear

Default value

nearest

Queried at

Category: [transport.time]

start

Starting time in seconds.

Possible values

float

Default value

0

Queried at

end

Ending time in seconds.

Possible values

float

Default value

1E6

Queried at

minTimestep

Minimum time step that is allowed before DORiE stops running. with an error, in seconds.

Possible values

float

Default value

0.1

Queried at

startTimestep

Value of the first time step in seconds.

Possible values

float

Default value

10

Queried at

maxTimestep

Largest allowed time step in seconds. Use this to control the density of your output.

Possible values

float

Default value

1E5

Queried at

timestepIncreaseFactor

Factor the current time step is multiplied with when increasing the time step.

Possible values

float > 1

Default value

1.5

Queried at

timestepDecreaseFactor

Factor the current time step is multiplied with when decreasing the time step.

Possible values

float < 1

Default value

0.5

Queried at

Category: [transport.parameters]

file

YAML file containing the parameter definitions.

Possible values

path

Default value

transport_param.yml

Queried at

Category: [transport.numerics]

timestepMethod

Numerical scheme to perform time steps in the simulation. alex2 and implicit_euler are implicit methods. explicit_euler is a explicit method.

Possible values

explicit_euler, implicit_euler, alex2

Default value

alex2

Queried at

courant

Courant number for explicit methods. Serves as multiplier of the CFL condition which estimates the maximum time step based on effective velocity and grid element size. Reduce this value if the solution is unstable. Notice that doing so also limits the maximum time step and hence increases the overall simulation time.

Possible values

0 < float < 1

Default value

0.5

Queried at

FEorder

Polynomial order of the DG method used. Setting this value to 0 (zero) selects the finite volume (FV) solver (only compatible to structured rectangular grids).

Possible values

0, 1, 2, 3

Default value

1

Queried at

upwinding

Enable upwinding for the convective flux term. Upwinding leads to quasi-optimal error estimates of convective flux problems and is therefore recommended for DG schemes. For FV, upwinding is always enabled.

Possible values

true, false

Default value

true

Queried at

DGMethod

DG discretization method for skeleton terms.

  • SIPG: Symmetric Interior Penalty

  • NIPG: Non-Symmetric Interior Penalty

  • OBB: Oden, Babuska, Baumann: no penalty term

  • IIP: Incomplete Interior Penalty: no symmetry term

Possible values

SIPG, NIPG, OBB, IIP

Default value

SIPG

Queried at

DGWeights

Apply harmonic weighting to skeleton term contributions in DG.

Possible values

true, false

Default value

true

Queried at

penaltyFactor

Penalty factor to be used in the Discontinuous Galerkin scheme

Possible values

float

Default value

10

Queried at

Category: [transport.fluxReconstruction]

enable

Apply the flux reconstruction method to the solved solute concentration and obtain conservative fluxes.

Possible values

true, false

Default value

true

Queried at

checkJumps

Check that flux reconstruction engine is creating conforming normal fluxes up to jumpTol. ProTip: Setting warnings together with a very low tolerance will let you track the changes on the quality of the flux reconstruction.

Possible values

none, warn, error

Default value

none

Queried at

checkTol

Whenever checkJumps is activated, it check that flux reconstruction engine is creating conforming normal fluxes up to jumpTol.

Possible values

float > 0

Default value

1E-10

Queried at

Category: [transport.solutionCheck]

negativeConcentration

Check for negative solute concentrations in the computed solution.

  • pass: Pass silently when negative values are encountered.

  • warn: Issue a warning when finding negative values, but continue the computation.

  • retry: Discard the computed solution, and repeat it with a reduced time step size according to the transport.time settings.

Possible values

pass, warn, retry

Default value

retry

Queried at

negativeTol

Relative tolerance when checking negative values. This factor is multiplied with the largest value of the current solute concentration.

Possible values

float > 0

Default value

1E-6

Queried at

Category: [transport.solverParameters]

reduction

Required relative defect reduction in the linear solver. Reduce this value to increase precision.

Possible values

float

Default value

1E-8

Queried at

min_defect

Minimum absolute defect at which linear solver stops. Reduce this value to increase precision.

Possible values

float

Default value

1E-20

Queried at