From e811c782349f490ec5cd840eba8b6c72c9e2ce26 Mon Sep 17 00:00:00 2001
From: Lukas Riedel
Date: Wed, 8 May 2019 13:15:38 +0200
Subject: [PATCH] Update docs on flux reconstruction wrt FV solver
---
doc/introduction/features.rst | 2 ++
doc/manual/fluxes.rst | 52 +++++++++++++++++++++--------------
2 files changed, 33 insertions(+), 21 deletions(-)
diff --git a/doc/introduction/features.rst b/doc/introduction/features.rst
index a4e70819..8ce29ae9 100644
--- a/doc/introduction/features.rst
+++ b/doc/introduction/features.rst
@@ -39,6 +39,8 @@ singularities.
Use the value ``richards`` in the ``simulation.mode`` keyword to run the
standalone Richards solver.
+.. _richards_solver_options:
+
Solver Options
--------------
diff --git a/doc/manual/fluxes.rst b/doc/manual/fluxes.rst
index 09fcd763..70305bf5 100644
--- a/doc/manual/fluxes.rst
+++ b/doc/manual/fluxes.rst
@@ -10,7 +10,10 @@ Firstly, we have to recall that DORiE solves a Discontinuous Galerking finite el
From the description above one can infer that one has to distinguish between * fluxes* at the interior of each element and at the intersections of all elements (we call these intersections skeleton of the grid). Unfortunately, there is no a standard form to write the skeleton fluxes on formats like VTK and that's the main reason why DORiE only provides the interior fluxes. However, assuming one can write both fluxes into some output format, they are still discontinuous (notice that direct use of discontinuous fluxes are useless for conservative computations since the transported quantities are very likely to get stagnated or over-transported in the nearby of intersections between elements). It means that it is needed some sort of post-processing that ensures that the *mass* is still locally and globally conserved.
-DORiE allows finite volume computations under certain specific conditions. In such case, if generated, the raw flux output has no meaning. The reason is that finite volumes are computed with finite elements of order 0 where gradients are 0. In such case, flux reconstruction is the only alternative.
+When employing a finite volume solver, the regular flux output is omitted
+because the basis function gradients are always zero. In this case, the only
+option for evaluating flux data is flux reconstruction which has to be enabled
+in the :doc:`config file `.
Flux reconstruction
-------------------
@@ -18,26 +21,33 @@ The flux reconstruction is a projection of the fluxes used in the Discontinuous
The flux reconstruction technique always use Raviar Thomas finite elements of one degree less than the one set for the Richards model. It can be identified in the vtk file by the name ``flux_RT{min(k-1,0)}``, where ``k`` is the finite element order set for the Richards model. Flux reconstruction is not available for non-conforming grids (i.e. Cube-adaptive grids).
-+---------------------------+---+---+---+
-| Richards FEorder | 1 | 2 | 3 |
-+============+====+=========+===+===+===+
-| | 2D | Simplex | ✓ | ✓ | ✓ |
-| | +---------+---+---+---+
-| | | Cube | ✓ | ✓ | ✓ |
-| Non-adapt. +----+---------+---+---+---+
-| | 3D | Simplex | ✓ | ✓ | ✓ |
-| | +---------+---+---+---+
-| | | Cube | ✓ | ✓ | |
-+------------+----+---------+---+---+---+
-| | 2D | Simplex | ✓ | ✓ | ✓ |
-| | +---------+---+---+---+
-| | | Cube | | | |
-| Adapt. +----+---------+---+---+---+
-| | 3D | Simplex | ✓ | ✓ | ✓ |
-| | +---------+---+---+---+
-| | | Cube | | | |
-+------------+----+---------+---+---+---+
++---------------------------+---+---+---+---+
+| Richards FEorder | 0 | 1 | 2 | 3 |
++============+====+=========+===+===+===+===+
+| | 2D | Simplex | ✗ | ✓ | ✓ | ✓ |
+| | +---------+---+---+---+---+
+| | | Cube | ✓ | ✓ | ✓ | ✓ |
+| Non-adapt. +----+---------+---+---+---+---+
+| | 3D | Simplex | ✗ | ✓ | ✓ | ✓ |
+| | +---------+---+---+---+---+
+| | | Cube | ✓ | ✓ | ✓ | |
++------------+----+---------+---+---+---+---+
+| | 2D | Simplex | ✗ | ✓ | ✓ | ✓ |
+| | +---------+---+---+---+---+
+| | | Cube | ✗ | | | |
+| Adapt. +----+---------+---+---+---+---+
+| | 3D | Simplex | ✗ | ✓ | ✓ | ✓ |
+| | +---------+---+---+---+---+
+| | | Cube | ✗ | | | |
++------------+----+---------+---+---+---+---+
+
+Legend:
+
+* ✓: Flux reconstruction available.
+* ( ): Flux reconstruction unavailable.
+* ✗: Invalid setting. Finite volume solvers only works on regular grids,
+ see :ref:`Richards Solver Options `.
Usage
-----
-To activate/deactivate flux reconstruction use the keyword ``richards.numeric.fluxReconstruction = true/false`` in the :doc:`config file`.
+To activate/deactivate flux reconstruction use the keyword ``richards.numeric.fluxReconstruction = true/false`` in the :doc:`config file `.
--
GitLab