# DORiE 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 (.)

• 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


## 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¶

#### general¶

Parameter Definition Possible values Default Queried at
generator Specifies which parameter field generator module should be used. image, csv, fft, hdf5 csv
inputFile Path to file holding the parameter distribution data (i.e., image, CSV file, or HDF5 file). Has no effect when using FFT generator. path None
outputFile Output file name of the parameter field array. path field.h5
parameterization Parameterization to be used when mapping field value to parameter. Essentially sets which parameters.<parameterization>.<x> values should be used. vanGenuchten vanGenuchten
overwrite Whether an existing parameter field array should be overwritten. bool false

#### parameters.vanGenuchten.1¶

Parameter Definition Possible values Default Queried at
theta_r Residual water content of medium 1, used in the Mualem-van Genuchten parameterization. Default values for sand, according to Soil Physics, p. 92. float 0.03
theta_s Saturated water content. float 0.32
alpha log10(α) in the van Genuchten parameterization. Units: [1/m] float -2.3
tau τ in the Mualem parameterization of the hydraulic permeability. float -1.1
n n in the van Genuchten parameterization. float 4.17
k0 Saturated hydraulic conductivity. Units: [m/s] float 2.2E-5

#### parameters.vanGenuchten.2¶

Parameter Definition Possible values Default Queried at
theta_r Residual water content of medium 2, used in the Mualem-van Genuchten parameterization. Default values for silt, according to Soil Physics, p. 92. float 0.01
theta_s Saturated water content. float 0.41
alpha log10(α) in the van Genuchten parameterization. Units: [1/m] float -0.7
tau τ in the Mualem parameterization of the hydraulic permeability. float .0
n n in the van Genuchten parameterization. float 1.3
k0 Saturated hydraulic conductivity. Units: [m/s] float 1E-5

#### generator¶

Parameter Definition Possible values Default Queried at
millerSimilarity Whether to use Miller similarity or not. If set to true, only the first specified parameter set is used. Also, make sure to set a proper variance. bool false
dimensions Spatial dimension of the created field. 3-dimensional fields are only supported by the fft and hdf5 generators. 2, 3 2 dorie-rfg.cc:67
variance Variance of the resulting field, if millerSimilarity is used. float 0.2
extensions Physical extensions of the created field. float × float (× float) 1 1

#### generator.fft¶

Parameter Definition Possible values Default Queried at
outputPath Path to the output folder of the generated field. Note that this only accepts a folder, not a file name (file names are fixed). path /tmp/fft_generator/ dorie-rfg.cc:70
N Suggested size (in cells) of the created random field. int × int (× int) 1000 1000
correlationLengths Correlation lengths in each dimension of the random field, in meters. float × float (× float) .1 .05
seed Seed of all random number generators involved. Ensures reproducibility (the same seed will always lead to the same random field). int 123456789 dorie-rfg.cc:89
covariance Defines which variogram function should be used to create the random field. exponential, gaussian, spherical gaussian

### Main Routine¶

#### output¶

Parameter Definition Possible values Default Queried at
verbose Overall verbosity of the program 0, 1, 2, 3 0

dorie.cc:118

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

dorie.cc:119

dorie.cc:131

fileName Base file name for VTK output. string None interface/output.hh:79
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. true, false false interface/output.hh:96
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! int 0
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. true, false false interface/output.hh:87

#### grid¶

Parameter Definition Possible values Default Queried at
gridType Grid geometry. The grid can either be structured rectangular / cubic (rectangular) or unstructured triangular / tetrahedral (gmsh). The former does not require any additional input, while in the latter case a gmsh file with the corresponding grid is to be given. rectangular, gmsh rectangular dorie.cc:115
dimensions Dimensionality of the domain. 2, 3 2 dorie.cc:116
FEorder Order of the finite element method used. Values > 1 are not thoroughly tested. 1, 2, 3 1 dorie.cc:117
gridFile Path to the gmsh file containing the grid if gridType is set to gmsh. path None …util_grid_creator.hh:89
extensions Physical extensions of the domain in meters. Given in x, then y, then z-direction. If a mesh file is imported, they have to match its maximum extensions. float × float (× float) 1 1
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). int × int (× int) 100 100 …util_grid_creator.hh:139
initialLevel Initial level of refinement of the grid. 0 means no refinement. int 0

#### boundary¶

Parameter Definition Possible values Default Queried at
file Path to the boundary condition file. path None

dorie.cc:130

fileType Type of spatial segmentation of the boundaries specified in the BC file rectangularGrid rectangularGrid …richards_boundary.hh:42
interpolateBCvalues Whether to interpolate between the boundary conditions at different times linearly (true) or not at all (false). May require different boundary condition files. true, false false …oundary_condition.hh:128

