From 487d0ef4b3c12c9ecc412ef76ab5c8ddca1146a9 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Tue, 2 May 2006 01:49:55 +0000 Subject: [PATCH] Add significant documentation. git-svn-id: https://svn.dealii.org/trunk@12950 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/deal.II/include/dofs/dof_levels.h | 275 ++++++++++++++++++++-- 1 file changed, 249 insertions(+), 26 deletions(-) diff --git a/deal.II/deal.II/include/dofs/dof_levels.h b/deal.II/deal.II/include/dofs/dof_levels.h index 2e1a3f1ca4..c4b720c5dc 100644 --- a/deal.II/deal.II/include/dofs/dof_levels.h +++ b/deal.II/deal.II/include/dofs/dof_levels.h @@ -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. * *

Information for all DoFLevel classes

* - * The DoFLevel 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 DoFLevel 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. + * + * + *

DoFLevel@<0@>

+ * + * 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. + * + * + *

DoFLevel@<1@>, DoFLevel@<2@>, and DoFLevel@<3@>

+ * + * 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 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 void set_line_dof_index (const ::DoFHandler &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 unsigned int get_line_dof_index (const ::DoFHandler &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 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 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 void set_quad_dof_index (const ::DoFHandler &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 unsigned int get_quad_dof_index (const ::DoFHandler &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 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 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 void set_hex_dof_index (const ::DoFHandler &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 unsigned int get_hex_dof_index (const ::DoFHandler &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 friend class ::DoFHandler; }; } -- 2.39.5