A general (interface) class for DOF handling, see Lecture Document Paragraph 2.7.4.13. More...

#include <lf/assemble/dofhandler.h>

Inheritance diagram for lf::assemble::DofHandler:

Public Member Functions
virtual	~DofHandler ()=default
	virtual Destructor

virtual size_type	NumDofs () const =0
	total number of dof's handled by the object

virtual size_type	NumLocalDofs (const lf::mesh::Entity &entity) const =0
	tells the number of degrees of freedom subordinate/_belonging_ to to an entity

virtual size_type	NumInteriorDofs (const lf::mesh::Entity &entity) const =0
	provides number of shape functions associated with an entity

virtual std::span< const gdof_idx_t >	GlobalDofIndices (const lf::mesh::Entity &entity) const =0
	access to indices of global dof's belonging to an entity

virtual std::span< const gdof_idx_t >	InteriorGlobalDofIndices (const lf::mesh::Entity &entity) const =0
	global indices of shape functions associated with an entity_

virtual const lf::mesh::Entity &	Entity (gdof_idx_t dofnum) const =0
	retrieve unique entity at which a basis function is located

virtual std::shared_ptr< const lf::mesh::Mesh >	Mesh () const =0
	Acess to underlying mesh object.

Protected Member Functions
	DofHandler ()=default
	Default constructor, can only be called from derived class.

Protected constructors
Copying and assignment do not make sense for DofHandler objects, but derived classes may be copied/assigned
	DofHandler (const DofHandler &)=default

	DofHandler (DofHandler &&)=default

DofHandler &	operator= (const DofHandler &)=default

DofHandler &	operator= (DofHandler &&)=default

Related Symbols
(Note that these are not member symbols.)
void	PrintInfo (std::ostream &stream, const DofHandler &dof_handler, unsigned int ctrl=0)
	Output information about the given dof handler to the given stream object.

Detailed Description

A general (interface) class for DOF handling, see Lecture Document Paragraph 2.7.4.13.

Objects of this class provide the local-to-global map for indices of local/global shape functions.

Some terminology

The terms "degrees of freedom", "global basis functions", and "global shape functions" are synomymous.
Every global and local shape function is associated with a unique geometric entity.
The global/local shape functions associated with a mesh entity are called its interior shape functions/degrees of freedom.
The shape functions/degrees of freedom belonging to a mesh entity or subordinate to a mesh entity are those whose supports cover that entity. Hence all interior d.o.f. must also belong to an entity.

Rules for ordering global shape functions <-> degrees of freedom (dof)

Note that every global shape (dof) function belongs to a unique mesh entity. Ordering them means assigning a unique (vector component) index starting from zero until NumDofs-1.

Dofs belonging to entities of a larger co-dimension are arranged before dofs associated with entities of a smaller co-dimension:

This means First dofs on nodes, then dofs on edges, then dofs on cells
Dofs owned by the same mesh entity are numbered contiguously.
if two entities have the same co-dimension, then the dofs of that with the lower index are numbered before the dofs of that with the higher index: dof numbering is compatible with indexing

Rules for numbering local shape functions (local dof)

As above, Dofs belonging to sub-entities of a larger (relative) co-dimension are arranged before dofs associated with sub-entities of a smaller co-dimension.
As above, dofs belonging to the same sub-entity are numbered contiguously.
dofs for sub-entities of the same co-dimension are taken into account in the order given by the local indexing of the sub-entities.

Local-to-global dof index mapping for entities of higher co-dimension

The method getGlobalDofs() is available for entities of any co-dimension. For instance, this allows assembly of contributions from low-dimensional manifolds like boundaries or interfaces.

Note: When an entity carries several interior degrees of freedom, then the consistency of local and global numberings becomes an issue if the orientation of the edge is used to fix the global shape functions. This is happens in the case of Lagrangian finite element spaces for polynomial degree \(\geq 3\). In two dimensions this is an issue for edges only and can be resolved by taking into account the orientation (direction) of the edge: dofs are ordered along the edge and those "closer to endpoint 0" are numbered first. In 3D many more situations have to be dealt with.

The local numbering conventions are also defined in Lecture Document Paragraph 2.7.4.11 and illustrated in Lecture Document Example 2.7.4.12.

Demonstration code

(Lecture Document Code 2.7.4.15)

