]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Update documentation of this file. 9/head
authorWolfgang Bangerth <bangerth@math.tamu.edu>
Mon, 21 Jul 2014 23:33:10 +0000 (18:33 -0500)
committerWolfgang Bangerth <bangerth@math.tamu.edu>
Tue, 22 Jul 2014 17:53:15 +0000 (12:53 -0500)
- Rename a documentation section to be more descriptive.
- Reshuffle some more functions and group them into appropriate categories. Not all functions are in categories yet, though, see http://www.dealii.org/developer/doxygen/deal.II/namespaceDoFTools.html

include/deal.II/dofs/dof_tools.h

index 72a3791bfef943bdc44c5c48f364f7bb11b4f1dd..5daf49d9de9b7c2b3478052c343972b6b86ec647 100644 (file)
@@ -219,7 +219,7 @@ namespace DoFTools
   };
 
   /**
-   * @name Auxiliary functions
+   * @name Functions to support code that generically uses both DoFHandler and hp::DoFHandler
    * @{
    */
   /**
@@ -346,7 +346,7 @@ namespace DoFTools
    */
 
   /**
-   * @name Sparsity Pattern Generation
+   * @name Sparsity pattern generation
    * @{
    */
 
@@ -649,9 +649,11 @@ namespace DoFTools
                               const Table<2,Coupling> &int_mask,
                               const Table<2,Coupling> &flux_mask);
 
-  //@}
   /**
-   * @name Hanging Nodes
+   * @}
+   */
+  /**
+   * @name Hanging nodes and other constraints
    * @{
    */
 
@@ -700,11 +702,142 @@ namespace DoFTools
   void
   make_hanging_node_constraints (const DH         &dof_handler,
                                  ConstraintMatrix &constraints);
