parameters.xml 14.6 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 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 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 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226
        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>
      <values> 0, 1, 2 </values>
      <comment> Values &gt; 1 are not thoroughly tested </comment>
    </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,
        then z-direction. </definition>
      <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``
        is set to ``rectangular``. </definition>
      <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>
      <suggestion> 10 </suggestion>
    </parameter>

    <parameter name="startTimestep">
      <definition> Value of the first time step in seconds. </definition>
      <values> float </values>
      <suggestion> 1000 </suggestion>
    </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>
      <suggestion> 10 </suggestion>
    </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
227 228 229 230 231
    <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
232 233
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
234 235 236 237
    <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
238 239
      </definition>
      <values> float &times; float (&times; float) </values>
Dion Haefner's avatar
Dion Haefner committed
240
      <suggestion> 1 1 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
241 242
    </parameter>

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

Dion Haefner's avatar
Dion Haefner committed
249 250 251 252 253 254
    <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
255 256 257 258 259 260 261 262 263 264 265 266 267
    </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
268
    <parameter name="ReassembleThreshold" hidden="true">
Dion Haefner's avatar
Dion Haefner committed
269 270 271 272 273 274
      <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>
      <suggestion> 0.0 </suggestion>
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
275
    <parameter name="LineSearchMaxIterations" hidden="true">
Dion Haefner's avatar
Dion Haefner committed
276 277 278 279 280
      <definition> ? </definition>
      <values> int </values>
      <suggestion> 10 </suggestion>
    </parameter>

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

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

Dion Haefner's avatar
Dion Haefner committed
293
    <parameter name="MinLinearReduction" hidden="true">
Dion Haefner's avatar
Dion Haefner committed
294 295 296 297 298 299 300 301 302 303 304
      <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
305 306
        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
307 308 309 310 311 312 313 314 315 316 317 318 319 320 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
      <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
         across the grid. </definition>
      <values> int </values>
      <suggestion> 15 </suggestion>
    </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>