]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Clarify documentation of (hp::)?DoFHandler::distribute_dofs(). 5743/head
authorWolfgang Bangerth <bangerth@colostate.edu>
Tue, 16 Jan 2018 03:49:08 +0000 (20:49 -0700)
committerWolfgang Bangerth <bangerth@colostate.edu>
Wed, 17 Jan 2018 14:38:12 +0000 (07:38 -0700)
include/deal.II/dofs/dof_handler.h
include/deal.II/hp/dof_handler.h

index dc3357d030b01e0928ce6054b076aaa9c4d98cab..41010865bd7e5110dd6e8f566ec54bc3eddbef72 100644 (file)
@@ -370,20 +370,42 @@ public:
                   const FiniteElement<dim,spacedim> &fe);
 
   /**
-   * Go through the triangulation and "distribute" the degrees of freedoms
-   * needed for the given finite element. "Distributing" degrees of freedom
-   * involves allocating memory to store the information that describes it
-   * (e.g., whether it is located on a vertex, edge, face, etc) and to
-   * sequentially enumerate all degrees of freedom. In other words, while the
-   * mesh and the finite element object by themselves simply define a finite
-   * element space $V_h$, the process of distributing degrees of freedom makes
-   * sure that there is a basis for this space and that the shape functions of
-   * this basis are enumerated in an indexable, predictable way.
+   * Go through the triangulation and "distribute" the degrees of
+   * freedoms needed for the given finite element. "Distributing"
+   * degrees of freedom involves allocating memory to store the
+   * indices on all entities on which degrees of freedom can be
+   * located (e.g., vertices, edges, faces, etc.) and to then enumerate
+   * all degrees of freedom. In other words, while the mesh and the
+   * finite element object by themselves simply define a finite
+   * element space $V_h$, the process of distributing degrees of
+   * freedom makes sure that there is a basis for this space and that
+   * the shape functions of this basis are enumerated in an indexable,
+   * predictable way.
    *
-   * The purpose of this function is first discussed in the introduction to
-   * the step-2 tutorial program.
+   * The exact order in which degrees of freedom on a mesh are
+   * ordered, i.e., the order in which basis functions of the finite
+   * element space are enumerated, is something that deal.II treats as
+   * an implementation detail. By and large, degrees of freedom are
+   * enumerated in the same order in which we traverse cells, but you
+   * should not rely on any specific numbering. In contrast, if you
+   * want a particular ordering, use the functions in namespace
+   * DoFRenumbering.
    *
-   * @note A copy of the finite element given as argument is stored.
+   * This function is first discussed in the introduction to the
+   * step-2 tutorial program.
+   *
+   * @note This function makes a copy of the finite element given as
+   * argument, and stores it as a member variable. Consequently, it is
+   * possible to write code such as
+   * @code
+   *   dof_handler.distribute_dofs (FE_Q<dim>(2));
+   * @endcode
+   * You can then access the finite element later on by calling
+   * DoFHandler::get_fe().  However, it is often more convenient to
+   * keep a named finite element object as a member variable in your
+   * main class and refer to it directly whenever you need to access
+   * properties of the finite element (such as FiniteElement::dofs_per_cell).
+   * This is what all tutorial programs do.
    */
   virtual void distribute_dofs (const FiniteElement<dim,spacedim> &fe);
 
index 28aaea76a7ce0e4376bb54897a869500ba4654a1..a54afc278eca894441d63e9d80d51648c077ec03 100644 (file)
@@ -280,25 +280,36 @@ namespace hp
     DoFHandler &operator = (const DoFHandler &) = delete;
 
     /**
-     * Go through the triangulation and "distribute" the degrees of freedoms
-     * needed for the given finite element. "Distributing" degrees of freedom
-     * involves allocating memory to store the information that describes it
-     * (e.g., whether it is located on a vertex, edge, face, etc) and to
-     * sequentially enumerate all degrees of freedom. In other words, while
-     * the mesh and the finite element object by themselves simply define a
-     * finite element space $V_h$, the process of distributing degrees of
-     * freedom makes sure that there is a basis for this space and that the
-     * shape functions of this basis are enumerated in an indexable,
+     * Go through the triangulation and "distribute" the degrees of
+     * freedoms needed for the given finite element. "Distributing"
+     * degrees of freedom involves allocating memory to store the
+     * indices on all entities on which degrees of freedom can be
+     * located (e.g., vertices, edges, faces, etc.) and to then enumerate
+     * all degrees of freedom. In other words, while the mesh and the
+     * finite element object by themselves simply define a finite
+     * element space $V_h$, the process of distributing degrees of
+     * freedom makes sure that there is a basis for this space and that
+     * the shape functions of this basis are enumerated in an indexable,
      * predictable way.
      *
-     * The purpose of this function is first discussed in the introduction to
-     * the step-2 tutorial program.
+     * The exact order in which degrees of freedom on a mesh are
+     * ordered, i.e., the order in which basis functions of the finite
+     * element space are enumerated, is something that deal.II treats as
+     * an implementation detail. By and large, degrees of freedom are
+     * enumerated in the same order in which we traverse cells, but you
+     * should not rely on any specific numbering. In contrast, if you
+     * want a particular ordering, use the functions in namespace
+     * DoFRenumbering.
      *
-     * @note A pointer of the finite element given as argument is stored.
-     * Therefore, the lifetime of the finite element object shall be longer
-     * than that of this object. If you don't want this behavior, you may want
-     * to call the @p clear member function which also releases the lock of
-     * this object to the finite element.
+     * @note In contrast to the dealii::DoFHandler::distribute_dofs()
+     * function, this function does not make a copy of the object
+     * given as argument. Rather, it stores a reference to the given
+     * object, and it is the responsibility of user code to ensure
+     * that the hp::FECollection given as argument lives at least as
+     * long as the hp::DoFHandler object. If you want to break this
+     * dependence by asking the hp::DoFHandler to release the
+     * reference to the hp::FECollection object, call the
+     * hp::DoFHandler::clear() function.
      */
     virtual void distribute_dofs (const hp::FECollection<dim,spacedim> &fe);
 

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.