richards-parameters.xml 12.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
<?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>
34
  <category name="output">
35 36 37
    <parameter name="logLevel">
      <definition> Logging level of the Richards solver. </definition>
      <suggestion> info </suggestion>
38
      <values> trace, debug, info, warning, error, critical </values>
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
    </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="vertexData">
      <definition> Plot vertex based (``true``) or cell-centered (``false``)
55 56 57
       data into VTK files. Prefer vertex over cell data for full-precision
       output. System tests and plotting functions (``dorie plot``) require
       cell-centered data.
58 59
      </definition>
      <values> true, false </values>
60
      <suggestion> true </suggestion>
61 62
    </parameter>

63 64
    <parameter name="policy">
      <definition> Policy to write the data. </definition>
65 66
      <suggestion> endOfRichardsStep </suggestion>
      <values> endOfRichardsStep, none </values>
67 68
    </parameter>
    
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90
    <parameter name="subsamplingLevel">
      <definition> 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 &gt; 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!
      </definition>
      <values> int </values>
      <suggestion> 0 </suggestion>
    </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>

91
  <category name="boundary">
Dion Haefner's avatar
Dion Haefner committed
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
    <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>

113
  <category name="initial">
114
    <parameter name="type">
115 116
      <definition> The data type representing the initial condition. Either an
        HDF datafile (``data``), or analytic equations (``analytic``).
117
      </definition>
118 119 120
      <values> data, analytic </values>
      <suggestion> analytic </suggestion>
      <comment> Choose initial condition type: data, analytic </comment>
121 122 123 124 125 126 127 128 129
    </parameter>

    <parameter name="quantity">
      <definition> The physical quantity represented by the initial condition
        data.
      </definition>
      <values> matricHead </values>
      <suggestion> matricHead </suggestion>
      <comment> Choose quantity represented: matricHead </comment>
Dion Haefner's avatar
Dion Haefner committed
130 131
    </parameter>

132 133
    <parameter name="equation">
      <definition> Equation for the initial condition </definition>
134 135
      <values> equation [x,y,z,h] </values>
      <suggestion> -h </suggestion>
Dion Haefner's avatar
Dion Haefner committed
136 137
    </parameter>

138 139
    <parameter name="file">
      <definition> Path to the initial condition data file
140 141
        (``data`` type only). DORiE currently only supports H5 files with
        file extension ``.h5``.
142
      </definition>
143 144 145 146
      <values> path </values>
    </parameter>

    <parameter name="dataset">
147
      <definition> Dataset to use as initial condition (``data`` type only).
148
      </definition>
149
      <values> string </values>
150
    </parameter>
151

152 153 154 155 156
    <parameter name="interpolation">
      <definition> Interpolation type used for the data (``data`` type only).
      </definition>
      <values> nearest </values>
      <suggestion> nearest </suggestion>
157
    </parameter>
Dion Haefner's avatar
Dion Haefner committed
158 159
  </category>

160
  <category name="time">
Dion Haefner's avatar
Dion Haefner committed
161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176
    <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>
177
      <suggestion> 0.1 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
178 179 180 181 182
    </parameter>

    <parameter name="startTimestep">
      <definition> Value of the first time step in seconds. </definition>
      <values> float </values>
183
      <suggestion> 10 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205
    </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>
206
      <suggestion> 12 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224
    </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">
225 226
    <parameter name="file">
      <definition> YAML file containing the parameter definitions.
Dion Haefner's avatar
Dion Haefner committed
227
      </definition>
228
      <values> path </values>
229
      <suggestion> richards_param.yml </suggestion>
Dion Haefner's avatar
Dion Haefner committed
230 231 232
    </parameter>
  </category>

233
  <category name="numerics">
Dion Haefner's avatar
Dion Haefner committed
234 235 236 237 238 239
    <parameter name="penaltyFactor">
      <definition> Penalty factor to be used in the Discontinuous Galerkin scheme
      </definition>
      <values> float </values>
      <suggestion> 10 </suggestion>
    </parameter>
