From: Timo Heister <timo.heister@gmail.com>
Date: Mon, 15 Jan 2024 21:07:32 +0000 (-0500)
Subject: exchange refinement flags: doc and changelog
X-Git-Tag: relicensing~153^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F16478%2Fhead;p=dealii.git

exchange refinement flags: doc and changelog
---

diff --git a/doc/news/changes/minor/20240115tjhei b/doc/news/changes/minor/20240115tjhei
new file mode 100644
index 0000000000..de5d27a531
--- /dev/null
+++ b/doc/news/changes/minor/20240115tjhei
@@ -0,0 +1,7 @@
+Changed:
+parallel::distributed::Triangulation::prepare_coarsening_and_refinement()
+is now a collective call that exchanges coarsen/refinement flags on
+ghost cells. This makes adaptive refinement independent of the number
+of MPI ranks involved.
+<br>
+(Timo Heister, Quang Hoang, Vladimir Yushutin, 2024/01/15)
diff --git a/include/deal.II/distributed/tria.h b/include/deal.II/distributed/tria.h
index 96856f4a42..908f17835b 100644
--- a/include/deal.II/distributed/tria.h
+++ b/include/deal.II/distributed/tria.h
@@ -484,14 +484,17 @@ namespace parallel
        * Coarsen and refine the mesh according to refinement and coarsening
        * flags set.
        *
-       * Since the current processor only has control over those cells it owns
-       * (i.e. the ones for which <code>cell-@>subdomain_id() ==
-       * this-@>locally_owned_subdomain()</code>), refinement and coarsening
-       * flags are only respected for those locally owned cells. Flags may be
-       * set on other cells as well (and may often, in fact, if you call
-       * dealii::Triangulation::prepare_coarsening_and_refinement()) but will
-       * be largely ignored: the decision to refine the global mesh will only
-       * be affected by flags set on locally owned cells.
+       * Since the current processor only has control over those cells
+       * it owns (i.e. the ones for which <code>cell-@>subdomain_id()
+       * == this-@>locally_owned_subdomain()</code>), refinement and
+       * coarsening flags are only respected for those locally owned
+       * cells. Flags set on other cells will be ignored: the decision
+       * to refine the global mesh will only be affected by flags set
+       * on locally owned cells.
+       *
+       * This is a
+       * @ref GlossCollectiveOperation "collective operation"
+       * and needs to be called by all participating MPI ranks.
        *
        * @note This function by default partitions the mesh in such a way that
        * the number of cells on all processors is roughly equal. If you want
@@ -513,10 +516,16 @@ namespace parallel
       execute_coarsening_and_refinement() override;
 
       /**
-       * Override the implementation of prepare_coarsening_and_refinement from
-       * the base class. This is necessary if periodic boundaries are enabled
-       * and the level difference over vertices over the periodic boundary
-       * must not be more than 2:1.
+       * Prepare the triangulation for coarsening and refinement.
+       *
+       * This function performs necessary modifications of the
+       * coarsening and refinement flags to be consistent in parallel,
+       * to conform to smoothing flags set, and to conform to 2:1
+       * hanging node constraints.
+       *
+       * This is a
+       * @ref GlossCollectiveOperation "collective operation"
+       * and needs to be called by all participating MPI ranks.
        */
       virtual bool
       prepare_coarsening_and_refinement() override;
@@ -579,7 +588,9 @@ namespace parallel
       memory_consumption_p4est() const;
 
       /**
-       * A @ref GlossCollectiveOperation "collective operation" that produces a sequence of output files with
+       * A
+       * @ref GlossCollectiveOperation "collective operation"
+       * that produces a sequence of output files with
        * the given file base name that contain the mesh in VTK format.
        *
        * More than anything else, this function is useful for debugging the