From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Wed, 30 Mar 2022 20:02:34 +0000 (-0600)
Subject: Minor updates to DataOutFilter.
X-Git-Tag: v9.4.0-rc1~332^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F13583%2Fhead;p=dealii.git

Minor updates to DataOutFilter.
---

diff --git a/include/deal.II/base/data_out_base.h b/include/deal.II/base/data_out_base.h
index c517955581..fc3ef8f44e 100644
--- a/include/deal.II/base/data_out_base.h
+++ b/include/deal.II/base/data_out_base.h
@@ -1283,14 +1283,15 @@ namespace DataOutBase
   };
 
   /**
-   * Flags controlling the DataOutFilter.
+   * Flags controlling the behavior of the DataOutFilter class.
    *
    * @ingroup output
    */
   struct DataOutFilterFlags
   {
     /**
-     * Filter duplicate vertices and associated values. This will drastically
+     * Whether or not to filter out duplicate vertices and associated values.
+     * Setting this value to `true` will drastically
      * 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. In particular, along subdomain boundaries
@@ -1338,23 +1339,33 @@ namespace DataOutBase
   /**
    * DataOutFilter provides a way to remove redundant vertices and values
    * generated by the deal.II output. By default, DataOutBase and the classes
-   * that build on it output data at each corner of each cell. This means that
-   * data is output multiple times for each vertex of the mesh. The purpose of
+   * that build on it output data at each vertex of each cell. This means that
+   * data is output multiple times for each vertex of the mesh, once for each
+   * cell adjacent to the vertex. The purpose of
    * this scheme is to support output of discontinuous quantities, either
    * because the finite element space is discontinuous or because the quantity
    * that is output is computed from a solution field and is discontinuous
-   * across faces.
+   * across faces (for example for quantities computed via DataPostprocessor;
+   * typical cases where output quantities are discontinuous are when a
+   * postprocessor computes a quantity using the *gradient* of the solution,
+   * which is generally discontinuous even if the element itself is
+   * continuous). Other cases where the output is discontinuous are if the
+   * data to be output is not a finite element field but, for example,
+   * results from a class such as MatrixOut.
    *
    * This class is an attempt to rein in the amount of data that is written.
    * If the fields that are written to files are indeed discontinuous, the
    * only way to faithfully represent them is indeed to write multiple values
-   * for each vertex (this is typically done by writing multiple node
-   * locations for the same vertex and defining data at these nodes). However,
+   * for each vertex (this is typically done by creating multiple logical nodes
+   * in the output file, all of which have the same physical location; data is
+   * then associated to nodes, allowing to have multiple values associated
+   * with the same location). However,
    * for fine meshes, one may not necessarily be interested in an exact
    * representation of output fields that will likely only have small
    * discontinuities. Rather, it may be sufficient to just output one value
    * per vertex, which may be chosen arbitrarily from among those that are
-   * defined at this vertex from any of the adjacent cells.
+   * defined at this vertex, i.e., chosen arbitrarily from any of the
+   * adjacent cells.
    */
   class DataOutFilter
   {
@@ -1365,7 +1376,7 @@ namespace DataOutBase
     DataOutFilter();
 
     /**
-     * Destructor with a given set of flags. See DataOutFilterFlags for
+     * Constructor with a given set of flags. See DataOutFilterFlags for
      * possible flags.
      */
     DataOutFilter(const DataOutBase::DataOutFilterFlags &flags);