+
+  /**
+   * This function can be used when different variables shall be
+   * discretized on different grids, where one grid is coarser than
+   * the other. This idea might seem nonsensical at first, but has
+   * reasonable applications in inverse (parameter estimation)
+   * problems, where there might not be enough information to recover
+   * the parameter on the same grid as the state variable;
+   * furthermore, the smoothness properties of state variable and
+   * parameter might not be too much related, so using different grids
+   * might be an alternative to using stronger regularization of the
+   * problem.
+   *
+   * The basic idea of this function is explained in the
+   * following. Let us, for convenience, denote by ``parameter grid''
+   * the coarser of the two grids, and by ``state grid'' the finer of
+   * the two. We furthermore assume that the finer grid can be
+   * obtained by refinement of the coarser one, i.e. the fine grid is
+   * at least as much refined as the coarse grid at each point of the
+   * domain. Then, each shape function on the coarse grid can be
+   * represented as a linear combination of shape functions on the
+   * fine grid (assuming identical ansatz spaces). Thus, if we
+   * discretize as usual, using shape functions on the fine grid, we
+   * can consider the restriction that the parameter variable shall in
+   * fact be discretized by shape functions on the coarse grid as a
+   * constraint. These constraints are linear and happen to have the
+   * form managed by the ``ConstraintMatrix'' class.
+   *
+   * The construction of these constraints is done as follows: for
+   * each of the degrees of freedom (i.e. shape functions) on the
+   * coarse grid, we compute its representation on the fine grid,
+   * i.e. how the linear combination of shape functions on the fine
+   * grid looks like that resembles the shape function on the coarse
+   * grid. From this information, we can then compute the constraints
+   * which have to hold if a solution of a linear equation on the fine
+   * grid shall be representable on the coarse grid. The exact
+   * algorithm how these constraints can be computed is rather
+   * complicated and is best understood by reading the source code,
+   * which contains many comments.
+   *
+   * Before explaining the use of this function, we would like to
+   * state that the total number of degrees of freedom used for the
+   * discretization is not reduced by the use of this function,
+   * i.e. even though we discretize one variable on a coarser grid,
+   * the total number of degrees of freedom is that of the fine
+   * grid. This seems to be counter-productive, since it does not give
+   * us a benefit from using a coarser grid. The reason why it may be
+   * useful to choose this approach nonetheless is three-fold: first,
+   * as stated above, there might not be enough information to recover
+   * a parameter on a fine grid, i.e. we chose to discretize it on the
+   * coarse grid not to save DoFs, but for other reasons. Second, the
+   * ``ConstraintMatrix'' includes the constraints into the linear
+   * system of equations, by which constrained nodes become dummy
+   * nodes; we may therefore exclude them from the linear algebra, for
+   * example by sorting them to the back of the DoF numbers and simply
+   * calling the solver for the upper left block of the matrix which
+   * works on the non-constrained nodes only, thus actually realizing
+   * the savings in numerical effort from the reduced number of actual
+   * degrees of freedom. The third reason is that for some or other
+   * reason we have chosen to use two different grids, it may be
+   * actually quite difficult to write a function that assembles the
+   * system matrix for finite element spaces on different grids; using
+   * the approach of constraints as with this function allows to use
+   * standard techniques when discretizing on only one grid (the finer
+   * one) without having to take care of the fact that one or several
+   * of the variable actually belong to different grids.
+   *
+   * The use of this function is as follows: it accepts as parameters
+   * two DoF Handlers, the first of which refers to the coarse grid
+   * and the second of which is the fine grid. On both, a finite
+   * element is represented by the DoF handler objects, which will
+   * usually have several components, which may belong to different
+   * finite elements. The second and fourth parameter of this function
+   * therefore state which variable on the coarse grid shall be used
+   * to restrict the stated component on the fine grid. Of course, the
+   * finite elements used for the respective components on the two
+   * grids need to be the same. An example may clarify this: consider
+   * the parameter estimation mentioned briefly above; there, on the
+   * fine grid the whole discretization is done, thus the variables
+   * are ``u'', ``q'', and the Lagrange multiplier ``lambda'', which
+   * are discretized using continuous linear, piecewise constant
+   * discontinuous, and continuous linear elements, respectively. Only
+   * the parameter ``q'' shall be represented on the coarse grid, thus
+   * the DoFHandler object on the coarse grid represents only one
+   * variable, discretized using piecewise constant discontinuous
+   * elements. Then, the parameter denoting the component on the
+   * coarse grid would be zero (the only possible choice, since the
+   * variable on the coarse grid is scalar), and one on the fine grid
+   * (corresponding to the variable ``q''; zero would be ``u'', two
+   * would be ``lambda''). Furthermore, an object of type IntergridMap
+   * is needed; this could in principle be generated by the function
+   * itself from the two DoFHandler objects, but since it is probably
+   * available anyway in programs that use this function, we shall use
+   * it instead of re-generating it. Finally, the computed constraints
+   * are entered into a variable of type ConstraintMatrix; the
+   * constraints are added, i.e. previous contents which may have, for
+   * example, be obtained from hanging nodes, are not deleted, so that
+   * you only need one object of this type.
+   */
+  template <int dim, int spacedim>
+  void
+  compute_intergrid_constraints (const DoFHandler<dim,spacedim>              &coarse_grid,
+                                 const unsigned int                  coarse_component,
+                                 const DoFHandler<dim,spacedim>              &fine_grid,
+                                 const unsigned int                  fine_component,
+                                 const InterGridMap<DoFHandler<dim,spacedim> > &coarse_to_fine_grid_map,
+                                 ConstraintMatrix                   &constraints);
+
+
+  /**
+   * This function generates a matrix such that when a vector of data
+   * with as many elements as there are degrees of freedom of this
+   * component on the coarse grid is multiplied to this matrix, we
+   * obtain a vector with as many elements as there are global
+   * degrees of freedom on the fine grid. All the elements of the
+   * other components of the finite element fields on the fine grid
+   * are not touched.
+   *
+   * The output of this function is a compressed format that can be
+   * given to the @p reinit functions of the SparsityPattern ad
+   * SparseMatrix classes.
+   */
+  template <int dim, int spacedim>
+  void
+  compute_intergrid_transfer_representation (const DoFHandler<dim,spacedim>              &coarse_grid,
+                                             const unsigned int                  coarse_component,
+                                             const DoFHandler<dim,spacedim>              &fine_grid,
+                                             const unsigned int                  fine_component,
+                                             const InterGridMap<DoFHandler<dim,spacedim> > &coarse_to_fine_grid_map,
+                                             std::vector<std::map<types::global_dof_index, float> > &transfer_representation);
+
   //@}
 
 
   /**
-   * @name Periodic Boundary Conditions
+   * @name Periodic boundary conditions
    * @{
    */
 
@@ -1074,6 +1207,14 @@ namespace DoFTools
                                  Vector<double>        &dof_data,
                                  const unsigned int     component = 0);
 
