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 baf0570577f9eaf0f3da8a5947aa33b076a0dfa8..125846ddbe8a07c4db7ee2e4bbfd25db90eef983 100644 (file)
--- 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 e2005c9bf2bda05b08a59104bb64fcfd867715ad..14ff205c9f31c3f2091c4dadecb2b9124d18c7c7 100644 (file)
--- 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.");