parameter-file.rst 15.7 KB
Newer Older
1 2
Parameterization
================
3

4
Specifying the domain properties requires input of the
Lukas Riedel's avatar
Lukas Riedel committed
5
:doc:`soil architecture <grid>`
6
(in relation to the grid) and of the soil parameters. The latter incorporate
7 8 9
the *subscale physics*, the representation of the soil hydraulic and solute
properties below the REV scale. DORiE requires several input files for
retrieving this information, depending on the type of grid used for the
10
computation.
11

12
.. contents::
13
   :depth: 3
14 15 16
   :local:

A YAML_ parameter file is always required. It specifies a set of
17
parameterizations, along with a medium index. This index is used to reference
18 19
the medium specified in the architecture files, or with the "global" indices
given in the config file.
20

21 22 23
Additionally, you can specify settings for the small-scale heterogeneities
of the soil. They require an input via H5 datasets that contain appropriate
scaling factors. You can conveniently create such datasets using the random
Lukas Riedel's avatar
Lukas Riedel committed
24
field generator of the :doc:`command line interface </manual/cli>`.
25

26
.. _man-parameter_file:
27

28 29 30 31
YAML Parameter File
-------------------
This file is used to specify the parameterization for each medium inside the
simulated domain. It follows a simple hierarchical syntax. The file path and
32
name must be specified via the ``<model>.parameters.file`` key of the
Lukas Riedel's avatar
Lukas Riedel committed
33
:doc:`config file <config-file>`.
34

35 36
The top-level mapping must contain the key ``volumes``. This key contains a
sequence of arbitrary parameterization names. These, in turn, contain the
37 38
medium ``index``, and the model type (``richards`` or ``transport``).
The medium index must be an **integer**. Each model key contains the
39
parameterization ``type``, and the actual ``parameters``.
40

41 42 43
.. note:: Parameterization data for model ``transport`` is only required if
          the model is actually enabled in the :doc:`config file settings
          <config-file>`, via ``simulation.mode = richards+transport``.
44 45 46 47 48 49 50

Heterogeneities throughout the entire domain are set via the top level key
``scaling``. It must contain a supported scaling ``type``, which may default
to ``none``. In case an actual scaling is to be applied, the section must
contain the key ``data``, which specifies the datasets required for this type
of scaling.

51 52 53
.. warning::
   Transport parameters like `porosity` or `characteristic length` currently
   are not affected by small scale heterogoeneities.
54

55 56
Every ``scaling_section`` has the same keys: The H5 filepath is given by
``file``, and the internal dataset path by ``dataset``. You can then choose an
57
``interpolation`` method for the dataset. You may optionally insert values
58
for the physical ``extensions`` of the dataset and the ``offset`` of its
59 60 61
(front) lower left corner from the origin. If at least one of them is omitted,
the inserted field is automatically scaled to match the maximum grid
extensions. This also works for irregular grid shapes.
62

63
.. code-block:: yaml
64

65 66
    volumes:
      <name-0>:
67
        index: <int>
68 69 70 71 72
        richards:
          type: <string>
          parameters:
            <param-name-0>: <float>
            # more parameters ...
73 74

        # if transport mode is enabled ...
75 76 77
        transport:
          type: <string>
          parameters:
78
            <param-name-0>: <float or sequence>
79
            # more parameters ...
80 81

      # more volumes ...
82

83
    scaling:
84
      type: <string>
85 86
      data:
        <scaling_section>:
87 88 89
          file: <string>
          dataset: <string>
          interpolation: <string>
90
          # optional:
91 92
          extensions: <sequence>
          offset: <sequence>
93 94

        # more scaling sections ...
95

96 97
You find a documentation of the parameterizations implemented in DORiE
along with the parameters they require below.
98 99
The parameterization ``type`` must match a static parameterization name or a
valid combination of them. Likewise, the parameters must match the names of
100
parameters these objects use.
101

Lukas Riedel's avatar
Lukas Riedel committed
102
.. _man-parameter_scaling:
103

104 105 106 107 108 109
Scaling Field Datasets
----------------------
One or more datasets in possibly multiple HDF5_ files are required for creating
a medium with small-scale heterogeneities. The datasets must consist of
floating-point values and must have the same dimensionality as the grid.
Other than that, there is no restriction on their shape because they are
110 111 112 113
inserted into :doc:`Interpolators <interpolators>`. The interpolators supply
scaling factor values ased on positions on the grid and thus create a
grid-independent representation. Scaling field input works the same for any
supported grid type.
114 115 116 117 118 119 120 121 122

During setup, the program reads the interpolator values at the **barycenter**
of every grid cell on the **coarsest** grid configuration. These values are
stored and referenced with the grid cell. If the cell is refined, the same
scaling factors apply in all its child cells.

