[Doc] Polish tutorial 1

parent 828f6d00
message(STATUS "Handling cookbook tests") message(STATUS "Handling cookbook tests")
configure_file(${CMAKE_BINARY_DIR}/doc/default_files/config.ini
${CMAKE_CURRENT_SOURCE_DIR}/config.ini
COPYONLY)
add_subdirectory("tutorial-1") add_subdirectory("tutorial-1")
\ No newline at end of file
dorie_add_metaini_test(TARGET dorie dorie_add_metaini_test(TARGET dorie
METAINI config.mini.in) METAINI tutorial-1.mini.in)
configure_file(${CMAKE_CURRENT_BINARY_DIR}/config.ini configure_file(${CMAKE_CURRENT_BINARY_DIR}/tutorial-1.ini
${CMAKE_CURRENT_SOURCE_DIR}/config.ini ${CMAKE_CURRENT_SOURCE_DIR}/config.ini
COPYONLY)
# Copy file needed for the test to run
configure_file(${CMAKE_BINARY_DIR}/doc/default_files/2d_infiltr.bcdat
2d_infiltr.bcdat
COPYONLY)
configure_file(${CMAKE_BINARY_DIR}/doc/default_files/richards_param.yml
richards_param.yml
COPYONLY) COPYONLY)
\ No newline at end of file
include ${CMAKE_BINARY_DIR}/doc/default_files/config.ini
__name = config
# WARNING: Any change in the line ordering of this file will affect the
# tutorial view on this file
\ No newline at end of file
include ${CMAKE_BINARY_DIR}/doc/default_files/config.ini
_test_command = run
__name = tutorial-1
# WARNING: Any change in the line ordering of this file will affect the
# tutorial view on this file
[simulation]
mode = richards
[grid]
gridType = rectangular
dimensions = 2
extensions = 1 4
cells = 1 200
[grid.mapping]
volume = 0
[richards.parameters]
file = richards_param.yml
[richards.initial]
type = analytic
quantity = matricHead
equation = -h
[richards.boundary]
file = 2d_infiltr.bcdat
[richards.output]
fileName = infiltr_homogeneous_sand_2D
outputPath = ./
\ No newline at end of file
...@@ -3,88 +3,182 @@ Infiltration in homogeneous medium ...@@ -3,88 +3,182 @@ Infiltration in homogeneous medium
********************************** **********************************
One of the most simple DORiE simulations is the case of constant infiltration on One of the most simple DORiE simulations is the case of constant infiltration on
a 2D homogeneous medium. In particular, we will recreate the simulation a 2D homogeneous medium. In particular, we will create a similar simulation to
conducted by Kurt Roth in his the one conducted by Kurt Roth in his
`Soil Physics Lecture Notes <http://ts.iup.uni-heidelberg.de/teaching/#c520>`_, `Soil Physics Lecture Notes <http://ts.iup.uni-heidelberg.de/teaching/#c520>`_,
Chapter 6.3.1. Chapter 6.3.1.
.. todo:: Small summary of the experiment 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.
Configure DORiE Input Files
---------------------------
Hence, in what follows, we will set up input files and run In what follows, we will set up input files and run the simulation step-by-step
the simulation step-by-step reviewing the most important parts of the DORiE reviewing the most important parts of the DORiE work-flow.
workflow.
Configurate DORiE Input Files
-----------------------------
Simulation Mode 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 case, we are only interested in the water flow movement. Hence, the richards
mode is well suited for our purpose mode in the configuration file is well suited for our purpose.
.. code-block:: ini
[simulation] .. literalinclude:: tutorial-1.mini.in
mode = richards :language: ini
:lines: 9-10
Grid Creation Grid Creation
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
Independet of the simulation mode, the grid settings have to be setup For any simulation, the :doc:`grid settings <../../manual/grid>` have to be
because all models always share the grid. setup exactly once since all models share the same grid.
Now let's begin with the spatial extensions. The point of origin in DORiE's
reference frame is located at the lower left (front) point of the domain. In 2D, In this case, we will create a ``rectangular`` grid by specifying the number
the x-direction points to the right, and the y-direction upwards. In 3D, the of ``cells`` and the ``extensions`` of the domain. Grids of this type are
x-direction points to the right, the y-direction points backwards, and the directly created within DORiE, thus, the keyword ``gridFile`` is ignored.
z-direction points upwards. Notice that DORiE does not support negative
coordinates! .. note::
The simulation by Roth is one dimensional, but DORiE only supports two and
The simulation by Roth is one dimensional, but DORiE only supports two and three three dimensions. Hence, we use a 2D simulation with 1 cell for the
dimensions. For now, we leave the extension in x-direction at :math:`x`-direction, as the simulation is symmetrical along this axis.
:math:`1 \, \text{m}`. For the y-direction, we notice that
:math:`y_\text{DORiE} = -z_\text{Roth}`, so we set this extension to We set ``1 4`` as the ``extensions`` of the domain. This means that the
:math:`4 \, \text{m}`. 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 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 x-direction, we specifying the number of cells into each direction. For the
will set this to 1, as the simulation is symmetrical along this axis. For the :math:`x`-direction, we will set this to ``1``. For the :math:`y`-direction,
y-direction, we choose a reasonable resolution of :math:`2 \, \text{cm}` per we choose a reasonable resolution of :math:`2 \, \text{cm}` per cell, meaning
cell, meaning that we need 200 cells in total. 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
.. code-block:: ini Soil Parameterization
^^^^^^^^^^^^^^^^^^^^^
[grid]
extensions = 1 4
cells = 1 200
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.
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 21-22
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
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
Initial Condition Initial Condition
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
The initial condition can be feed with HDF5 data files or with analytic The :doc:`initial condition </manual/initial>` can be feed with HDF5 data
functions (see details in ....). In this case, taking the water table at 0m the files or with analytic functions. In this case, we set an initial
the hydrostaic equilibrium lead to a matric head proportional to the height. condition with the water table at :math:`0\,\text{m}` with a fluid phase in
hydrostatic equilibrium. This can be represented by an ``analytic`` function
.. code-block:: ini where the ``matricHead`` is set to ``-y``.
[richards.initial] .. tip::
type = analytic
quantity = matricHead When referring to the vertical coordinate it is more convenient to use the
equation = -h 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
.. literalinclude:: config.mini.in :math:`z` for 3D domains.
.. literalinclude:: tutorial-1.mini.in
:language: ini :language: ini
:lines: 1,3 :lines: 24-27
:emphasize-lines: 1,3-4
:linenos: 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.
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 29-30
Output
^^^^^^
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
Run DORiE
---------
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
configuration file. A typical DORiE simulation has the following output:
.. code-block:: bash
[18:27:32.762 I] Starting DORiE
[18:27:32.762 I] Reading configuration file: config.ini
[18:27:32.768 I] Creating output directory: ./
[18:27:32.768 I] Creating a rectangular grid in 2D
[18:27:32.776 I] [RIC] Loading parameter data file: richards_param.yml
[18:27:32.779 I] [RIC] Reading boundary condition data file: 2d_infiltr.bcdat
[18:27:32.784 I] [RIC] Setup complete
[18:27:33.296 I] [RIC] Time Step 0: 0.00e+00 + 1.00e+01 -> 1.00e+01
[18:27:33.581 I] [RIC] Time Step 1: 1.00e+01 + 1.50e+01 -> 2.50e+01
[18:27:33.899 I] [RIC] Time Step 2: 2.50e+01 + 2.25e+01 -> 4.75e+01
[18:27:34.177 I] [RIC] Time Step 3: 4.75e+01 + 3.38e+01 -> 8.12e+01
...
[18:27:46.863 I] [RIC] Time Step 51: 7.67e+05 + 1.00e+05 -> 8.67e+05
[18:27:46.894 I] [RIC] Time Step 52: 8.67e+05 + 1.00e+05 -> 9.67e+05
[18:27:46.923 I] [RIC] Time Step 53: 9.67e+05 + 3.34e+04 -> 1.00e+06
[18:27:46.938 I] DORiE finished after 1.47e+01s :)
.. todo:: Analyze results
.. admonition:: Input files .. admonition:: Input files
============= ====================================================================== ============= ======================================================================
Configuration :download:`config.ini <config.ini>` Configuration :download:`config.ini <config.ini>`
Boundary :download:`2d_infiltr.bcdat <../../default_files/2d_infiltr.bcdat>` Boundary :download:`2d_infiltr.bcdat </default_files/2d_infiltr.bcdat>`
Parameters :download:`richards_param.yml <../../default_files/richards_param.yml>` Parameters :download:`richards_param.yml </default_files/richards_param.yml>`
============= ====================================================================== ============= ======================================================================
\ No newline at end of file
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