]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Add significant documentation.
authorWolfgang Bangerth <bangerth@math.tamu.edu>
Tue, 2 May 2006 01:49:55 +0000 (01:49 +0000)
committerWolfgang Bangerth <bangerth@math.tamu.edu>
Tue, 2 May 2006 01:49:55 +0000 (01:49 +0000)
git-svn-id: https://svn.dealii.org/trunk@12950 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/deal.II/include/dofs/dof_levels.h

index 2e1a3f1ca42d20e53bccb48a143fd4fd49df69bb..c4b720c5dcabee10caffd523356e33801e616a8d 100644 (file)
@@ -32,19 +32,20 @@ namespace internal
     
 /**
  * Store the indices of the degrees of freedom which are located on
- * objects of dimension @p N.  Declare this general template
+ * objects of dimension @p N. We declare this general template
  * class, but do not actually use it. Rather, only specializations of
  * this class are used.
  *
  * <h3>Information for all DoFLevel classes</h3>
  *
- * The <tt>DoFLevel<N></tt> classes 
- * store the global indices of the degrees of freedom for each cell on a
- * certain level. The index or number of a degree of freedom is the zero-based
- * index of the according value in the solution vector and the row and column
- * index in the global matrix or the multigrid matrix for this level. These
- * indices refer to the unconstrained vectors and matrices, where we have not
- * taken account of the constraints introduced by hanging nodes.
+ * The <tt>DoFLevel<N></tt> classes store the global indices of the
+ * degrees of freedom for each cell on a certain level. The global
+ * index or number of a degree of freedom is the zero-based index of
+ * the according value in the solution vector and the row and column
+ * index in the global matrix or the multigrid matrix for this
+ * level. These indices refer to the unconstrained vectors and
+ * matrices, where we have not taken account of the constraints
+ * introduced by hanging nodes.
  *
  * The storage format of the degrees of freedom indices (short: DoF
  * indices) is somewhat like a mirror of the data structures of the
@@ -62,15 +63,62 @@ namespace internal
  * memory since we actually only use the memory so allocated for
  * active lines, whereas the index entries for line i remain unused if
  * this line has children. On the other hand, it is easy to see that
- * at least for dim>1 does not constitute a too big fraction of memory
- * entries, and we opt for higher memory consumption in return for
- * less index computations that usually slow down modern processors
- * due to more complex memory access patterns.
+ * at least for dim>1 this does not constitute a too big fraction of
+ * memory entries, and we opt for higher memory consumption in return
+ * for less index computations that usually slow down modern
+ * processors due to more complex memory access patterns.
  *
  * Since vertices are not associated with a particular level, the
  * indices associated with vertices are not stored in the DoFLevel
  * classes but rather in the DoFHandler::vertex_dofs array.
  *
+ * In the following, we describe the individual classes of the
+ * DoFLevel hierachy. Note that in 1d, the hierarchy consists of
+ * DoFLevel<1> (storing line dofs) which is derived from DoFLevel<0>
+ * (storing things that are related to cells, whatever that may be in
+ * a given space dimension); in 2d, the class hierarchy consists of
+ * DoFLevel<2> which is derived from DoFLevel<1>, thus extending the
+ * previous data by quad dofs; a similar hierarchy of course also
+ * exists for higher dimensions.
+ *
+ *
+ * <h4>DoFLevel@<0@></h4>
+ *
+ * This class is the common base class for all the DoFLevel
+ * classes. We here store information that is associated with
+ * (logical) cells, rather than concrete objects such as lines, quads,
+ * or hexes.
+ *
+ * At present, all we store are cached values for the DoF indices on
+ * each cell, since this is a frequently requested operation. The
+ * values are set by DoFCellAccessor::update_cell_dof_indices_cache
+ * and are used by DoFCellAccessor::get_dof_indices. Note that for
+ * objects that are not cell, such as lines in 2d and 3d, or quads in
+ * 3d, no caching is done since accessing the degrees of freedom on
+ * these objects is a comparatively rare operation.
+ *
+ * Note that vertices are separate from, and in fact have nothing to
+ * do with cells. The indices of degrees of freedom located on
+ * vertices therefore are not stored here, but rather in member
+ * variables of the ::DoFHandler class.
+ *
+ *
+ * <h4>DoFLevel@<1@>, DoFLevel@<2@>, and DoFLevel@<3@> </h4>
+ *
+ * These classes are used, respectively, to store the indices located
+ * on lines, quads, and hexes. The storage format is as laid out
+ * above, and data is stored in arrays line_dofs, quad_dofs, and
+ * hex_dofs. However, it isn't usually directly accessed. Rather,
+ * except for some access from the DoFHandler class, access is usually
+ * through the DoFAccessor::set_dof_index() and
+ * DoFAccessor::dof_index() functions or similar functions of derived
+ * classes that in turn access the member variables using the
+ * DoFLevel<1>::get_line_dof_index(), corresponding setter functions,
+ * and similar functions in the DoFLevel<2> and DoFLevel<3>
+ * classes. Knowledge of the actual data format is therefore
+ * encapsulated to the present hierarchy of classes as well as the
+ * ::DoFHandler class.
+ * 
  * @ingroup dofs
  * @author Wolfgang Bangerth, 1998
  */
