From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Sun, 4 Feb 2024 17:15:02 +0000 (-0700)
Subject: Better document one aspect of what you can't do with ghosted vectors.
X-Git-Tag: relicensing~69^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5693d36436a11ced9e5c93eed243745a7cac0983;p=dealii.git

Better document one aspect of what you can't do with ghosted vectors.
---

diff --git a/doc/doxygen/headers/glossary.h b/doc/doxygen/headers/glossary.h
index cde731c39a..2ee8b44ea9 100644
--- a/doc/doxygen/headers/glossary.h
+++ b/doc/doxygen/headers/glossary.h
@@ -1180,9 +1180,9 @@
  * 0...49 of a vector and processor one stores elements 50...99,
  * then processor one is out of luck accessing element 42 of this
  * vector: it is not stored here and the value can not be assessed.
- * This will result in an assertion.
+ * This will result in a failed assertion.
  *
- * On the other hand, there are many situations where one needs to
+ * On the other hand, there are many situations where one *needs* to
  * know vector elements that aren't locally owned, for example to
  * evaluate the solution on a locally owned cell (see
  * @ref GlossLocallyOwnedCell) for which one of the degrees of freedom
@@ -1191,7 +1191,7 @@
  * and for which the neighboring cell may be the owner -- in other
  * words, the degree of freedom is not a
  * @ref GlossLocallyOwnedDof "locally owned" but instead only a
- * @ref GlossLocallyActiveDof "locally active DoFs". The values of such
+ * @ref GlossLocallyActiveDof "locally active" DoF. The values of such
  * degrees of freedom are typically stored on the machine that owns the
  * degree of freedom and, consequently, would not be accessible on the
  * current machine.
@@ -1235,6 +1235,19 @@
  * a mirror value of a primary location as there is no owner of each
  * element.
  *
+ * In the end, there are two key take-away messages from the separation between
+ * ghosted and non-ghosted vectors:
+ * - Ghosted vectors are read-only. You cannot write into them, or add
+ *   one such vector into another.
+ * - Even if every process participates in storing a vector with
+ *   ghost elements, not all elements of the vector may be stored anywhere;
+ *   some elements may be stored on multiple processes but no process may
+ *   be a designated "owner" of these elements. As a consequence, reduction
+ *   operations such as dot products or norms may not be computed on
+ *   vectors with ghost elements because in these storage schemes, it is
+ *   not possible to ensure that each entry of the vector is counted exactly
+ *   once.
+ *
  * @note The @ref distributed documentation module provides a brief
  * overview of where the different kinds of vectors are typically
  * used.
diff --git a/include/deal.II/base/exceptions.h b/include/deal.II/base/exceptions.h
index 99dceb5450..10628f2cd1 100644
--- a/include/deal.II/base/exceptions.h
+++ b/include/deal.II/base/exceptions.h
@@ -1094,10 +1094,18 @@ namespace StandardExceptions
   DeclExceptionMsg(ExcGhostsPresent,
                    "You are trying an operation on a vector that is only "
                    "allowed if the vector has no ghost elements, but the "
-                   "vector you are operating on does have ghost elements. "
-                   "Specifically, vectors with ghost elements are read-only "
+                   "vector you are operating on does have ghost elements."
+                   "\n\n"
+                   "Specifically, there are two kinds of operations that "
+                   "are typically not allowed on vectors with ghost elements. "
+                   "First, vectors with ghost elements are read-only "
                    "and cannot appear in operations that write into these "
-                   "vectors."
+                   "vectors. Second, reduction operations (such as computing "
+                   "the norm of a vector, or taking dot products between "
+                   "vectors) are not allowed to ensure that each vector "
+                   "element is counted only once (as opposed to once for "
+                   "the owner of the element plus once for each process "
+                   "on which the element is stored as a ghost copy)."
                    "\n\n"
                    "See the glossary entry on 'Ghosted vectors' for more "
                    "information.");