Commit c9c4817e authored by Lukas Riedel's avatar Lukas Riedel

Add doxygen docs for new grid creation process

* Add module for grid creation
* Add author and date information
* Improve docstrings of classes and functions
parent 6386af8b
......@@ -37,6 +37,9 @@ namespace Dorie {
* soil layers (parameter sets) via the GridMapper.
*
* \tparam Grid The type of the grid to build
* \ingroup Grid
* \author Lukas Riedel
* \date 2018
*/
template<typename Grid>
class GridCreator
......
This diff is collapsed.
......@@ -35,6 +35,75 @@
Notice that `helper` will be of *reference* type `Dune::MPIHelper &`.
@}
@defgroup Grid Grid Creation and Mapping Utilities
@{
@ingroup Common
@brief Classes for building grids and load-balancing mapping data
## Overview
DORiE offers a variety of grid setups which require different DUNE grid
managers and different setup routines. For structured rectangular grids,
we use `Dune::YaspGrid`, and for unstructured rectangular or simplex grids,
we use `Dune::UGGrid`.
In addition to the actual grid, DORiE also manages mappings of grid elements
(cells) and boundary segments to indices. These indices are used to refer to
medium layers in case of cells and boundary conditions in case of boundary
faces. Through the medium layer, a certain
\ref RichardsParam "hydraulic Parameterization" is applied to the
respective cell.
The Dorie::GridCreator builds a DUNE grid from the settings given in the
config file. It then internally assembles the Dorie::GridMapper which
loads the mapping data and load-balances it appropriately across all
processes if executed in parallel. The resulting local maps are retrieved
by the Dorie::GridCreator and can be queried by the user.
There are two general ways of constructing a grid:
1. Assembling an unstructured grid from a [GMSH](http://gmsh.info/)
file. This always uses `UGGrid`. GMSH has the capability of storing
grid element and boundary mappings and the `Dune::GmshReader` also loads
this information. It is then passed to the `GridMapper` and properly
load-balanced, as the `GmshReader` currently only works sequentially.
2. Building a rectangular grid with user-defined extensions and numbers
of cells in each direction. Depending on wether grid adaptivity was
enabled, this either creates a `UGGrid` or a `YaspGrid`. In both cases,
the user has to supply the mapping information separately. DORiE offers
two options here: Mapping a single ("global") index to all elements,
or reading a mapping dataset. This H5 dataset must have the same shape
as the grid. Each of its values maps to a single grid cell.
## Constructing The Grid
Initialize the grid creator with the config file settings. This will
automatically build the grid.
@code{.cc}
Dune::Dorie::GridCreator<GridType> grid_creator(config, helper);
@endcode
Retrieve a shared pointer to the grid from it. The grid will already be
properly load-balanced.
@code{.cc}
auto grid = grid_creator.grid();
@endcode
The index maps are managed by the `GridMapper`, which is created internally.
After initializing the `GridCreator`, they can be retrieved from it.
Notice that these maps only remain valid if the grid is **not load-balanced
any further** (e.g., after local grid refinement)!
@code{.cc}
auto element_index_map = grid_creator.get_element_index_map();
auto boundary_index_map = grid_creator.get_boundary_index_map();
@endcode
@}
@defgroup Logging Terminal Logging
@{
@ingroup Common
......
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