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 08de1e4bffae3cf45dd4c3cb10b866041b4678c9..2fcb74a894279626ae5f28156d483724eddcd888 100644 (file)
--- 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 <i>all</i> cells of the entire mesh, whereas some
+ *   other classes such as parallel::distributed::Triangulation only
+ *   store <i>some</i> 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.
+ * </dd>
+ *
+ *
+ * <dt class="glossary">@anchor GlossCoarseCellId <b>Coarse cell ID</b></dt>
+ * <dd>
+ *   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.
  * </dd>
  *
  *

diff --git a/include/deal.II/base/types.h b/include/deal.II/base/types.h
index ff94c958916057abddecbaa23cafb34cf971f9ac..17318eea56b9fa9a1e2923ffcec01543e523a4bc 100644 (file)
--- 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<types::global_dof_index>(-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<types::coarse_cell_id>(-1);

diff --git a/include/deal.II/grid/cell_id.h b/include/deal.II/grid/cell_id.h
index 702dc4de06d4fef84bfe801c20f5208fda6db9f1..169295818c3cd0724e886885090192b70f8383ed 100644 (file)
--- 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 <tt>cell->id()</tt> if <tt>cell</tt> 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 0c140e52ce8ef5d40e6cf3ba7cd7dfc33ad8467a..3021a39ab99f81d3cafd6d2b9e8edb364824a586 100644 (file)
--- 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().