diff --git a/.gitignore b/.gitignore
index 6913e567f049a0fa343034dde9f724830b5da66e..0c45c75c6dd5a20320bc8bf3a498a416901ddfb6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,6 +3,8 @@ build-cmake/
# Exclude generated files
doc/manual/config-file.rst
+doc/cookbook/config.ini
+doc/cookbook/tutorial-1/config.ini
python/dorie/wrapper/pf_from_file.py
python/dorie/wrapper/test_dorie.py
python/dorie/dorie/cli/cmds.py
diff --git a/CMakeLists.txt b/CMakeLists.txt
index c080a3315461e30d4883e100c3bb063e5be67aa6..0f86baad7bbcf4ee32b9f547c4858d976372c189 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -50,6 +50,7 @@ add_subdirectory("dune")
add_subdirectory("lib")
if(dune-testtools_FOUND)
add_subdirectory("test")
+ add_subdirectory("doc/cookbook")
endif()
# finalize the dune project, e.g. generating config.h etc.
diff --git a/doc/cookbook/CMakeLists.txt b/doc/cookbook/CMakeLists.txt
new file mode 100644
index 0000000000000000000000000000000000000000..d0b9b17f3c02682782d6d6c9250bd61f32820765
--- /dev/null
+++ b/doc/cookbook/CMakeLists.txt
@@ -0,0 +1,7 @@
+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
diff --git a/doc/cookbook/index.rst b/doc/cookbook/index.rst
index d9e341294567fd2849d2899845ad83a4e886e80c..4273b504763825545fcb05a601a65c92c097800c 100644
--- a/doc/cookbook/index.rst
+++ b/doc/cookbook/index.rst
@@ -2,17 +2,76 @@ Introduction
************
This part of the documentation guides through increasingly complicated
-use-cases of DORiE. It is intended for users who wish to jump right into using
-DORiE, without much knowledge of all its functions. 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 `_ or use a local
-installation. See the installation manual for details.
-Additionally, install Paraview_ for analyzing the output.
+installation. See the installation manual for details. Additionally, install Paraview_ for analyzing the output.
.. _Paraview: http://www.paraview.org/download/
-.. _Gmsh: http://gmsh.info
+
+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
+:ref:`command line interface documentation `.
+
+Once ready, create a directory where you want to perform the simulations.
+For instance
+
+.. code-block:: bash
+
+ mkdir $HOME/Documents/dorie/ex1
+ cd $HOME/Documents/dorie/ex1
+
+Create DORiE Input Files
+========================
+
+DORiE needs multiple input files to work. Let's check them:
+
+* **Configuration File:** (:file:`.ini`) Supplies static information on the
+ simulation. Have a look at the :doc:`config-file` for more information on
+ the file syntax, or default and possible values.
+* **Parameter File:** (:file:`.yml`) Supplies information on the parameters of
+ the richards model. Have a look at the :doc:`parameter-file` for more information on
+ the file syntax, or default and possible values.
+* **Boundary Condition Datafile:** (:file:`.bcdat`) Specifying the boundary
+ conditions dependent on time and space. Name (and path) of the desired file
+ have to be stated in the Parameter File at key ``boundary.file``.
+ The :doc:`bcfile` supplies information on how write and use the BC
+ Datafile.
+* *Optional* **Mesh File:** (:file:`.msh`) Representing the grid on which the
+ simulation will run. This file is only required if ``grid.gridType = simplex``
+ is chosen in the Parameter File. The Path to the file and it's name will then
+ have to be stated at ``grid.gridFile``. Use Gmsh_ to easily create such a
+ file.
+
+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, where could you find an example of these input files? The command
+
+.. code-block:: bash
+ dorie create
+will provide the three first mentioned files in your current folder.
+Explore them!
+
+.. tip::
+ Each recipe in this cookbook provides a complete set of input files. You will
+ find them at the end of the recipe in blocks as the one below.
+
+.. admonition:: Input files
+
+ ============= ======================================================================
+ Configuration :download:`config.ini `
+ Boundary :download:`2d_infiltr.bcdat `,
+ :download:`3d_infiltr.bcdat `,
+ :download:`2d_solute.bcdat `,
+ :download:`3d_solute.bcdat `
+ Parameters :download:`richards_param.yml `,
+ :download:`transport_param.yml `
+ ============= ======================================================================
\ No newline at end of file
diff --git a/doc/cookbook/restart.rst b/doc/cookbook/restart.rst
index e61705fa528027ef6a33c1683fee245f4452a4e7..b71b2edde319336645b8d4a9b764baa55acac11c 100644
--- a/doc/cookbook/restart.rst
+++ b/doc/cookbook/restart.rst
@@ -75,3 +75,6 @@ Notice that this qualifies as a pseudo-restart because the degrees of freedom
of the last simulation are not completely recovered. Indeed, they are
degenerated! Hence, strictly speaking, a pseudo-restart will lead to different
results compared with respect to a one-run simulation.
+
+.. todo:: Add files
+.. todo:: Add test
\ No newline at end of file
diff --git a/doc/cookbook/tutorial-1/CMakeLists.txt b/doc/cookbook/tutorial-1/CMakeLists.txt
new file mode 100644
index 0000000000000000000000000000000000000000..6e9645871355184148f216d9bbe123b0d4f0c1d9
--- /dev/null
+++ b/doc/cookbook/tutorial-1/CMakeLists.txt
@@ -0,0 +1,15 @@
+
+dorie_add_metaini_test(TARGET dorie
+ METAINI config.mini.in)
+
+configure_file(${CMAKE_CURRENT_BINARY_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)
\ No newline at end of file
diff --git a/doc/cookbook/tutorial-1/config.mini.in b/doc/cookbook/tutorial-1/config.mini.in
new file mode 100644
index 0000000000000000000000000000000000000000..8ae96c4ca9175600e8f3bd2b95e3057c67495a85
--- /dev/null
+++ b/doc/cookbook/tutorial-1/config.mini.in
@@ -0,0 +1,5 @@
+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
diff --git a/doc/cookbook/tutorial-1/tutorial.rst b/doc/cookbook/tutorial-1/tutorial.rst
new file mode 100644
index 0000000000000000000000000000000000000000..f68e2aa14a10ac486980dc415ae765381ec995a0
--- /dev/null
+++ b/doc/cookbook/tutorial-1/tutorial.rst
@@ -0,0 +1,90 @@
+**********************************
+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
+`Soil Physics Lecture Notes `_,
+Chapter 6.3.1.
+
+.. todo:: Small summary of the experiment
+
+
+
+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
+-----------------------------
+
+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
+
+ [simulation]
+ mode = richards
+
+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}`.
+
+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.
+
+.. code-block:: ini
+
+ [grid]
+ extensions = 1 4
+ cells = 1 200
+
+
+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
+ :language: ini
+ :lines: 1,3
+ :emphasize-lines: 1,3-4
+ :linenos:
+
+
+.. admonition:: Input files
+
+ ============= ======================================================================
+ Configuration :download:`config.ini `
+ Boundary :download:`2d_infiltr.bcdat `
+ Parameters :download:`richards_param.yml `
+ ============= ======================================================================
\ No newline at end of file
diff --git a/doc/index.rst b/doc/index.rst
index 524e0601fc981d70cc2b9ddfacbc474c583988e8..4f3e10dfede69bed46058bd5444209f62f3ccf5e 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -22,6 +22,15 @@ assignment and increment are based on the :doc:`public-api`.
introduction/features
introduction/data-io
+.. toctree::
+ :maxdepth: 1
+ :numbered:
+ :caption: Cook Book
+
+ cookbook/index
+ cookbook/tutorial-1/tutorial
+ cookbook/restart
+
.. toctree::
:maxdepth: 2
:caption: Manual
@@ -36,13 +45,6 @@ assignment and increment are based on the :doc:`public-api`.
manual/interpolators
public-api
-.. toctree::
- :maxdepth: 2
- :caption: Cook Book
-
- cookbook/index
- cookbook/restart
-
.. toctree::
:maxdepth: 1
:caption: Python Modules
diff --git a/dune/dorie/test/CMakeLists.txt b/dune/dorie/test/CMakeLists.txt
index 8f0c52ee1fe354d75dd9a9df361174f1b9229b11..989fc192d690ab6780c278ac557b780bd308ff86 100644
--- a/dune/dorie/test/CMakeLists.txt
+++ b/dune/dorie/test/CMakeLists.txt
@@ -1,3 +1,5 @@
+message(STATUS "Handling unit tests")
+
# copy ALL the config files and stuff
file(COPY scaling.h5
scaling.yml