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 ignoredKeys 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¶
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 |
generator.image¶
generator.csv¶
generator.h5¶
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 |
| headGradient | Gradient of the matric head towards the upper boundary (positive y coordinate). | float | -1 | …/richards_initial.hh:44 |
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 |
adaptivity¶
| 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 |