Supported Parameter File Types
------------------------------
This section lists the available types for parameterizations, scalings, and
123
interpolators in a understandable format.
124

125
Richards Parameterizations
126
~~~~~~~~~~~~~~~~~~~~~~~~~~
127

128 129 130 131 132 133 134
As the *soil porosity* :math:`\phi \, [-]` and the *residual water content*
:math:`\theta_s \, [-]` vary between soil types, it is convenient to define the
*soil water saturation* :math:`\Theta \, [-]` by

.. math::

   \Theta = \frac{\theta_w - \theta_r}{\phi - \theta_r},
135
   \quad \Theta \in \left[ 0, 1 \right],
136

137
where :math:`\theta_w \, [-]` is the volumetric soil water content.
138 139 140 141
One typically assumes that the entire pore space can be filled up with water,
hence we set the *saturated water content* :math:`\theta_s \, [-]` equal to the
porosity, :math:`\theta_s = \phi`.

142 143
Mualem–van Genuchten
""""""""""""""""""""
144

145 146 147 148 149 150 151 152 153 154 155 156
    Implements the following parameterization functions:

    .. math::

        \Theta (h_m) &= \left[ 1 + \left[ \alpha h_m \right]^n \right]^{-1+1/n}
        \\
        K (\Theta) &= K_0 \Theta^\tau
                        \left[ 1 -
                            \left[ 1 - \Theta^{n / \left[ n-1 \right]}
                            \right]^{1-1/n}
                        \right]^2

157 158 159
    * ``type: MvG``

    Parameters:
160
        * ``theta_r``: Residual water content :math:`\theta_r`
161
        * ``theta_s``: Saturated water content / Porosity :math:`\theta_s`
162 163
        * ``k0``: Saturated conductivity :math:`K_0 \, [\text{ms}^{-1}]`
        * ``alpha``: Air-entry value :math:`\alpha \, [\text{m}^{-1}]`
164 165
        * ``n``: Retention curve shape factor :math:`n`
        * ``tau``: Skew factor :math:`\tau`
166 167 168 169 170

    YAML template:

    .. code-block:: yaml

171
      richards:
172 173 174 175 176 177 178 179 180
        type: MvG
        parameters:
          theta_r:
          theta_s:
          k0:
          alpha:
          n:
          tau:

181
Transport Parameterizations
182
~~~~~~~~~~~~~~~~~~~~~~~~~~~
183

184
Regardless of the parameterization, the transport model always computes
185
the microscopic péclet number, for which it requires the characteristic pore
186
length, the molecular diffusion, and the fluid velocity. The latter is directly
187
provided by the richards model while the other two have to be specified
188 189 190 191
for each volume:

Permanent parameters:
  * ``mol_diff``: Molecular diffusion
192 193
    :math:`D_m \, [\text{m}^2\text{s}^{-1}]`
  * ``char_length``: Characteristic pore length :math:`\ell \, [\text{m}]`
194

195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213
.. note::
    We support two options for specifying tensors through the YAML syntax.
    You may either specify every entry of the tensor with a dedicated key, like

    .. code-block:: yaml

        <param>_xx: <value_xx>
        <param>_xy: <value_xy>
        # ...

    or give an entire sequence that will be mapped to the respective entries,

    .. code-block:: yaml

        <param>: [<value_xx>, <value_xy> # , ...
                 ]

    The sequence is interpreted as a flattened tensor with row-major layout.

214 215 216 217 218 219
.. warning::
   You must omit any component containing the spatial direction ``z`` in a
   2D setup.

The hydrodynamic dispersion tensor :math:`\mathsf{D}_\text{hd} \,
[\text{m}^2\text{s}^{-1}]` is the main parameter to provide in the
220
transport model. Below you will find several parameterization for this.
221

222 223
Constant
""""""""
224

225 226
  In this case, the hydrodynamic dispersion tensor is inserted directly
  component-by-compoment.
227

228 229 230
  .. note::
      From a physical point of view, the hydrodynamic tensor must be
      symmetric, but the user input is not verified by DORiE in this regard.
231

232
  .. math::
233

234
      \mathsf{D}_\text{hd}  = \text{const}.
235

236
  * ``type: Dhd_const``
237

238 239 240 241 242 243 244
  Parameters:
      * ``hydrodynamic_disp_<ij>``: (i, j)-th component of the
        hydrodynamic dispersion tensor,
        :math:`\left( \mathsf{D}_\text{hd} \right)_{ij} \, [\text{m}^2\text{s}^{-1}]`,
        **or**
      * ``hydrodynamic_disp``: Flattened hydrodynamic dispersion tensor
        :math:`\mathsf{D}_\text{hd} \, [\text{m}^2\text{s}^{-1}]`.
245

246
  YAML template:
247

248
  .. code-block:: yaml
249

