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 1b275f1ee6d63f6398b2215181c5d2aa7f9702f4..70375e33a4465342dbd3a211b6a5274ee1d61221 100644 (file)
--- 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);