*
* 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
* <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
/**
* 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);
/**
* 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.
*
* @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
*
* <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
/**
* 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);
/**
* 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);
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);
projects / dealii.git / commitdiff