parameters.xml 16.5 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
303
304
305
      <definition> Relative error tolerance of the Newton solver. </definition>
      <values> float </values>
      <suggestion> 1E-10 </suggestion>
    </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
313
314
315
316
317
      <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
318
319
        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
320
321
322
323
324
325
326
327
      <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
328
329
         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
330
      <values> int </values>
331
      <suggestion> 10 </suggestion>
Dion Haefner's avatar
Dion Haefner committed
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
389
390
391
392
393
394
395
396
397
398
399
400
401
    </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>

402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
   <category name="dg.experimental">
    <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>
428
      <suggestion> none </suggestion>
429
430
431
432
433
434
435
436
437
438
    </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
439
</dorie>