common-parameters.xml 9.99 KB
Newer Older
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
<?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>
33 34
  <category name="simulation">
    <parameter name="mode">
35
      <definition> Sets the simulation mode of DORiE. 
36 37
        (``richards``) mode calculates the matric head with a
        DG scheme and produce water fluxes with Raviart Thomas reconstruction.
38 39 40 41
        (``richards+transport``) mode calculates (``richards``) mode and use 
        the generated water flux and saturation at each step to calculate the 
        solute transport model for unsaturated media with a DG scheme.
        </definition>
42 43 44 45 46
      <suggestion> richards </suggestion>
      <values> richards, richards+transport </values>
    </parameter>
  </category>

47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 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
  <category name="grid">
    <parameter name="gridType">
      <definition> Grid geometry. The grid can either be structured rectangular / cubic
        (``rectangular``) or unstructured triangular / tetrahedral (``gmsh``). The former does not
        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="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. If a mesh file is imported, they have to match its maximum
        extensions. </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``. This represents the coarsest level of the grid
        (i.e., refinement level 0). </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>
92
  </category>
93

94 95 96 97
  <category name="grid.mapping">
    <parameter name="file">
      <definition> The H5 file containing all mapping datasets.
        Leave empty or set to ``None`` for global mappings.
98 99
      </definition>
      <values> path </values>
100
      <suggestion> None </suggestion>
101
      <comment> This category is only used for 'rectangular' grids </comment>
102 103
    </parameter>

104 105 106 107
    <parameter name="volume">
      <definition> The H5 dataset containing the
        mapping from cell to medium index. May specify a global index for the
        entire volume if its value can be parsed as ``int``.
108
      </definition>
109
      <suggestion> 0 </suggestion>
110
      <values> path or int </values>
111 112
    </parameter>

113 114 115 116
    <parameter name="boundaryLower">
      <definition> The H5 dataset mapping the lower boundary faces to
        boundary condition indices. May specify a global index for the
        boundary if its value can be parsed as ``int``.
117
      </definition>
118
      <suggestion> 0 </suggestion>
119 120 121 122 123 124 125 126
      <values> path or int </values>
    </parameter>

    <parameter name="boundaryUpper">
      <definition> The H5 dataset mapping the upper boundary faces to
        boundary condition indices. May specify a global index for the
        boundary if its value can be parsed as ``int``.
      </definition>
127
      <suggestion> 1 </suggestion>
128 129 130 131 132 133 134 135
      <values> path or int </values>
    </parameter>

    <parameter name="boundaryLeft">
      <definition> The H5 dataset mapping the left boundary faces to
        boundary condition indices. May specify a global index for the
        boundary if its value can be parsed as ``int``.
      </definition>
136
      <suggestion> 2 </suggestion>
137 138 139 140 141 142 143 144
      <values> path or int </values>
    </parameter>

    <parameter name="boundaryRight">
      <definition> The H5 dataset mapping the right boundary faces to
        boundary condition indices. May specify a global index for the
        boundary if its value can be parsed as ``int``.
      </definition>
145
      <suggestion> 3 </suggestion>
146 147 148 149 150 151 152 153
      <values> path or int </values>
    </parameter>

    <parameter name="boundaryFront">
      <definition> The H5 dataset mapping the front boundary faces to
        boundary condition indices (3D only). May specify a global index for
        the boundary if its value can be parsed as ``int``.
      </definition>
154
      <suggestion> 4 </suggestion>
155 156 157 158 159 160 161 162 163
      <values> path or int </values>
      <comment> Only in 3D </comment>
    </parameter>

    <parameter name="boundaryBack">
      <definition> The H5 dataset mapping the back boundary faces to
        boundary condition indices (3D only).  May specify a global index for
        the boundary if its value can be parsed as ``int``.
      </definition>
164
      <suggestion> 5 </suggestion>
165
      <values> path or int </values>
166
    </parameter>
167 168 169
  </category>

  <category name="adaptivity">
170
    <parameter name="policy">
171 172 173
      <definition> Switches the target policy to do adaptive grid refinement
        (h-adaptivity). If enabled, an unstructured grid manager with higher
        computational cost is used when using rectangular / cubic grids.
174
      </definition>
175 176
      <values> none, waterFlux </values>
      <suggestion> none </suggestion>
177
      <comment> none, waterFlux </comment>
178 179
    </parameter>

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 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241
    <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. Make sure you avoid refinement levels which imply grid cell sizes
         beyond the Richards continuum scale. </definition>
      <values> int </values>
      <suggestion> 10 </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;.

      </definition>
      <values> elementFraction, errorFraction, threshold </values>
      <suggestion> elementFraction </suggestion>
      <comment> elementFraction, errorFraction, 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>

Santiago Ospina De Los Ríos's avatar
Santiago Ospina De Los Ríos committed
242
  <category name="output">
243 244
    <parameter name="logLevel">
      <definition> Logging level of the core functions. </definition>
245 246
      <suggestion> info </suggestion>
      <values> trace, debug, info, warning, error, critical </values>
Santiago Ospina De Los Ríos's avatar
Santiago Ospina De Los Ríos committed
247 248 249
    </parameter>
  </category>

250 251 252 253 254 255 256 257 258 259 260 261
  <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>