]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Doc updates for build_patches(). 563/head
authorWolfgang Bangerth <bangerth@math.tamu.edu>
Wed, 18 Feb 2015 00:11:35 +0000 (18:11 -0600)
committerWolfgang Bangerth <bangerth@math.tamu.edu>
Wed, 18 Feb 2015 00:11:35 +0000 (18:11 -0600)
include/deal.II/numerics/data_out.h
include/deal.II/numerics/data_out_dof_data.h
include/deal.II/numerics/data_out_faces.h
include/deal.II/numerics/data_out_rotation.h
include/deal.II/numerics/data_out_stack.h

index 1288722fc1fad0fff4925856e74c29693380d8fa..9c9b5e4d8d91b5abaab70612500bb41be99716f1 100644 (file)
@@ -62,9 +62,8 @@ namespace internal
  *
  * This class is an actual implementation of the functionality proposed by the
  * DataOut_DoFData class. It offers a function build_patches() that generates
- * the patches to be written in some graphics format from the data stored in
- * the base class. Most of the interface and an example of its use is
- * described in the documentation of the base class.
+ * the data to be written in some graphics format. Most of the interface and
+ * an example of its use is described in the documentation of this base class.
  *
  * The only thing this class offers is the function build_patches() which
  * loops over all cells of the triangulation stored by the
@@ -98,7 +97,7 @@ namespace internal
  * <h3>User interface information</h3>
  *
  * The base classes of this class, DataOutBase, DataOutInterface and
- * DataOut_DoFData() offer several interfaces of their own. Refer to the
+ * DataOut_DoFData offer several interfaces of their own. Refer to the
  * DataOutBase class's documentation for a discussion of the different output
  * formats presently supported, DataOutInterface for ways of selecting which
  * format to use upon output at run-time and without the need to adapt your
@@ -179,11 +178,45 @@ public:
 
   /**
    * This is the central function of this class since it builds the list of
-   * patches to be written by the low-level functions of the base class. See
-   * the general documentation of this class for further information.
+   * patches to be written by the low-level functions of the base class. A
+   * patch is, in essence, some intermediate representation of the data on
+   * each cell of a triangulation and DoFHandler object that can then be
+   * used to write files in some format that is readable by visualization
+   * programs.
    *
-   * The default value <tt>0</tt> of <tt>n_subdivisions</tt> indicates that
-   * the value stored in DataOutInterface::default_subdivisions is to be used.
+   * You can find an overview of the use of this function in
+   * the general documentation of this class. An example is also provided in
+   * the documentation of this class's base class DataOut_DoFData.
+   *
+   * @param n_subdivisions A parameter that determines how many "patches" this
+   *   function will build out of every cell. If you do not specify this
+   *   value in calling, or provide the default value zero, then this is
+   *   interpreted as DataOutInterface::default_subdivisions which most of
+   *   the time will be equal to one (unless you have set it to something else).
+   *   The purpose of this parameter is to subdivide each cell of the mesh
+   *   into $2\times 2, 3\times 3, \ldots$ "patches" in 2d, and
+   *   $2\times 2\times 2, 3\times 3\times 3, \ldots$ (if passed the value
+   *   2, 3, etc) where each patch represents the data from a regular subdivision
+   *   of the cell into equal parts. Most of the times, this is not necessary
+   *   and outputting one patch per cell is exactly what you want to plot
+   *   the solution. That said, the data we write into files for visualization
+   *   can only represent (bi-, tri)linear data on each cell, and most
+   *   visualization programs can in fact only visualize this kind of data.
+   *   That's good enough if you work with (bi-, tri)linear finite elements,
+   *   in which case what you get to see is exactly what has been computed.
+   *   On the other hand, if you work with (bi-, tri)quadratic elements, then
+   *   what is written into the output file is just a (bi-, tri)linear
+   *   interpolation onto the current mesh, i.e., only the values at the
+   *   vertices. If this is not good enough, you can, for example, specify
+   *   @p n_subdivisions equal to 2 to plot the solution on a once-refined
+   *   mesh, or if set to 3, on a mesh where each cell is represented by
+   *   3-by-3 patches. On each of these smaller patches, given the limitations
+   *   of output formats, the data is still linearly interpolated, but a
+   *   linear interpolation of quadratic data on a finer mesh is still a
+   *   better representation of the actual quadratic surface than on the
+   *   original mesh. In other words, using this parameter can not help
+   *   you plot the solution exactly, but it can get you closer if you
+   *   use finite elements of higher polynomial degree.
    */
   virtual void build_patches (const unsigned int n_subdivisions = 0);
 
