From: Wolfgang Bangerth Date: Wed, 18 Feb 2015 00:11:35 +0000 (-0600) Subject: Doc updates for build_patches(). X-Git-Tag: v8.3.0-rc1~450^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F563%2Fhead;p=dealii.git Doc updates for build_patches(). --- diff --git a/include/deal.II/numerics/data_out.h b/include/deal.II/numerics/data_out.h index 1288722fc1..9c9b5e4d8d 100644 --- a/include/deal.II/numerics/data_out.h +++ b/include/deal.II/numerics/data_out.h @@ -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 *

User interface information

* * 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 0 of n_subdivisions 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); diff --git a/include/deal.II/numerics/data_out_dof_data.h b/include/deal.II/numerics/data_out_dof_data.h index d7131cadde..a80702b8a5 100644 --- a/include/deal.II/numerics/data_out_dof_data.h +++ b/include/deal.II/numerics/data_out_dof_data.h @@ -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 * *

Information for derived classes

* - * 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 diff --git a/include/deal.II/numerics/data_out_faces.h b/include/deal.II/numerics/data_out_faces.h index 16f5c88c82..06dde1d5a9 100644 --- a/include/deal.II/numerics/data_out_faces.h +++ b/include/deal.II/numerics/data_out_faces.h @@ -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); diff --git a/include/deal.II/numerics/data_out_rotation.h b/include/deal.II/numerics/data_out_rotation.h index 8256eeb45e..8f0f9c12be 100644 --- a/include/deal.II/numerics/data_out_rotation.h +++ b/include/deal.II/numerics/data_out_rotation.h @@ -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); diff --git a/include/deal.II/numerics/data_out_stack.h b/include/deal.II/numerics/data_out_stack.h index 57e32f40b3..128c27a632 100644 --- a/include/deal.II/numerics/data_out_stack.h +++ b/include/deal.II/numerics/data_out_stack.h @@ -209,15 +209,23 @@ public: const std::vector &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);