parameters.xml 14.9 KB
Newer Older
Dion Haefner's avatar
Dion Haefner committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64
<?xml version="1.0" encoding="UTF-8"?>

<!--
If you want to use any special characters, you will need to define them here.
A full list is found at https://www.w3.org/TR/REC-html40/sgml/entities.html
-->

<!DOCTYPE naughtyxml [
    <!ENTITY alpha "&#945;">
    <!ENTITY beta "&#946;">
    <!ENTITY eta "&#951;">
    <!ENTITY tau "&#964;">
    <!ENTITY times "&#215;">
]>

<!--
XML file hierarchy:
<dorie> -> <category> -> <parameter> -> (parameter attributes)

Possible parameter attributes:

  definition: meaning of the parameter, will only show up in html output
  suggestion: standard value in created parameter files
  values: possible values, will only show up in html output
  comment: extra comment, will only show up in parameter files

All attributes are optional.

The parser supports rudimentary markdown / styling. You can add a paragraph by
adding an empty line, make text **bold** or ``monospaced``.
-->

<dorie>
  <category name="output">
    <parameter name="verbose">
      <definition> Overall verbosity of the program </definition>
      <suggestion> 0 </suggestion>
      <values> 0, 1, 2, 3 </values>
    </parameter>

    <parameter name="outputPath">
      <definition> Path to the directory where most of the outputs are stored.
         DORiE will attempt to create it if it does not exist. </definition>
      <suggestion> ./ </suggestion>
      <values> path </values>
    </parameter>

    <parameter name="fileName">
      <definition> Base file name for VTK output. </definition>
      <values> string </values>
    </parameter>

    <parameter name="asciiVtk">
      <definition> 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.
      </definition>
      <values> true, false </values>
      <suggestion> false </suggestion>
    </parameter>
  </category>

  <category name="grid">
    <parameter name="gridType">
Dion Haefner's avatar
Dion Haefner committed
65 66
      <definition> Grid geometry. The grid can either be structured rectangular / cubic
        (``rectangular``) or unstructured triangular / tetrahedral (``gmsh``). The former does not
Dion Haefner's avatar
Dion Haefner committed
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
        require any additional input, while in the latter case a gmsh file with
        the corresponding grid is to be given. </definition>
      <suggestion> rectangular </suggestion>
      <values> rectangular, gmsh </values>
      <comment> Choose grid type: rectangular, gmsh </comment>
    </parameter>

    <parameter name="dimensions">
      <definition> Dimensionality of the domain. </definition>
      <suggestion> 2 </suggestion>
      <values> 2, 3 </values>
    </parameter>

    <parameter name="FEorder">
      <definition> Order of the finite element method used. Values &gt; 1 are not
        thoroughly tested. </definition>
      <suggestion> 1 </suggestion>
84
      <values> 1, 2, 3 </values>
Dion Haefner's avatar
Dion Haefner committed
85 86 87 88 89 90 91 92 93 94
    </parameter>

    <parameter name="gridFile">
      <definition> Path to the gmsh file containing the grid if ``gridType`` is set
        to ``gmsh``. </definition>
      <values> path </values>
    </parameter>

    <parameter name="extensions">
      <definition> Physical extensions of the domain in meters. Given in x, then y,
95 96
        then z-direction. If a mesh file is imported, they have to match its maximum
        extensions. </definition>
Dion Haefner's avatar
Dion Haefner committed
97 98 99 100 101 102
      <values> float &times; float (&times; float) </values>
      <suggestion> 1 1 </suggestion>
    </parameter>

    <parameter name="cells">
      <definition> Initial number of cells in each dimension (x, then y, then z) if ``gridType``
103 104
        is set to ``rectangular``. This represents the coarsest level of the grid
        (i.e., refinement level 0). </definition>
