Degrees of Freedom

Collaboration diagram for Degrees of Freedom:

Modules
	Constraints on degrees of freedom

Namespaces
namespace	internal::DoFHandlerImplementation
namespace	DoFRenumbering
namespace	DoFTools

Classes
class	BlockInfo
	A small class collecting the different BlockIndices involved in global, multilevel and local computations. More...
struct	internal::DoFAccessorImplementation::Inheritance< structdim, dim, spacedim >
class	DoFAccessor< structdim, dim, spacedim, level_dof_access >
class	DoFCellAccessor< dimension_, space_dimension_, level_dof_access >
class	DoFHandler< dim, spacedim >
class	internal::DoFHandlerImplementation::DoFObjects< dim >
class	AffineConstraints< number >

Typedefs
template<int dim, int spacedim = dim>
using	hp::DoFHandler = ::DoFHandler< dim, spacedim >

Detailed Description

This module groups classes and namespaces that have to do with handling degrees of freedom. The central class of this group is the DoFHandler class: it is built on top of a triangulation and a finite element class and allocated degrees of freedom on each cell of the triangulation as required for the finite element space described by the finite element object. There are other variants of the DoFHandler class such as hp::DoFHandler that do similar things for more special cases.

DoFHandler objects are used together with objects of type FiniteElement (or hp::FECollection in the case of hp::DoFHandler) to enumerate all the degrees of freedom that exist in a triangulation for this particular finite element. As such, the combination of mesh, finite element, and DoF handler object can be thought of as providing a basis of the finite element space: the mesh provides the locations at which basis functions are defined; the finite element describes what kinds of basis functions exist; and the DoF handler object provides an enumeration of the basis, i.e., it is provides a concrete structure of the space so that we can describe functions in this finite dimensional space by vectors of coefficients.

DoFHandlers extend Triangulation objects (and the other classes in the Grids and Triangulations module) in that they, too, offer iterators that run over all cells, faces, or other geometric objects that make up a triangulation. These iterators are derived from the triangulation iterators and therefore offer the same functionality, but they also offer additional functions. For example, they allow to query the indices of the degrees of freedom associated with the present cell. Note that DoFHandler classes are not derived from Triangulation, though they use Triangulation objects; the reason is that there can be more than one DoFHandler object that works on the same Triangulation object.

In addition to the DoF handler classes, this module holds a number of auxiliary classes not commonly used in application programs, as well as three classes that are not directly associated with the data structures of the DoFHandler class. The first of these is the AffineConstraints class that stores and treats the constraints associated with hanging nodes. Secondly, the DoFRenumbering namespace offers functions that can reorder degrees of freedom; among its functions are ones that sort degrees of freedom in downstream direction, for example, and ones that sort degrees of freedom in such a way that the bandwidth of associated matrices is minimized. Finally, the DoFTools namespace offers a variety of algorithms around handling degrees of freedom.

In the grand scheme of things, the pieces of this module interact with a variety of other parts of the library:

Typedef Documentation

DoFHandler

template<int dim, int spacedim = dim>

using hp::DoFHandler = typedef ::DoFHandler<dim, spacedim>

Manage the distribution and numbering of the degrees of freedom for hp- FEM algorithms. This class satisfies the MeshType concept requirements.

The purpose of this class is to allow for an enumeration of degrees of freedom in the same way as the DoFHandler class, but it allows to use a different finite element on every cell. To this end, one assigns an active_fe_index to every cell that indicates which element within a collection of finite elements (represented by an object of type hp::FECollection) is the one that lives on this cell. The class then enumerates the degree of freedom associated with these finite elements on each cell of a triangulation and, if possible, identifies degrees of freedom at the interfaces of cells if they match. If neighboring cells have degrees of freedom along the common interface that do not immediate match (for example, if you have \(Q_2\) and \(Q_3\) elements meeting at a common face), then one needs to compute constraints to ensure that the resulting finite element space on the mesh remains conforming.

The whole process of working with objects of this type is explained in step-27. Many of the algorithms this class implements are described in the hp-paper.

Active FE indices and their behavior under mesh refinement

The typical workflow for using this class is to create a mesh, assign an active FE index to every active cell, calls hp::DoFHandler::distribute_dofs(), and then assemble a linear system and solve a problem on this finite element space. However, one can skip assigning active FE indices upon mesh refinement in certain circumstances. In particular, the following rules apply:

• Upon mesh refinement, child cells inherit the active FE index of the parent.
• When coarsening cells, the (now active) parent cell will be assigned an active FE index that is determined from its (no longer active) children, following the FiniteElementDomination logic: Out of the set of elements previously assigned to the former children, we choose the one dominated by all children for the parent cell. If none was found, we pick the most dominant element in the whole collection that is dominated by all former children. See hp::FECollection::find_dominated_fe_extended() for further information on this topic.

Note

Finite elements need to be assigned to each cell by either calling set_fe() or distribute_dofs() first to make this functionality available.

Active FE indices and parallel meshes

When this class is used with either a parallel::shared::Triangulation or a parallel::distributed::Triangulation, you can only set active FE indices on cells that are locally owned, using a call such as cell->set_active_fe_index(...). On the other hand, setting the active FE index on ghost or artificial cells is not allowed.

Ghost cells do acquire the information what element is active on them, however: whenever you call hp::DoFHandler::distribute_dofs(), all processors that participate in the parallel mesh exchange information in such a way that the active FE index on ghost cells equals the active FE index that was set on that processor that owned that particular ghost cell. Consequently, one can query the active_fe_index on ghost cells, just not set it by hand.

On artificial cells, no information is available about the active_fe_index used there. That's because we don't even know whether these cells exist at all, and even if they did, the current processor does not know anything specific about them. See the glossary entry on artificial cells for more information.

During refinement and coarsening, information about the active_fe_index of each cell will be automatically transferred.

However, using a parallel::distributed::Triangulation with an hp::DoFHandler requires additional attention during serialization, since no information on active FE indices will be automatically transferred. This has to be done manually using the prepare_for_serialization_of_active_fe_indices() and deserialize_active_fe_indices() functions. The former has to be called before parallel::distributed::Triangulation::save() is invoked, and the latter needs to be run after parallel::distributed::Triangulation::load(). If further data will be attached to the triangulation via the parallel::distributed::CellDataTransfer, parallel::distributed::SolutionTransfer, or Particles::ParticleHandler classes, all corresponding preparation and deserialization function calls need to happen in the same order. Consult the documentation of parallel::distributed::SolutionTransfer for more information.

Deprecated:

The basic DoFHandler is capable of hp-adaptation now.

Definition at line 124 of file dof_handler.h.