[Cookbook] Add test for first tutorial and organise some of the pages

parent 272e78ff
...@@ -3,6 +3,8 @@ build-cmake/ ...@@ -3,6 +3,8 @@ build-cmake/
# Exclude generated files # Exclude generated files
doc/manual/config-file.rst 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/pf_from_file.py
python/dorie/wrapper/test_dorie.py python/dorie/wrapper/test_dorie.py
python/dorie/dorie/cli/cmds.py python/dorie/dorie/cli/cmds.py
......
...@@ -50,6 +50,7 @@ add_subdirectory("dune") ...@@ -50,6 +50,7 @@ add_subdirectory("dune")
add_subdirectory("lib") add_subdirectory("lib")
if(dune-testtools_FOUND) if(dune-testtools_FOUND)
add_subdirectory("test") add_subdirectory("test")
add_subdirectory("doc/cookbook")
endif() endif()
# finalize the dune project, e.g. generating config.h etc. # finalize the dune project, e.g. generating config.h etc.
......
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
...@@ -2,17 +2,76 @@ Introduction ...@@ -2,17 +2,76 @@ Introduction
************ ************
This part of the documentation guides through increasingly complicated 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 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.
DORiE, without much knowledge of all its functions. The relevant manual pages
will be linked on the way.
Prerequisites Prerequisites
============= =============
You need a working application. You can either use the image shipped via 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 `Docker Hub <https://hub.docker.com/r/dorie/dorie/>`_ or use a local
installation. See the installation manual for details. installation. See the installation manual for details. Additionally, install Paraview_ for analyzing the output.
Additionally, install Paraview_ for analyzing the output.
.. _Paraview: http://www.paraview.org/download/ .. _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 <manual/cli>`.
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 <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>`,
:download:`3d_solute.bcdat <../default_files/3d_solute.bcdat>`
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
...@@ -75,3 +75,6 @@ Notice that this qualifies as a pseudo-restart because the degrees of freedom ...@@ -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 of the last simulation are not completely recovered. Indeed, they are
degenerated! Hence, strictly speaking, a pseudo-restart will lead to different degenerated! Hence, strictly speaking, a pseudo-restart will lead to different
results compared with respect to a one-run simulation. results compared with respect to a one-run simulation.
.. todo:: Add files
.. todo:: Add test
\ No newline at end of file
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
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
**********************************
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 <http://ts.iup.uni-heidelberg.de/teaching/#c520>`_,
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 <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
...@@ -22,6 +22,15 @@ assignment and increment are based on the :doc:`public-api`. ...@@ -22,6 +22,15 @@ assignment and increment are based on the :doc:`public-api`.
introduction/features introduction/features
introduction/data-io introduction/data-io
.. toctree::
:maxdepth: 1
:numbered:
:caption: Cook Book
cookbook/index
cookbook/tutorial-1/tutorial
cookbook/restart
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
:caption: Manual :caption: Manual
...@@ -36,13 +45,6 @@ assignment and increment are based on the :doc:`public-api`. ...@@ -36,13 +45,6 @@ assignment and increment are based on the :doc:`public-api`.
manual/interpolators manual/interpolators
public-api public-api
.. toctree::
:maxdepth: 2
:caption: Cook Book
cookbook/index
cookbook/restart
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
:caption: Python Modules :caption: Python Modules
......
message(STATUS "Handling unit tests")
# copy ALL the config files and stuff # copy ALL the config files and stuff
file(COPY scaling.h5 file(COPY scaling.h5
scaling.yml scaling.yml
......
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