Dion Haefner's avatar
Dion Haefner committed
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179
      <values> int &times; int (&times; int) </values>
      <suggestion> 100 100 </suggestion>
    </parameter>

    <parameter name="initialLevel">
      <definition> Initial level of refinement of the grid. 0 means no refinement.
      </definition>
      <values> int </values>
      <suggestion> 0 </suggestion>
    </parameter>
  </category>

  <category name="boundary">
    <parameter name="file">
      <definition> Path to the boundary condition file. </definition>
      <values> path </values>
    </parameter>

    <parameter name="fileType">
      <definition> Type of spatial segmentation of the boundaries specified in the BC file </definition>
      <values> rectangularGrid </values>
      <suggestion> rectangularGrid </suggestion>
      <comment> Choose type of boundary segmentation: rectangularGrid </comment>
    </parameter>

    <parameter name="interpolateBCvalues">
      <definition> Whether to interpolate between the boundary conditions
        at different times linearly (``true``) or not at all (``false``). May require
        different boundary condition files. </definition>
      <values> true, false </values>
      <suggestion> false </suggestion>
    </parameter>
  </category>

  <category name="initial">
    <parameter name="condition">
      <definition> There are currently two possible initial conditions to choose
        from: A constant potential throughout the domain (``gravityFlow``), or a
        linear potential gradient (``hydrEquilibrium``).</definition>
      <values> hydrEquilibrium, gravityFlow </values>
      <suggestion> hydrEquilibrium </suggestion>
      <comment> Choose initial condition: hydrEquilibrium, gravityFlow </comment>
    </parameter>

    <parameter name="headLower">
      <definition> Initial matric head at the lower boundary of the domain </definition>
      <values> float </values>
      <suggestion> 0 </suggestion>
    </parameter>

    <parameter name="headGradient">
      <definition> Gradient of the matric head towards the upper boundary
        (positive y coordinate). </definition>
      <values> float </values>
      <suggestion> -1 </suggestion>
    </parameter>
  </category>

  <category name="time">
    <parameter name="start">
      <definition> Starting time in seconds. </definition>
      <values> float </values>
      <suggestion> 0 </suggestion>
    </parameter>

    <parameter name="end">
      <definition> Ending time in seconds. </definition>
      <values> float </values>
      <suggestion> 1E6 </suggestion>
    </parameter>

    <parameter name="minTimestep">
      <definition> Minimum time step that is allowed before DORiE stops running.
        with an error, in seconds. </definition>
      <values> float </values>
180
      <suggestion> 0.1 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
181 182 183 184 185
    </parameter>

    <parameter name="startTimestep">
      <definition> Value of the first time step in seconds. </definition>
      <values> float </values>
186
      <suggestion> 10 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208
    </parameter>

    <parameter name="maxTimestep">
      <definition> Largest allowed time step in seconds. Use this to control the
        density of your output. </definition>
      <values> float </values>
      <suggestion> 1E5 </suggestion>
    </parameter>

    <parameter name="minIterations">
      <definition> 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. </definition>
      <values> int </values>
      <suggestion> 1 </suggestion>
    </parameter>

    <parameter name="maxIterations">
      <definition> 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. </definition>
      <values> int </values>
209
      <suggestion> 12 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227
    </parameter>

    <parameter name="timestepIncreaseFactor">
      <definition> Factor the current time step is multiplied with when increasing
        the time step. </definition>
      <values> float &gt; 1 </values>
      <suggestion> 1.5 </suggestion>
    </parameter>

    <parameter name="timestepDecreaseFactor">
      <definition> Factor the current time step is multiplied with when decreasing
        the time step. </definition>
      <values> float &lt; 1 </values>
      <suggestion> 0.5 </suggestion>
    </parameter>
  </category>

  <category name="parameters">
Dion Haefner's avatar
Dion Haefner committed
228 229 230 231 232
    <parameter name="arrayFile">
      <definition> Path to an HDF5 array file containing all parameters used in the chosen
      parameterization. Can be created using the ``dorie pfg`` command. </definition>
      <values> path </values>
      <comment> Create with 'dorie pfg' </comment>
Dion Haefner's avatar
Dion Haefner committed
233 234
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
235 236 237 238
    <parameter name="scale">
      <definition> Scaling factor of the parameter field. A value &gt; 1 zooms into
        the field; a value &lt; 1 zooms out. This may of course change the statistical
        properties of the field (e.g. correlation lengths).
Dion Haefner's avatar
Dion Haefner committed
239 240
      </definition>
      <values> float &times; float (&times; float) </values>
Dion Haefner's avatar
Dion Haefner committed
241
      <suggestion> 1 1 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
242 243
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
244
    <parameter name="offset">
245
      <definition> The parameter field is shifted by this value (in physical units) </definition>
Dion Haefner's avatar
Dion Haefner committed
246 247
      <values> float &times; float (&times; float) </values>
      <suggestion> 0 0 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
248 249
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
250 251 252 253 254 255
    <parameter name="interpolation">
      <definition> 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. </definition>
      <values> nearest, linear, cubic </values>
      <suggestion> nearest </suggestion>
Dion Haefner's avatar
Dion Haefner committed
256 257 258 259 260 261 262 263 264 265 266 267 268
    </parameter>
  </category>

  <category name="dg">
    <parameter name="penaltyFactor">
      <definition> Penalty factor to be used in the Discontinuous Galerkin scheme
      </definition>
      <values> float </values>
      <suggestion> 10 </suggestion>
    </parameter>
  </category>

  <category name="NewtonParameters">
