Commit 46655567 authored by Lukas Riedel's avatar Lukas Riedel

Further restructure docs. Add new doc pages

* Adjust toctree to have proper sections
* Add new doc pages:
  - Feature overview
  - Data I/O
* Add new doc section 'Introduction'
* Rename main file to `index.rst`
parent e1663417
# DORiE README
# 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](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.
......
The Cook Book
*************
Introduction
============
************
This part of the documentation guides through increasingly complicated
use-cases of DORiE. It is intended for users who wish to jump right into using
DORiE, without much knowledge of all its functions. The relevant manual pages
will be linked on the way.
Prerequisites
-------------
=============
You need a working application. You can either use the image shipped via
`Docker Hub <https://hub.docker.com/r/dorie/dorie/>`_ or use a local
installation. See the :doc:`installation manual <man-installation>` for
details. Additionally, install Paraview_ for analyzing the output.
Data I/O
--------
Let's start with the files required for running DORiE and the data that can
be retrieved!
Input Files
^^^^^^^^^^^
Templates for the required files can conveniently be generated with the
:doc:`CLI </manual/cli>`.
* :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 </manual/bcfile>` (``.bcdat``):
Specifies the boundary segmentation and the boundary conditions.
Templates: ``2d_infiltr.bcdat``, ``3d_infiltr.bcdat``
* :ref:`GMSH Mesh File <man-grid_gmsh>` (optional): Mesh with possibly
complicated geometry to build an unstructured grid from.
* :ref:`Grid Mapping H5 File <man-grid_mapping-dataset>` (optional):
Used to generate heterogeneous soil architectures and boundary segmentations
for rectangular grids.
* :ref:`Scaling Field H5 Files <man-parameter_scaling>` (optional):
Datasets for interpolating local heterogeneities in the parameterization.
Output Files
^^^^^^^^^^^^
* Time Stamp File (``.pvd``): Lists the time step information and the
respective VTK output files of a single program run. This file is always
saved into the directory from which DORiE was executed.
* VTK Files (``.vtu``): The output data in unstructured grid format.
It contains multiple datasets:
- ``head``: Matric head
- ``K0``: Saturated conductivity
- ``flux``: Water flux (not reconstructed!)
- ``theta_w``: Volumetric water content
- ``Theta``: Water saturation
* VTK Parallel Collection Files (``.pvtu``): Merging multiple VTK files in case
DORiE is run in parallel.
installation. See the installation manual for details.
Additionally, install Paraview_ for analyzing the output.
.. _Paraview: http://www.paraview.org/download/
.. _Gmsh: http://gmsh.info
The documentation of DORiE
***************************
DORiE Documentation
*******************
.. ifconfig:: deploy_mode
.. warning::
This documentation was built automatically for the |branch| branch of the repository
at |today|.
Please note that it does not necessarily correspond to the version you are using.
Introduction
=============
Welcome to the DORiE Documentation!
DORiE is a DUNE module for solving the Richards equation. The source code is
......@@ -19,32 +8,39 @@ 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/>`_.
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 :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!
DORiE complies to `Semantic Versioning <https://semver.org/>`_. Version number
assignment and increment are based on the :doc:`public-api`.
Contents
=========
.. _quickstart:
.. toctree::
:maxdepth: 2
:caption: Getting Started
Manual
------
introduction/install-prep
The README <introduction/readme>
introduction/features
introduction/data-io
.. toctree::
:maxdepth: 1
manual/index
:maxdepth: 2
:caption: Manual
manual/cli
manual/config-file
manual/grid
manual/parameter-file
manual/bcfile
public-api
cookbook/index
python/index
.. toctree::
:maxdepth: 2
:caption: Cook Book
Indices and tables
==================
cookbook/index
.. toctree::
:maxdepth: 1
:caption: Python Modules
:glob:
* :ref:`genindex`
* :ref:`modindex`
python/*
Data I/O
********
Executing DORiE requires several input files, some of which are optional and
depending on the mode the program runs in. The configuration input files can
typically be created and manipulated by any text editor. For larger portions
of input data we use HDF5_, a hierachical binary data format. These files can
easily be written using the h5py_ Python module.
DORiE writes output files in the VTK_ format, a filetype suitable for storing
grid-based datasets. These files can be evaluated interactively using
Paraview_. The VTK software library can be included into C++ code and even
has :ref:`Python bindings <https://pypi.org/project/vtk/>`.
Input Files
===========
Templates for the required files can conveniently be generated with the
:doc:`CLI </manual/cli>`.
* :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 </manual/bcfile>` (``.bcdat``):
Specifies the boundary segmentation and the boundary conditions.
Templates: ``2d_infiltr.bcdat``, ``3d_infiltr.bcdat``
* :ref:`GMSH Mesh File <man-grid_gmsh>` (optional): Mesh with possibly
complicated geometry to build an unstructured grid from.
* :ref:`Grid Mapping H5 File <man-grid_mapping-dataset>` (optional):
Used to generate heterogeneous soil architectures and boundary segmentations
for rectangular grids.
* :ref:`Scaling Field H5 Files <man-parameter_scaling>` (optional):
Datasets for interpolating local heterogeneities in the parameterization.
Output Files
============
* Time Stamp File (``.pvd``): Lists the time step information and the
respective VTK output files of a single program run. This file is always
saved into the directory from which DORiE was executed.
* VTK Files (``.vtu``): The output data in unstructured grid format.
It contains multiple datasets:
- ``head``: Matric head
- ``K0``: Saturated conductivity
- ``flux``: Water flux (not reconstructed!)
- ``theta_w``: Volumetric water content
- ``Theta``: Water saturation
* VTK Parallel Collection Files (``.pvtu``): Merging multiple VTK files in case
DORiE is run in parallel.
.. _HDF5: https://www.hdfgroup.org/solutions/hdf5/
.. _h5py: https://www.h5py.org/
.. _Paraview: https://www.paraview.org/
.. _VTK: https://vtk.org/
****************
Feature Overview
****************
DORiE is a flexible partial differential equation (PDE) solver based on DUNE_
and the DUNE-PDELab_ module. DORiE runs in 2D and 3D and computes solutions on
structured and unstructured grids.
Richards Solver
===============
The Richards equation describes water flow in unsaturated porous media by two
state variables, the *matric head* :math:`h_m \, [\mathrm{m}]` and the
*volumetric water content* :math:`\theta_w`,
.. math::
\frac{\partial}{\partial t} \theta_w
- \nabla \left[ K (\theta_w)
\left[ \nabla h_m - \mathbf{\hat{g}} \right]
\right]
= 0,
where :math:`K \, [\mathrm{ms}^{-1}]` is the hydraulic conductivity
and :math:`\mathbf{\hat{g}}` is the unit vector in the direction of
gravitational force. To solve the equation, we need to convert the matric head
into water content and vice versa. The function :math:`\theta_w (h_m)` is
called *retention curve*. Both functions :math:`\theta_w (h_m)` and
:math:`K (\theta_w)` are supplied by a *parameterization* and represent the
hydraulic material properties.
DORiE solves the Richards equation for the matric head because it that a
reformulation of the matric potential :math:`\psi_m [\mathrm{Jm}^{-3}]` which,
by definition, is continuous and differentiable at any point in the soil.
Depending on the soil architecture, the hydraulic parameters may be
discontinuous which would lead to water content and conductivity exhibiting
singularities.
.. _DUNE: https://www.dune-project.org/
.. _DUNE-PDELab: https://www.dune-project.org/modules/dune-pdelab/
......@@ -26,25 +26,6 @@ To install and run DORiE, your computer needs to meet the following requirements
- about 10GB of free disk space
Cloning The Repository
======================
Create a new folder at a suitable location on your machine. Navigate to it, and
clone the DORiE repository by executing
.. code-block:: shell
git clone ssh://git@ts-gitlab.iup.uni-heidelberg.de:10022/dorie/dorie.git
in the terminal. By default, the remote host will be called ``origin``, and the
``master`` branch will be checked out. If you wish to checkout another branch, do so by calling
.. code-block:: shell
git checkout --track origin/<branch>
from a terminal inside the repository folder. Refer to the `Atlassian Git Tutorial <https://www.atlassian.com/git>`_ for more information on using Git.
OS-Dependent Configuration
==========================
......
......@@ -10,7 +10,7 @@ This wrapper script supplies input files, and manages the execution of these
routines. The CLI is available from within the virtual environment
(``venv``).
The virtual environment
The Virtual Environment
=======================
A `virtual environment <https://docs.python.org/3/tutorial/venv.html>`_ is
......
The Manual
==========
This section of the documentation provides detailed information on the
respective parts of the setup for DORiE.
.. toctree::
:maxdepth: 1
install-prep
The README <readme>
cli
config-file
grid
parameter-file
bcfile
Python Packages
===============
.. toctree::
:maxdepth: 1
:glob:
./*
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