From: Daniel Arndt <arndtd@ornl.gov>
Date: Tue, 29 Aug 2023 12:33:33 +0000 (-0400)
Subject: Improve documentation for allow_check_for_cell_similarity
X-Git-Tag: relicensing~507^2~1
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6d1107d24181eb33d2cb5581383ded52af0d469a;p=dealii.git

Improve documentation for allow_check_for_cell_similarity
---

diff --git a/include/deal.II/fe/fe_values_base.h b/include/deal.II/fe/fe_values_base.h
index 1b275f1ee6..70375e33a4 100644
--- a/include/deal.II/fe/fe_values_base.h
+++ b/include/deal.II/fe/fe_values_base.h
@@ -223,8 +223,14 @@ public:
   virtual ~FEValuesBase() override;
 
   /**
-   * Explicitly allow to check for cell similarity. By default, this is only
-   * enabled when the number of threads is 1.
+   * Explicitly allow to check for cell similarity.
+   * The detection of simple geometries with CellSimilarity is sensitive to the
+   * first cell detected. When using multiple threads, each thread might get a
+   * thread local copy of the FEValues object that is initialized to the first
+   * cell the thread sees. As this cell might be differ between runs and number
+   * of threads used, this slight deviation leads to difference in roundoff
+   * errors that propagate through the program. Therefore, the CellSimilarity
+   * check is disabled by default in case more than one thread is used.
    */
   void
   allow_check_for_cell_similarity(bool allow);