transport-parameters.xml 11.5 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 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 38
    <parameter name="logLevel">
      <definition> Logging level of the Richards solver. </definition>
      <suggestion> info </suggestion>
      <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> endOfTransportStep, endOfRichardsStep, none </values>
68 69
    </parameter>

70 71 72 73 74 75 76 77 78 79
    <parameter name="writeDispersionTensor">
      <definition> Defines whether VTK files should include the hydrodynamic 
       dispersion tensor. Tensors are written in 3D and have 9 componentents 
       independently of the world dimension. This can be easily be visualizated
       in Paraview with the ``Tensor Glyph`` filter.
      </definition>
      <values> true, false </values>
      <suggestion> false </suggestion>
    </parameter>

80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101
    <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>

102
  <category name="boundary">
103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121
    <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>
122 123 124 125 126 127 128

    <parameter name="dirichletMode">
      <definition> Type of the input value for the dirichlet condition. 
      </definition>
      <values> soluteConcentration, totalSolute </values>
      <suggestion> soluteConcentration </suggestion>
    </parameter>
129 130
  </category>

131
  <category name="initial">
132
    <parameter name="type">
133 134 135
      <definition> The data type representing the initial condition. Either an
        HDF datafile (``data``), or analytic equations (``analytic``).
      </definition>
136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151
      <values> data, analytic </values>
      <suggestion> analytic </suggestion>
      <comment> Choose initial condition type: data, analytic </comment>
    </parameter>

    <parameter name="quantity">
      <definition> The physical quantity represented by the initial condition
        data.
      </definition>
      <values> soluteConcentration </values>
      <suggestion> soluteConcentration </suggestion>
      <comment> Choose quantity represented: soluteConcentration </comment>
    </parameter>

    <parameter name="equation">
      <definition> Equation for the initial condition </definition>
152
      <values> equation [x,y,z,h] </values>
153 154
      <suggestion> 0 </suggestion>
    </parameter>
155

156 157 158 159
    <parameter name="file">
      <definition> Path to the initial condition data file
        (``data`` type only). DORiE currently only supports H5 files with
        file extension ``.h5``.
160 161 162 163 164
      </definition>
      <values> path </values>
    </parameter>

    <parameter name="dataset">
165
      <definition> Dataset to use as initial condition (``data`` type only).
166 167
      </definition>
      <values> string </values>
168
    </parameter>
169 170 171 172 173 174 175

    <parameter name="interpolation">
      <definition> Interpolation type used for the data (``data`` type only).
      </definition>
      <values> nearest </values>
      <suggestion> nearest </suggestion>
    </parameter>
176 177
  </category>

178
  <category name="time">
179 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="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>
      <suggestion> 0.1 </suggestion>
    </parameter>

    <parameter name="startTimestep">
      <definition> Value of the first time step in seconds. </definition>
      <values> float </values>
      <suggestion> 10 </suggestion>
    </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>
      <suggestion> 12 </suggestion>
    </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>

242 243 244 245 246
 <category name="parameters">
    <parameter name="file">
      <definition> YAML file containing the parameter definitions.
      </definition>
      <values> path </values>
247
      <suggestion> transport_param.yml </suggestion>
248 249 250
    </parameter>
  </category>

251
  <category name="numerics">
252
    <parameter name="timestepMethod">
253 254 255
      <definition> Numerical scheme to perform time steps in the simulation.
        ``alex2`` and ``implicit_euler`` are implicit methods. 
        ``explicit_euler`` is a explicit method.
256
      </definition>
257 258
      <values> explicit_euler, implicit_euler, alex2 </values>
      <suggestion> alex2 </suggestion>
259 260 261
    </parameter>

    <parameter name="courant">
262 263 264 265 266 267
      <definition> Courant number for explicit methods. It is a scale for the
        maximum stable time step according to the CFL condition. The CFL 
        condition penalizes high velocities, low dispersion coefficients, and 
        small grid elements. Hence, Courant numbers near to 1 tend to be more 
        instable while numbers near to 0 tend to considerably limit the 
        maximum time step.
268
      </definition>
269
      <values> 0 &lt; float &lt; 1 </values>
270
      <suggestion> 0.8 </suggestion>
271
    </parameter>
272 273

    <parameter name="FEorder">
274
      <definition> Order of the finite element method used. </definition>
275
      <suggestion> 0 </suggestion>
276
      <values> 0 </values>
277 278
    </parameter>
  </category>
279 280 281

  <category name="fluxReconstruction">
    <parameter name="enable">
282 283
      <definition> Apply the flux reconstruction method to the solved solute 
      concentration and obtain conservative fluxes.
284 285 286 287 288 289 290
      </definition>
      <suggestion> true </suggestion>
      <values> true, false </values>
    </parameter>

    <parameter name="checkJumps">
      <definition> Check that flux reconstruction engine is creating conforming
291 292
        normal fluxes up to ``jumpTol``. ProTip: Setting warnings together 
        with a very low tolerance will let you track the changes on the 
293 294
        quality of the flux reconstruction.
      </definition>
295 296
      <suggestion> none </suggestion>
      <values> none, warn, error </values>
297 298 299
    </parameter>

    <parameter name="checkTol">
300
      <definition> Whenever ``checkJumps`` is activated, it check that flux 
301 302 303
        reconstruction engine is creating conforming normal fluxes up to ``jumpTol``. 
      </definition>
      <values> float &gt; 0 </values>
304
      <suggestion> 1E-10 </suggestion>
305 306
    </parameter>
  </category>
307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324

  <category name="solverParameters">
    <parameter name="reduction">
      <definition> Required relative defect reduction.
        Reduce this value to increase precision.
      </definition>
      <suggestion> 1E-6 </suggestion>
      <values> float </values>
    </parameter>

    <parameter name="minDefect">
      <definition> Minimum absolute defect at which linear solver stops.
        Reduce this value to increase precision.
      </definition>
      <suggestion> 1E-20 </suggestion>
      <values> float </values>
    </parameter>
  </category>
325
</dorie>