[Doc] Polish tutorial 1

parent 828f6d00
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")
\ No newline at end of file
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
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)
\ 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
**********************************
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
conducted by Kurt Roth in his
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.
.. 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
the simulation step-by-step reviewing the most important parts of the DORiE
workflow.
Configurate DORiE Input Files
-----------------------------
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
case, we are only interested in the water flow movement. Hence, the richards
mode is well suited for our purpose
.. code-block:: ini
mode in the configuration file is well suited for our purpose.
[simulation]
mode = richards
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 9-10
Grid Creation
^^^^^^^^^^^^^
Independet of the simulation mode, the grid settings have to be setup
because all models always share the 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,
the x-direction points to the right, and the y-direction upwards. In 3D, the
x-direction points to the right, the y-direction points backwards, and the
z-direction points upwards. Notice that DORiE does not support negative
coordinates!
The simulation by Roth is one dimensional, but DORiE only supports two and three
dimensions. For now, we leave the extension in x-direction at
:math:`1 \, \text{m}`. For the y-direction, we notice that
:math:`y_\text{DORiE} = -z_\text{Roth}`, so we set this extension to
:math:`4 \, \text{m}`.
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
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
: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 x-direction, we
will set this to 1, as the simulation is symmetrical along this axis. For the
y-direction, we choose a reasonable resolution of :math:`2 \, \text{cm}` per
cell, meaning that we need 200 cells in total.
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
.. code-block:: ini
[grid]
extensions = 1 4
cells = 1 200
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.
.. 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
^^^^^^^^^^^^^^^^^
The initial condition can be feed with HDF5 data files or with analytic
functions (see details in ....). In this case, taking the water table at 0m the
the hydrostaic equilibrium lead to a matric head proportional to the height.
.. code-block:: ini
[richards.initial]
type = analytic
quantity = matricHead
equation = -h
.. literalinclude:: config.mini.in
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
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.
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 1,3
:emphasize-lines: 1,3-4
:linenos:
:lines: 24-27
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
============= ======================================================================
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>`
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
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