*
* @sect3{Information for derived classes}
*
- * What is actually missing this class is a way to produce the patched 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 depth of output to a certain number of refinement levels and write
- * data from finer cells only in a way interpolated to coarser cells, to
- * reduce the amount of output. Also, it might be wanted to use different
- * numbers of subdivisions on different cells when forming a patch, for example
- * to accomplish for different polynomial degrees of the trial space on
- * different cells.
+ * What is actually missing this class 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 depth of output to a certain number of
+ * refinement levels and write data from finer cells only in a way
+ * interpolated to coarser cells, to reduce the amount of
+ * output. Also, it might be wanted to use different numbers of
+ * subdivisions on different cells when forming a patch, for example
+ * to accomplish for different polynomial degrees of the trial space
+ * on different cells. Also, the output need not necessarily consist
+ * of a patch for each cell, but might be made up of patches for
+ * faces, of other things. Take a look at derived classes to what is
+ * possible in this respect.
*
- * For this reason, it is left to a derived class to provide a function, named
- * usually @p{build_patches} or the like, which fills the @p{patches} array of
- * this class.
+ * For this reason, it is left to a derived class to provide a
+ * function, named usually @p{build_patches} or the like, which fills
+ * the @p{patches} array of this class.
*
- * Regarding the templates of this class, it needs two values: first
+ * Regarding the templates of this class, it needs three values: first
* the space dimension in which the triangulation and the DoF handler
- * operate, second the space dimension of the output to be
- * generated. Although in most cases they are equal, there are also
+ * operate, second the dimension of the objects which the patches
+ * represent. Although in most cases they are equal, there are also
* classes for which this does not hold, for example if one outputs
* the result of a computation exploiting rotational symmetry in the
* original domain (in which the space dimension of the output would
* @ref{DataOut_Rotation} class), or one might conceive that one could
* write a class that only outputs the solution on a cut through the
* domain, in which case the space dimension of the output is less
- * than that of the DoF handler.
+ * than that of the DoF handler. The last template argument denotes
+ * the dimension of the space into which the patches are embedded;
+ * usually, this dimension is the same as the dimensio of the patches
+ * themselves (which is also the default value of the template
+ * parameter), but there might be cases where this is not so. For
+ * example, in the @ref{DataOut_Faces} class, patches are generated
+ * from faces of the triangulation. Thus, the dimension of the patch
+ * is one less than the dimension of the embedding space, which is, in
+ * this case, equal to the dimension of the triangulation and DoF
+ * handler. However, for the cut through the domain mentioned above,
+ * if the cut is a straight one, then the cut can be embedded into a
+ * space of one dimension lower than the dimension of the
+ * triangulation, so that the last template parameter has the same
+ * value as the second one.
*
* @author Wolfgang Bangerth, 1999
*/
/**
+ * This class generates output from faces of a triangulation rather
+ * than from cells, as do for example the @ref{DataOut} and
+ * @ref{DataOut_Rotation} classes. It might be used to generate output
+ * only for the surface of the triangulation (this is the default of
+ * this class), or for another arbitrary set of faces. The output of
+ * this class is a set of patches (as defined by the class
+ * @ref{DataOutBase::Patch}), one for each face for which output is to
+ * be generated. These patches can then be written in several
+ * graphical data formats by the functions of the underlying classes.
*
* @sect3{Interface}
*
* The interface of this class is copied from the @ref{DataOut}
* class. Furthermore, they share the common parent class
* @ref{DataOut_DoFData}. See the reference of these two classes for a
- * discussion of the interface and how to extend it by deriving
- * further classes from this class.
+ * discussion of the interface.
*
*
+ * @sect3{Extending this class}
+ *
+ * The sequence of faces to generate patches from is generated in the
+ * same way as in the @ref{DataOut} class, see there for a description
+ * of the respective interface. For obvious reasons, the functions
+ * generating the sequence of faces which shall be used to generate
+ * output, are called @p{first_face} and @p{next_face} in this class,
+ * rather than @p{first_cell} and @p{next_cell}.
+ *
+ * Since we need to initialize objects of type @ref{FEValues} with the
+ * faces generated from these functions, it is not sufficient that
+ * they only return face iterators. Rather, we need a pair of cell and
+ * the number of the face, as the values of finite element fields need
+ * not necessarily be unique on a face (think of discontinuous finite
+ * elements, where the value of the finite element field depend on the
+ * direction from which you approach a face, thus it is necessary to
+ * use a pair of cell and face, rather than only a face
+ * iterator). Therefore, this class defines a @p{typedef} which
+ * creates a type @p{FaceDescriptor} that is an abbreviation for a
+ * pair of cell iterator and face number. The functions @p{first_face}
+ * and @p{next_face} operate on objects of this type.
+ *
+ * Extending this class might, for example, be useful if you only want
+ * output from certain portions of the boundary, e.g. as indicated by
+ * the boundary indicator of the respective faces. However, it is also
+ * conceivable that one generates patches not from boundary faces, but
+ * from interior faces that are selected due to other criteria; one
+ * application might be to use only those faces where one component of
+ * the solution attains a certain value, in order to display the
+ * values of other solution components on these faces. Other
+ * applications certainly exist, for which the author is not
+ * imaginative enough.
*
* @author Wolfgang Bangerth, 2000
*/
/**
- * Print intermediate solutions in solvers.
- * This is derived from a solver class provided as template argument.
- * It implements the @p{print_vector} function of the solver using a
- * @ref{DoFHandler}. This way, the intermediate vectors can be viewed as
- * finite element functions.
+ * Print intermediate solutions in solvers. This is derived from a
+ * solver class provided as template argument. It implements the
+ * @p{print_vector} function of the solver using a
+ * @ref{DoFHandler}. This way, the intermediate vectors can be viewed
+ * as finite element functions. This class might be used first to
+ * understand how solvers work (for example to visualize the smoothing
+ * properties of various solvers, e.g. in a multigrid context), and
+ * second to investigate why and how a solver fails to solve certain
+ * classes of problems.
*
- * This class may produce enormous amounts of data!
+ * Objects of this class are provided with a solver class through a
+ * template argument, and with a file name (as a string), with which a
+ * new file is constructed in each iteration (named
+ * @p{basename.[step].[suffix]}) and into which the solution is
+ * written as a finite element field using the @ref{DataOut} class.
+ * Please note that this class may produce enormous amounts of data!
*
* @author Guido Kanschat, 2000
*/
};
+/* ----------------------- template functions --------------- */
template<int dim, class SOLVER, class VECTOR>
DoFPrintSolverStep<dim, SOLVER, VECTOR>::DoFPrintSolverStep (SolverControl& control,
* algorithm and afterwards renumbering component-wise. This will bring out the
* matrix structure and additionally have a good numbering within each block.
*
+ *
* @sect2{Cell-wise numbering for Discontinuous Galerkin FEM}
*
* One advantage of DGFEM is the fact, that it yields invertible
* accomplishes this. Inside the cells, the previous ordering will be
* preserved, so it may be useful to apply @component_wise} first.
*
+ *
* @sect2{Multigrid DoF numbering}
*
* Most algorithms also work on multigrid degree of freedom numberings. Refer
* different methods.
*/
template <int dim>
- static void Cuthill_McKee (DoFHandler<dim> &dof_handler,
- const bool reversed_numbering = false,
- const bool use_constraints = false,
- const vector<unsigned int> &starting_indices = vector<unsigned int>());
+ static void
+ Cuthill_McKee (DoFHandler<dim> &dof_handler,
+ const bool reversed_numbering = false,
+ const bool use_constraints = false,
+ const vector<unsigned int> &starting_indices = vector<unsigned int>());
/**
* Renumber the degrees of freedom
* different methods.
*/
template <int dim>
- static void Cuthill_McKee (MGDoFHandler<dim> &dof_handler,
- const unsigned int level,
- const bool reversed_numbering = false,
- const vector<unsigned int> &starting_indices = vector<unsigned int> ());
+ static void
+ Cuthill_McKee (MGDoFHandler<dim> &dof_handler,
+ const unsigned int level,
+ const bool reversed_numbering = false,
+ const vector<unsigned int> &starting_indices = vector<unsigned int> ());
/**
* Sort the degrees of freedom by
* Exception
*/
DeclException0 (ExcInvalidComponentOrder);
-
/**
- * The function is only
- * implemented for Discontinuous
- * Galerkin Finite elements.
+ * Exception. The function is
+ * only implemented for
+ * Discontinuous Galerkin Finite
+ * elements.
*/
DeclException0 (ExcNotDGFEM);
};
projects / dealii-svn.git / commitdiff