richards-parameters.xml 13 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
       data into VTK files. Prefer vertex over cell data for full-precision
       output. System tests and plotting functions (``dorie plot``) require
57 58 59
       cell-centered data.
      </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 117
      <definition> The data type representing the initial condition. Either an
        HDF datafile (``data``), or analytic equations (``analytic``).
      </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
    </parameter>
137

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
    <parameter name="interpolation">
      <definition> Interpolation type used for the data (``data`` type only).
      </definition>
155 156
      <values> nearest, linear </values>
      <suggestion> linear </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">
234
    <parameter name="FEorder">
235 236 237 238
      <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>
239
      <suggestion> 1 </suggestion>
240
      <values> 0, 1, 2, 3 </values>
241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286
      <comment> Select '0' for the finite volume (FV) solver </comment>
    </parameter>

    <parameter name="upwinding">
      <definition> Upwinding method for skeleton terms. Upwinding typically
        increases numeric stability while reducing accuracy.

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

        **fullUpwind:** Apply upwinding to conductivity.
        **Not recommended for DG**.
      </definition>
      <values> none, semiUpwind, fullUpwind </values>
      <suggestion> none </suggestion>
      <comment> Choose upwinding type: 'none', 'semiUpwind', 'fullUpwind'
      </comment>
    </parameter>

    <parameter name="DGMethod">
      <definition> DG discretization method for skeleton terms.

        **SIPG:** Symmetric Interior Penalty

        **NIPG:** Non-Symmetric Interior Penalty

        **OBB:** Oden, Babuska, Baumann: no penalty term

        **IIP:** Incomplete Interior Penalty: no symmetry term
      </definition>
      <values> SIPG, NIPG, OBB, IIP </values>
      <suggestion> SIPG </suggestion>
    </parameter>

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

    <parameter name="penaltyFactor">
      <definition> Penalty factor to be used in the Discontinuous Galerkin scheme
      </definition>
      <values> float </values>
      <suggestion> 10 </suggestion>
287
    </parameter>
Dion Haefner's avatar
Dion Haefner committed
288 289
  </category>

290 291 292 293 294 295 296 297 298 299 300 301 302
  <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
303 304
        normal fluxes up to ``jumpTol``. ProTip: Setting warnings together 
        with a very low tolerance will let you track the changes on the 
305 306
        quality of the flux reconstruction.
      </definition>
307 308
      <suggestion> none </suggestion>
      <values> none, warn, error </values>
309 310 311
    </parameter>

    <parameter name="checkTol">
312
      <definition> Whenever ``checkJumps`` is activated, it check that flux 
313 314 315
        reconstruction engine is creating conforming normal fluxes up to ``jumpTol``. 
      </definition>
      <values> float &gt; 0 </values>
316
      <suggestion> 1E-10 </suggestion>
317 318 319 320
    </parameter>
  </category>


321
  <category name="NewtonParameters">
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
    <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
347
    <parameter name="ReassembleThreshold" hidden="true">
Dion Haefner's avatar
Dion Haefner committed
348 349 350
      <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>
351
      <suggestion> 5E-2 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
352 353
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
354
    <parameter name="LineSearchMaxIterations" hidden="true">
355 356
      <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
357 358 359 360
      <values> int </values>
      <suggestion> 10 </suggestion>
    </parameter>

Dion Haefner's avatar
Dion Haefner committed
361
    <parameter name="MinLinearReduction" hidden="true">
Dion Haefner's avatar
Dion Haefner committed
362 363 364 365 366 367 368 369 370
      <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>

</dorie>