]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
Write some more docs.
authorwolf <wolf@0785d39b-7218-0410-832d-ea1e28bc413d>
Fri, 8 Sep 2000 22:17:57 +0000 (22:17 +0000)
committerwolf <wolf@0785d39b-7218-0410-832d-ea1e28bc413d>
Fri, 8 Sep 2000 22:17:57 +0000 (22:17 +0000)
git-svn-id: https://svn.dealii.org/trunk@3315 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/deal.II/include/numerics/data_out.h
deal.II/deal.II/include/numerics/data_out_faces.h
deal.II/deal.II/include/numerics/dof_print_solver_step.h
deal.II/deal.II/include/numerics/dof_renumbering.h

index fef249b50a3ac551e63182a7f5f28b9af5c57359..b067e5754a581bf43481d066553ed9d01a3f5d35 100644 (file)
@@ -103,25 +103,29 @@ template <int dim> 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 <int dim> 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
  */
index 16126c45887794be5a06fff2252a92bc3d6972ae..72e4816c1407ff8bfd7688a8dafb98fddbc46395 100644 (file)
@@ -23,16 +23,56 @@ template <int dim> 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
  */
index 2797893b6b3ad075367f15be3117ee33d3cd3938..85ee4acea348418745a606fec3f51723b723ecf0 100644 (file)
 
 
 /**
- * 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<int dim, class SOLVER, class VECTOR>
 DoFPrintSolverStep<dim, SOLVER, VECTOR>::DoFPrintSolverStep (SolverControl& control,
index c9810428ba76f61c32f68dbfe44f6cc14b446e2e..808c9027b387f116d0a4d8c0c1e83a3749348e75 100644 (file)
  * 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
@@ -191,10 +193,11 @@ class DoFRenumbering
                                      * 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
@@ -216,10 +219,11 @@ class DoFRenumbering
                                      * 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
@@ -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);
 };

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.