The TS-GitLab will have to shut down towards the end of the year — please think about migrating your projects to or GitHub.
(This is still a very early message, meant to keep you informed. There will be more urgent ones in the future.)

Commit 0cd6b69c authored by Lukas Riedel's avatar Lukas Riedel 🎧
Browse files

Merge branch '77-define-the-public-api' into 'master'

Resolve "Define the public API"

Closes #77

See merge request !69
parents 6b59520d c7f473cf
......@@ -11,6 +11,7 @@
* CI pipeline now also compiles a Debug build with the LLVM Clang compiler
* Add `.gitattributes` for `` to reduce merge conflicts with
* Public API definition in documentation.
### Changed
* Update code base to DUNE v2.6
......@@ -30,6 +31,9 @@
explicitly in the config file. The key will become mandatory in future
### Removed
* Complete doxygen documentation from Sphinx docs.
### Fixed
* The source code is now compatible to the Clang LLVM compiler.
DORiE can now be compiled with the onboard compiler on macOS.
......@@ -33,10 +33,9 @@ dune_cmake_sphinx_doc(SPHINX_CONF ${CMAKE_CURRENT_SOURCE_DIR}/
......@@ -45,6 +44,7 @@ dune_cmake_sphinx_doc(SPHINX_CONF ${CMAKE_CURRENT_SOURCE_DIR}/
if(TARGET sphinx_html)
......@@ -85,17 +85,18 @@ master_doc = 'index'
# General information about the project.
project = 'DORiE'
copyright = '2016, DORiE developer team'
copyright = '2018, DORiE developer team'
author = 'Dion Häfner'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
# The short X.Y version.
version = '0.9'
# The full version, including alpha/beta/rc tags.
release = '0.9-master'
with open("@PROJECT_SOURCE_DIR@/VERSION") as version_file:
# The short X.Y version.
version =
# The full version, including alpha/beta/rc tags.
release =
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
......@@ -46,17 +46,13 @@ for computing the solution.
.. doxygenfunction:: build_grid_cube
.. doxygenfunction:: RichardsSolverSimplex
.. doxygenfunction:: RichardsSolverRectangular
.. _code-solver:
Solver Routine
The Solver Routine receives the assembled Grid Function Space and initializes the PDELab Backends
The Simulation template receives the assembled Grid Function Space and initializes the PDELab Backends
to compute the solution.
.. doxygenfunction:: RichardsSolver
.. doxygenclass:: Dune::Dorie::Simulation
.. _code-param:
Richards Equation Classes
......@@ -66,7 +62,10 @@ have to be represented. This is achieved by building objects which provide appro
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::RichardsEquationParameter
.. doxygenclass:: Dune::Dorie::ParameterizationBase
.. doxygenclass:: Dune::Dorie::MualemVanGenuchten
.. doxygenclass:: Dune::Dorie::FlowBoundary
......@@ -82,10 +81,10 @@ The local operators bind to the PDELab backend and compute the local residual al
They represent the numeric implementation of the PDE's *strong formulation*.
DORiE uses the mass conserving Discontinuous Galerkin (DG) discretization scheme.
.. doxygenclass:: Dune::Dorie::RichardsDGSpatialOperator
.. doxygenclass:: Dune::Dorie::Operator::RichardsDGSpatialOperator
.. doxygenclass:: Dune::Dorie::RichardsDGTemporalOperator
.. doxygenclass:: Dune::Dorie::Operator::RichardsDGTemporalOperator
.. _code-controller:
......@@ -106,8 +105,8 @@ local residuals along the grid. The residual represents the estimated error of t
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::FluxErrorEstimator
.. doxygenclass:: Dune::Dorie::Operator::FluxErrorEstimator
.. doxygenclass:: Dune::Dorie::AdaptivityController
.. doxygenclass:: Dune::Dorie::AdaptivityHandler
DORiE Code Modules
\ No newline at end of file
Complete Class Overview
.. doxygenfile::
.. doxygenfunction:: RichardsSolverSimplex
.. doxygenfunction:: RichardsSolverRectangular
.. doxygenfunction:: RichardsSolver
.. doxygennamespace:: Dune::Dorie
......@@ -14,6 +14,11 @@ Introduction
Welcome to the DORiE Documentation!
DORiE is a DUNE module for solving the Richards equation. The source code is
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:`quickstart-cookbook`
and have a look at the test cases described therein!
......@@ -26,6 +31,9 @@ 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`.
......@@ -41,6 +49,8 @@ Quick Start
.. _c-reference:
Public API Definition
DORiE's Public API comprises the usage of the compiled program as well as the
main code segments for using instances of DORiE in other (DUNE) modules and
Command Line API
The compiled program and the Docker application are executed via the
:doc:`Command Line Interface <python-dorie-wrapper>`. The specifications for the
respective configuration files are given in the
:doc:`Config File Guide <quickstart-parameters>`.
The main routine (`dorie run <config>`) also requires input files for
:doc:`boundary conditions <quickstart-bcfile>` and
:doc:`soil parameters <quickstart-parameter-file>`.
Code API
DORiE supplies the `Simulation` template. This is the main class for assembling
and running the solver.
.. doxygenclass:: Dune::Dorie::Simulation
The simulation template requires compile-time type specifications wrapped in a
suitable `Traits` structure.
.. doxygenstruct:: Dune::Dorie::BaseTraits
DORiE Wrapper Script
DORiE Command Line Interface
DORiE consists of two main executables and multiple utility scripts. This wrapper script supplies input files, and manages the execution of these routines. It takes three main arguments:
Parameter Field File Specifications
The parameter field file is used to supply soil parameter information to the
simulation. It is supplied as
`H5 File <>`_.
The Parameter Field Generator module always generates files compliant to this
The structure of this file is as follows:
* H5Group: `parameters`
* array: `extensions` : n-dimensional spatial extensions of the field
* bool: `millerSimilarity` : whether Miller scaling shall be used
* string: `parameterization` : Only "vanGenuchten" supported
* double: `variance` : Variance of the Gaussian random field for Miller scaling
* H5Group: `vanGenuchten`
Datasets for each parameter in a n-dimensional field. The extensions of
all datasets must match. Additionally, there is the `raw_field` dataset,
specifying the natural logarithm of the Miller scaling factor.
* H5Dataset: `alpha`
* H5Dataset: `k0`
* H5Dataset: `n`
* H5Dataset: `tau`
* H5Dataset: `theta_r`
* H5Dataset: `theta_s`
* H5Dataset: `raw_field`
\ No newline at end of file
DORiE Parameter File Guide
DORiE Configuration File Guide
.. contents::
:depth: 2
......@@ -44,10 +44,23 @@ A set of rules defines this syntax:
.. _inifile-cheatsheet:
Cheat Sheet
Cheat Sheets
These cheat sheets are automatically generated by
:doc:`the Parameter Scraper <python-dorie-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>`.
Parameter Field Generator
.. include:: default_files/field-parameters.rst
This is a description of all parameters that have to be specified to run DORiE.
It is automatically generated by :doc:`the Parameter Scraper <python-dorie-parscraper>`.
Main Routine
.. include:: default_files/parameters.rst
......@@ -4,7 +4,7 @@
#Name of the module
Module: dorie
Version: 0.9
Version: 1.1.0-pre
#depending on
Depends: dune-pdelab dune-uggrid dune-randomfield
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