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 cde731c39a61bf3ab96538245482354a800381da..2ee8b44ea985ceccf7017d027353be208972e622 100644 (file)
--- 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 99dceb54503410ebb0167b6cc4b484be7de83b84..10628f2cd143d9d32ee2f3d26aa344a0ac58e401 100644 (file)
--- 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.");