From fade0f2704f21155c1922e93c1b22ac4fb7a6924 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Fri, 8 Sep 2000 22:17:57 +0000 Subject: [PATCH] Write some more docs. git-svn-id: https://svn.dealii.org/trunk@3315 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/deal.II/include/numerics/data_out.h | 51 ++++++++++++------- .../deal.II/include/numerics/data_out_faces.h | 44 +++++++++++++++- .../include/numerics/dof_print_solver_step.h | 22 +++++--- .../include/numerics/dof_renumbering.h | 28 +++++----- 4 files changed, 108 insertions(+), 37 deletions(-) diff --git a/deal.II/deal.II/include/numerics/data_out.h b/deal.II/deal.II/include/numerics/data_out.h index fef249b50a..b067e5754a 100644 --- a/deal.II/deal.II/include/numerics/data_out.h +++ b/deal.II/deal.II/include/numerics/data_out.h @@ -103,25 +103,29 @@ template class DoFHandler; * * @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 @@ -129,7 +133,20 @@ template class DoFHandler; * @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 */ diff --git a/deal.II/deal.II/include/numerics/data_out_faces.h b/deal.II/deal.II/include/numerics/data_out_faces.h index 16126c4588..72e4816c14 100644 --- a/deal.II/deal.II/include/numerics/data_out_faces.h +++ b/deal.II/deal.II/include/numerics/data_out_faces.h @@ -23,16 +23,56 @@ template class DoFHandler; /** + * 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 */ diff --git a/deal.II/deal.II/include/numerics/dof_print_solver_step.h b/deal.II/deal.II/include/numerics/dof_print_solver_step.h index 2797893b6b..85ee4acea3 100644 --- a/deal.II/deal.II/include/numerics/dof_print_solver_step.h +++ b/deal.II/deal.II/include/numerics/dof_print_solver_step.h @@ -23,13 +23,22 @@ /** - * 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 */ @@ -75,6 +84,7 @@ class DoFPrintSolverStep : public SOLVER }; +/* ----------------------- template functions --------------- */ template DoFPrintSolverStep::DoFPrintSolverStep (SolverControl& control, diff --git a/deal.II/deal.II/include/numerics/dof_renumbering.h b/deal.II/deal.II/include/numerics/dof_renumbering.h index c9810428ba..808c9027b3 100644 --- a/deal.II/deal.II/include/numerics/dof_renumbering.h +++ b/deal.II/deal.II/include/numerics/dof_renumbering.h @@ -154,6 +154,7 @@ * 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 @@ -169,6 +170,7 @@ * 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 @@ -191,10 +193,11 @@ class DoFRenumbering * different methods. */ template - static void Cuthill_McKee (DoFHandler &dof_handler, - const bool reversed_numbering = false, - const bool use_constraints = false, - const vector &starting_indices = vector()); + static void + Cuthill_McKee (DoFHandler &dof_handler, + const bool reversed_numbering = false, + const bool use_constraints = false, + const vector &starting_indices = vector()); /** * Renumber the degrees of freedom @@ -216,10 +219,11 @@ class DoFRenumbering * different methods. */ template - static void Cuthill_McKee (MGDoFHandler &dof_handler, - const unsigned int level, - const bool reversed_numbering = false, - const vector &starting_indices = vector ()); + static void + Cuthill_McKee (MGDoFHandler &dof_handler, + const unsigned int level, + const bool reversed_numbering = false, + const vector &starting_indices = vector ()); /** * Sort the degrees of freedom by @@ -368,11 +372,11 @@ class DoFRenumbering * 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); }; -- 2.39.5