Commit 0cd6b69c authored by Lukas Riedel's avatar Lukas Riedel

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 `CHANGELOG.md` to reduce merge conflicts with
`merge=union`
* 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
versions.
### 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}/conf.py.in
RST_SOURCES
index.rst
doxygen-guide.rst
doxygen-modules.rst
doxygen-quick-all.rst
logs-install.rst
other-cmake.rst
public-api.rst
python-dorie-wrapper.rst
python-dorie-parscraper.rst
python-dorie-testtools.rst
......@@ -45,6 +44,7 @@ dune_cmake_sphinx_doc(SPHINX_CONF ${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in
quickstart-cookbook.rst
quickstart-installation.rst
quickstart-parameters.rst
quickstart-parameter-file.rst
MODULE_ONLY)
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 = version_file.read()
# The full version, including alpha/beta/rc tags.
release = version_file.read()
# 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
Simulation
----------
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
:members:
.. doxygenclass:: Dune::Dorie::MualemVanGenuchten
:members:
.. 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
:members:
.. doxygenclass:: Dune::Dorie::RichardsDGTemporalOperator
.. doxygenclass:: Dune::Dorie::Operator::RichardsDGTemporalOperator
:members:
.. _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
:members:
.. doxygenclass:: Dune::Dorie::AdaptivityController
.. doxygenclass:: Dune::Dorie::AdaptivityHandler
:members:
******************
DORiE Code Modules
******************
\ No newline at end of file
***********************
Complete Class Overview
***********************
.. doxygenfile:: dorie.cc
.. doxygenfunction:: RichardsSolverSimplex
.. doxygenfunction:: RichardsSolverRectangular
.. doxygenfunction:: RichardsSolver
.. doxygennamespace:: Dune::Dorie
:members:
:private-members:
:protected-members:
:undoc-members:
......@@ -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 <https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie>`_.
A ready-to-use application is available from `Docker Hub <https://hub.docker.com/r/dorie/dorie/>`_.
DORiE is licensed under the `MIT License <https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/blob/master/LICENSE.md>`_.
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 <https://semver.org/>`_. Version number
assignment and increment are based on the :doc:`public-api`.
Contents
=========
......@@ -41,6 +49,8 @@ Quick Start
quickstart-cookbook
quickstart-parameters
quickstart-bcfile
python-dorie-wrapper
public-api
.. _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
programs.
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
:members:
The simulation template requires compile-time type specifications wrapped in a
suitable `Traits` structure.
.. doxygenstruct:: Dune::Dorie::BaseTraits
:members:
:undoc-members:
********************
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 <https://support.hdfgroup.org/HDF5/doc/H5.intro.html>`_.
The Parameter Field Generator module always generates files compliant to this
specification.
The structure of this file is as follows:
* H5Group: `parameters`
Attributes:
* 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
Maintainer: dorieteam@iup.uni-heidelberg.de
#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