+  /**
+   * @}
+   */
+  /**
+   * @name Identifying subsets of degrees of freedom with particular properties
+   * @{
+   */
+  
   /**
    * Extract the indices of the degrees of freedom belonging to
    * certain vector components of a vector-valued finite element. The
@@ -1288,7 +1429,49 @@ namespace DoFTools
                                          const std::set<types::boundary_id> &boundary_indicators = std::set<types::boundary_id>());
 
   /**
-   * @name Hanging Nodes
+   * Extract a vector that represents the constant modes of the
+   * DoFHandler for the components chosen by <tt>component_mask</tt>
+   * (see @ref GlossComponentMask).  The constant modes on a
+   * discretization are the null space of a Laplace operator on the
+   * selected components with Neumann boundary conditions applied. The
+   * null space is a necessary ingredient for obtaining a good AMG
+   * preconditioner when using the class
+   * TrilinosWrappers::PreconditionAMG.  Since the ML AMG package only
+   * works on algebraic properties of the respective matrix, it has no
+   * chance to detect whether the matrix comes from a scalar or a
+   * vector valued problem. However, a near null space supplies
+   * exactly the needed information about the components placement of vector
+   * components within the matrix. The null space (or rather, the constant
+   * modes) is provided by the finite element underlying the given DoFHandler
+   * and for most elements, the null space will consist of as many vectors as
+   * there are true arguments in <tt>component_mask</tt> (see @ref
+   * GlossComponentMask), each of which will be one in one vector component
+   * and zero in all others. However, the representation of the constant
+   * function for e.g. FE_DGP is different (the first component on each
+   * element one, all other components zero), and some scalar elements may
+   * even have two constant modes (FE_Q_DG0). Therefore, we store this object
+   * in a vector of vectors, where the outer vector contains the collection of
+   * the actual constant modes on the DoFHandler. Each inner vector has as
+   * many components as there are (locally owned) degrees of freedom in the
+   * selected components. Note that any matrix associated with this null space
+   * must have been constructed using the same <tt>component_mask</tt>
+   * argument, since the numbering of DoFs is done relative to the selected
+   * dofs, not to all dofs.
+   *
+   * The main reason for this program is the use of the null space
+   * with the AMG preconditioner.
+   */
+  template <class DH>
+  void
+  extract_constant_modes (const DH                        &dof_handler,
+                          const ComponentMask             &component_mask,
+                          std::vector<std::vector<bool> > &constant_modes);
+  
+  /**
+   * @}
+   */
+  /**
+   * @name Hanging nodes
    * @{
    */
 
@@ -1495,7 +1678,7 @@ namespace DoFTools
                                           const types::subdomain_id subdomain);
   // @}
   /**
-   * @name Dof indices for patches
+   * @name DoF indices on patches of cells
    *
    * Create structures containing a large set of degrees of freedom
    * for small patches of cells. The resulting objects can be used in
@@ -1643,61 +1826,13 @@ namespace DoFTools
                          const unsigned int level,
                          const bool interior_dofs_only = false);
 
-  //@}
   /**
-   * Extract a vector that represents the constant modes of the
-   * DoFHandler for the components chosen by <tt>component_mask</tt>
-   * (see @ref GlossComponentMask).  The constant modes on a
-   * discretization are the null space of a Laplace operator on the
-   * selected components with Neumann boundary conditions applied. The
-   * null space is a necessary ingredient for obtaining a good AMG
-   * preconditioner when using the class
-   * TrilinosWrappers::PreconditionAMG.  Since the ML AMG package only
-   * works on algebraic properties of the respective matrix, it has no
-   * chance to detect whether the matrix comes from a scalar or a
-   * vector valued problem. However, a near null space supplies
-   * exactly the needed information about the components placement of vector
-   * components within the matrix. The null space (or rather, the constant
-   * modes) is provided by the finite element underlying the given DoFHandler
-   * and for most elements, the null space will consist of as many vectors as
-   * there are true arguments in <tt>component_mask</tt> (see @ref
-   * GlossComponentMask), each of which will be one in one vector component
-   * and zero in all others. However, the representation of the constant
-   * function for e.g. FE_DGP is different (the first component on each
-   * element one, all other components zero), and some scalar elements may
-   * even have two constant modes (FE_Q_DG0). Therefore, we store this object
-   * in a vector of vectors, where the outer vector contains the collection of
-   * the actual constant modes on the DoFHandler. Each inner vector has as
-   * many components as there are (locally owned) degrees of freedom in the
-   * selected components. Note that any matrix associated with this null space
-   * must have been constructed using the same <tt>component_mask</tt>
-   * argument, since the numbering of DoFs is done relative to the selected
-   * dofs, not to all dofs.
-   *
-   * The main reason for this program is the use of the null space
-   * with the AMG preconditioner.
+   * @}
    */