void printDofInfo(const lf::assemble::DofHandler &dofh) {
  // Obtain pointer to the underlying mesh
  const lf::mesh::Mesh &mesh{*dofh.Mesh()};
  // Number of degrees of freedom managed by the DofHandler object
  const lf::assemble::size_type N_dofs(dofh.NumDofs());
  // Output information about dofs for entities of all co-dimensions
  for (lf::base::dim_t codim = 0; codim <= mesh.DimMesh(); codim++) {
    // Visit all entities of a codimension codim
    for (const lf::mesh::Entity *e : mesh.Entities(codim)) {
      // Fetch unique index of current entity supplied by mesh object
      const lf::base::glb_idx_t e_idx = mesh.Index(*e);
      // Number of shape functions covering current entity
      const lf::assemble::size_type no_dofs(dofh.NumLocalDofs(*e));
      // Obtain global indices of those shape functions ...
      std::span<const lf::assemble::gdof_idx_t> dofarray{
          dofh.GlobalDofIndices(*e)};
      // and print them
      std::cout << *e << ' ' << e_idx << ": " << no_dofs << " dofs = [";
      for (int loc_dof_idx = 0; loc_dof_idx < no_dofs; ++loc_dof_idx) {
        std::cout << dofarray[loc_dof_idx] << ' ';
      }
      std::cout << ']';
      // Also output indices of interior shape functions
      std::span<const lf::assemble::gdof_idx_t> intdofarray{
          dofh.InteriorGlobalDofIndices(*e)};
      std::cout << " int = [";
      for (lf::assemble::gdof_idx_t int_dof : intdofarray) {
        std::cout << int_dof << ' ';
      }
      std::cout << ']' << std::endl;
    }
  }
  // List entities associated with the dofs managed by the current
  // DofHandler object
  for (lf::assemble::gdof_idx_t dof_idx = 0; dof_idx < N_dofs; dof_idx++) {
    const lf::mesh::Entity &e(dofh.Entity(dof_idx));
    std::cout << "dof " << dof_idx << " -> " << e << " " << mesh.Index(e)
              << std::endl;
  }
}  // end function printDofInfo

Conventions for numbering global shape functions

Though not important for most finite element computations, the current implementations of the local-to-global d.o.f. mapping interface comply with the following rules:

The shape functions associated to entities of higher co-dimension have smaller indices than those blonding to entities of lower co-dimension. This means that for 2D meshes d.o.f. for nodes are numbered first, then those for edges, finally those for cells.
Within entities of the same co-dimension the numbering follows their indexing through the member function lf::mesh::Mesh::Index().

Also refer to Lecture Document Remark 2.7.4.17.

Definition at line 112 of file dofhandler.h.

Constructor & Destructor Documentation

◆ DofHandler() [1/3]

lf::assemble::DofHandler::DofHandler ( )

protecteddefault

Default constructor, can only be called from derived class.

◆ DofHandler() [2/3]

lf::assemble::DofHandler::DofHandler ( const DofHandler & )

protecteddefault

◆ DofHandler() [3/3]

lf::assemble::DofHandler::DofHandler ( DofHandler && )

protecteddefault

◆ ~DofHandler()

virtual lf::assemble::DofHandler::~DofHandler ( )

virtualdefault

virtual Destructor

Member Function Documentation

◆ Entity()

virtual const lf::mesh::Entity & lf::assemble::DofHandler::Entity ( gdof_idx_t dofnum ) const

pure virtual

retrieve unique entity at which a basis function is located

Parameters

dofnum global index of the basis function/degree of freedom

This function returns the unique geometric entity to which a particular basis function = degree of freedom is associated.

This function is hardly ever needed in finite element codes and is supplied for debugging purposes.

See also: GlobalDofIndices()

Implemented in lf::assemble::UniformFEDofHandler, and lf::assemble::DynamicFEDofHandler.

◆ GlobalDofIndices()

virtual std::span< const gdof_idx_t > lf::assemble::DofHandler::GlobalDofIndices ( const lf::mesh::Entity & entity ) const

pure virtual

access to indices of global dof's belonging to an entity

Parameters

entity reference to the entity for which the dof's are to be fetched. This entity must belong to the underlying mesh.

Returns: cardinal number range of global dof indices, see std::span data type documentation.

The basis functions of every finite element space must be associated with a unique geometric entity. Conversely, every entity can possess a finite number of basis functions = degrees of freedom. This member function returns the global indices of all basis functions associated with the entity and its sub-entitites (the covering local shape functions).

The size of the returned range must agree with the value returned by NumLocalDofs() when supplied with the same arguments.

Consult Lecture Document Paragraph 2.7.4.13 for more information.

Implemented in lf::assemble::UniformFEDofHandler, and lf::assemble::DynamicFEDofHandler.

Referenced by lf::assemble::AssembleMatrixLocally(), and lf::fe::InitEssentialConditionFromFunction().

◆ InteriorGlobalDofIndices()

