From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Fri, 20 Oct 2017 16:29:47 +0000 (-0600)
Subject: Update some discussion in DataOutFilter.
X-Git-Tag: v9.0.0-rc1~899^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=817fcd8098d3733f69a256bb5923d6a3ff9a37c1;p=dealii.git

Update some discussion in DataOutFilter.

In particular, warn about the dangers of using this class.
---

diff --git a/include/deal.II/base/data_out_base.h b/include/deal.II/base/data_out_base.h
index baf0570577..125846ddbe 100644
--- a/include/deal.II/base/data_out_base.h
+++ b/include/deal.II/base/data_out_base.h
@@ -1208,13 +1208,13 @@ namespace DataOutBase
    *
    * @ingroup output
    */
-
   struct DataOutFilterFlags
   {
     /**
      * Filter duplicate vertices and associated values. This will drastically
-     * reduce the output data size but may affect the correctness of some
-     * calculated values.
+     * reduce the output data size but will result in an output file that
+     * does not faithfully represent the actual data if the data corresponds
+     * to discontinuous fields.
      */
     bool filter_duplicate_vertices;
 
@@ -1440,7 +1440,6 @@ namespace DataOutBase
      * Empty functions to do base class inheritance.
      */
     void flush_cells () {};
-
   };
 
 
diff --git a/source/base/data_out_base.cc b/source/base/data_out_base.cc
index e2005c9bf2..14ff205c9f 100644
--- a/source/base/data_out_base.cc
+++ b/source/base/data_out_base.cc
@@ -1778,7 +1778,25 @@ namespace DataOutBase
   {
     prm.declare_entry ("Filter duplicate vertices", "false",
                        Patterns::Bool(),
-                       "Whether to remove duplicate vertex values.");
+                       "Whether to remove duplicate vertex values. deal.II duplicates "
+                       "vertices once for each adjacent cell so that it can output "
+                       "discontinuous quantities for which there may be more than one "
+                       "value for each vertex position. Setting this flag to "
+                       "'true' will merge all of these values by selecting a "
+                       "random one and outputting this as 'the' value for the vertex. "
+                       "As long as the data to be output corresponds to continuous "
+                       "fields, merging vertices has no effect. On the other hand, "
+                       "if the data to be output corresponds to discontinuous fields "
+                       "(either because you are using a discontinuous finite element, "
+                       "or because you are using a DataPostprocessor that yields "
+                       "discontinuous data, or because the data to be output has been "
+                       "produced by entirely different means), then the data in the "
+                       "output file no longer faithfully represents the underlying data "
+                       "because the discontinuous field has been replaced by a "
+                       "continuous one."
+                       "\n\n"
+                       "In any case, filtering results in drastically smaller output "
+                       "files (smaller by about a factor of 2^dim).");
     prm.declare_entry ("XDMF HDF5 output", "false",
                        Patterns::Bool(),
                        "Whether the data will be used in an XDMF/HDF5 combination.");