@@ -89,17 +137,9 @@ namespace internal
 
 
 /**
- * Common base class for all the DoFLevel classes. We here store
- * information that is associated with (logical) cells, rather than
- * concrete objects such as lines, quads, or hexes.
- *
- * At present, all we store are cached values for the DoF indices on
- * each cell, since this is a frequently requested operation. The
- * values are set by DoFCellAccessor::update_cell_dof_indices_cache
- * and are used by DoFCellAccessor::get_dof_indices. Note that for
- * objects that are not cell, such as lines in 2d and 3d, or quads in
- * 3d, no caching is done since accessing the degrees of freedom on
- * these objects is a comparatively rare operation.
+ * Storage for degrees of freedom on cells. See the documentation of
+ * the DoFLevel class template for more complete information on the
+ * purpose and layout of this class.
  */
     template <>
     class DoFLevel<0>
@@ -134,7 +174,7 @@ namespace internal
     template <>
     class DoFLevel<1> : public DoFLevel<0>
     {
-      public:
+      private:
                                          /**
                                           * Store the global indices of
                                           * the degrees of freedom. See
@@ -143,6 +183,34 @@ namespace internal
                                           */
         std::vector<unsigned int> line_dofs;
 
+      public:
+                                         /**
+                                          * Set the global index of
+                                          * the @p local_index-th
+                                          * degree of freedom located
+                                          * on the line with number @p
+                                          * line_index to the value
+                                          * given by the last
+                                          * argument. The @p
+                                          * dof_handler argument is
+                                          * used to access the finite
+                                          * element that is to be used
+                                          * to compute the location
+                                          * where this data is stored.
+                                          *
+                                          * The third argument, @p
+                                          * fe_index, must equal
+                                          * zero. It is otherwise
+                                          * unused, but we retain the
+                                          * argument so that we can
+                                          * use the same interface for
+                                          * non-hp and hp finite
+                                          * element methods, in effect
+                                          * making it possible to
+                                          * share the DoFAccessor
+                                          * class hierarchy between hp
+                                          * and non-hp classes.
+                                          */
         template <int dim>
         void
         set_line_dof_index (const ::DoFHandler<dim> &dof_handler,
@@ -151,6 +219,31 @@ namespace internal
                             const unsigned int       local_index,
                             const unsigned int       global_index);
 
+                                         /**
+                                          * Return the global index of
+                                          * the @p local_index-th
+                                          * degree of freedom located
+                                          * on the line with number @p
+                                          * line_index. The @p
+                                          * dof_handler argument is
+                                          * used to access the finite
+                                          * element that is to be used
+                                          * to compute the location
+                                          * where this data is stored.
+                                          *
+                                          * The third argument, @p
+                                          * fe_index, must equal
+                                          * zero. It is otherwise
+                                          * unused, but we retain the
+                                          * argument so that we can
+                                          * use the same interface for
+                                          * non-hp and hp finite
+                                          * element methods, in effect
+                                          * making it possible to
+                                          * share the DoFAccessor
+                                          * class hierarchy between hp
+                                          * and non-hp classes.
+                                          */
         template <int dim>
         unsigned int
         get_line_dof_index (const ::DoFHandler<dim> &dof_handler,
@@ -164,6 +257,14 @@ namespace internal
                                           * of this object.
                                           */
         unsigned int memory_consumption () const;
+
+                                         /**
+                                          * Make the DoFHandler class
+                                          * a friend, so that it can
+                                          * resize arrays as
+                                          * necessary.
+                                          */
+        template <int> friend class ::DoFHandler;
     };
 
 
@@ -178,7 +279,7 @@ namespace internal
     template <>
     class DoFLevel<2> : public DoFLevel<1>
     {
-      public:
+      private:
                                          /**
                                           * Store the global indices of
                                           * the degrees of freedom. See
@@ -187,6 +288,34 @@ namespace internal
                                           */
         std::vector<unsigned int> quad_dofs;
 
+      public:
+                                         /**
+                                          * Set the global index of
+                                          * the @p local_index-th
+                                          * degree of freedom located
+                                          * on the quad with number @p
+                                          * quad_index to the value
+                                          * given by the last
+                                          * argument. The @p
+                                          * dof_handler argument is
+                                          * used to access the finite
+                                          * element that is to be used
+                                          * to compute the location
+                                          * where this data is stored.
+                                          *
+                                          * The third argument, @p
+                                          * fe_index, must equal
+                                          * zero. It is otherwise
+                                          * unused, but we retain the
+                                          * argument so that we can
+                                          * use the same interface for
+                                          * non-hp and hp finite
+                                          * element methods, in effect
+                                          * making it possible to
+                                          * share the DoFAccessor
+                                          * class hierarchy between hp
+                                          * and non-hp classes.
+                                          */
         template <int dim>
         void
         set_quad_dof_index (const ::DoFHandler<dim> &dof_handler,
@@ -195,6 +324,31 @@ namespace internal
                             const unsigned int       local_index,
                             const unsigned int       global_index);
 
+                                         /**
+                                          * Return the global index of
+                                          * the @p local_index-th
+                                          * degree of freedom located
+                                          * on the quad with number @p
+                                          * quad_index. The @p
+                                          * dof_handler argument is
+                                          * used to access the finite
+                                          * element that is to be used
+                                          * to compute the location
+                                          * where this data is stored.
+                                          *
+                                          * The third argument, @p
+                                          * fe_index, must equal
+                                          * zero. It is otherwise
+                                          * unused, but we retain the
+                                          * argument so that we can
+                                          * use the same interface for
+                                          * non-hp and hp finite
+                                          * element methods, in effect
+                                          * making it possible to
+                                          * share the DoFAccessor
+                                          * class hierarchy between hp
+                                          * and non-hp classes.
+                                          */
         template <int dim>
         unsigned int
         get_quad_dof_index (const ::DoFHandler<dim> &dof_handler,
@@ -208,6 +362,14 @@ namespace internal
                                           * of this object.
                                           */
         unsigned int memory_consumption () const;
+
+                                         /**
+                                          * Make the DoFHandler class
+                                          * a friend, so that it can
+                                          * resize arrays as
+                                          * necessary.
+                                          */
+        template <int> friend class ::DoFHandler;
     };
 
 
@@ -222,7 +384,7 @@ namespace internal
     template <>
     class DoFLevel<3> : public DoFLevel<2>
     {
-      public:
+      private:
                                          /**
                                           * Store the global indices of
                                           * the degrees of freedom. See
@@ -231,6 +393,34 @@ namespace internal
                                           */
         std::vector<unsigned int> hex_dofs;
 
+      public:
+                                         /**
+                                          * Set the global index of
+                                          * the @p local_index-th
+                                          * degree of freedom located
+                                          * on the hex with number @p
+                                          * hex_index to the value
+                                          * given by the last
+                                          * argument. The @p
+                                          * dof_handler argument is
+                                          * used to access the finite
+                                          * element that is to be used
+                                          * to compute the location
+                                          * where this data is stored.
+                                          *
+                                          * The third argument, @p
+                                          * fe_index, must equal
+                                          * zero. It is otherwise
+                                          * unused, but we retain the
+                                          * argument so that we can
+                                          * use the same interface for
+                                          * non-hp and hp finite
+                                          * element methods, in effect
+                                          * making it possible to
+                                          * share the DoFAccessor
+                                          * class hierarchy between hp
+                                          * and non-hp classes.
+                                          */
         template <int dim>
         void
         set_hex_dof_index (const ::DoFHandler<dim> &dof_handler,
@@ -239,6 +429,31 @@ namespace internal
                            const unsigned int       local_index,
                            const unsigned int       global_index);
 
+                                         /**
+                                          * Return the global index of
+                                          * the @p local_index-th
+                                          * degree of freedom located
+                                          * on the hex with number @p
+                                          * hex_index. The @p
+                                          * dof_handler argument is
+                                          * used to access the finite
+                                          * element that is to be used
+                                          * to compute the location
+                                          * where this data is stored.
+                                          *
+                                          * The third argument, @p
+                                          * fe_index, must equal
+                                          * zero. It is otherwise
+                                          * unused, but we retain the
+                                          * argument so that we can
+                                          * use the same interface for
+                                          * non-hp and hp finite
+                                          * element methods, in effect
+                                          * making it possible to
+                                          * share the DoFAccessor
+                                          * class hierarchy between hp
+                                          * and non-hp classes.
+                                          */
         template <int dim>
         unsigned int
         get_hex_dof_index (const ::DoFHandler<dim> &dof_handler,
@@ -252,6 +467,14 @@ namespace internal
                                           * of this object.
                                           */
         unsigned int memory_consumption () const;
+
+                                         /**
+                                          * Make the DoFHandler class
+                                          * a friend, so that it can
+                                          * resize arrays as
+                                          * necessary.
+                                          */
+        template <int> friend class ::DoFHandler;
     };
     
   }

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.