From: Peter Munch <peterrmuench@gmail.com>
Date: Sun, 14 Mar 2021 16:21:56 +0000 (+0100)
Subject: Extend text regarding allow_artificial_cells
X-Git-Tag: v9.3.0-rc1~305^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F11910%2Fhead;p=dealii.git

Extend text regarding allow_artificial_cells
---

diff --git a/include/deal.II/distributed/shared_tria.h b/include/deal.II/distributed/shared_tria.h
index 0d4efafe5e..798a7b9be4 100644
--- a/include/deal.II/distributed/shared_tria.h
+++ b/include/deal.II/distributed/shared_tria.h
@@ -228,11 +228,25 @@ namespace parallel
       /**
        * Constructor.
        *
-       * If @p allow_aritifical_cells is true, this class will behave similar
-       * to parallel::distributed::Triangulation in that there will be locally
-       * owned, ghost and artificial cells.
+       * The flag @p allow_artificial_cells can be used to enable artifical
+       * cells. If enabled, this class will behave similarly
+       * to parallel::distributed::Triangulation and
+       * parallel::fullydistributed::Triangulation in the sense that there will
+       * be locally owned cells, a single layer of ghost cells, and
+       * artificial cells. However, one should not forget that in contrast to
+       * those parallel triangulations all cells are duplicated on all
+       * processes, leading in most cases to significantly more artificial
+       * cells.
        *
-       * Otherwise all non-locally owned cells are considered ghost.
+       * If artificial cells are disabled, all non-locally owned cells are
+       * considered ghost cells. This might lead to very expensive ghost-value
+       * update steps. While in the case of artificial cells, ghost-value
+       * updates lead to communication only with the direct process neighbors in
+       * a point-to-point fashion, these degenerate to an operation in which
+       * every process communicates with every other process (an "all-to-all"
+       * communication) if no artifical cells are available. If such ghost-value
+       * updates are the bottleneck in your code, you may want to consider
+       * enabling artificial cells.
        */
       Triangulation(
         const MPI_Comm &mpi_communicator,