240 241

    <parameter name="FEorder">
242 243 244 245
      <definition> Polynomial order of the DG method used. Setting this value
        to 0 (zero) selects the finite volume (FV) solver (only compatible to
        structured rectangular grids).
      </definition>
246
      <suggestion> 1 </suggestion>
247
      <values> 0, 1, 2, 3 </values>
248
    </parameter>
Dion Haefner's avatar
Dion Haefner committed
249 250
  </category>

251 252 253 254 255 256 257 258 259 260 261 262 263
  <category name="fluxReconstruction">
    <parameter name="enable">
      <definition> Apply the flux reconstruction method to the solved matric 
        head and obtain conservative gradients. It always computes 
        (internally) the local lifting independent whether the ``lifting`` 
        keyword is active or not.
      </definition>
      <suggestion> true </suggestion>
      <values> true, false </values>
    </parameter>

    <parameter name="checkJumps">
      <definition> Check that flux reconstruction engine is creating conforming
264 265
        normal fluxes up to ``jumpTol``. ProTip: Setting warnings together 
        with a very low tolerance will let you track the changes on the 
266 267
        quality of the flux reconstruction.
      </definition>
268 269
      <suggestion> none </suggestion>
      <values> none, warn, error </values>
270 271 272
    </parameter>

    <parameter name="checkTol">
273
      <definition> Whenever ``checkJumps`` is activated, it check that flux 
274 275 276
        reconstruction engine is creating conforming normal fluxes up to ``jumpTol``. 
      </definition>
      <values> float &gt; 0 </values>
277
      <suggestion> 1E-10 </suggestion>
278 279 280 281
    </parameter>
  </category>


282
  <category name="NewtonParameters">
283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307
    <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>
      <suggestion> false </suggestion>
    </parameter>

    <parameter name="AbsoluteLimit" hidden="true">
      <definition> Absolute error tolerance of the Newton solver.
        Reduce this value to increase precision.
      </definition>
      <values> 1E-11 &lt; float &lt; 1E-8 </values>
      <suggestion> 1E-10 </suggestion>
    </parameter>

    <parameter name="Reduction" hidden="true">
      <definition> Relative error tolerance of the Newton solver.
        Reduce this value to increase precision.
      </definition>
      <values> float </values>
      <suggestion> 1E-4 </suggestion>
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
308
    <parameter name="ReassembleThreshold" hidden="true">
Dion Haefner's avatar
Dion Haefner committed
309 310 311
      <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>
312
      <suggestion> 5E-2 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
313 314
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
315
    <parameter name="LineSearchMaxIterations" hidden="true">
316 317
      <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
318 319 320 321
      <values> int </values>
      <suggestion> 10 </suggestion>
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
322
    <parameter name="MinLinearReduction" hidden="true">
Dion Haefner's avatar
Dion Haefner committed
323 324 325 326 327 328 329 330
      <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>

331
   <category name="numerics.experimental">
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
    <parameter name="method">
      <definition> 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
      </definition>
      <values> SIPG, NIPG, OOB, IIP </values>
      <suggestion> SIPG </suggestion>
      <comment> Experimental settings are enabled by the appropriate CMake flag.
      </comment>
    </parameter>

    <parameter name="upwinding">
      <definition> Upwinding method for skeleton terms.

        **semiUpwind:** Apply upwinding to conductivity factor (only).

        **fullUpwind:** Apply upwinding on numeric flux and conductivity.
      </definition>
      <values> none, semiUpwind, fullUpwind </values>
357
      <suggestion> none </suggestion>
358 359 360 361 362 363 364 365 366 367
    </parameter>

    <parameter name="weights">
      <definition> Apply harmonic weighting to skeleton term contributions.
      </definition>
      <values> true, false </values>
      <suggestion> true </suggestion>
    </parameter>
  </category>

Dion Haefner's avatar
Dion Haefner committed
368
</dorie>