-  template <class DH>
-  void
-  extract_constant_modes (const DH                        &dof_handler,
-                          const ComponentMask             &component_mask,
-                          std::vector<std::vector<bool> > &constant_modes);
-
   /**
-   * For each active cell of a DoFHandler or hp::DoFHandler, extract
-   * the active finite element index and fill the vector given as
-   * second argument. This vector is assumed to have as many entries
-   * as there are active cells.
-   *
-   * For non-hp DoFHandler objects given as first argument, the
-   * returned vector will consist of only zeros, indicating that all
-   * cells use the same finite element. For a hp::DoFHandler, the
-   * values may be different, though.
+   * @name Counting degrees of freedom and related functions
+   * @{
    */
-  template <class DH>
-  void
-  get_active_fe_indices (const DH                  &dof_handler,
-                         std::vector<unsigned int> &active_fe_indices);
 
   /**
    * Count how many degrees of freedom out of the total number belong
@@ -1779,136 +1914,27 @@ namespace DoFTools
                             std::vector<types::global_dof_index> &dofs_per_component,
                             std::vector<unsigned int>  target_component) DEAL_II_DEPRECATED;
 
+  
   /**
-   * This function can be used when different variables shall be
-   * discretized on different grids, where one grid is coarser than
-   * the other. This idea might seem nonsensical at first, but has
-   * reasonable applications in inverse (parameter estimation)
-   * problems, where there might not be enough information to recover
-   * the parameter on the same grid as the state variable;
-   * furthermore, the smoothness properties of state variable and
-   * parameter might not be too much related, so using different grids
-   * might be an alternative to using stronger regularization of the
-   * problem.
-   *
-   * The basic idea of this function is explained in the
-   * following. Let us, for convenience, denote by ``parameter grid''
-   * the coarser of the two grids, and by ``state grid'' the finer of
-   * the two. We furthermore assume that the finer grid can be
-   * obtained by refinement of the coarser one, i.e. the fine grid is
-   * at least as much refined as the coarse grid at each point of the
-   * domain. Then, each shape function on the coarse grid can be
-   * represented as a linear combination of shape functions on the
-   * fine grid (assuming identical ansatz spaces). Thus, if we
-   * discretize as usual, using shape functions on the fine grid, we
-   * can consider the restriction that the parameter variable shall in
-   * fact be discretized by shape functions on the coarse grid as a
-   * constraint. These constraints are linear and happen to have the
-   * form managed by the ``ConstraintMatrix'' class.
-   *
-   * The construction of these constraints is done as follows: for
-   * each of the degrees of freedom (i.e. shape functions) on the
-   * coarse grid, we compute its representation on the fine grid,
-   * i.e. how the linear combination of shape functions on the fine
-   * grid looks like that resembles the shape function on the coarse
-   * grid. From this information, we can then compute the constraints
-   * which have to hold if a solution of a linear equation on the fine
-   * grid shall be representable on the coarse grid. The exact
-   * algorithm how these constraints can be computed is rather
-   * complicated and is best understood by reading the source code,
-   * which contains many comments.
-   *
-   * Before explaining the use of this function, we would like to
-   * state that the total number of degrees of freedom used for the
-   * discretization is not reduced by the use of this function,
-   * i.e. even though we discretize one variable on a coarser grid,
-   * the total number of degrees of freedom is that of the fine
-   * grid. This seems to be counter-productive, since it does not give
-   * us a benefit from using a coarser grid. The reason why it may be
-   * useful to choose this approach nonetheless is three-fold: first,
-   * as stated above, there might not be enough information to recover
-   * a parameter on a fine grid, i.e. we chose to discretize it on the
-   * coarse grid not to save DoFs, but for other reasons. Second, the
-   * ``ConstraintMatrix'' includes the constraints into the linear
-   * system of equations, by which constrained nodes become dummy
-   * nodes; we may therefore exclude them from the linear algebra, for
-   * example by sorting them to the back of the DoF numbers and simply
-   * calling the solver for the upper left block of the matrix which
-   * works on the non-constrained nodes only, thus actually realizing
-   * the savings in numerical effort from the reduced number of actual
-   * degrees of freedom. The third reason is that for some or other
-   * reason we have chosen to use two different grids, it may be
-   * actually quite difficult to write a function that assembles the
-   * system matrix for finite element spaces on different grids; using
-   * the approach of constraints as with this function allows to use
-   * standard techniques when discretizing on only one grid (the finer
-   * one) without having to take care of the fact that one or several
-   * of the variable actually belong to different grids.
+   * For each active cell of a DoFHandler or hp::DoFHandler, extract
+   * the active finite element index and fill the vector given as
+   * second argument. This vector is assumed to have as many entries
+   * as there are active cells.
    *
-   * The use of this function is as follows: it accepts as parameters
-   * two DoF Handlers, the first of which refers to the coarse grid
-   * and the second of which is the fine grid. On both, a finite
-   * element is represented by the DoF handler objects, which will
-   * usually have several components, which may belong to different
-   * finite elements. The second and fourth parameter of this function
-   * therefore state which variable on the coarse grid shall be used
-   * to restrict the stated component on the fine grid. Of course, the
-   * finite elements used for the respective components on the two
-   * grids need to be the same. An example may clarify this: consider
-   * the parameter estimation mentioned briefly above; there, on the
-   * fine grid the whole discretization is done, thus the variables
-   * are ``u'', ``q'', and the Lagrange multiplier ``lambda'', which
-   * are discretized using continuous linear, piecewise constant
-   * discontinuous, and continuous linear elements, respectively. Only
-   * the parameter ``q'' shall be represented on the coarse grid, thus
-   * the DoFHandler object on the coarse grid represents only one
-   * variable, discretized using piecewise constant discontinuous
-   * elements. Then, the parameter denoting the component on the
-   * coarse grid would be zero (the only possible choice, since the
-   * variable on the coarse grid is scalar), and one on the fine grid
-   * (corresponding to the variable ``q''; zero would be ``u'', two
-   * would be ``lambda''). Furthermore, an object of type IntergridMap
-   * is needed; this could in principle be generated by the function
-   * itself from the two DoFHandler objects, but since it is probably
-   * available anyway in programs that use this function, we shall use
-   * it instead of re-generating it. Finally, the computed constraints
-   * are entered into a variable of type ConstraintMatrix; the
-   * constraints are added, i.e. previous contents which may have, for
-   * example, be obtained from hanging nodes, are not deleted, so that
-   * you only need one object of this type.
+   * For non-hp DoFHandler objects given as first argument, the
+   * returned vector will consist of only zeros, indicating that all
+   * cells use the same finite element. For a hp::DoFHandler, the
+   * values may be different, though.
    */
