parameters.xml 15.7 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
<?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>

53 54 55 56 57 58 59 60 61 62 63
    <parameter name="vertexData">
      <definition> 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.
      </definition>
      <values> true, false </values>
      <suggestion> false </suggestion>
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
64 65 66 67 68 69 70 71 72 73 74 75
    <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
76 77
      <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
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
        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>
95
      <values> 1, 2, 3 </values>
Dion Haefner's avatar
Dion Haefner committed
96 97 98 99 100 101 102 103 104 105
    </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,
106 107
        then z-direction. If a mesh file is imported, they have to match its maximum
        extensions. </definition>
Dion Haefner's avatar
Dion Haefner committed
108 109 110 111 112 113
      <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``
114 115
        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
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 180 181 182 183 184 185 186 187 188 189 190
      <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>
191
      <suggestion> 0.1 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
192 193 194 195 196
    </parameter>

    <parameter name="startTimestep">
      <definition> Value of the first time step in seconds. </definition>
      <values> float </values>
197
      <suggestion> 10 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219
    </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>
220
      <suggestion> 12 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238
    </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
239 240 241 242 243
    <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
244 245
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
246 247 248 249
    <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
250 251
      </definition>
      <values> float &times; float (&times; float) </values>
Dion Haefner's avatar
Dion Haefner committed
252
      <suggestion> 1 1 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
253 254
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
255
    <parameter name="offset">
256
      <definition> The parameter field is shifted by this value (in physical units) </definition>
Dion Haefner's avatar
Dion Haefner committed
257 258
      <values> float &times; float (&times; float) </values>
      <suggestion> 0 0 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
259 260
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
261 262 263 264 265 266
    <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
267 268 269 270 271 272 273 274 275 276 277 278 279
    </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
280
    <parameter name="ReassembleThreshold" hidden="true">
Dion Haefner's avatar
Dion Haefner committed
281 282 283
      <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>
284
      <suggestion> 5E-2 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
285 286
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
287
    <parameter name="LineSearchMaxIterations" hidden="true">
288 289
      <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
290 291 292 293
      <values> int </values>
      <suggestion> 10 </suggestion>
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
294
    <parameter name="AbsoluteLimit" hidden="true">
Dion Haefner's avatar
Dion Haefner committed
295 296 297 298 299
      <definition> Absolute error tolerance of the Newton solver. </definition>
      <values> float </values>
      <suggestion> 1E-10 </suggestion>
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
300
    <parameter name="Reduction" hidden="true">
Dion Haefner's avatar
Dion Haefner committed
301 302
      <definition> Relative error tolerance of the Newton solver. </definition>
      <values> float </values>
303
      <suggestion> 1E-4 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
304 305
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
306
    <parameter name="MinLinearReduction" hidden="true">
Dion Haefner's avatar
Dion Haefner committed
307 308 309 310 311 312
      <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>
313 314 315 316 317 318 319

    <parameter name="ForceIteration" hidden="true">
      <definition> 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.
      </definition>
      <values> true, false </values>
320
      <suggestion> false </suggestion>
321
    </parameter>
Dion Haefner's avatar
Dion Haefner committed
322 323 324 325 326
  </category>

  <category name="adaptivity">
    <parameter name="useAdaptivity">
      <definition> Switches adaptive grid refinement (h-adaptivity) on (``true``) or
Dion Haefner's avatar
Dion Haefner committed
327 328
        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
329 330 331 332 333 334 335 336
      <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
337 338
         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
339
      <values> int </values>
340
      <suggestion> 10 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
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 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411
    </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>