virtual std::span< const gdof_idx_t > lf::assemble::DofHandler::InteriorGlobalDofIndices ( const lf::mesh::Entity & entity ) const

pure virtual

global indices of shape functions associated with an entity_

Parameters

entity entity for which shape functin indices are queried

Returns: cardinal number range of global indices of shape functions, see std::span data type documentation.

Each global shape function is associated with a unique mesh entity. This method provides all the global indices of the shape function associated to the entity specified by the function arguments, see Lecture Document Paragraph 2.7.4.13 for additional explanations.

Note: Be aware of the difference of GlobalDofIndices() and InteriorGlobalDofIndices()

Implemented in lf::assemble::UniformFEDofHandler, and lf::assemble::DynamicFEDofHandler.

◆ Mesh()

virtual std::shared_ptr< const lf::mesh::Mesh > lf::assemble::DofHandler::Mesh ( ) const

pure virtual

Acess to underlying mesh object.

Every DofHandler object has to be associated with a unique mesh. All entities passed to the DofHandler object must belong to that mesh.

Implemented in lf::assemble::UniformFEDofHandler, and lf::assemble::DynamicFEDofHandler.

Referenced by lf::assemble::AssembleMatrixLocally().

◆ NumDofs()

virtual size_type lf::assemble::DofHandler::NumDofs ( ) const

pure virtual

total number of dof's handled by the object

Implemented in lf::assemble::UniformFEDofHandler, and lf::assemble::DynamicFEDofHandler.

Referenced by lf::assemble::AssembleMatrixLocally(), lf::fe::InitEssentialConditionFromFunction(), lf::uscalfe::PrintInfo(), and lf::fe::prolongate().

◆ NumInteriorDofs()

virtual size_type lf::assemble::DofHandler::NumInteriorDofs ( const lf::mesh::Entity & entity ) const

pure virtual

provides number of shape functions associated with an entity

Parameters

entity entity of underlying mesh whose number of shape functions is queried

The return value of this method must be equal to the length of the range built by InteriorGlobalDofIndices().

See also: InteriorGlobalDofIndices()

Implemented in lf::assemble::UniformFEDofHandler, and lf::assemble::DynamicFEDofHandler.

◆ NumLocalDofs()

virtual size_type lf::assemble::DofHandler::NumLocalDofs ( const lf::mesh::Entity & entity ) const

pure virtual

tells the number of degrees of freedom subordinate/_belonging_ to to an entity

Parameters

entity reference to an entity of the underlying mesh

This method informs about the length of the vector returned by GlobalDofIndices().

See also: GlobalDofIndices()

Implemented in lf::assemble::UniformFEDofHandler, and lf::assemble::DynamicFEDofHandler.

Referenced by lf::assemble::AssembleMatrixLocally(), and lf::fe::InitEssentialConditionFromFunction().

◆ operator=() [1/2]

DofHandler & lf::assemble::DofHandler::operator= ( const DofHandler & )

protecteddefault

◆ operator=() [2/2]

DofHandler & lf::assemble::DofHandler::operator= ( DofHandler && )

protecteddefault

Friends And Related Symbol Documentation

◆ PrintInfo()

void PrintInfo	(	std::ostream &	stream,
		const DofHandler &	dof_handler,
		unsigned int	ctrl = 0 )

Parameters

stream	The stream to which we should print
dof_handler	The dof handler that should be printed
ctrl	controls the level of detail of the printed output (see below)

The following output levels are supported

if = 0: minimal out: just prints global no of dofs
if > 0 and divisible by 2: print dofs associated with all entities
if > 0 and divisible by 3: print entities belonging to dofs
if > 0 and divisible by 10: also print interior dof indices

The documentation for this class was generated from the following file:

/__w/lehrfempp/lehrfempp/lib/lf/assemble/dofhandler.h

Public Member Functions

Protected Member Functions

Related Symbols

Detailed Description

Some terminology

Rules for ordering global shape functions <-> degrees of freedom (dof)

Rules for numbering local shape functions (local dof)

Local-to-global dof index mapping for entities of higher co-dimension

Demonstration code

Conventions for numbering global shape functions

Constructor & Destructor Documentation

◆ DofHandler() [1/3]

◆ DofHandler() [2/3]

◆ DofHandler() [3/3]

◆ ~DofHandler()

Member Function Documentation

◆ Entity()

◆ GlobalDofIndices()

◆ InteriorGlobalDofIndices()

◆ Mesh()

◆ NumDofs()

◆ NumInteriorDofs()

◆ NumLocalDofs()

◆ operator=() [1/2]

◆ operator=() [2/2]

Friends And Related Symbol Documentation

◆ PrintInfo()