-  template <int dim, int spacedim>
+  template <class DH>
   void
-  compute_intergrid_constraints (const DoFHandler<dim,spacedim>              &coarse_grid,
-                                 const unsigned int                  coarse_component,
-                                 const DoFHandler<dim,spacedim>              &fine_grid,
-                                 const unsigned int                  fine_component,
-                                 const InterGridMap<DoFHandler<dim,spacedim> > &coarse_to_fine_grid_map,
-                                 ConstraintMatrix                   &constraints);
-
+  get_active_fe_indices (const DH                  &dof_handler,
+                         std::vector<unsigned int> &active_fe_indices);
 
   /**
-   * This function generates a matrix such that when a vector of data
-   * with as many elements as there are degrees of freedom of this
-   * component on the coarse grid is multiplied to this matrix, we
-   * obtain a vector with as many elements as there are global
-   * degrees of freedom on the fine grid. All the elements of the
-   * other components of the finite element fields on the fine grid
-   * are not touched.
-   *
-   * The output of this function is a compressed format that can be
-   * given to the @p reinit functions of the SparsityPattern ad
-   * SparseMatrix classes.
+   * @}
    */
-  template <int dim, int spacedim>
-  void
-  compute_intergrid_transfer_representation (const DoFHandler<dim,spacedim>              &coarse_grid,
-                                             const unsigned int                  coarse_component,
-                                             const DoFHandler<dim,spacedim>              &fine_grid,
-                                             const unsigned int                  fine_component,
-                                             const InterGridMap<DoFHandler<dim,spacedim> > &coarse_to_fine_grid_map,
-                                             std::vector<std::map<types::global_dof_index, float> > &transfer_representation);
-
+  
   /**
    * Create a mapping from degree of freedom indices to the index of
    * that degree of freedom on the boundary. After this operation,

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.