Dion Haefner's avatar
Dion Haefner committed
269
    <parameter name="ReassembleThreshold" hidden="true">
Dion Haefner's avatar
Dion Haefner committed
270 271 272
      <definition> If the ratio between last and current calculation defect exceeds this value,
         the linear operator matrix is reassembled to ensure convergence. </definition>
      <values> float </values>
273
      <suggestion> 5E-2 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
274 275
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
276
    <parameter name="LineSearchMaxIterations" hidden="true">
277 278
      <definition> Maximum iteration count of linear searches performed to deduce
         the optimal damping factor for reducing the defect. </definition>
Dion Haefner's avatar
Dion Haefner committed
279 280 281 282
      <values> int </values>
      <suggestion> 10 </suggestion>
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
283
    <parameter name="AbsoluteLimit" hidden="true">
Dion Haefner's avatar
Dion Haefner committed
284 285 286 287 288
      <definition> Absolute error tolerance of the Newton solver. </definition>
      <values> float </values>
      <suggestion> 1E-10 </suggestion>
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
289
    <parameter name="Reduction" hidden="true">
Dion Haefner's avatar
Dion Haefner committed
290 291 292 293 294
      <definition> Relative error tolerance of the Newton solver. </definition>
      <values> float </values>
      <suggestion> 1E-10 </suggestion>
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
295
    <parameter name="MinLinearReduction" hidden="true">
Dion Haefner's avatar
Dion Haefner committed
296 297 298 299 300 301 302 303 304 305 306
      <definition> 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. </definition>
      <values> float </values>
      <suggestion> 1E-3 </suggestion>
    </parameter>
  </category>

  <category name="adaptivity">
    <parameter name="useAdaptivity">
      <definition> Switches adaptive grid refinement (h-adaptivity) on (``true``) or
Dion Haefner's avatar
Dion Haefner committed
307 308
        off (``false``). If enabled, an unstructured grid manager with higher computational 
        cost is used when using rectangular / cubic grids. </definition>
Dion Haefner's avatar
Dion Haefner committed
309 310 311 312 313 314 315 316
      <values> true, false </values>
      <suggestion> false </suggestion>
    </parameter>

    <parameter name="maxLevel">
      <definition> 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
317 318
         across the grid. Make sure you avoid refinement levels which imply grid cell sizes
         beyond the Richards continuum scale. </definition>
Dion Haefner's avatar
Dion Haefner committed
319
      <values> int </values>
320
      <suggestion> 10 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391
    </parameter>

    <parameter name="minLevel">
      <definition> Minimum refinement level of the grid. Grid cells will not get
        coarsened below this level. </definition>
      <values> int </values>
      <suggestion> 0 </suggestion>
    </parameter>

    <parameter name="markingStrategy">
      <definition> 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
        &alpha;N elements are refined while the last &beta;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 &alpha; (&beta;), starting with the most (least) contributing
        element. The total number of affected entities can vary greatly
        between different iterations, and (with &alpha; = &beta;) much more elements
        are coarsened than refined.

        **threshold**: All elements with a local error &eta; &gt; &alpha; are being refined once.
        Coarsening occurs for all elements that carry an error smaller
        than &beta;.

        **targetTolerance**: All elements with a local error &eta; &gt; &alpha; are being refined as often
        as necessary until the requirement &eta; &lt; &alpha; is met for all grid cells.
        Coarsening occurs for all elements that carry an error smaller
        than &beta;.
      </definition>
      <values> elementFraction, errorFraction, targetTolerance, threshold </values>
      <suggestion> elementFraction </suggestion>
      <comment> elementFraction, errorFraction, targetTolerance, threshold </comment>
    </parameter>

    <parameter name="refinementFraction">
      <definition> The value of &alpha; for the chosen ``markingStrategy``. </definition>
      <values> float </values>
      <suggestion> 0.1 </suggestion>
    </parameter>

    <parameter name="coarseningFraction">
      <definition> The value of &beta; for the chosen ``markingStrategy``. </definition>
      <values> float </values>
      <suggestion> 0.2 </suggestion>
    </parameter>

    <parameter name="threshold">
      <definition> 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. </definition>
      <values> float </values>
      <suggestion> 1E-8 </suggestion>
    </parameter>
  </category>

  <category name="misc">
    <parameter name="debugMode">
      <definition> 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 &gt; 0. Only
        intended for use by developers.
      </definition>
      <values> true, false </values>
      <suggestion> false </suggestion>
    </parameter>
  </category>

</dorie>