richards-parameters.xml 12.8 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 55 56 57 58 59 60
    </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``)
       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>
61
      <suggestion> true </suggestion>
62 63
    </parameter>

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

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

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

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

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

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

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

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

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

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

    <parameter name="FEorder">
      <definition> Order of the finite element method used. Values &gt; 1 are not
        thoroughly tested. </definition>
      <suggestion> 1 </suggestion>
246
      <values> 0, 1, 2, 3 </values>
247
    </parameter>
Dion Haefner's avatar
Dion Haefner committed
248 249
  </category>

250 251 252 253 254 255 256 257 258 259 260 261 262
  <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
263 264
        normal fluxes up to ``jumpTol``. ProTip: Setting warnings together 
        with a very low tolerance will let you track the changes on the 
265 266
        quality of the flux reconstruction.
      </definition>
267 268
      <suggestion> none </suggestion>
      <values> none, warn, error </values>
269 270 271
    </parameter>

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


281
  <category name="NewtonParameters">
282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306
    <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
307
    <parameter name="ReassembleThreshold" hidden="true">
Dion Haefner's avatar
Dion Haefner committed
308 309 310
      <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>
311
      <suggestion> 5E-2 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
312 313
    </parameter>

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

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

330
   <category name="numerics.experimental">
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
    <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>
356
      <suggestion> none </suggestion>
357 358 359 360 361 362 363 364 365 366
    </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
367
</dorie>