Enhance documentation of local_cell_relations.

diff --git a/include/deal.II/distributed/fully_distributed_tria.h b/include/deal.II/distributed/fully_distributed_tria.h
index 4996109c63d353590a7b5ea3831c04dad7990e36..27480d4815147b6d0041a3d187ac51eeaeb2b780 100644 (file)
--- a/include/deal.II/distributed/fully_distributed_tria.h
+++ b/include/deal.II/distributed/fully_distributed_tria.h
@@ -265,10 +265,15 @@ namespace parallel
         const unsigned int coarse_cell_index) const override;
 
       /**
-       * Go through all locally owned cells and store the relations between
-       * cells and their CellStatus in the private member local_cell_relations.
+       * Go through all active cells that are locally owned and record how they
+       * will change in the private member vector local_cell_relations.
        *
-       * The stored vector will be ordered by the occurrence of cells.
+       * As no adaptive mesh refinement is supported at the moment for this
+       * class, all cells will be flagged with the CellStatus CELL_PERSIST.
+       * These relations will currently only be used for serialization.
+       *
+       * The stored vector will have a size equal to the number of locally owned
+       * active cells and will be ordered by the occurrence of those cells.
        */
       virtual void
       update_cell_relations() override;

diff --git a/include/deal.II/distributed/tria.h b/include/deal.II/distributed/tria.h
index 8ba5939840bd32980017fc6a4b80ac75c28c2097..9e629bd120399fc6b9f4af2e4226b5bfc4f730b4 100644 (file)
--- a/include/deal.II/distributed/tria.h
+++ b/include/deal.II/distributed/tria.h
@@ -694,13 +694,25 @@ namespace parallel
       typename dealii::internal::p4est::types<dim>::ghost *parallel_ghost;
 
       /**
-       * Go through all p4est trees and store the relations between a deal.II
-       * cell and its current CellStatus in the private member
-       * local_cell_relations.
+       * Go through all p4est trees and record the relations between locally
+       * owned p4est quadrants and active deal.II cells in the private member
+       * vector local_cell_relations.
+       *
+       * The vector contains an active cell iterator for every locally owned
+       * p4est quadrant, as well as a CellStatus flag to describe their
+       * relation.
        *
        * The stored vector will be ordered by the occurrence of quadrants in
        * the corresponding local sc_array of the parallel_forest. p4est requires
-       * this specific ordering for its transfer functions.
+       * this specific ordering for its transfer functions. Therefore, the size
+       * of this vector will be equal to the number of locally owned quadrants
+       * in the parallel_forest object.
+       *
+       * These relations will be established for example in the mesh refinement
+       * process: after adapting the parallel_forest, but before applying these
+       * changes to this triangulation, we will record how cells will change in
+       * the refinement process. With this information, we can prepare all
+       * buffers for data transfer accordingly.
        */
       virtual void
       update_cell_relations() override;

diff --git a/include/deal.II/distributed/tria_base.h b/include/deal.II/distributed/tria_base.h
index 235939c50d210bd26e70a296b2f5e5259a0d5b3d..eae6bd8053042882d355c738e11d642634c86d94 100644 (file)
--- a/include/deal.II/distributed/tria_base.h
+++ b/include/deal.II/distributed/tria_base.h
@@ -688,31 +688,29 @@ namespace parallel
                        const unsigned int n_attached_deserialize_variable);
 
     /**
-     * Go through all cells and store the relations between a deal.II cell and
-     * its current CellStatus in the private member local_cell_relations.
-     * For an extensive description of CellStatus, see the documentation
-     * for the member function register_data_attach().
+     * A function to record the CellStatus of currently active cells that
+     * are locally owned. This information is mandatory to transfer data
+     * between meshes during adaptation or serialization, e.g., using
+     * parallel::distributed::SolutionTransfer.
      *
-     * The stored vector will be ordered by the occurrence of quadrants.
+     * Relations will be stored in the private member local_cell_relations. For
+     * an extensive description of CellStatus, see the documentation for the
+     * member function register_data_attach().
      */
     virtual void
     update_cell_relations() = 0;
 
     /**
-     * This auxiliary data structure stores the relation between
-     * a deal.II cell and its current CellStatus. For an extensive
-     * description of the latter, see the documentation for the member
-     * function register_data_attach().
+     * Auxiliary data structure for assigning a CellStatus to a deal.II cell
+     * iterator. For an extensive description of the former, see the
+     * documentation for the member function register_data_attach().
      */
     using cell_relation_t = typename std::pair<cell_iterator, CellStatus>;
 
     /**
-     * Vector of pair, each containing a deal.II cell iterator
-     * and their relation after refinement. To update its contents, use the
+     * Vector of pairs, each containing a deal.II cell iterator and its
+     * respective CellStatus. To update its contents, use the
      * update_cell_relations() member function.
-     *
-     * The size of this vector is assumed to be equal to the number of locally
-     * owned quadrants in the parallel_forest object.
      */
     std::vector<cell_relation_t> local_cell_relations;