Commit 2cac8df3 authored by Lukas Riedel's avatar Lukas Riedel

Update layout, and directives in parameter file user docs

* Add notes on sequence and component notation of tensors, combine
  both in YAML templates.
* Add paragraphs for simple and superposed transport parameterizations.
* Fix indentations and trailing whitespace.
* Add contents directive.
parent 1cebe05b
......@@ -4,12 +4,16 @@ Soil Parameterization
Specifying the domain properties requires input of the
:doc:`soil architecture <grid>`
(in relation to the grid) and of the soil parameters. The latter incorporate
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
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
computation.
A YAML_ parameter file is always required. It specifies a set of
.. contents::
:depth: 2
:local:
A YAML_ parameter file is always required. It specifies a set of
parameterizations, along with a medium index. This index is used to reference
the medium specified in the architecture files, or with the "global" indices
given in the config file.
......@@ -29,19 +33,24 @@ name must be specified via the ``<model>.parameters.file`` key of the
:doc:`config file <config-file>`.
The top-level mapping must contain the key ``volumes``. This key contains a
sequence of arbitrary parameterization names. These, in turn, contain the
medium ``index``, and the model type (i.e. ``ricards`` and ``transport``).
The medium index must be an **integer**. Each model key contain the
sequence of arbitrary parameterization names. These, in turn, contain the
medium ``index``, and the model type (``richards`` or ``transport``).
The medium index must be an **integer**. Each model key contains the
parameterization ``type``, and the actual ``parameters``.
.. 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``.
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.
.. warning:: Transport parameters like *porosity* or *characteristic lenght*
are not currently affected by small scale heterogoeneities.
.. warning::
Transport parameters like `porosity` or `characteristic length` currently
are not affected by small scale heterogoeneities.
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
......@@ -62,11 +71,14 @@ shapes.
parameters:
<param-name-0>: <float>
# more parameters ...
# if transport mode is enabled ...
transport:
type: <string>
parameters:
<param-name-0>: <float>
<param-name-0>: <float or sequence>
# more parameters ...
# more volumes ...
scaling:
......@@ -84,8 +96,8 @@ shapes.
You find a documentation of the parameterizations implemented in DORiE
along with the parameters they require below.
The parameterization ``type`` must match a static parameterization name or a
valid combination of them. Likewise, the parameters must match the names of
The parameterization ``type`` must match a static parameterization name or a
valid combination of them. Likewise, the parameters must match the names of
parameters these objects use.
.. _man-parameter_scaling:
......@@ -168,9 +180,9 @@ porosity, :math:`\theta_s = \phi`.
Transport Parameterizations
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Regarless the parameterization, the transport simulation always computes the
microscopic péclet number, for which it requires the characteristic pore length,
the molecular diffusion, and the fluid velocity. The latter is directly
Regarless the parameterization, the transport simulation always computes the
microscopic péclet number, for which it requires the characteristic pore
length, the molecular diffusion, and the fluid velocity. The latter is directly
provided by the richards simulation while the other two have to be specified
for each volume:
......@@ -179,26 +191,54 @@ Permanent parameters:
:math:`\mathsf{D}^\mathsf{m} \, [\mathrm{m}^2\mathrm{s}^{-1}]`
* ``char_length``: Characteristic pore length :math:`\ell \, [\mathrm{m}]`
The hydrodynamic dispersion tensor :math:`\mathsf{D}^\mathsf{hd} \,
[\mathrm{m}^2\mathrm{s}^{-1}]` is the main parameter to provide in the
.. 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.
Hydrodynamic Dispersion Parameterizations
"""""""""""""""""""""""""""""""""""""""""
The hydrodynamic dispersion tensor :math:`\mathsf{D}^\mathsf{hd} \,
[\mathrm{m}^2\mathrm{s}^{-1}]` is the main parameter to provide in the
transport simulation. Below you will find several parameterization for this.
.. object:: Constant parameterization
In this case, the hydrodynamic dispersion tensor is inserted directly
component-by-compoment. Altough the hydrodynamic tensor must be symmetric
because of the physics, DORiE does not check the symmetry of tensors.
In this case, the hydrodynamic dispersion tensor is inserted directly
component-by-compoment.
.. 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.
.. math::
\mathsf{D}^\mathsf{hd}_{ij} = \text{const}.
\mathsf{D}^\mathsf{hd} = \text{const}.
* ``type: Dhd_const``
Parameters:
* ``hydrodynamic_disp_ij``: (i,j) Component of the hydrodynamic
dispersion tensor
:math:`\mathsf{D}^\mathsf{hd}_{ij} \, [\mathrm{m}^2\mathrm{s}^{-1}]`
* ``hydrodynamic_disp_<ij>``: :math:`(i,j)` Component of the
hydrodynamic dispersion tensor,
:math:`\mathsf{D}^\mathsf{hd}_{ij} \, [\mathrm{m}^2\mathrm{s}^{-1}]`,
**or**
* ``hydrodynamic_disp``: Flattened hydrodynamic dispersion tensor
:math:`\mathsf{D}^\mathsf{hd} \, [\mathrm{m}^2\mathrm{s}^{-1}]`.
YAML template:
......@@ -209,6 +249,11 @@ transport simulation. Below you will find several parameterization for this.
parameters:
mol_diff:
char_length:
# sequence notation, or...
hydrodynamic_disp: [ ]
# component notation
hydrodynamic_disp_xx:
hydrodynamic_disp_xy:
hydrodynamic_disp_xz:
......@@ -219,20 +264,6 @@ transport simulation. Below you will find several parameterization for this.
hydrodynamic_disp_zy:
hydrodynamic_disp_zz:
A more readable alternative is possible. In this case, the
``hydrodynamic_disp`` key is a list of values containing all values
(:math:`\text{dim}\times\text{dim}`) of the tensor. The list is row-wise
oriented.
.. code-block:: yaml
transport:
type: Dhd_const
parameters:
mol_diff:
char_length:
hydrodynamic_disp: [ ... ]
.. object:: Power law parameterization
Implements the following parameterization function:
......@@ -246,6 +277,11 @@ transport simulation. Below you will find several parameterization for this.
Parameters:
* ``gamma``: Scale the power law :math:`[-]`
* ``alpha``: Exponent of the power law :math:`[-]`
* ``mol_diff``: Molecular diffusion
:math:`\mathsf{D}^\mathsf{m} \, [\mathrm{m}^2\mathrm{s}^{-1}]`
The Peclét number :math:`\text{pe}` is specified in the :doc:`config file
<config-file>`.
YAML template:
......@@ -259,23 +295,24 @@ transport simulation. Below you will find several parameterization for this.
alpha:
gamma:
.. object:: Superposition parameterization
Superposition Parameterizations
"""""""""""""""""""""""""""""""
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:`\mathsf{D}^\mathsf{eff}` and for the *effective hydromechanic tensor*
:math:`\mathsf{D}^\mathsf{hm}` identified by the key prefixes ``Deff`` and
``Dhm`` respectively.
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:`\mathsf{D}^\mathsf{eff}` and for the *effective hydromechanic tensor*
:math:`\mathsf{D}^\mathsf{hm}` identified by the key prefixes ``Deff`` and
``Dhm`` respectively.
.. math::
.. math::
\mathsf{D}^\mathsf{hd} = \mathsf{D}^\mathsf{hm}+I\mathsf{D}^\mathsf{eff}.
\mathsf{D}^\mathsf{hd} = \mathsf{D}^\mathsf{hm}+\mathsf{D}^\mathsf{eff}.
* ``type: <Dhm_type> + <Deff_type>``
* ``type: <Dhm_type> + <Deff_type>``
Each of the types are furthere parameterized and can be found below.
Each of the types are further parameterized and can be found below.
.. object:: Constant effective diffusion parameterization
......@@ -288,7 +325,7 @@ transport simulation. Below you will find several parameterization for this.
* ``Deff_type: Deff_const``
Parameters:
* ``eff_diff``: Effective diffusion
* ``eff_diff``: Effective diffusion
:math:`\mathsf{D}^\mathsf{eff} \, [\mathrm{m}^2\mathrm{s}^{-1}]`
YAML template:
......@@ -375,9 +412,12 @@ transport simulation. Below you will find several parameterization for this.
* ``Dhm_type: Dhm_const``
Parameters:
* ``eff_hydromechanic_disp_ij``: (i,j) Component of the hydromechanic
dispersion tensor
:math:`\mathsf{D}^\mathsf{hm}_{ij} \, [\mathrm{m}^2\mathrm{s}^{-1}]`
* ``eff_hydromechanic_disp_<ij>``: (i,j) Component of the hydromechanic
dispersion tensor,
:math:`\mathsf{D}^\mathsf{hm}_{ij} \, [\mathrm{m}^2\mathrm{s}^{-1}]`,
**or**
* ``eff_hydromechanic_disp``: Flattened hydromechanic dispersion tensor
:math:`\mathsf{D}^\mathsf{hm} \, [\mathrm{m}^2\mathrm{s}^{-1}]`.
YAML template:
......@@ -388,6 +428,11 @@ transport simulation. Below you will find several parameterization for this.
parameters:
mol_diff:
char_length:
# sequence notation, or...
eff_hydromechanic_disp: [ ]
# component notation
eff_hydromechanic_disp_xx:
eff_hydromechanic_disp_xy:
eff_hydromechanic_disp_xz:
......@@ -397,24 +442,9 @@ transport simulation. Below you will find several parameterization for this.
eff_hydromechanic_disp_zx:
eff_hydromechanic_disp_zy:
eff_hydromechanic_disp_zz:
# <Deff_type> parameters ...
A more readable alternative is possible. In this case, the
``eff_hydromechanic_disp`` key is a list of values containing all values
(:math:`\text{dim}\times\text{dim}`) of the tensor. The list is row-wise
oriented.
.. code-block:: yaml
transport:
type: Dhm_const + <Deff_type>
parameters:
mol_diff:
char_length:
eff_hydromechanic_disp: [ ... ]
# <Deff_type> parameters ...
.. object:: Effective hydromechanic dispersion tensor for isotropic media parameterization
Implements the following parameterization function:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment