Commit e1663417 authored by Lukas Riedel's avatar Lukas Riedel

Restructure user docs

* Do not use DUNE CMake module for creating Sphinx docs anymore
* Create subdirectories: manual, python, cookbook
* Remove unused files
* Remove 'Guided doxygen documentation'
* Add symlink from doc/manual/ to README
parent b506eee7
......@@ -2,6 +2,7 @@
# Exclude generated files
# Welcome to DORiE!
(**D**UNE-**O**perated **Ri**chards equation solving **E**nvironment)
DORiE is a software suite for solving the Richards Equation. The core feature is a C++ PDE-solver powered by [DUNE]( and the [DUNE-PDELab]( module. It implements a Discontinous Galerkin (DG) discretization scheme on structured rectangular / cubic and unstructured simplex grids in two and three spatial dimensions, and makes use of advanced features like adaptive grid refinement.
......@@ -8,7 +8,7 @@ The suite encapsulates a documentation and various tools for program setup, prog
DORiE is developed and maintained by the [DORiE Developers]( of the [TS-CCEES]( research group at [IUP Heidelberg](, supervised by [Kurt Roth](, in collaboration with [Ole Klein]( and the [Scientific Computing Group]( of [IWR Heidelberg](
# Installation Instructions
## Installation Instructions
DORiE is a [DUNE]( module and requires several other DUNE modules as well as third party software packages. Installation can be handled manually on your local machine, but for inexperienced users it is recommended to use the deployment software [Docker]( instead.
......@@ -18,7 +18,7 @@ directly to the the instructions on [how to execute DORiE](#run-dorie-run).
The commands listed there are appended to the usual commands for running a
Docker container. See the description on Docker Hub for further details.
## Download Docker image
### Download Docker image
If you want to use any stable version of DORiE, or the most recent unstable
version, you can download the appropriate images from Docker Hub. To do so,
......@@ -32,7 +32,7 @@ refers to the latest stable version. You can download any tag by specifying
the release tags list of the Git repository. The latest unstable version is
tagged as `devel`.
## Docker Installation
### Docker Installation
You can also compile any local version of DORiE into a new Docker image. To do
so, execute
......@@ -43,7 +43,7 @@ from within the top-level DORiE source directory. Docker will use a prepared
image from Dockerhub and install DORiE into it. The created image will be called
## Manual Installation
### Manual Installation
Installing all packages manually can be quite an effort, but useful for developers who want to have easy access to the source files or users who prefer to run DORiE without the Docker overhead.
......@@ -53,7 +53,7 @@ DORiE is configured, built, and installed via the
[DUNE Buildsystem](, using the
`dunecontrol` script to handle DUNE-internal dependencies.
### Dependencies
#### Dependencies
Depending on your system configuration, there will be more packages necessary to
install DORiE on your machine. See the step-by-step manual for further details.
......@@ -86,7 +86,7 @@ by CI tests.
| [dune-randomfield]( | master
### Optional Packages
#### Optional Packages
| Software | Version/Branch | Comments |
| ---------| -------------- | -------- |
| [dune-testtools]( | releases/2.6 | Handles system tests
......@@ -95,7 +95,7 @@ by CI tests.
| [ParMETIS]( | 4 | For parallel runs
### Step-by-step Instructions
#### Step-by-step Instructions
These instructions are suitable for a clean **Ubuntu** or **macOS** setup. The main difference between the two systems is the package manager. Debian-based systems have the APT manager already built in. On Mac, we recommend installing [Homebrew]( If you prefer to use [MacPorts](, you need to check if some of the packages require different installation options than displayed here.
If you installed [Anaconda]( on your machine, you don't need to install Python or Pip. Simply skip these packages when using the package managers for installing the software. However, notice the warnings when compiling DORiE below!
......@@ -105,10 +105,10 @@ If you installed [Anaconda](
xcode-select --install
2. Install third party packages:
apt update
apt update
apt install cmake doxygen gcc g++ gfortran \
git libatlas-base-dev libfftw3-dev libfftw3-mpi-dev \
libfreetype6-dev libhdf5-mpi-dev libopenmpi-dev libpng-dev \
......@@ -159,7 +159,7 @@ If you installed [Anaconda](
to the `CMAKE_FLAGS` in the call to `dunecontrol` above.
### Experimental Features
#### Experimental Features
The local operator implementing Richards equation's discretization supports
multiple scheme settings. Setting these via the config file is disabled by
default. You can enable this feature by reconfiguring DORiE with the CMake flag
......@@ -169,16 +169,16 @@ The configuration settings in the section `[dg.experimental]` will then override
the default settings.
## Recommended Third-Party Software
### Recommended Third-Party Software
The following software packages are cross-platform, so you should be able to find a release that fits your operating system:
* [Gmsh]( An open-source CAD that can be used to create the `.msh` files used by DORiE to define triangular meshes.
* [ParaView]( A powerful post-processing tool for VTK files. Offers both visualization and data analysis tools.
# Usage
## Usage
## Documentation
### Documentation
The documentation of the latest release branch can be found [online](
......@@ -193,14 +193,14 @@ or navigate to the `dorie/build-cmake` directory and call
You will then find the index page of the documentation at
## Run, DORiE, Run!
### Run, DORiE, Run!
DORiE provides a command line interface (CLI) for all its functions.
The required Python modules and all their dependencies are readily installed
into a virtual environment (`venv`), which has to be activated within a
shell session. You can do so by activating it in your current session
(Manual Installation only) or by running the Docker application.
### Run the `venv` using the Docker application
#### Run the `venv` using the Docker application
If you did not install DORiE locally, you can use the Docker
application to boot up the virtual environment in a mounted directory of choice.
......@@ -222,7 +222,7 @@ virtual environment activated.
Notice, that you can only use **local file paths** in all configuration settings
due to the directory mount.
### Activate the `venv` locally
#### Activate the `venv` locally
To activate the virtual environment within your current shell session, execute
source <path/to/>dorie/build-cmake/activate
......@@ -241,7 +241,7 @@ terminal session!
_With the virtual environment activated,_ you can now navigate to any directory
that you would like to contain your simulation input and/or output data.
### Execute the application
#### Execute the application
Any command to the DORiE application has the signature
dorie <cmd> [<opts>] [<args>]
......@@ -255,7 +255,7 @@ by calling
dorie create
DORiE implements a lightweight wrapper around the `dune-randomfield`
DORiE implements a lightweight wrapper around the `dune-randomfield`
generator. You can use it to easily create a heterogeneous soil architecture.
This step is optional. Tweak the parameters of `parfield.ini` to your liking
and then call
......@@ -274,12 +274,12 @@ Once prepared, call
to execute the solver.
## Troubleshooting
### Troubleshooting
CMake heavily caches the results of its configuration process. In case you encounter errors or strange behavior, especially after an update, you should delete the DORiE build folder (called `build-cmake` by default) and re-install DORiE using `dunecontrol`.
If the problem persists, take a look at the [List of Known Bugs](, or create an issue yourself. For problems related to the installation, refer to the sections below.
### Debugging
#### Debugging
DORiE can be built with debugging flags via CMake. To do so, run
CMAKE_FLAGS="-DCMAKE_BUILD_TYPE=Debug" dunecontrol --only=dorie all
......@@ -292,14 +292,7 @@ To re-create a release build, configure DORiE with the release build type by exe
CMAKE_FLAGS="-DCMAKE_BUILD_TYPE=Release" dunecontrol --only=dorie all
#### Debugging inside Docker
A debugger needs special security privileges usually not provided by the Docker engine. To enable debugging inside Docker, these privileges have to be granted when calling `docker run` by adding the options
--security-opt seccomp=unconfined
The debugger `gdb` is pre-installed in the Docker container.
### Running System Tests
#### Running System Tests
DORiE includes a testing system for comparing its results the ones of ODE solvers
or former versions of itself. This ensures that DORiE is running correctly and
producing the expected results. We distinguish _unit tests_ for testing certain
......@@ -319,5 +312,5 @@ After building them with `Debug` flags and executing them, you can
retrieve code coverage information using the
[`gcovr`]( utility.
### Further Help
#### Further Help
[Open an issue](, or write to the [DORiE developer mailing list](
# .. cmake_function:: dorie_install_doc_utils
# Installs the software required for building the documentation
# into the `venv`. Resets the cache entry `SPHINX_EXECUTABLE`
# if it was found before and replaces it with the executable
# installed into the `venv`.
# install requirements into dune venv
set(INSTALL_CMD -m pip install -r ${CMAKE_CURRENT_SOURCE_DIR}/requirements.txt)
......@@ -23,31 +31,30 @@ dorie_install_doc_utils()
# copy static files to build tree
dune_cmake_sphinx_doc(SPHINX_CONF ${CMAKE_CURRENT_SOURCE_DIR}/
-T -b html
-d ${CMAKE_CURRENT_BINARY_DIR}/_doctrees # doctree pickles dir
${CMAKE_CURRENT_BINARY_DIR}/html # output dir
if(TARGET sphinx_html)
add_dependencies(sphinx_html doxygen_dorie)
add_dependencies(doc sphinx_html)
......@@ -16,7 +16,7 @@
import sys
import os
import shlex
import recommonmark
# import recommonmark
from recommonmark.parser import CommonMarkParser
from recommonmark.transform import AutoStructify
......@@ -53,9 +53,9 @@ extensions = [
# Path to local MathJax JS file (set through CMake)
......@@ -70,7 +70,7 @@ templates_path = ['_templates']
# specify custom source parsers
source_parsers = {
'.md': 'recommonmark.parser.CommonMarkParser',
'.md': CommonMarkParser,
# The suffix(es) of source filenames.
......@@ -81,8 +81,8 @@ source_suffix = ['.rst', '.md']
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# The master toctree document. (defaults to 'contents')
master_doc = 'contents'
# General information about the project.
project = 'DORiE'
......@@ -338,4 +338,4 @@ def setup(app):
app.add_config_value('deploy_mode', '', 'env')
app.add_config_value('recommonmark_config', {
}, True)
\ No newline at end of file
......@@ -19,18 +19,10 @@ available from the `public repository <
A ready-to-use application is available from `Docker Hub <>`_.
DORiE is licensed under the `MIT License <>`_.
Never used DORiE before? Get to learn its features by working through :ref:`quickstart`.
If you have already installed DORiE, jump straight to the :doc:`man-cookbook`
Never used DORiE before? Get to learn its features by working through :doc:`the manual <manual/index>`.
If you have already installed DORiE, jump straight to the :doc:`Cook Book <cookbook/index>`
and have a look at the test cases described therein!
You might also want to have a look at both the :doc:`man-config-file`
and :doc:`man-bcfile`, explaining all input parameters and boundary condition
files, respectively.
A complete documentation of the :ref:`DORiE source code <c-reference>`, the
:ref:`Python modules <python-reference>` and the :ref:`CMake files <cmake-reference>`
is provided for DORiE developers.
DORiE complies to `Semantic Versioning <>`_. Version number
assignment and increment are based on the :doc:`public-api`.
......@@ -45,38 +37,10 @@ Manual
.. toctree::
:maxdepth: 1
.. _c-reference:
C++ Package Reference
.. toctree::
:maxdepth: 1
.. _python-reference:
Python Package Reference
.. toctree::
:maxdepth: 1
.. _cmake-reference:
Indices and tables
......@@ -24,16 +24,16 @@ be retrieved!
Input Files
Templates for the required files can conveniently be generated with the
:doc:`CLI <python-dorie-wrapper>`.
:doc:`CLI </manual/cli>`.
* :doc:`Configuration File <man-config-file>` (``.ini``):
* :doc:`Configuration File </manual/config-file>` (``.ini``):
The main input file for the solver. Template: ``config.ini``
* :ref:`Parameterization Data File <man-parameter_file>` (``.yml``):
Specifies the soil parameterization type(s) and parameters.
Template: ``param.yml``
* :doc:`Boundary Condition Data File <man-bcfile>` (``.bcdat``):
* :doc:`Boundary Condition Data File </manual/bcfile>` (``.bcdat``):
Specifies the boundary segmentation and the boundary conditions.
Templates: ``2d_infiltr.bcdat``, ``3d_infiltr.bcdat``
......@@ -44,7 +44,7 @@ Templates for the required files can conveniently be generated with the
Used to generate heterogeneous soil architectures and boundary segmentations
for rectangular grids.
* :ref:`Scaling Field H5 Files <man-parameter_sclaing>` (optional):
* :ref:`Scaling Field H5 Files <man-parameter_scaling>` (optional):
Datasets for interpolating local heterogeneities in the parameterization.
Output Files
Guided Doxygen Documentation
.. contents::
:depth: 3
This documentation includes the documentation created by Doxygen, and enhances it by adding further overview features and explanations not suitable for inclusion in the source code.
DORiE consists of several thousand lines of C++ source code, not accounting for the DUNE functions and classes included in the program. There are two approaches on getting to know the code, first by following the programs course fairly linearly, and second by studying class functions and interactions via the modules overview. - Don't worry! The modularity of the code enables you to work with portions of it while neglecting other parts.
Programming Philosophy
DORiE makes high use of object oriented programming by constructing different classes and letting them interact quite independently.
In general, the constructor of every class reads the parameters important to the same class and immediately assembles all variables and functions needed for further use. Class constructors usually do not receive parameters explicitly, but read them from the parameter file independently. This improves readability of the code but can cause conflicts in parameter declarations. The :doc:`python-dorie-parscraper` makes sure that all parameter queries are consistent before DORiE is compiled.
Query functions are handled in a top-down approach, where requests for and the sending of data are initiated by the higher-order or owner class. Ownership itself, however, is intended to be as flat as possible, with the main program functions assembling most of the classes and handing them over to other classes with which they interact.
Programming Guide
None so far.
.. _code-guide:
DORiE Routine
.. _code-main:
Main Function
The Main Routine of DORiE creates a Parameter File Parser object, to read out the parameter file.
It assembles a Dune::Grid object by calling the appropriate functions for a structured rectangular
or an unstructured simplex grid. The latter is created from a Gmsh :file:`.msh` Mesh data file.
The grid is handed over to the appropriate Solver functions, which build the Dune Grid Function Space
for a rectangular or simplex grid, respectively. The Solver helper functions then call the actual :ref:`code-solver`
for computing the solution.
.. doxygenfile::
.. doxygenfunction:: build_grid_gmsh
.. doxygenfunction:: build_grid_cube
.. _code-solver:
The Simulation template receives the assembled Grid Function Space and initializes the PDELab Backends
to compute the solution.
.. doxygenclass:: Dune::Dorie::RichardsSimulation
.. _code-param:
Richards Equation Classes
To compute the solution, the various parts of the Richards Equation and the chosen parameterization
have to be represented. This is achieved by building objects which provide appropriate queries for
Boundary Conditions, Parameters and Sink/Source terms, depending on both time and space. There are
three classes with standardized function queries for these tasks:
.. doxygenclass:: Dune::Dorie::ParameterizationBase
.. doxygenclass:: Dune::Dorie::MualemVanGenuchten
.. doxygenclass:: Dune::Dorie::FlowBoundary
.. doxygenclass:: Dune::Dorie::FlowSource
.. _code-operator:
Richards Equation Local Operators
The local operators bind to the PDELab backend and compute the local residual along quadrature points on the grid.
They represent the numeric implementation of the PDE's *strong formulation*.
DORiE uses the mass conserving Discontinuous Galerkin (DG) discretization scheme.
.. doxygenclass:: Dune::Dorie::Operator::RichardsDGSpatialOperator
.. doxygenclass:: Dune::Dorie::Operator::RichardsDGTemporalOperator
.. _code-controller:
Time Step Controller
The time step interval is controlled by an own class. It is adjusted according to the performance of the
non-linear Newton Solver and possible changes in the boundary conditions.
.. doxygenclass:: Dune::Dorie::CalculationController
.. _code-adaptivity:
Adaptive Grid Refinement
If enabled, adaptive grid refinement is applied after a time step has been computed successfully.
Similar to the actual solver, the Adaptivity Controller implements a Local Operator which computes
local residuals along the grid. The residual represents the estimated error of the solution based
on an estimation on the error in the water flux along an grid interface. Depending on the refinement
scheme, the grid is then refined or coarsened at positions of large or small errors, respectively.
.. doxygenclass:: Dune::Dorie::Operator::FluxErrorEstimator
.. doxygenclass:: Dune::Dorie::AdaptivityHandler
The following document is a log file of the complete installation on our integration server.
It provides a rough reference to what the output of ``doriecontrol install all`` should
look like, in case you suspect anything to be wrong with your installation.
.. include:: logs/installation.log
......@@ -87,7 +87,7 @@ These lines follow a simple grammar:
The boundary conditions defined here are parsed in the same order as the boundary segments have been specified. In 3D, the rectangular boundary segments are parsed in a tabular fashion, where columns run faster than rows. Columns are defined along the first direction specified in the `Boundary Segmentation`_, and rows are defined along the second direction.
.. figure:: figures/man-bcfile-segm1.png
.. figure:: /figures/man-bcfile-segm1.png
:width: 40 %
:align: left
......@@ -111,13 +111,13 @@ Simple Boundary Condition datafiles can be created with the command ``dorie crea
Exemplary BC File for Infiltration (2D)
.. include:: default_files/2d_infiltr.bcdat
.. include:: /default_files/2d_infiltr.bcdat
:code: ini
Exemplary BC File for Infiltration (3D)
.. include:: default_files/3d_infiltr.bcdat
.. include:: /default_files/3d_infiltr.bcdat
:code: ini
Code Documentation
......@@ -87,4 +87,4 @@ instance used for the CLI.
.. argparse::
:ref: dorie.cli.parser.create_cl_parser
:prog: dorie
\ No newline at end of file
:prog: dorie
......@@ -37,7 +37,7 @@ A set of rules defines this syntax:
is equivalent with
.. code-block:: none
heading1.heading2.key1.key2 = value
heading1.heading2.key1.key3 = value
......@@ -48,21 +48,21 @@ Cheat Sheets
These cheat sheets are automatically generated by
:doc:`the Parameter Scraper <python-dorie-parscraper>`.
:doc:`the Parameter Scraper </python/parscraper>`.
The configuration files are used for the Parameter Field Generator module and
the main simulation routine. They are executed by `dorie pfg <config>` and
`dorie run <config>`, respectively, see the
:doc:`CLI documentation <python-dorie-wrapper>`.
:doc:`CLI documentation </manual/cli>`.
Parameter Field Generator
.. include:: default_files/field-parameters.rst
Main Routine
Common and richards parameters are needed in the configuration file.
Common and richards parameters are needed in the configuration file.
.. include:: default_files/parameters.rst
Grid Creation and Mapping
To guarantee numeric accuracy, :doc:`boundary conditions <man-bcfile>`
and :doc:`parameterizations <man-parameter-file>` must exactly map to grid
To guarantee numeric accuracy, :doc:`boundary conditions <bcfile>`
and :doc:`parameterizations <parameter-file>` must exactly map to grid
boundary faces and grid cells, respectively. DORiE therefore not only requires
a specification of the actual grid, but also of these mappings.
......@@ -102,7 +102,7 @@ that the left and right boundaries consist of two *geometric* lines each.
This code can directly be transferred to a Python script using
the pygmsh_ module. It writes a ``.geo`` file while checking for a correct
syntax within your script. It is readily installed into the
:doc:`virtual environment <python-dorie-wrapper>`.
:doc:`virtual environment <cli>`.
.. code-block:: default
The Manual
This section of the documentation provides detailed information on the
respective parts of the setup for DORiE.
.. toctree::
:maxdepth: 1
The README <readme>
Installation Preparations
.. contents::
.. _readme:
ReadMe File
.. toctree::
:maxdepth: 1
You can build DORiE locally on your machine for maximum performance. This requires you to take care of all dependencies and to handle the installation process yourself. On the other hand, you can use a virtual environment to run DORiE. We support this feature by using `Docker <>`_.
You can install your local DORiE source code into a Docker image or load a
prepared image from `Docker Hub <>`_.
You can then run the application as Docker container. Depending on your
operating system, this will lead to impared performance.
Refer to :doc:`the ReadMe file <readme>` for installation instructions.