Skip to content

GitLab

D
dorie
Commit c9c4817e authored by Lukas Riedel's avatar Lukas Riedel
Browse files
Options

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
Hide whitespace changes
Inline Side-by-side
Showing with 159 additions and 42 deletions
dune/dorie/common/grid_creator.hh
View file @ c9c4817e
......@@ -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
......
dune/dorie/common/grid_mapper.hh
View file @ c9c4817e
......@@ -20,9 +20,13 @@ namespace Dune {
namespace Dorie {
/// Type of grid loading mode. Defines how parameters are read from the grid.
/** \ingroup Grid
*/
enum class GridMode {
gmsh, //!< Read a GMSH file containing parameter and boundary mappings
rectangular //!< Build a grid internally and read parameter mappings from files
/// Read a GMSH file containing parameter and boundary mappings
gmsh,
/// Build a grid internally and read parameter mappings from files
rectangular
};
/// Retrieve the grid extensions as a position vector
......@@ -32,6 +36,7 @@ enum class GridMode {
* \param grid Shared pointer to the grid
* \note This assumes the grid has rectangular shape and its origin
* is the origin of Euklidian space.
* \ingroup Grid
*/
template<typename Grid>
auto get_grid_extensions (const std::shared_ptr<Grid> grid)
......@@ -70,7 +75,15 @@ inline std::string to_lower (const std::string& in)
return out;
}
/// Basic class members of any grid mapper
/// Base class for mappers for assembling local element and boundary index maps
/** This class provides common members and methods for retrieving the maps,
* and broadcasting data to all processes.
*
* \tparam Grid Type of the grid used
* \ingroup Grid
* \author Lukas Riedel
* \date 2018
*/
template<typename Grid>
class GridMapperBase
{
......@@ -105,7 +118,7 @@ protected:
public:
/// Construct the mapper. Initialize the grid view to level 0.
/** \param grid Shared pointer to the grid
* \param log The logger of this instance
* \param log The logger of this instance (defaults to log_base).
*/
GridMapperBase (const std::shared_ptr<Grid> grid,
const Logger log=get_logger(log_base)):
......@@ -191,10 +204,15 @@ protected:
};
#ifndef DOXYGEN
/// Unspecified grid mapper specizalization
template<typename Grid, GridMode>
class GridMapper
class GridMapper : public GridMapperBase<Grid>
{ };
#endif // DOXYGEN
/// Specialized mapper for grids loaded from GMSH
/** The maps are retrieved together with the acutal grid by the
* Dune::GmshReader. DORiE only supports UGGrid in this case.
......@@ -205,6 +223,15 @@ class GridMapper
*
* For the element map, we have to create a global ID map, broadcast it,
* load-balance the grid, and re-create a local element index map.
*
* \note Only works for UG grids built by the Dune::GmshReader
* \note Only works for grids that exist on a single process.
* \todo Add capability for re-balancing. Assume that local maps exist on
* every process and use functions like `gatherv` for balancing all data.
*
* \ingroup Grid
* \author Lukas Riedel
* \date 2018
*/
template<typename Grid>
class GridMapper<Grid, GridMode::gmsh> : public GridMapperBase<Grid>
......@@ -227,6 +254,16 @@ public:
using Map = typename Base::Map;
/// Construct this mapper with local maps retrieved from the GMSH file
/** If run sequentially, only copy the local maps. Otherwise, build a
* globally consistent ID map, load-balance the grid, and re-build the
* index maps locally.
*
* \param grid Shared pointer to the grid
* \param element_index_map_local The local element index map retrieved
* from the GmshReader.
* \param boundary_index_map_local The local boundary index map retrieved
* from the GmshReader.
*/
explicit GridMapper (const std::shared_ptr<Grid> grid,
const Map& element_index_map_local,
Map& boundary_index_map_local) :
......@@ -281,11 +318,12 @@ private:
return ret;
}
/// Build a local element_index_map from a global ID mapping
/// Build a local element index map from a global ID mapping
/** The global ID is consistent across all processors and is used for
* identifying the respective cell.
*
* \param id_map The ID map to build the index map from
* \return Local element index map for elements on this process
*/
Map rebuild_local_index_map (const std::map<IdType, int>& id_map)
{
......@@ -303,6 +341,21 @@ private:
}
};
/// Specialized mapper for grids built by StructuredGridFactory
/** The maps are built by loading mapping data files specified in the config
* file. If no files are given, global default mappings are applied.
*
* The behavior is independent of the current load-balancing of the grid.
* The H5 files containing global mappings are (collectively) read on every
* process. The local mapping is built from transferring global coordinates
* to indices of the datasets.
*
* \todo Add input of boundary mappings and mapping files
*
* \ingroup Grid
* \author Lukas Riedel
* \date 2018
*/
template<typename Grid>
class GridMapper<Grid, GridMode::rectangular> : public GridMapperBase<Grid>
{
......@@ -331,6 +384,14 @@ public:
/// Type of the maps returned by this mapper
using Map = typename Base::Map;
/// Read config settings, load global maps, and localize them.
/** Load the global maps from files (or create a mapping to a single
* value). Then localize this mapping by using the (local) MCMGMapper,
* and by inferring the global element index via global coordinates.
*
* \param grid Shared pointer to the grid
* \param config The config file settings
*/
explicit GridMapper (const std::shared_ptr<Grid> grid,
const Dune::ParameterTree& config):
Base(grid),
......@@ -340,7 +401,7 @@ public:
{
Map element_index_map_global;
// check if mapping file is given
// load global mapping (on every process)
const auto file_path = _config.get<std::string>("grid.mappingFile", "");
if (to_lower(file_path) != "none" and not file_path.empty()){
H5File mapping_file(file_path);
......@@ -358,7 +419,7 @@ public:
this->_mapper.update();
// broadcast the index vectors
this->broadcast_contiguous_container(element_index_map_global);
// this->broadcast_contiguous_container(element_index_map_global);
// localize
this->_element_index_map
......@@ -372,26 +433,20 @@ public:
private:
/// Map a (global) position on the grid to continuous index
/** \param position The (center) position of a grid cell
* \param extensions The extensions of the grid
* \param cell_count The number of cells in each dimension
/** \param position The (center) position of a grid element
* \return Index for querying the continuous array.
*/
auto map_position_to_index (const Domain& position) const
{
const auto multi_index = map_position_to_multi_index(
position
);
const auto multi_index = map_to_multi_index(position);
return multi_index_to_index(multi_index);
}
/// Map a (global) position on the grid to a multi index
/** \param position The (center) position of a grid cell
* \param extensions The extensions of the grid
* \param cell_count The number of cells in each dimension
* \return The multi index for querying a cell mapping: (x, y[, z])
/** \param position The (center) position of a grid element
* \return The multi index for querying a element mapping: (x, y[, z])
*/
MultiIndex map_position_to_multi_index (const Domain& position) const
MultiIndex map_to_multi_index (const Domain& position) const
{
MultiIndex ret;
for (size_t i = 0; i < dim; ++i) {
......@@ -405,13 +460,9 @@ private:
/// Create a single index from multi indices
/** This assumes that the first index one runs fastest: x->y->z.
* \param multi_index Multi index to transform
* \param cell_count Number of cells in each direction. Assumed to map to
* the multi indices.
* \return Index for querying the continuous array.
*/
size_t multi_index_to_index (
const MultiIndex multi_index
) const
size_t multi_index_to_index (const MultiIndex multi_index) const
{
size_t ret = 0;
......@@ -431,23 +482,14 @@ private:
return ret;
}
/// Open and return the H5 mapping file if it was specified
/** \return Object of type std::optional<Dune::Dorie::H5File>, containing
* the H5 file if the user specified it in the config file
*/
// std::optional<H5File> open_mapping_file () const
// {
// // check if mapping file is given
// const auto file_path = _config.get<std::string>("grid.mappingFile", "");
// if (to_lower(file_path) != "none" or not file_path.empty()){
// return H5File(file_path);
// }
// // return nothing
// return {};
// }
/// Return element mapping retrieved from a mapping file
/** Load the `Grid::dimension`-dimensional element mapping dataset and
* compare its shape with the grid cells. Return the flattened array.
*
* \param mapping_file The H5file to read from
* \return Global element index map (directly read from file)
* \throw Dataset does not conform to grid shape
*/
Map read_medium_mapping (H5File& mapping_file) const
{
// load heterogeneous mapping
......@@ -490,6 +532,9 @@ private:
}
/// Return element mapping for a global index
/** Read the global index from the entry in the config file
* \return Global element index map mapping to the single global index.
*/
Map read_medium_global_index () const
{
const auto global_id = _config.get<int>("grid.globalIndex");
......@@ -514,10 +559,10 @@ private:
*/
Map localize_element_index_map (const Map& element_index_map_global) const
{
// prepare new map
// prepare new map in correct size for this process
Map ret(this->_mapper.size(), 0);
// iterate over local cells
// iterate over cells on this process
for (const auto& cell : elements(this->_gv)) {
const auto index = this->_mapper.index(cell);
const auto pos = cell.geometry().center();
......
dune/dorie/common/modules.dox
View file @ c9c4817e
......@@ -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