Skip to content

GitLab

Commit c68b47ac authored by Lukas Riedel's avatar Lukas Riedel
Browse files
Options

Refactor first Cookbook tutorial 

* Move into folder '1-infiltration-sand'.
* Remove trailing whitespace from files.
* Add captions to source code.
* Slightly reformulate instructions.
* Add more links to manual.
parent 0de80b22
Hide whitespace changes
Inline Side-by-side
Showing with 97 additions and 86 deletions
doc/cookbook/tutorial-1/tutorial.rst → doc/cookbook/1-infiltration-sand/tutorial.rst
View file @ c68b47ac
......@@ -3,158 +3,161 @@ Infiltration in Homogeneous Medium
**********************************
One of the most simple DORiE simulations is the case of constant infiltration on
a 2D homogeneous medium. In particular, we will create a similar simulation to
the one conducted by Kurt Roth in his
`Soil Physics Lecture Notes <http://ts.iup.uni-heidelberg.de/teaching/#c520>`_,
Chapter 6.3.1.
a 2D homogeneous medium. In particular, we will create a similar simulation to
the one conducted by Kurt Roth in his
`Soil Physics Lecture Notes <http://ts.iup.uni-heidelberg.de/teaching/#c520>`_,
Chapter 6.3.1.
Study Case
----------
Consider a uniform and isotropic soil with a constant water table at depth
:math:`y=0\,\text{m}, h_m = 0` and vertical, constant water flux in the vadose
zone. We choose the :math:`y`-axis to point upwards, hence :math:`y` > 0 above
the water table. For times :math:`t < 0`, the water phase is in static
equilibrium with the water table, i.e., :math:`j_w = 0` in the entire profile.
Let the groundwater table be :math:`4\,\text{m}` below the soil surface where,
for :math:`t<0,\,h_m = 0` . For :math:`t≥0`, the water flux through the upper
boundary is set to :math:`j_{w_0} = 5.56 \cdot 10^{−6}\,\text{m/s}`. This
corresponds to :math:`20 \,\text{mm/h}`, a heavy rainfall.
Consider a uniform and isotropic soil with constant water table
(:math:`h_m = 0\,\text{m}`) at height :math:`y=0\,\text{m}` and vertical flux
in the vadose zone. We choose the :math:`y`-axis to point upwards.
For times :math:`t < 0`, the water phase is in static equilibrium, i.e.,
:math:`j_w = 0\,\text{ms}^{-1}` in the entire domain. The soil surface is
located at :math:`y=4\,\text{m}`. For :math:`t \leq 0`, the water flux through
the surface boundary is set to
:math:`j_w = 5.56 \cdot 10^{−6}\,\text{ms}^{-1} = 20\,\text{mm}\,\text{h}^{-1}`,
equivalent to heavy rainfall.
Configure DORiE Input Files
---------------------------
In what follows, we will set up input files and run the simulation step-by-step
In what follows, we will set up input files and run the simulation step-by-step
reviewing the most important parts of the DORiE work-flow.
Simulation Mode
^^^^^^^^^^^^^^^
The first decision to make is to choose the mode of your simulation. In this
The first decision to make is to choose the mode of your simulation. In this
case, we are only interested in the water flow movement. Hence, the richards
mode in the configuration file is well suited for our purpose.
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 9-10
:caption: config.ini
Grid Creation
^^^^^^^^^^^^^
For any simulation, the :doc:`grid settings <../../manual/grid>` have to be
For any simulation, the :doc:`grid settings </manual/grid>` have to be
setup exactly once since all models share the same grid.
In this case, we will create a ``rectangular`` grid by specifying the number
of ``cells`` and the ``extensions`` of the domain. Grids of this type are
In this case, we will create a ``rectangular`` grid by specifying the number
of ``cells`` and the ``extensions`` of the domain. Grids of this type are
directly created within DORiE, thus, the keyword ``gridFile`` is ignored.
.. note::
The simulation by Roth is one dimensional, but DORiE only supports two and
three dimensions. Hence, we use a 2D simulation with 1 cell for the
The original simulation is one dimensional, but DORiE only supports two and
three dimensions. Hence, we use a 2D simulation with 1 cell for the
:math:`x`-direction, as the simulation is symmetrical along this axis.
We set ``1 4`` as the ``extensions`` of the domain. This means that the
rectangular grid will be generated with an extension of :math:`1\,\text{m}` in
the :math:`x`-direction and an extension of :math:`4\,\text{m}` in
the :math:`y`-direction. Notice that the :math:`x`-direction points to the
right, and the :math:`y`-direction upwards. Also, notice that the point of
origin in DORiE's reference frame is located at the lower left point.
Now we have to fill a domain of this size with rectangular grid cells by
specifying the number of cells into each direction. For the
:math:`x`-direction, we will set this to ``1``. For the :math:`y`-direction,
we choose a reasonable resolution of :math:`2 \, \text{cm}` per cell, meaning
that we need ``200`` cells in total. That is, we set the pair ``1 200`` of
We set ``1 4`` as the ``extensions`` of the domain. This means that the
rectangular grid will be generated with an extension of :math:`1\,\text{m}` in
the :math:`x`-direction and an extension of :math:`4\,\text{m}` in
the :math:`y`-direction. Notice that the :math:`x`-direction points to the
right, and the :math:`y`-direction upwards. The point of origin in DORiE's
reference frame is located at the lower left point.
Now we have to fill a domain of this size with rectangular grid cells by
specifying the number of cells into each direction. For the
:math:`x`-direction, we will set this to ``1``. For the :math:`y`-direction,
we choose a reasonable resolution of :math:`2\,\text{cm}` per cell, meaning
that we need ``200`` cells in total. That is, we set the pair ``1 200`` of
``cells`` in the config file.
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 12-16
:caption: config.ini
Soil Parameterization
^^^^^^^^^^^^^^^^^^^^^
First, in the configuration file we set the parameterization file that we want
to use. In this case, we provide the file ``richards_param.yml`` provided by
the ``dorie create`` command.
First, in the configuration file we set the
:ref:`parameterization file <man-parameter_file>` that we want to use. In this
case, we select the file ``richards_param.yml`` provided by the
``dorie create`` command.
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 21-22
:caption: config.ini
Now, for homogeneous materials, the key ``grid.mapping.volume`` in the config
file refers to the keyword ``index`` to use in the parameterization file for
Now, for homogeneous materials, the key ``grid.mapping.volume`` in the config
file refers to the keyword ``index`` to use in the parameterization file for
the whole domain. That said, if the parameterization file looks like this:
.. literalinclude:: ../../default_files/richards_param.yml
:emphasize-lines: 2-3,14-15
:language: yaml
:caption: richards_param.yml
then, a ``volume`` set to ``0`` will have a parameterization for ``sand`` while
a ``volume`` set to ``1`` will have a parameterization for
then, a ``volume`` set to ``0`` will have a parameterization for ``sand`` while
a ``volume`` set to ``1`` will have a parameterization for
``silt``. For now, let's say we want to simulate an homogeneous sand.
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 18-19
:caption: config.ini
Initial Condition
^^^^^^^^^^^^^^^^^
The :doc:`initial condition </manual/initial>` can be feed with HDF5 data
files or with analytic functions. In this case, we set an initial
condition with the water table at :math:`0\,\text{m}` with a fluid phase in
The :doc:`initial condition </manual/initial>` can be fed with HDF5 data
files or with analytic functions. In this case, we set an initial
condition with the water table at :math:`y = 0\,\text{m}` with a fluid phase in
hydrostatic equilibrium. This can be represented by an ``analytic`` function
where the ``matricHead`` is set to ``-y``.
.. tip::
When referring to the vertical coordinate it is more convenient to use the
the `height` ``h`` instead of the :math:`i`-axis of the domain. This is
because the vertical direction in DORiE is :math:`y` for 2D while it is
:math:`z` for 3D domains.
where the ``matricHead`` is simply set to ``-h``. See the documentation of
:ref:`analytic initial conditions <man-initial-types>` for details.
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 24-27
:caption: config.ini
Boundary Condition
^^^^^^^^^^^^^^^^^^
The :doc:`boundary conditions file </manual/bcfile>` has to be specified by the
keyword ``richards.boundary.file`` in the configuration file. For now, we will
use the infiltration file for 2D, ``2d_infiltr.bcdat``, provided by the command
``dorie create``. By default, this file sets a constant infiltration of
:math:`-5.55\cdot 10^{-6}\,\text{ms^{-1}}` at the top, a constant matric head of
:math:`0\,\text{m}` at the bottom, and a no-flux condition on the sides of the
domain.
The :doc:`boundary conditions file </manual/bcfile>` has to be specified by the
keyword ``richards.boundary.file`` in the configuration file. For now, we will
use the infiltration file for 2D, ``2d_infiltr.bcdat``, provided by the command
``dorie create``. By default, this file sets a constant infiltration of
:math:`j_w = -5.55\cdot 10^{-6}\,\text{ms}^{-1}` at the top, a constant matric
head of :math:`h_m = 0\,\text{m}` at the bottom, and a no-flux condition on the
sides of the domain.
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 29-30
:caption: config.ini
Output
^^^^^^
Finally, we give a name and a path to the
Finally, we give a name and a path to the
:doc:`output files </introduction/data-io>` of the simulation:
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 32-34
:caption: config.ini
Run DORiE
---------
Once everything is set up, we :doc:`run DORiE </manual/cli>` by calling the
Once everything is set up, we :doc:`run DORiE </manual/cli>` by calling the
command ``dorie run`` followed by the configuration file ``confing.ini``:
.. code-block:: bash
dorie run config.ini
By doing this, the simulation should start and provide information about the
status of the simulation depending on the on the ``logLevel`` keyword on the
By doing this, the simulation should start and provide information about the
status of the simulation depending on the on the ``logLevel`` keyword on the
configuration file. A typical DORiE simulation has the following output:
.. code-block:: bash
.. code-block:: none
[18:27:32.762 I] Starting DORiE
[18:27:32.762 I] Reading configuration file: config.ini
......@@ -176,10 +179,11 @@ configuration file. A typical DORiE simulation has the following output:
Results
-------
The :doc:`results should have been written </introduction/data-io>` in several
:file:`.vtu` files, one for each time step, and gathered by a :file:`.pvd` file.
By opening the latter in Paraview_ (or VisIt_) it is possible to visualize the
dynamics of the matric head, water content, and water flux as shown below.
The :ref:`results <intro-io-output>` should have been written in several
:file:`.vtu` files, one for each time step, and gathered by a :file:`.pvd`
file. By opening the latter in Paraview_ (or VisIt_) it is possible to
visualize the dynamics of the matric head, water content, and water flux as
shown below.
.. _Paraview: http://www.paraview.org/
.. _VisIt: https://visit.llnl.gov/
......@@ -192,4 +196,4 @@ dynamics of the matric head, water content, and water flux as shown below.
Configuration :download:`config.ini <config.ini>`
Boundary :download:`2d_infiltr.bcdat </default_files/2d_infiltr.bcdat>`
Parameters :download:`richards_param.yml </default_files/richards_param.yml>`
============= ======================================================================
\ No newline at end of file
============= ======================================================================
doc/cookbook/CMakeLists.txt
View file @ c68b47ac
message(STATUS "Handling cookbook tests")
add_subdirectory("tutorial-1")
\ No newline at end of file
add_subdirectory(1-infiltration-sand)
doc/cookbook/index.rst
View file @ c68b47ac
......@@ -2,14 +2,17 @@ Introduction
************
This part of the documentation guides through increasingly complicated
use-cases of DORiE. It is intended for users who are using DORiE for the first time. It explains the usage of the program, how to execute a simulation and how to analyze its results. The relevant manual pages will be linked on the way.
use-cases of DORiE. It is intended for users who are using DORiE for the first
time. It explains the usage of the program, how to execute a simulation and how
to analyze its results. The relevant manual pages will be linked on the way.
Prerequisites
=============
You need a working application. You can either use the image shipped via
`Docker Hub <https://hub.docker.com/r/dorie/dorie/>`_ or use a local
installation. See the :doc:`installation manual </introduction/readme>` for details. Additionally, install Paraview_ for analyzing the output.
installation. See the :doc:`installation manual </introduction/readme>` for
details. Additionally, install Paraview_ for analyzing the output.
.. _Paraview: http://www.paraview.org/download/
......@@ -17,11 +20,11 @@ Setup DORiE virtual environment
===============================
Before of any proper calculation, it is necessary to set up the DORiE virtual
environment in your terminal. This will allow you to call the DORiE commands
anywhere in your system. For this, follow the instructions in the
:doc:`command line interface documentation </manual/cli>`.
environment in your terminal. This will allow you to call the DORiE commands
anywhere in your system. For this, follow the instructions in the
:doc:`command line interface documentation </manual/cli>`.
Once ready, create a directory where you want to perform the simulations.
Once ready, create a directory where you want to perform the simulations.
For instance
.. code-block:: bash
......@@ -32,9 +35,9 @@ For instance
Create DORiE Input Files
========================
DORiE needs multiple :doc:`input files </introduction/data-io>` to work.
Although these files seem to be quite overwhelming at the beginning, you will
notice that most of their parameters will not be modified in most of the
DORiE needs multiple :doc:`input files </introduction/data-io>` to work.
Although these files seem to be quite overwhelming at the beginning, you will
notice that most of their parameters will not be modified in most of the
cases. Now, you can find an example of these input files using the command
.. code-block:: bash
......@@ -42,22 +45,22 @@ cases. Now, you can find an example of these input files using the command
dorie create
which will provide the files for a simple DORiE application in your
which will provide the files for a simple DORiE application in your
current folder. Explore them!
.. tip::
Most recipes in this cookbook provide a complete set of input files for the
specified simulation. You will find them at the end of the recipe in blocks
Most recipes in this cookbook provide a complete set of input files for the
specified simulation. You will find them at the end of the recipe in blocks
as the one below.
.. admonition:: Input files
============= ======================================================================
Configuration :download:`config.ini </default_files/config.ini>`
Boundary :download:`2d_infiltr.bcdat <../default_files/2d_infiltr.bcdat>`,
:download:`3d_infiltr.bcdat </default_files/3d_infiltr.bcdat>`,
:download:`2d_solute.bcdat </default_files/2d_solute.bcdat>`,
Boundary :download:`2d_infiltr.bcdat <../default_files/2d_infiltr.bcdat>`,
:download:`3d_infiltr.bcdat </default_files/3d_infiltr.bcdat>`,
:download:`2d_solute.bcdat </default_files/2d_solute.bcdat>`,
:download:`3d_solute.bcdat </default_files/3d_solute.bcdat>`
Parameters :download:`richards_param.yml </default_files/richards_param.yml>`,
Parameters :download:`richards_param.yml </default_files/richards_param.yml>`,
:download:`transport_param.yml </default_files/transport_param.yml>`
============= ======================================================================
\ No newline at end of file
============= ======================================================================
doc/index.rst
View file @ c68b47ac
......@@ -28,7 +28,7 @@ assignment and increment are based on the :doc:`public-api`.
:caption: Cook Book
cookbook/index
cookbook/tutorial-1/tutorial
cookbook/1-infiltration-sand/tutorial
cookbook/restart
.. toctree::
......
doc/introduction/data-io.rst
View file @ c68b47ac
......@@ -44,6 +44,8 @@ Templates for the required files can conveniently be generated with the
| | | | |
+----------------------------------------+----------------+------------------------------------------+----------------------------------------------------------------------+
.. _intro-io-output:
Output Files
============
......
doc/manual/initial.rst
View file @ c68b47ac
......@@ -22,6 +22,8 @@ Initial condition input is controlled entirely via the
interpolator (if applicable), the resulting solution may vary greatly from
the actual input data.
.. _man-initial-types:
Input Types
-----------
This is an overview of all input types for initial conditions.
......
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