index d7131cadde140f0100da9fcb40a4ca7a1086b4fe..a80702b8a511be2600ddf0ba7e52137906237762 100644 (file)
@@ -256,7 +256,7 @@ namespace internal
 /**
  * This is an abstract class which provides the functionality to generate
  * patches for output by base classes from data vectors on a grid. It allows
- * to store one or more pointers to a DoFHandler and attached node and cell
+ * to attach one or more pointers to a DoFHandler and attached node and cell
  * data denoting functions on the grid which shall later be written in any of
  * the implemented data formats.
  *
@@ -324,20 +324,22 @@ namespace internal
  * @ref step_22 "step-22"
  * tutorial program).
  *
- * It should be noted that this class does not copy the vector given to it
+ * This class does not copy the vector given to it
  * through the add_data_vector() functions, for memory consumption reasons. It
  * only stores a reference to it, so it is in your responsibility to make sure
  * that the data vectors exist long enough.
  *
  * After adding all data vectors, you need to call a function which generates
- * the patches for output from the stored data. Derived classes name this
+ * the patches (i.e., some intermediate data representation) for output from
+ * the stored data. Derived classes name this
  * function build_patches(). Finally, you write() the data in one format or
  * other, to a file.
  *
- * Please note that in the example above, an object of type DataOut was used,
- * i.e. an object of a derived class. This is necessary since this class does
+ * In the example above, an object of type DataOut was used,
+ * i.e. an object of a derived class. This is necessary since the current class does
  * not provide means to actually generate the patches, only aids to store and
- * access data.
+ * access data. Any real functionality is implemented in derived classes such
+ * as DataOut.
  *
  * Note that the base class of this class, DataOutInterface offers several
  * functions to ease programming with run-time determinable output formats
@@ -351,7 +353,7 @@ namespace internal
  *
  * <h3>Information for derived classes</h3>
  *
- * What is actually missing this class is a way to produce the patches for
+ * What this class lacks is a way to produce the patches for
  * output itself, from the stored data and degree of freedom information.
  * Since this task is often application dependent it is left to derived
  * classes. For example, in many applications, it might be wanted to limit the
index 16f5c88c8267554d0f4324d2a0410a91b3208d6e..06dde1d5a95da0232765bc50db61299a7eb3f48d 100644 (file)
@@ -142,11 +142,18 @@ public:
 
   /**
    * This is the central function of this class since it builds the list of
-   * patches to be written by the low-level functions of the base class. See
-   * the general documentation of this class for further information.
+   * patches to be written by the low-level functions of the base class. A
+   * patch is, in essence, some intermediate representation of the data on
+   * each face of a triangulation and DoFHandler object that can then be
+   * used to write files in some format that is readable by visualization
+   * programs.
    *
-   * The function supports multithreading, if deal.II is compiled in
-   * multithreading mode.
+   * You can find an overview of the use of this function in
+   * the general documentation of this class. An example is also provided in
+   * the documentation of this class's base class DataOut_DoFData.
+   *
+   * @param n_subdivisions See DataOut::build_patches() for an extensive
+   *   description of this parameter.
    */
   virtual void
   build_patches (const unsigned int n_subdivisions = 0);
index 8256eeb45e7cd0e4adc9da41a4bdb1de2b6a5d10..8f0f9c12bec12e9076cd6914efc12e249aad4ca1 100644 (file)
@@ -139,15 +139,21 @@ public:
 
   /**
    * This is the central function of this class since it builds the list of
-   * patches to be written by the low-level functions of the base class. See
-   * the general documentation of this class for further information.
+   * patches to be written by the low-level functions of the base class. A
+   * patch is, in essence, some intermediate representation of the data on
+   * each cell of a triangulation and DoFHandler object that can then be
+   * used to write files in some format that is readable by visualization
+   * programs.
    *
-   * In addition to the same parameters as found in the respective function of
-   * the DataOut class, the first parameter denotes into how many intervals
-   * the angular (rotation) variable is to be subdivided.
+   * You can find an overview of the use of this function in
+   * the general documentation of this class. An example is also provided in
+   * the documentation of this class's base class DataOut_DoFData.
    *
-   * The function supports multithreading, if deal.II is compiled in
-   * multithreading mode.
+   * @param n_patches_per_circle Denotes into how many intervals
+   *   the angular (rotation) variable is to be subdivided.
+   *
+   * @param n_subdivisions See DataOut::build_patches() for an extensive
+   *   description of this parameter.
    */
   virtual void build_patches (const unsigned int n_patches_per_circle,
                               const unsigned int n_subdivisions = 0);
index 57e32f40b3c595b50dee98a50e1680ac6e79782c..128c27a632d37e9b0848d70206eb5dff313954ba 100644 (file)
@@ -209,15 +209,23 @@ public:
                         const std::vector<std::string> &names);
 
   /**
-   * Actually build the patches for output by the base classes from the data
-   * stored in the data vectors and using the previously attached DoFHandler
-   * object.
+   * This is the central function of this class since it builds the list of
+   * patches to be written by the low-level functions of the base class. A
+   * patch is, in essence, some intermediate representation of the data on
+   * each cell of a triangulation and DoFHandler object that can then be
+   * used to write files in some format that is readable by visualization
+   * programs.
+   *
+   * You can find an overview of the use of this function in
+   * the general documentation of this class. An example is also provided in
+   * the documentation of this class's base class DataOut_DoFData.
+   *
+   * @param n_patches_per_circle Denotes into how many intervals
+   *   the angular (rotation) variable is to be subdivided.
    *
-   * By @p n_subdivisions you can decide into how many subdivisions (in each
-   * space and parameter direction) each patch is divided. This is useful if
-   * higher order elements are used. Note however, that the number of
-   * subdivisions in parameter direction is always the same as the one is
-   * space direction for technical reasons.
+   * @param n_subdivisions See DataOut::build_patches() for an extensive
+   *   description of this parameter. The number of subdivisions is always
+   *   one in the direction of the time-like parameter used by this class.
    */
   void build_patches (const unsigned int n_subdivisions = 0);
 

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.