250 251 252 253 254
    transport:
      type: Dhd_const
      parameters:
        mol_diff:
        char_length:
255

256 257
        # sequence notation, or...
        hydrodynamic_disp: [ ]
258

259 260 261 262 263 264 265 266 267 268
        # component notation
        hydrodynamic_disp_xx:
        hydrodynamic_disp_xy:
        hydrodynamic_disp_xz:
        hydrodynamic_disp_yx:
        hydrodynamic_disp_yy:
        hydrodynamic_disp_yz:
        hydrodynamic_disp_zx:
        hydrodynamic_disp_zy:
        hydrodynamic_disp_zz:
269

270
Power Law
271 272
"""""""""
  Implements the following parameterization function:
273

274
  .. math::
275

276
      D_\text{hd}  = \gamma D_m \operatorname{pe}^\alpha.
277

278
  * ``type: Dhd_pl``
279

280 281 282 283 284
  Parameters:
      * ``gamma``: Scale the power law :math:`\gamma \, [-]`
      * ``alpha``: Exponent of the power law :math:`\alpha \, [-]`
      * ``mol_diff``: Molecular diffusion
        :math:`D_m \, [\text{m}^2\text{s}^{-1}]`
285

286 287
  The Peclét number :math:`\operatorname{pe}` is specified in the
  :doc:`config file <config-file>`.
288

289
  YAML template:
290

291
  .. code-block:: yaml
292

293 294 295 296 297 298 299
    transport:
      type: Dhd_pl
      parameters:
        mol_diff:
        char_length:
        alpha:
        gamma:
300

301 302
Superposition
"""""""""""""
303

304 305 306 307 308 309 310
  The hydrodynamic dispersion tensor is said to be the superposition of
  several diffusion/dispersion processes. In DORiE this possible by summing
  several valid parameterizations types. Currently we provide
  parameterizations for the *effective diffusion*
  :math:`D_\text{eff}` and for the *effective hydromechanic tensor*
  :math:`\mathsf{D}_\text{hm}` identified by the key prefixes ``Deff`` and
  ``Dhm`` respectively.
311

312
  .. math::
313

314
      \mathsf{D}_\text{hd}  = \mathsf{D}_\text{hm} + D_\text{eff}.
315

316
  * ``type: <Dhm_type> + <Deff_type>``
317

318
  Each of the types are further parameterized and can be found below.
319

320
Effective Diffusion
321
^^^^^^^^^^^^^^^^^^^
322

323
Constant Effective Diffusion
324
############################
325

326
  In this case, the effective diffusion is inserted directly,
327

328
  .. math::
329

330
      D_\text{eff}  = \text{const}.
331

332
  * ``Deff_type: Deff_const``
333

334
  Parameters:
335

336 337
      * ``eff_diff``: Effective diffusion
        :math:`D_\text{eff} \, [\text{m}^2\text{s}^{-1}]`
338

339
  YAML template:
340

341
  .. code-block:: yaml
342

343 344 345 346 347 348 349
    transport:
      type: <Dhm_type> + Deff_const
      parameters:
        mol_diff:
        char_length:
        eff_diff:
        # <Dhm_type> parameters ...
350

351
Milligton-Quirk I Effective Diffusion
352
#####################################
353

354
  Implements the following parameterization function:
355

356
  .. math::
357

358
      D_\text{eff} = D_m \frac{\theta_w^{7/3}}{\phi^{2/3}}.
359

360
  where the volumetric water content :math:`\theta_w \, [-]`
361
  is automatically obtained from the Richards model.
362

363
  * ``Deff_type: Deff_MQ1``
364

365 366 367 368
  Parameters:
      * ``mol_diff``: Molecular diffusion
        :math:`D_m \, [\text{m}^2\text{s}^{-1}]`
      * ``phi``: Soil porosity :math:`\phi \, [-]`
369

370
  YAML template:
371

372
  .. code-block:: yaml
373

374 375 376 377 378 379 380
    transport:
      type: <Dhm_type> + Deff_MQ1
      parameters:
        mol_diff:
        char_length:
        phi:
        # <Dhm_type> parameters ...
381

382 383
Milligton-Quirk II Effective Diffusion
######################################
384

385
  Implements the following parameterization function:
386

387
  .. math::
388

389
      D_\text{eff} = D_m \frac{\theta_w}{\phi^{2/3}}.
390

391
  where the volumetric water content :math:`\theta_w \, [-]`
392
  is automatically obtained from the Richards model.
393

394
  * ``Deff_type: Deff_MQ2``
395

396 397 398 399
  Parameters:
      * ``mol_diff``: Molecular diffusion
        :math:`D_m \, [\text{m}^2\text{s}^{-1}]`
      * ``phi``: Soil porosity :math:`\phi \, [-]`
400

401
  YAML template:
402

403
  .. code-block:: yaml
404

405 406 407 408 409 410 411
    transport:
      type: <Dhm_type> + Deff_MQ1
      parameters:
        mol_diff:
        char_length:
        phi:
        # <Dhm_type> parameters ...
412

413
Effective Hydromechanic Dispersion
414
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
415

416
Constant Effective Hydromechanic Dispersion Tensor
417
##################################################
418

419 420
  In this case, the effective hydromechanic dispersion tensor is inserted
  directly.
421

422
  .. math::
423

424
      \mathsf{D}_\text{hm} = \text{const}.
425

426
  * ``Dhm_type: Dhm_const``
427

428 429 430 431 432 433 434
  Parameters:
      * ``eff_hydromechanic_disp_<ij>``: (i, j)-th component of the
        hydromechanic dispersion tensor,
        :math:`\left(\mathsf{D}_\text{hm}\right)_{ij} \, [\text{m}^2\text{s}^{-1}]`,
        **or**
      * ``eff_hydromechanic_disp``: Flattened hydromechanic dispersion tensor
        :math:`\mathsf{D}_\text{hm} \, [\text{m}^2\text{s}^{-1}]`.
435

436
  YAML template:
437

438
  .. code-block:: yaml
439

440 441 442 443 444
    transport:
      type: Dhm_const + <Deff_type>
      parameters:
        mol_diff:
        char_length:
445

446 447
        # sequence notation, or...
        eff_hydromechanic_disp: [ ]
448

449 450 451 452 453 454 455 456 457 458
        # component notation
        eff_hydromechanic_disp_xx:
        eff_hydromechanic_disp_xy:
        eff_hydromechanic_disp_xz:
        eff_hydromechanic_disp_yx:
        eff_hydromechanic_disp_yy:
        eff_hydromechanic_disp_yz:
        eff_hydromechanic_disp_zx:
        eff_hydromechanic_disp_zy:
        eff_hydromechanic_disp_zz:
459

460 461
        # <Deff_type> parameters ...

462
Effective Hydromechanic Dispersion Tensor for Isotropic Media
463
#############################################################
464 465 466 467 468

    Implements the following parameterization function:

    .. math::

469 470 471 472 473 474
        \left( \mathsf{D}_\text{hm} \right)_{ij}
          = (\lambda_l-\lambda_t)\frac{v_i v_j}{\lvert \mathbf{v} \rvert}
            + \delta_{ij}\lambda_t \lvert \mathbf{v} \rvert,

    where :math:`\mathbf{v} \, [\text{ms}^{-1}]` is the local fluid velocity
    and :math:`\delta_{ij}` is the Kronecker delta.
475 476 477 478

    * ``Dhm_type: Dhm_iso``

    Parameters:
479 480
        * ``lambda_l``: Longitudinal dispersivity :math:`\lambda_l \, [\text{m}^2\text{s}^{-1}]`
        * ``lambda_t``: Transverse dispersivity :math:`\lambda_t \, [\text{m}^2\text{s}^{-1}]`
481 482 483 484 485 486 487 488

    YAML template:

    .. code-block:: yaml

      transport:
        type: Dhm_iso + <Deff_type>
        parameters:
489 490
          mol_diff:
          char_length:
491 492
          lambda_l:
          lambda_t:
493
          # <Deff_type> parameters ...
494 495


496
Scalings
497
~~~~~~~~
498
Every ``scaling_section`` has the following layout:
499 500 501 502

.. code-block:: yaml

    <scaling_section>:
503 504 505
      file: <string>
      dataset: <string>
      interpolation: <string>
506
      # optional:
507 508
      extensions: <sequence>
      offset: <sequence>
509 510 511 512

The values of ``extensions`` and ``offset`` are sequences containing the
coordinates in the respective spatial dimensions.

513 514 515 516 517 518 519
.. note::

    ``extensions`` and ``offset`` of the scaling field will be set to match
    the grid extensions automatically, if at least one of these *keys* is
    omitted. Only omitting the respective *values* of both keys will lead to
    a parser error.

520
Miller Scaling
521
""""""""""""""
522

523 524
  Assumes geometric similarity between scaled regions. Applies the following
  scaling:
525

526
  .. math ::
527

528 529
      \Theta &= \Theta (h_m \cdot \xi_M)\\
      K &= K (\Theta) \cdot \xi_M^2
530

531
  * ``type: Miller``
532

533 534 535
  Scaling sections:
      * ``scale_miller``: Scaling factor :math:`\xi_M` to be applied onto
        matric head and conductivity simultaneously.
536

537
  YAML template:
538

539
  .. code-block:: yaml
540

541 542 543 544
      type: Miller
      data:
        scale_miller:
          # ...
545

546 547 548

.. _YAML: https://gettaurus.org/docs/YAMLTutorial/
.. _HDF5: https://www.h5py.org/