From 5693d36436a11ced9e5c93eed243745a7cac0983 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Sun, 4 Feb 2024 10:15:02 -0700 Subject: [PATCH] Better document one aspect of what you can't do with ghosted vectors. --- doc/doxygen/headers/glossary.h | 19 ++++++++++++++++--- include/deal.II/base/exceptions.h | 14 +++++++++++--- 2 files changed, 27 insertions(+), 6 deletions(-) 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."); -- 2.39.5