Commit 3c18ce02 authored by Lukas Riedel's avatar Lukas Riedel

Add public API specification

* Add new page which explicitly references all contents of the API
* Add new page for parameter file specs
parent a79422d8
......@@ -37,6 +37,7 @@ dune_cmake_sphinx_doc(SPHINX_CONF ${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in
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 +46,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)
......
......@@ -26,6 +26,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 +44,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:
***********************************
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
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