#### initial¶

Parameter Definition Possible values Default Queried at
condition There are currently two possible initial conditions to choose from: A constant potential throughout the domain (gravityFlow), or a linear potential gradient (hydrEquilibrium). hydrEquilibrium, gravityFlow hydrEquilibrium …/richards_initial.hh:43
headLower Initial matric head at the lower boundary of the domain float 0 …/richards_initial.hh:45

#### time¶

Parameter Definition Possible values Default Queried at
start Starting time in seconds. float 0
end Ending time in seconds. float 1E6
minTimestep Minimum time step that is allowed before DORiE stops running. with an error, in seconds. float 0.1 …r/util_controller.hh:41
startTimestep Value of the first time step in seconds. float 10 …r/util_controller.hh:38
maxTimestep Largest allowed time step in seconds. Use this to control the density of your output. float 1E5 …r/util_controller.hh:40
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. int 1 …r/util_controller.hh:47
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. int 12 …r/util_controller.hh:46
timestepIncreaseFactor Factor the current time step is multiplied with when increasing the time step. float > 1 1.5 …r/util_controller.hh:43
timestepDecreaseFactor Factor the current time step is multiplied with when decreasing the time step. float < 1 0.5 …r/util_controller.hh:44

#### parameters¶

Parameter Definition Possible values Default Queried at
arrayFile Path to an HDF5 array file containing all parameters used in the chosen parameterization. Can be created using the dorie pfg command. path None …ver/param_factory.hh:39
scale Scaling factor of the parameter field. A value > 1 zooms into the field; a value < 1 zooms out. This may of course change the statistical properties of the field (e.g. correlation lengths). float × float (× float) 1 1 solver/param_base.hh:114
offset The parameter field is shifted by this value (in physical units) float × float (× float) 0 0 solver/param_base.hh:115
interpolation Sets the interpolation behavior when querying parameter field values at a certain grid cell. Higher-order interpolation smoothes the parameter field, but comes at a computational cost. nearest, linear, cubic nearest

#### dg¶

Parameter Definition Possible values Default Queried at
penaltyFactor Penalty factor to be used in the Discontinuous Galerkin scheme float 10

#### NewtonParameters¶

Parameter Definition Possible values Default Queried at
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. true, false false
AbsoluteLimit Absolute error tolerance of the Newton solver. Reduce this value to increase precision. 1E-11 < float < 1E-8 1E-10
Reduction Relative error tolerance of the Newton solver. Reduce this value to increase precision. float 1E-4
ReassembleThreshold If the ratio between last and current calculation defect exceeds this value, the linear operator matrix is reassembled to ensure convergence. float 5E-2
LineSearchMaxIterations Maximum iteration count of linear searches performed to deduce the optimal damping factor for reducing the defect. int 10
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. float 1E-3

Parameter Definition Possible values Default Queried at
useAdaptivity Switches adaptive grid refinement (h-adaptivity) on (true) or off (false). If enabled, an unstructured grid manager with higher computational cost is used when using rectangular / cubic grids. true, false false dorie.cc:120
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. int 10 …erface/adaptivity.hh:92
minLevel Minimum refinement level of the grid. Grid cells will not get coarsened below this level. int 0 …erface/adaptivity.hh:93
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 β.

targetTolerance: All elements with a local error η > α are being refined as often as necessary until the requirement η < α is met for all grid cells. Coarsening occurs for all elements that carry an error smaller than β.

elementFraction, errorFraction, targetTolerance, threshold elementFraction …erface/adaptivity.hh:94
refinementFraction The value of α for the chosen markingStrategy. float 0.1 …erface/adaptivity.hh:95
coarseningFraction The value of β for the chosen markingStrategy. float 0.2 …erface/adaptivity.hh:96
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. float 1E-8 …erface/adaptivity.hh:97

#### misc¶

Parameter Definition Possible values Default Queried at
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. true, false false dorie.cc:100

#### dg.experimental¶

Parameter Definition Possible values Default Queried at
method

DG discretization method for skeleton terms.

SIPG: Symmetric Interior Penalty

NIPG: Non-Symmetric Interior Penalty

OOB: Oden, Babuska, Baumann: no penalty term

IIP: Incomplete Interior Penalty: no symmetry term

SIPG, NIPG, OOB, IIP SIPG …olver/operator_DG.hh:81
upwinding

Upwinding method for skeleton terms.

semiUpwind: Apply upwinding to conductivity factor (only).

fullUpwind: Apply upwinding on numeric flux and conductivity.

none, semiUpwind, fullUpwind none …olver/operator_DG.hh:94
weights Apply harmonic weighting to skeleton term contributions. true, false true …olver/operator_DG.hh:104