Commit a7b6b471 authored by Lukas Riedel's avatar Lukas Riedel Committed by Santiago Ospina De Los Ríos

Add cook book tutorial on random field generator

Explain basics of random field generation and include two main use
cases, Miller-similar media and heterogeneous media. Add input files for theses cases and include excerpts into the docs.

Images are already uploaded to the DORiE repository Wiki.
parent 4aee1e47
......@@ -5,6 +5,7 @@ build-cmake/
......@@ -233,6 +233,23 @@ test:unit-tests:
- $CI_PROJECT_DIR/build-cmake/coverage
expire_in: 1 day
stage: test
- build:system-tests
needs: ["build:system-tests"]
- schedules
- master@dorie/dorie
- $DUNECONTROL --only=dorie configure
- $DUNECONTROL --only=dorie make example_tests
name: "$CI_JOB_NAME"
- $CI_PROJECT_DIR/build-cmake/doc
expire_in: 1 day
<<: *test
dependencies: []
......@@ -36,6 +36,7 @@
* Changes to config file parameters listed per version in user docs !175
* Control negative transport solution by a check policy !181
* DG solver for solute transport model !112
* Cookbook tutorial on using the random field generator !184
### Changed
* Data structures for storing and accessing parameter information !55
......@@ -426,9 +426,10 @@ Additionaly, there is a set of tests for the Python module.
| Test category | Build tests | Execute tests | Recommended build type |
| ------------- | ----------- | ------------- | ---------------------- |
| Unit tests | `make build_unit_tests` | `make unit_tests` | `Debug`
| System tests | `make build_system_tests` | `make system_tests` | `Release`
| Python tests | _Not required_ | `make test_python` | _Any_
| Unit tests | `make build_unit_tests` | `make unit_tests` | `Debug` |
| System tests | `make build_system_tests` | `make system_tests` | `Release` |
| Python tests | _Not required_ | `make test_python` | _Any_ |
| Cookbook examples (no testing performed) | `make all` | `make example_tests` | `Release` |
The `make` commands are to be executed from within the `build-cmake` directory.
......@@ -8,7 +8,13 @@ add_custom_target(unit_tests
--output-on-failure --exclude-regex "^\\(ut.+\\|python_tests\\)$"
--output-on-failure --exclude-regex "^\\(ut.+\\|python_tests\\|dorie_example.+\\)$"
# Add target for manual examples
--output-on-failure --tests-regex ^dorie_example.+$
# create the mapping datafile as preparation for all tests
......@@ -20,9 +26,9 @@ add_dependencies(unit_tests prepare_testing)
# Create a fake library target to satisfy dune-testtools
add_library(dorie_test UNKNOWN IMPORTED)
set_property(TARGET dorie_test
add_library(dorie_example UNKNOWN IMPORTED)
set_target_properties(dorie_test dorie_example
# .. cmake_function:: add_coverage_links
dorie_add_metaini_test(TARGET dorie_test
dorie_add_metaini_test(TARGET dorie_example
# Expand a metaini file into the current binary dir
foreach(metaini ${ARGN})
--ini ${metaini}
--file ${CMAKE_CURRENT_BINARY_DIR}/interface.log
ERROR_MESSAGE "Error expanding ${metaini}"
dorie_add_metaini_test(TARGET dorie_example
dorie_add_metaini_test(TARGET dorie_example
# Configure file paths in the config files
# Expand the meta-ini files into current binary dir
# Copy inis into source dir for Sphinx to read
file(COPY ${CMAKE_CURRENT_BINARY_DIR}/3-config-miller.ini
# Copy files required for example runs into build dir
file(COPY richards_param_miller.yml
# Add PFG calls as tests
_add_test(NAME dorie_example_3_pfg_miller
dorie pfg ${CMAKE_CURRENT_BINARY_DIR}/3-parfield-miller.ini)
_add_test(NAME dorie_example_3_pfg_het
dorie pfg ${CMAKE_CURRENT_BINARY_DIR}/3-parfield-heterogeneous.ini)
# Call "dorie create" before actual tests
_add_test(NAME dorie_example_3_create
dorie create)
# Test dependency tree
set_tests_properties(dorie_example_3_create PROPERTIES FIXTURES_SETUP dorie_3)
set_tests_properties(dorie_example_3_pfg_miller PROPERTIES FIXTURES_SETUP dorie_3_miller)
set_tests_properties(dorie_example_3-config-miller PROPERTIES FIXTURES_REQUIRED "dorie_3;dorie_3_miller")
set_tests_properties(dorie_example_3_pfg_het PROPERTIES FIXTURES_SETUP dorie_3_het)
set_tests_properties(dorie_example_3-config-heterogeneous PROPERTIES FIXTURES_REQUIRED "dorie_3;dorie_3_het")
include ${CMAKE_BINARY_DIR}/doc/default_files/config.ini
_test_command = run
__name = 3-config-heterogeneous
# WARNING: Any change in the line ordering of this file will affect the
# tutorial view on this file
file = mapping.h5
volume = index_map
fileName = heterogeneous
outputPath = heterogeneous
include ${CMAKE_BINARY_DIR}/doc/default_files/config.ini
_test_command = run
__name = 3-config-miller
# WARNING: Any change in the line ordering of this file will affect the
# tutorial view on this file
fileName = miller
outputPath = miller
file = richards_param_miller.yml
include ${CMAKE_BINARY_DIR}/doc/default_files/parfield.ini
_test_command = pfg
__name = 3-parfield-heterogeneous
# WARNING: Any change in the line ordering of this file will affect the
# tutorial view on this file
outputFile = mapping.h5
dataset = index_map
converter = binary
indices = 0 1
include ${CMAKE_BINARY_DIR}/doc/default_files/parfield.ini
_test_command = pfg
__name = 3-parfield-miller
# WARNING: Any change in the line ordering of this file will affect the
# tutorial view on this file
outputFile = field.h5
dataset = miller
converter = exponential
varianceScaling = true
index: 0
type: MvG
alpha: -2.3
n: 4.17
k0: 2.2E-5
theta_r: 0.03
theta_s: 0.31
tau: -1.1
type: Miller
file: field.h5
dataset: miller
interpolation: nearest
Random Field Generator
DORiE includes the powerful Gaussian random field generator implemented in
`dune-randomfield <>`_.
We will use this generator for two different use cases to conduct simulations
on heterogeneous media.
The random field generator creates a set of random numbers on a physical
domain. The random variable :math:`X` itself follows a Gaussian (normal)
distribution with mean :math:`\mu = 0` and a selectable variance
.. math::
X \sim \mathcal{N}(\mu = 0, \sigma^2)
The spatial distribution is determined by covariance functions and correlation
lengths. Finally, the random number generation itself is pseudo-random, meaning
that it is actually deterministic but appears random with respect to most
benchmarks. The seed of the generator therefore lets one replicate a random
field from an unchanged system configuration.
The random field generator is wrapped into a DORiE Python module which obtains
the field supplied by the generator and can apply several transformations to
it, which are tailored for specific use cases. The module is dubbed "Parameter
Field Generator" (PFG) and takes an INI-configuration file (default:
``parfield.ini``) as argument, whose keys are documented in
:doc:`/manual/config-file`. The module is called via the
Use Case: Miller-Similar Medium
Small-scale heterogeneity in soil media are typically realized via scalings of
the parameterization functions, rather than changes of the individual
parameters themselves. In this section, we will apply
:ref:`Miller scaling <man-miller_scaling>` to a otherwise homogeneous medium.
This scaling is based on geometric similarity: It assumes that the local soil
heterogeneity can be described by a varying lengthscale of the soil grains
and pores.
Field Generation
We will alter the work flow of the first tutorial by executing the parameter
field generator (PFG) module in the
:ref:`command line interface <man-cli-commands>` before starting the solver.
The default PFG configuration file is called ``parfield.ini``. Enter a
clean directory and create it together with the other default input files
by using the ``dorie create`` command.
The PFG module writes a dataset into an H5 file. The file may already exist,
in which case a new dataset will be added to it. If a dataset with the intended
name already exists, the script throws an error. Let's choose ``miller`` as
dataset name for the dataset containing the Miller scaling factors:
.. literalinclude::
:language: ini
:lines: 9-11
:emphasize-lines: 3
:caption: parfield.ini
The scaling factors of typical Miller-similar media are log-normally
distributed. A log-normal distribution is readily obtained from a normal
distribution by applying the exponential function to all values. This is
achieved in the PFG module by applying the ``exponential`` converter to the
.. literalinclude::
:language: ini
:lines: 9,12
:emphasize-lines: 2
:caption: parfield.ini
Additionally, the exponential converter can apply a scaling to the resulting
distribution based on the variance of the original normal distribution. This
scaling is required to obtain the same mean conductivity as for the
homogeneous medium. The total transformation reads
.. math::
f = \exp (x - \sigma^2),
where :math:`f` is the final dataset value and :math:`x` the corresponing value
of the Gaussian random field. The variance scaling can be enabled in the PFG
config file:
.. literalinclude::
:language: ini
:lines: 14-15
:emphasize-lines: 2
:caption: parfield.ini
Execute the field generator via
.. code-block:: bash
dorie pfg parfield.ini
We now have to insert the resulting field into the simulation. The
:ref:`parameterization file <man-parameter_file>` of the Richars model
(default name: ``richards_param.yml``) contains a ``scaling`` section which
defaults to ``none``. Insert the YAML template for the
:ref:`Miller scaling <man-miller_scaling>` and specify the file path and
dataset path/name. In our current example, we use the default grid of
:math:`100 \times 100` cells on a :math:`1 \text{m} \times 1 \text{m}` domain
in both the PFG and the simulation, so we can set the interpolation to
``nearest``, and leave out ``offset`` and ``scale`` completely:
.. literalinclude:: richards_param_miller.yml
:language: yaml
:lines: 14-20
:emphasize-lines: 2-7
:caption: richards_param.yml
Now execute the simulation:
.. code-block:: bash
dorie run config.ini
The following screenshot shows the saturated conductivity field (left) and the
flux magnitude after 15 time steps (right).
.. image::
:alt: ParaView screenshot of simulation result.
.. admonition:: Input files
================= ==========================================================
PFG Configuration :download:`parfield.ini <3-parfield-miller.ini>`
Configuration :download:`config.ini <3-config-miller.ini>`
Parameters :download:`richards_param.yml <richards_param_miller.yml>`
================= ==========================================================
Use Case: Heterogeneous Medium
In contrast to the continuous approach of Miller-similarity, soil architecture
can feature sharp material interfaces at the scale of interest. To produce
random structures with this quality, we can use the parameter field generator
(PFG) module to build a :ref:`mapping dataset <man-grid_mapping-dataset>` from
a random field. Every integer entry of this dataset will then determine the
parameter set of the medium at the respective grid cell.
Field Generation
To clarify what the resulting field is used for, set the output file and
dataset names,
.. literalinclude::
:language: ini
:lines: 9-11
:emphasize-lines: 2-3
:caption: parfield.ini
To compute the mapping dataset from the Gaussian random field for two media
with indices :math:`i_a` and :math:`i_b`, respectively, the transformation is
achieved by "cutting the distribution in half,"
.. math::
f =
i_a \quad \text{if } x > 0, \\
i_b \quad \text{else}.
Notice that the ``variance`` setting has therefore no effect on the resulting
distribution. The converter for this and the indices can be readily selected in
the PFG configuration file:
.. literalinclude::
:language: ini
:lines: 9,12,13-15
:emphasize-lines: 2,5
:caption: parfield.ini
Execute the PFG module,
.. code-block:: bash
dorie pfg parfield.ini
In the simulation configuration file (default: ``config.ini``), select the
mapping dataset inside the output H5 file to insert the medium mapping:
.. literalinclude::
:language: ini
:lines: 9-11
:emphasize-lines: 2-3
:caption: config.ini
Now make sure that the indices chosen for the converter in the ``parfield.ini``
have valid parameter set entries in the
:ref:`parameterization file <man-parameter_file>` of the Richards model. By
default, index 0 maps to ``sand`` and index 1 maps to ``silt``:
.. literalinclude:: ../../default_files/richards_param.yml
:emphasize-lines: 2-3,14-15
:language: yaml
:caption: richards_param.yml
Execute the simulation:
.. code-block:: bash
dorie run config.ini
The following screenshot shows the water content (left) and the flux magnitude
(right) after 14 time steps.
.. image::
:alt: ParaView screenshot of simulation result.
.. admonition:: Input files
================= ==================================================================
PFG Configuration :download:`parfield.ini <3-parfield-heterogeneous.ini>`
Configuration :download:`config.ini <3-config-heterogeneous.ini>`
Parameters :download:`richards_param.yml </default_files/richards_param.yml>`
================= ==================================================================
message(STATUS "Handling cookbook tests")
......@@ -36,6 +36,7 @@ assignment and increment are based on the :doc:`public-api`.
.. toctree::
......@@ -517,6 +517,8 @@ coordinates in the respective spatial dimensions.
omitted. Only omitting the respective *values* of both keys will lead to
a parser error.
.. _man-miller_scaling:
Miller Scaling
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