From: Wolfgang Bangerth Date: Tue, 20 Aug 2019 22:19:23 +0000 (-0600) Subject: Document the concept of 'coarse cell id' in the glossary. X-Git-Tag: v9.2.0-rc1~1203^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9053bf34f81a62bce078554564d71e1556eb66da;p=dealii.git Document the concept of 'coarse cell id' in the glossary. --- diff --git a/doc/doxygen/headers/glossary.h b/doc/doxygen/headers/glossary.h index 08de1e4bff..2fcb74a894 100644 --- a/doc/doxygen/headers/glossary.h +++ b/doc/doxygen/headers/glossary.h @@ -413,6 +413,67 @@ * consists of exactly the level-zero cells of a triangulation. (Whether * they are active (i.e., have no children) or have been refined is not * important for this definition.) + * + * Most of the triangulation classes in deal.II store the entire coarse + * mesh along with at least some of the refined cells. (Both the + * dealii::Triangulation and parallel::shared::Triangulation classes + * actually store all cells of the entire mesh, whereas some + * other classes such as parallel::distributed::Triangulation only + * store some of the @ref GlossActive "active cells" on + * each process in a parallel computation.) In those cases, + * one can query the triangulation for all coarse mesh + * cells. Other triangulation classes (e.g., + * parallel::fullydistributed::Triangulation) only store a part + * of the coarse mesh. See also + * @ref GlossCoarseCellId "the concept of coarse cell ids" + * for that case. + * + * + * + *
@anchor GlossCoarseCellId Coarse cell ID
+ *
+ * Most of the triangulation classes in deal.II, notably + * dealii::Triangulation, parallel::shared::Triangulation, and + * parallel::distributed::Triangulation, store the entire + * @ref GlossCoarseMesh "coarse mesh" + * of a triangulation on each process of a parallel computation. On the + * other hand, this is not the case for other classes, notably for + * parallel::fullydistributed::Triangulation, which is designed for cases + * where even the coarse mesh is too large to be stored on each process + * and needs to be partitioned. + * + * In those cases, it is often necessary in algorithms to reference a coarse + * mesh cell uniquely. Because the triangulation object on the current + * process does not actually store the entire coarse mesh, one needs to have + * a globally unique identifier for each coarse mesh cell that is independent + * of the index within level zero of the triangulation stored locally. This + * globally unique ID is called the "coarse cell ID". It can be accessed via + * the function call + * @code + * triangulation.coarse_cell_index_to_coarse_cell_id (coarse_cell->index()); + * @endcode + * where `triangulation` is the triangulation to which the iterator + * `coarse_cell` pointing to a cell at level zero belongs. Here, + * `coarse_cell->index()` returns the index of that cell within its + * refinement level (see TriaAccessor::index()). This is a number + * between zero and the number of coarse mesh cells stored on the + * current process in a parallel computation; it uniquely identifies + * a cell on that parallel process, but different parallel processes may + * use that index for different cells located at different coordinates. + * + * For those classes that store all coarse mesh cells on each process, + * the Triangulation::coarse_cell_index_to_coarse_cell_id() simply + * returns a permutation of the possible argument values. In the + * simplest cases, such as for a sequential or a parallel shared + * triangulation, the function will in fact simply return the + * value of the argument. For others, such as + * parallel::distributed::Triangulation, the ordering of + * coarse cell IDs is not the same as the ordering of coarse + * cell indices. Finally, for classes such as + * parallel::fullydistributed::Triangulation, the function returns + * the globally unique ID, which is from a larger set of possible + * indices than the indices of the coarse cells actually stored on + * the current process. *
* * diff --git a/include/deal.II/base/types.h b/include/deal.II/base/types.h index ff94c95891..17318eea56 100644 --- a/include/deal.II/base/types.h +++ b/include/deal.II/base/types.h @@ -97,12 +97,14 @@ namespace types #ifdef DEAL_II_WITH_64BIT_INDICES /** - * The type used for coarse-cell ids. + * The type used for coarse-cell ids. See the glossary + * entry on @ref GlossCoarseCellId "coarse cell IDs" for more information. */ using coarse_cell_id = unsigned long long int; #else /** - * The type used for coarse-cell ids. + * The type used for coarse-cell ids. See the glossary + * entry on @ref GlossCoarseCellId "coarse cell IDs" for more information. */ using coarse_cell_id = unsigned int; #endif @@ -201,7 +203,8 @@ namespace numbers static_cast(-1); /** - * An invalid value for coarse-cell ids. + * An invalid value for coarse cell ids. See the glossary + * entry on @ref GlossCoarseCellId "coarse cell IDs" for more information. */ const types::coarse_cell_id invalid_coarse_cell_id = static_cast(-1); diff --git a/include/deal.II/grid/cell_id.h b/include/deal.II/grid/cell_id.h index 702dc4de06..169295818c 100644 --- a/include/deal.II/grid/cell_id.h +++ b/include/deal.II/grid/cell_id.h @@ -39,10 +39,12 @@ class Triangulation; /** * A class to represent a unique ID for a cell in a Triangulation. It is - * returned by cell->id() if cell is a cell iterator. + * returned by `cell->id()` (i.e., CellAccessor::id()) where + * `cell` is assumed to be a cell iterator. * - * This class - * stores the index of the coarse cell from which a cell is descendant, + * This class stores the index of the coarse cell from which a cell is + * descendant (or, more specifically, the + * entry on @ref GlossCoarseCellId "coarse cell IDs"), * together with information on how to reach the cell from that coarse cell * (i.e., which child index to take on each level of the triangulation when * moving from one cell to its children). The important point about this diff --git a/include/deal.II/grid/tria.h b/include/deal.II/grid/tria.h index 0c140e52ce..3021a39ab9 100644 --- a/include/deal.II/grid/tria.h +++ b/include/deal.II/grid/tria.h @@ -3484,7 +3484,8 @@ public: get_periodic_face_map() const; /** - * Translate the unique id of a coarse cell to its index. + * Translate the unique id of a coarse cell to its index. See the glossary + * entry on @ref GlossCoarseCellId "coarse cell IDs" for more information. * * @note For serial and shared triangulation both id and index are the same. * For distributed triangulations setting both might differ, since the @@ -3499,7 +3500,8 @@ public: /** - * Translate the index of coarse cell to its unique id. + * Translate the index of coarse cell to its unique id. See the glossary + * entry on @ref GlossCoarseCellId "coarse cell IDs" for more information. * * @note: See the note of the method * coarse_cell_id_to_coarse_cell_index().