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::Simulation

.. _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: