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 @@ ...@@ -2,6 +2,7 @@
build-cmake/ build-cmake/
# Exclude generated files # Exclude generated files
doc/manual/config-file.rst
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
......
# Welcome to DORiE! # DORiE README
(**D**UNE-**O**perated **Ri**chards equation solving **E**nvironment) (**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](https://dune-project.org/) and the [DUNE-PDELab](https://dune-project.org/modules/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. DORiE is a software suite for solving the Richards Equation. The core feature is a C++ PDE-solver powered by [DUNE](https://dune-project.org/) and the [DUNE-PDELab](https://dune-project.org/modules/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 ...@@ -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](mailto:dorieteam@iup.uni-heidelberg.de) of the [TS-CCEES](http://ts.iup.uni-heidelberg.de/) research group at [IUP Heidelberg](http://www.iup.uni-heidelberg.de/), supervised by [Kurt Roth](http://ts.iup.uni-heidelberg.de/people/prof-dr-kurt-roth/), in collaboration with [Ole Klein](https://conan.iwr.uni-heidelberg.de/people/oklein/) and the [Scientific Computing Group](https://conan.iwr.uni-heidelberg.de/) of [IWR Heidelberg](https://typo.iwr.uni-heidelberg.de/home/). DORiE is developed and maintained by the [DORiE Developers](mailto:dorieteam@iup.uni-heidelberg.de) of the [TS-CCEES](http://ts.iup.uni-heidelberg.de/) research group at [IUP Heidelberg](http://www.iup.uni-heidelberg.de/), supervised by [Kurt Roth](http://ts.iup.uni-heidelberg.de/people/prof-dr-kurt-roth/), in collaboration with [Ole Klein](https://conan.iwr.uni-heidelberg.de/people/oklein/) and the [Scientific Computing Group](https://conan.iwr.uni-heidelberg.de/) of [IWR Heidelberg](https://typo.iwr.uni-heidelberg.de/home/).
# Installation Instructions ## Installation Instructions
DORiE is a [DUNE](https://dune-project.org/) 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](https://www.docker.com/) instead. DORiE is a [DUNE](https://dune-project.org/) 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](https://www.docker.com/) instead.
...@@ -18,7 +18,7 @@ directly to the the instructions on [how to execute DORiE](#run-dorie-run). ...@@ -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 The commands listed there are appended to the usual commands for running a
Docker container. See the description on Docker Hub for further details. 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 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, 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 ...@@ -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 the release tags list of the Git repository. The latest unstable version is
tagged as `devel`. tagged as `devel`.
## Docker Installation ### Docker Installation
You can also compile any local version of DORiE into a new Docker image. To do You can also compile any local version of DORiE into a new Docker image. To do
so, execute so, execute
...@@ -43,7 +43,7 @@ from within the top-level DORiE source directory. Docker will use a prepared ...@@ -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 image from Dockerhub and install DORiE into it. The created image will be called
`<img>`. `<img>`.
## 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. 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 ...@@ -53,7 +53,7 @@ DORiE is configured, built, and installed via the
[DUNE Buildsystem](https://dune-project.org/doc/installation/), using the [DUNE Buildsystem](https://dune-project.org/doc/installation/), using the
`dunecontrol` script to handle DUNE-internal dependencies. `dunecontrol` script to handle DUNE-internal dependencies.
### Dependencies #### Dependencies
Depending on your system configuration, there will be more packages necessary to 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. install DORiE on your machine. See the step-by-step manual for further details.
...@@ -86,7 +86,7 @@ by CI tests. ...@@ -86,7 +86,7 @@ by CI tests.
| [dune-randomfield](https://gitlab.dune-project.org/oklein/dune-randomfield) | master | [dune-randomfield](https://gitlab.dune-project.org/oklein/dune-randomfield) | master
### Optional Packages #### Optional Packages
| Software | Version/Branch | Comments | | Software | Version/Branch | Comments |
| ---------| -------------- | -------- | | ---------| -------------- | -------- |
| [dune-testtools](https://gitlab.dune-project.org/quality/dune-testtools) | releases/2.6 | Handles system tests | [dune-testtools](https://gitlab.dune-project.org/quality/dune-testtools) | releases/2.6 | Handles system tests
...@@ -95,7 +95,7 @@ by CI tests. ...@@ -95,7 +95,7 @@ by CI tests.
| [ParMETIS](http://glaros.dtc.umn.edu/gkhome/views/metis) | 4 | For parallel runs | [ParMETIS](http://glaros.dtc.umn.edu/gkhome/views/metis) | 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](http://brew.sh/). If you prefer to use [MacPorts](https://www.macports.org/), you need to check if some of the packages require different installation options than displayed here. 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](http://brew.sh/). If you prefer to use [MacPorts](https://www.macports.org/), you need to check if some of the packages require different installation options than displayed here.
If you installed [Anaconda](https://conda.io/docs/user-guide/install/download.html) 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! If you installed [Anaconda](https://conda.io/docs/user-guide/install/download.html) 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](https://conda.io/docs/user-guide/install/download.ht ...@@ -105,10 +105,10 @@ If you installed [Anaconda](https://conda.io/docs/user-guide/install/download.ht
xcode-select --install xcode-select --install
2. Install third party packages: 2. Install third party packages:
**Ubuntu:** **Ubuntu:**
apt update apt update
apt install cmake doxygen gcc g++ gfortran \ apt install cmake doxygen gcc g++ gfortran \
git libatlas-base-dev libfftw3-dev libfftw3-mpi-dev \ git libatlas-base-dev libfftw3-dev libfftw3-mpi-dev \
libfreetype6-dev libhdf5-mpi-dev libopenmpi-dev libpng-dev \ libfreetype6-dev libhdf5-mpi-dev libopenmpi-dev libpng-dev \
...@@ -159,7 +159,7 @@ If you installed [Anaconda](https://conda.io/docs/user-guide/install/download.ht ...@@ -159,7 +159,7 @@ If you installed [Anaconda](https://conda.io/docs/user-guide/install/download.ht
to the `CMAKE_FLAGS` in the call to `dunecontrol` above. to the `CMAKE_FLAGS` in the call to `dunecontrol` above.
### Experimental Features #### Experimental Features
The local operator implementing Richards equation's discretization supports The local operator implementing Richards equation's discretization supports
multiple scheme settings. Setting these via the config file is disabled by 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 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 ...@@ -169,16 +169,16 @@ The configuration settings in the section `[dg.experimental]` will then override
the default settings. 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: The following software packages are cross-platform, so you should be able to find a release that fits your operating system:
* [Gmsh](http://gmsh.info/): An open-source CAD that can be used to create the `.msh` files used by DORiE to define triangular meshes. * [Gmsh](http://gmsh.info/): An open-source CAD that can be used to create the `.msh` files used by DORiE to define triangular meshes.
* [ParaView](http://www.paraview.org/): A powerful post-processing tool for VTK files. Offers both visualization and data analysis tools. * [ParaView](http://www.paraview.org/): 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](https://dorie-doc.netlify.com/). The documentation of the latest release branch can be found [online](https://dorie-doc.netlify.com/).
...@@ -193,14 +193,14 @@ or navigate to the `dorie/build-cmake` directory and call ...@@ -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 You will then find the index page of the documentation at
`dorie/build-cmake/doc/html/index.html`. `dorie/build-cmake/doc/html/index.html`.
## Run, DORiE, Run! ### Run, DORiE, Run!
DORiE provides a command line interface (CLI) for all its functions. DORiE provides a command line interface (CLI) for all its functions.
The required Python modules and all their dependencies are readily installed The required Python modules and all their dependencies are readily installed
into a virtual environment (`venv`), which has to be activated within a 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 shell session. You can do so by activating it in your current session
(Manual Installation only) or by running the Docker application. (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 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. application to boot up the virtual environment in a mounted directory of choice.
...@@ -222,7 +222,7 @@ virtual environment activated. ...@@ -222,7 +222,7 @@ virtual environment activated.
Notice, that you can only use **local file paths** in all configuration settings Notice, that you can only use **local file paths** in all configuration settings
due to the directory mount. due to the directory mount.
### Activate the `venv` locally #### Activate the `venv` locally
To activate the virtual environment within your current shell session, execute To activate the virtual environment within your current shell session, execute
source <path/to/>dorie/build-cmake/activate source <path/to/>dorie/build-cmake/activate
...@@ -241,7 +241,7 @@ terminal session! ...@@ -241,7 +241,7 @@ terminal session!
_With the virtual environment activated,_ you can now navigate to any directory _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. 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 Any command to the DORiE application has the signature
dorie <cmd> [<opts>] [<args>] dorie <cmd> [<opts>] [<args>]
...@@ -255,7 +255,7 @@ by calling ...@@ -255,7 +255,7 @@ by calling
dorie create 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. 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 This step is optional. Tweak the parameters of `parfield.ini` to your liking
and then call and then call
...@@ -274,12 +274,12 @@ Once prepared, call ...@@ -274,12 +274,12 @@ Once prepared, call
to execute the solver. 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`. 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](https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/issues), or create an issue yourself. For problems related to the installation, refer to the sections below. If the problem persists, take a look at the [List of Known Bugs](https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/issues), 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 DORiE can be built with debugging flags via CMake. To do so, run
CMAKE_FLAGS="-DCMAKE_BUILD_TYPE=Debug" dunecontrol --only=dorie all 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 ...@@ -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 CMAKE_FLAGS="-DCMAKE_BUILD_TYPE=Release" dunecontrol --only=dorie all
#### Debugging inside Docker #### Running System Tests
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
DORiE includes a testing system for comparing its results the ones of ODE solvers 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 or former versions of itself. This ensures that DORiE is running correctly and
producing the expected results. We distinguish _unit tests_ for testing certain 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 ...@@ -319,5 +312,5 @@ After building them with `Debug` flags and executing them, you can
retrieve code coverage information using the retrieve code coverage information using the
[`gcovr`](https://gcovr.com/index.html) utility. [`gcovr`](https://gcovr.com/index.html) utility.
### Further Help #### Further Help
[Open an issue](https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/issues/new), or write to the [DORiE developer mailing list](mailto:dorieteam@iup.uni-heidelberg.de). [Open an issue](https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/issues/new), or write to the [DORiE developer mailing list](mailto:dorieteam@iup.uni-heidelberg.de).
#
# .. 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`.
#
function(dorie_install_doc_utils) function(dorie_install_doc_utils)
# install requirements into dune venv # install requirements into dune venv
set(INSTALL_CMD -m pip install -r ${CMAKE_CURRENT_SOURCE_DIR}/requirements.txt) set(INSTALL_CMD -m pip install -r ${CMAKE_CURRENT_SOURCE_DIR}/requirements.txt)
...@@ -23,31 +31,30 @@ dorie_install_doc_utils() ...@@ -23,31 +31,30 @@ dorie_install_doc_utils()
add_subdirectory("doxygen") add_subdirectory("doxygen")
add_subdirectory("default_files") add_subdirectory("default_files")
# copy static files to build tree file(RELATIVE_PATH
file(COPY ${CMAKE_CURRENT_LIST_DIR}/examples DESTINATION ${CMAKE_CURRENT_BINARY_DIR}) CHEATSHEET_PFG_RELPATH
file(COPY ${CMAKE_CURRENT_LIST_DIR}/figures DESTINATION ${CMAKE_CURRENT_BINARY_DIR}) ${CMAKE_CURRENT_SOURCE_DIR}/manual
file(COPY ${CMAKE_SOURCE_DIR}/README.md DESTINATION ${CMAKE_CURRENT_BINARY_DIR}) ${CMAKE_CURRENT_BINARY_DIR}/default_files/field-parameters.rst)
file(RELATIVE_PATH
include(DuneSphinxCMakeDoc) CHEATSHEET_DORIE_RELPATH
dune_cmake_sphinx_doc(SPHINX_CONF ${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in ${CMAKE_CURRENT_SOURCE_DIR}/manual
RST_SOURCES ${CMAKE_CURRENT_BINARY_DIR}/default_files/parameters.rst)
index.rst configure_file(manual/config-file.rst.in
doxygen-guide.rst ${CMAKE_CURRENT_SOURCE_DIR}/manual/config-file.rst)
logs-install.rst
other-cmake.rst
public-api.rst configure_file(conf.py.in conf.py)
python-dorie-wrapper.rst
python-dorie-parscraper.rst add_custom_target(sphinx_html
python-dorie-testtools.rst COMMAND ${SPHINX_EXECUTABLE}
python-dorie-utilities.rst -T -b html
man-bcfile.rst -c ${CMAKE_CURRENT_BINARY_DIR} # conf.py dir
man-cookbook.rst -d ${CMAKE_CURRENT_BINARY_DIR}/_doctrees # doctree pickles dir
man-installation.rst ${CMAKE_CURRENT_SOURCE_DIR} # input dir
man-config-file.rst ${CMAKE_CURRENT_BINARY_DIR}/html # output dir
man-parameter-file.rst )
man-grid.rst
MODULE_ONLY)
if(TARGET sphinx_html) if(TARGET sphinx_html)
add_dependencies(sphinx_html doxygen_dorie) add_dependencies(sphinx_html doxygen_dorie)
add_dependencies(doc sphinx_html)
endif() endif()
...@@ -16,7 +16,7 @@ ...@@ -16,7 +16,7 @@
import sys import sys
import os import os
import shlex import shlex
import recommonmark # import recommonmark
from recommonmark.parser import CommonMarkParser from recommonmark.parser import CommonMarkParser
from recommonmark.transform import AutoStructify from recommonmark.transform import AutoStructify
...@@ -53,9 +53,9 @@ extensions = [ ...@@ -53,9 +53,9 @@ extensions = [
'sphinx.ext.mathjax', 'sphinx.ext.mathjax',
'sphinx.ext.ifconfig', 'sphinx.ext.ifconfig',
'sphinx.ext.viewcode', 'sphinx.ext.viewcode',
'sphinx_cmake_dune',
'sphinxarg.ext', 'sphinxarg.ext',
'breathe' 'breathe',
'recommonmark'
] ]
# Path to local MathJax JS file (set through CMake) # Path to local MathJax JS file (set through CMake)
...@@ -70,7 +70,7 @@ templates_path = ['_templates'] ...@@ -70,7 +70,7 @@ templates_path = ['_templates']
# specify custom source parsers # specify custom source parsers
source_parsers = { source_parsers = {
'.md': 'recommonmark.parser.CommonMarkParser', '.md': CommonMarkParser,
} }
# The suffix(es) of source filenames. # The suffix(es) of source filenames.
...@@ -81,8 +81,8 @@ source_suffix = ['.rst', '.md'] ...@@ -81,8 +81,8 @@ source_suffix = ['.rst', '.md']
# The encoding of source files. # The encoding of source files.
#source_encoding = 'utf-8-sig' #source_encoding = 'utf-8-sig'
# The master toctree document. # The master toctree document. (defaults to 'contents')
master_doc = 'index' master_doc = 'contents'
# General information about the project. # General information about the project.
project = 'DORiE' project = 'DORiE'
...@@ -338,4 +338,4 @@ def setup(app): ...@@ -338,4 +338,4 @@ def setup(app):
app.add_config_value('deploy_mode', '', 'env') app.add_config_value('deploy_mode', '', 'env')
app.add_config_value('recommonmark_config', { app.add_config_value('recommonmark_config', {
}, True) }, True)
app.add_transform(AutoStructify) app.add_transform(AutoStructify)
\ No newline at end of file
...@@ -19,18 +19,10 @@ available from the `public repository <https://ts-gitlab.iup.uni-heidelberg.de/d ...@@ -19,18 +19,10 @@ available from the `public repository <https://ts-gitlab.iup.uni-heidelberg.de/d
A ready-to-use application is available from `Docker Hub <https://hub.docker.com/r/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>`_. 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`. 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:`man-cookbook` 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! 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 <https://semver.org/>`_. Version number DORiE complies to `Semantic Versioning <https://semver.org/>`_. Version number
assignment and increment are based on the :doc:`public-api`. assignment and increment are based on the :doc:`public-api`.
...@@ -45,38 +37,10 @@ Manual ...@@ -45,38 +37,10 @@ Manual
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
man-installation manual/index
python-dorie-wrapper
man-config-file
man-grid
man-bcfile
man-cookbook
man-parameter-file
public-api public-api
cookbook/index
.. _c-reference: python/index
C++ Package Reference
---------------------
.. toctree::
:maxdepth: 1
:glob:
doxygen-*
.. _python-reference:
Python Package Reference
------------------------
.. toctree::
:maxdepth: 1
:glob:
python-*
.. _cmake-reference:
Indices and tables Indices and tables
......
...@@ -24,16 +24,16 @@ be retrieved! ...@@ -24,16 +24,16 @@ be retrieved!
Input Files Input Files
^^^^^^^^^^^ ^^^^^^^^^^^
Templates for the required files can conveniently be generated with the 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`` The main input file for the solver. Template: ``config.ini``
* :ref:`Parameterization Data File <man-parameter_file>` (``.yml``): * :ref:`Parameterization Data File <man-parameter_file>` (``.yml``):
Specifies the soil parameterization type(s) and parameters. Specifies the soil parameterization type(s) and parameters.
Template: ``param.yml`` 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. Specifies the boundary segmentation and the boundary conditions.
Templates: ``2d_infiltr.bcdat``, ``3d_infiltr.bcdat`` Templates: ``2d_infiltr.bcdat``, ``3d_infiltr.bcdat``
...@@ -44,7 +44,7 @@ Templates for the required files can conveniently be generated with the ...@@ -44,7 +44,7 @@ Templates for the required files can conveniently be generated with the
Used to generate heterogeneous soil architectures and boundary segmentations Used to generate heterogeneous soil architectures and boundary segmentations
for rectangular grids. 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. Datasets for interpolating local heterogeneities in the parameterization.
Output Files Output Files
......
Guided Doxygen Documentation
****************************
.. contents::
:depth: 3
Introduction
============
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:: dorie.cc
.. doxygenfunction:: build_grid_gmsh
.. doxygenfunction:: build_grid_cube
.. _code-solver:
Simulation
----------
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
:members:
.. doxygenclass:: Dune::Dorie::MualemVanGenuchten
:members:
.. doxygenclass:: Dune::Dorie::FlowBoundary
:members:
.. doxygenclass:: Dune::Dorie::FlowSource
:members:
.. _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
:members:
.. doxygenclass:: Dune::Dorie::Operator::RichardsDGTemporalOperator
:members:
.. _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
:members:
.. _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
:members:
.. doxygenclass:: Dune::Dorie::AdaptivityHandler
:members:
################
installation.log
################
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
:literal:
...@@ -87,7 +87,7 @@ These lines follow a simple grammar: ...@@ -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. 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 % :width: 40 %
:align: left :align: left
...@@ -111,13 +111,13 @@ Simple Boundary Condition datafiles can be created with the command ``dorie crea ...@@ -111,13 +111,13 @@ Simple Boundary Condition datafiles can be created with the command ``dorie crea
Exemplary BC File for Infiltration (2D) Exemplary BC File for Infiltration (2D)
--------------------------------------- ---------------------------------------
.. include:: default_files/2d_infiltr.bcdat .. include:: /default_files/2d_infiltr.bcdat
:code: ini :code: ini
Exemplary BC File for Infiltration (3D) Exemplary BC File for Infiltration (3D)
--------------------------------------- ---------------------------------------
.. include:: default_files/3d_infiltr.bcdat .. include:: /default_files/3d_infiltr.bcdat
:code: ini :code: ini
Code Documentation Code Documentation
......
...@@ -87,4 +87,4 @@ instance used for the CLI. ...@@ -87,4 +87,4 @@ instance used for the CLI.
.. argparse:: .. argparse::
:ref: dorie.cli.parser.create_cl_parser :ref: dorie.cli.parser.create_cl_parser
:prog: dorie :prog: dorie
\ No newline at end of file
...@@ -37,7 +37,7 @@ A set of rules defines this syntax: ...@@ -37,7 +37,7 @@ A set of rules defines this syntax:
is equivalent with is equivalent with
.. code-block:: none .. code-block:: none
heading1.heading2.key1.key2 = value heading1.heading2.key1.key2 = value