Reference documentation for deal.II version Git d3aed38b93 2021-10-28 13:33:27 +0200
\(\newcommand{\dealvcentcolon}{\mathrel{\mathop{:}}}\) \(\newcommand{\dealcoloneq}{\dealvcentcolon\mathrel{\mkern-1.2mu}=}\) \(\newcommand{\jump}[1]{\left[\!\left[ #1 \right]\!\right]}\) \(\newcommand{\average}[1]{\left\{\!\left\{ #1 \right\}\!\right\}}\)
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes | Friends | List of all members
DoFAccessor< structdim, dim, spacedim, level_dof_access > Class Template Reference

#include <deal.II/dofs/dof_accessor.h>

Inheritance diagram for DoFAccessor< structdim, dim, spacedim, level_dof_access >:
[legend]

Public Types

using BaseClass = typename ::internal::DoFAccessorImplementation::Inheritance< structdim, dimension, space_dimension >::BaseClass
 
using AccessorData = DoFHandler< dimension, space_dimension >
 

Public Member Functions

const DoFHandler< dim, spacedim > & get_dof_handler () const
 
template<bool level_dof_access2>
void copy_from (const DoFAccessor< structdim, dim, spacedim, level_dof_access2 > &a)
 
void copy_from (const TriaAccessorBase< structdim, dim, spacedim > &da)
 
template<int structdim2, int dim2, int spacedim2, bool level_dof_access2>
bool operator== (const DoFAccessor< structdim2, dim2, spacedim2, level_dof_access2 > &) const
 
template<int structdim2, int dim2, int spacedim2, bool level_dof_access2>
bool operator!= (const DoFAccessor< structdim2, dim2, spacedim2, level_dof_access2 > &) const
 
Constructors
 DoFAccessor ()
 
 DoFAccessor (const Triangulation< dim, spacedim > *tria, const int level, const int index, const DoFHandler< dim, spacedim > *dof_handler)
 
 DoFAccessor (const DoFAccessor< structdim, dim, spacedim, level_dof_access > &)=default
 
 DoFAccessor (DoFAccessor< structdim, dim, spacedim, level_dof_access > &&)
 
 ~DoFAccessor ()=default
 
template<int structdim2, int dim2, int spacedim2>
 DoFAccessor (const InvalidAccessor< structdim2, dim2, spacedim2 > &)
 
template<int structdim2, int dim2, int spacedim2, bool level_dof_access2>
 DoFAccessor (const DoFAccessor< structdim2, dim2, spacedim2, level_dof_access2 > &)
 
template<bool level_dof_access2>
 DoFAccessor (const DoFAccessor< structdim, dim, spacedim, level_dof_access2 > &)
 
DoFAccessor< structdim, dim, spacedim, level_dof_access > & operator= (const DoFAccessor< structdim, dim, spacedim, level_dof_access > &da)=delete
 
DoFAccessor< structdim, dim, spacedim, level_dof_access > & operator= (DoFAccessor< structdim, dim, spacedim, level_dof_access > &&)
 
Accessing sub-objects
TriaIterator< DoFAccessor< structdim, dim, spacedim, level_dof_access > > child (const unsigned int c) const
 
typename ::internal::DoFHandlerImplementation::Iterators< dim, spacedim, level_dof_access >::line_iterator line (const unsigned int i) const
 
typename ::internal::DoFHandlerImplementation::Iterators< dim, spacedim, level_dof_access >::quad_iterator quad (const unsigned int i) const
 
Accessing the DoF indices of this object
void get_dof_indices (std::vector< types::global_dof_index > &dof_indices, const unsigned int fe_index=DoFHandler< dim, spacedim >::invalid_fe_index) const
 
void get_mg_dof_indices (const int level, std::vector< types::global_dof_index > &dof_indices, const unsigned int fe_index=DoFHandler< dim, spacedim >::invalid_fe_index) const
 
void set_mg_dof_indices (const int level, const std::vector< types::global_dof_index > &dof_indices, const unsigned int fe_index=DoFHandler< dim, spacedim >::invalid_fe_index)
 
types::global_dof_index vertex_dof_index (const unsigned int vertex, const unsigned int i, const unsigned int fe_index=DoFHandler< dim, spacedim >::invalid_fe_index) const
 
types::global_dof_index mg_vertex_dof_index (const int level, const unsigned int vertex, const unsigned int i, const unsigned int fe_index=DoFHandler< dim, spacedim >::invalid_fe_index) const
 
types::global_dof_index dof_index (const unsigned int i, const unsigned int fe_index=DoFHandler< dim, spacedim >::invalid_fe_index) const
 
types::global_dof_index mg_dof_index (const int level, const unsigned int i) const
 
Accessing the finite element associated with this object
unsigned int n_active_fe_indices () const
 
unsigned int nth_active_fe_index (const unsigned int n) const
 
std::set< unsigned intget_active_fe_indices () const
 
bool fe_index_is_active (const unsigned int fe_index) const
 
const FiniteElement< dim, spacedim > & get_fe (const unsigned int fe_index) const
 

Static Public Member Functions

static bool is_level_cell ()
 
static ::ExceptionBaseExcInvalidObject ()
 
static ::ExceptionBaseExcVectorNotEmpty ()
 
static ::ExceptionBaseExcVectorDoesNotMatch ()
 
static ::ExceptionBaseExcMatrixDoesNotMatch ()
 
static ::ExceptionBaseExcNotActive ()
 
static ::ExceptionBaseExcCantCompareIterators ()
 

Static Public Attributes

static const unsigned int dimension = dim
 
static const unsigned int space_dimension = spacedim
 

Protected Member Functions

void set_dof_handler (DoFHandler< dim, spacedim > *dh)
 
void set_dof_index (const unsigned int i, const types::global_dof_index index, const unsigned int fe_index=DoFHandler< dim, spacedim >::invalid_fe_index) const
 
void set_mg_dof_index (const int level, const unsigned int i, const types::global_dof_index index) const
 
void set_vertex_dof_index (const unsigned int vertex, const unsigned int i, const types::global_dof_index index, const unsigned int fe_index=DoFHandler< dim, spacedim >::invalid_fe_index) const
 
void set_mg_vertex_dof_index (const int level, const unsigned int vertex, const unsigned int i, const types::global_dof_index index, const unsigned int fe_index=DoFHandler< dim, spacedim >::invalid_fe_index) const
 

Protected Attributes

DoFHandler< dim, spacedim > * dof_handler
 

Friends

template<typename >
class TriaRawIterator
 
template<int , int , int , bool >
class DoFAccessor
 
template<int , int >
class DoFHandler
 
struct ::internal::DoFHandlerImplementation::Policy::Implementation
 
struct ::internal::DoFHandlerImplementation::Implementation
 
struct ::internal::hp::DoFHandlerImplementation::Implementation
 
struct ::internal::DoFCellAccessorImplementation::Implementation
 
struct ::internal::DoFAccessorImplementation::Implementation
 

Detailed Description

template<int structdim, int dim, int spacedim, bool level_dof_access>
class DoFAccessor< structdim, dim, spacedim, level_dof_access >

A class that gives access to the degrees of freedom stored in a DoFHandler object. Accessors are used to access the data that pertains to edges, faces, and cells of a triangulation. The concept is explained in more detail in connection to Iterators on mesh-like containers.

This class follows mainly the route laid out by the accessor library declared in the triangulation library (TriaAccessor). It enables the user to access the degrees of freedom on lines, quads, or hexes. The first template argument of this class determines the dimensionality of the object under consideration: 1 for lines, 2 for quads, and 3 for hexes. The second argument denotes the type of DoFHandler we should work on. From the second template argument we also deduce the dimension of the Triangulation this object refers to as well as the dimension of the space into which it is embedded. Finally, the template argument level_dof_access governs the behavior of the function get_active_or_mg_dof_indices(). See the section on Generic loops below.

Alias

Usage is best to happen through the alias to the various kinds of iterators provided by the DoFHandler class, since they are more secure to changes in the class naming and template interface as well as providing easier typing (much less complicated names!).

Generic loops and the third template argument

Many loops look very similar, whether they operate on the active dofs of the active cells of the Triangulation or on the level dofs of a single level or the whole grid hierarchy. In order to use polymorphism in such loops, they access degrees of freedom through the function get_active_or_mg_dof_indices(), which changes behavior according to the third template argument. If the argument is false, then the active dofs of active cells are accessed. If it is true, the level dofs are used. DoFHandler has functions, for instance begin() and begin_mg(), which return either type or the other. Additionally, they can be cast into each other, in case this is needed, since they access the same data.

It is recommended to use the function get_active_or_mg_dof_indices() in generic loops in lieu of get_dof_indices() or get_mg_dof_indices().

Inheritance

If the structural dimension given by the first template argument equals the dimension of the DoFHandler (given as the second template argument), then we are obviously dealing with cells, rather than lower-dimensional objects. In that case, inheritance is from CellAccessor, to provide access to all the cell specific information afforded by that class. Otherwise, i.e. for lower-dimensional objects, inheritance is from TriaAccessor.

There is a DoFCellAccessor class that provides the equivalent to the CellAccessor class.

Template Parameters
structdimThe dimensionality of the objects the accessor represents. For example, points have structdim equal to zero, edges have structdim equal to one, etc.
dimDimension of the underlying DoFHandler.
spacedimSpace dimension of the underlying DoFHandler.
level_dof_accessIf false, then the accessor simply represents a cell, face, or edge in a DoFHandler for which degrees of freedom only exist on the finest level. Some operations are not allowed in this case, such as asking for DoF indices on non-active cells. On the other hand, if this template argument is true, then the accessor represents an object in a multilevel hierarchy of degrees of freedom. In this case, accessing DoF indices of any cell is possible, and will return the level indices (which, for active cells, may be different from the global indices).

Definition at line 211 of file dof_accessor.h.

Member Typedef Documentation

◆ BaseClass

template<int structdim, int dim, int spacedim, bool level_dof_access>
using DoFAccessor< structdim, dim, spacedim, level_dof_access >::BaseClass = typename ::internal::DoFAccessorImplementation:: Inheritance<structdim, dimension, space_dimension>::BaseClass

Declare an alias to the base class to make accessing some of the exception classes simpler.

Definition at line 232 of file dof_accessor.h.

◆ AccessorData

template<int structdim, int dim, int spacedim, bool level_dof_access>
using DoFAccessor< structdim, dim, spacedim, level_dof_access >::AccessorData = DoFHandler<dimension, space_dimension>

Data type passed by the iterator class.

Definition at line 237 of file dof_accessor.h.

Constructor & Destructor Documentation

◆ DoFAccessor() [1/7]

template<int structdim, int dim, int spacedim, bool level_dof_access>
DoFAccessor< structdim, dim, spacedim, level_dof_access >::DoFAccessor ( )

Default constructor. Provides an accessor that can't be used.

◆ DoFAccessor() [2/7]

template<int structdim, int dim, int spacedim, bool level_dof_access>
DoFAccessor< structdim, dim, spacedim, level_dof_access >::DoFAccessor ( const Triangulation< dim, spacedim > *  tria,
const int  level,
const int  index,
const DoFHandler< dim, spacedim > *  dof_handler 
)

Constructor that generates an access that points to a particular cell or face or edge in a DoFHandler.

Parameters
triaThe triangulation into which this accessor points.
levelThe level within the mesh hierarchy of the object pointed to. For example, coarse mesh cells will have level zero, their children level one, and so on. This argument is ignored for faces and edges which do not have a level.
indexThe index of the object pointed to within the specified refinement level.
dof_handlerA pointer to the DoFHandler object to which the accessor shall refer. This DoFHandler object must of course be built on the same triangulation as the one specified in the first argument.

◆ DoFAccessor() [3/7]

template<int structdim, int dim, int spacedim, bool level_dof_access>
DoFAccessor< structdim, dim, spacedim, level_dof_access >::DoFAccessor ( const DoFAccessor< structdim, dim, spacedim, level_dof_access > &  )
default

Copy constructor.

◆ DoFAccessor() [4/7]

template<int structdim, int dim, int spacedim, bool level_dof_access>
DoFAccessor< structdim, dim, spacedim, level_dof_access >::DoFAccessor ( DoFAccessor< structdim, dim, spacedim, level_dof_access > &&  )

Move constructor.

◆ ~DoFAccessor()

template<int structdim, int dim, int spacedim, bool level_dof_access>
DoFAccessor< structdim, dim, spacedim, level_dof_access >::~DoFAccessor ( )
default

Destructor.

◆ DoFAccessor() [5/7]

template<int structdim, int dim, int spacedim, bool level_dof_access>
template<int structdim2, int dim2, int spacedim2>
DoFAccessor< structdim, dim, spacedim, level_dof_access >::DoFAccessor ( const InvalidAccessor< structdim2, dim2, spacedim2 > &  )

Conversion constructor. This constructor exists to make certain constructs simpler to write in dimension independent code. For example, it allows assigning a face iterator to a line iterator, an operation that is useful in 2d but doesn't make any sense in 3d. The constructor here exists for the purpose of making the code conform to C++ but it will unconditionally abort; in other words, assigning a face iterator to a line iterator is better put into an if-statement that checks that the dimension is two, and assign to a quad iterator in 3d (an operator that, without this constructor would be illegal if we happen to compile for 2d).

◆ DoFAccessor() [6/7]

template<int structdim, int dim, int spacedim, bool level_dof_access>
template<int structdim2, int dim2, int spacedim2, bool level_dof_access2>
DoFAccessor< structdim, dim, spacedim, level_dof_access >::DoFAccessor ( const DoFAccessor< structdim2, dim2, spacedim2, level_dof_access2 > &  )

Another conversion operator between objects that don't make sense, just like the previous one.

◆ DoFAccessor() [7/7]

template<int structdim, int dim, int spacedim, bool level_dof_access>
template<bool level_dof_access2>
DoFAccessor< structdim, dim, spacedim, level_dof_access >::DoFAccessor ( const DoFAccessor< structdim, dim, spacedim, level_dof_access2 > &  )

Copy constructor allowing to switch level access and active access.

Member Function Documentation

◆ operator=() [1/2]

template<int structdim, int dim, int spacedim, bool level_dof_access>
DoFAccessor<structdim, dim, spacedim, level_dof_access>& DoFAccessor< structdim, dim, spacedim, level_dof_access >::operator= ( const DoFAccessor< structdim, dim, spacedim, level_dof_access > &  da)
delete

Copy operator. These operators are usually used in a context like iterator a,b; *a=*b;. Presumably, the intent here is to copy the object pointed to by b to the object pointed to by a. However, the result of dereferencing an iterator is not an object but an accessor; consequently, this operation is not useful for iterators on DoF handler objects. Consequently, this operator is declared as deleted and can not be used.

◆ operator=() [2/2]

template<int structdim, int dim, int spacedim, bool level_dof_access>
DoFAccessor<structdim, dim, spacedim, level_dof_access>& DoFAccessor< structdim, dim, spacedim, level_dof_access >::operator= ( DoFAccessor< structdim, dim, spacedim, level_dof_access > &&  )

Move assignment operator.

◆ get_dof_handler()

template<int structdim, int dim, int spacedim, bool level_dof_access>
const DoFHandler<dim, spacedim>& DoFAccessor< structdim, dim, spacedim, level_dof_access >::get_dof_handler ( ) const

Return a handle on the DoFHandler object which we are using.

◆ copy_from() [1/2]

template<int structdim, int dim, int spacedim, bool level_dof_access>
template<bool level_dof_access2>
void DoFAccessor< structdim, dim, spacedim, level_dof_access >::copy_from ( const DoFAccessor< structdim, dim, spacedim, level_dof_access2 > &  a)

Implement the copy operator needed for the iterator classes.

◆ copy_from() [2/2]

template<int structdim, int dim, int spacedim, bool level_dof_access>
void DoFAccessor< structdim, dim, spacedim, level_dof_access >::copy_from ( const TriaAccessorBase< structdim, dim, spacedim > &  da)

Copy operator used by the iterator class. Keeps the previously set dof handler, but sets the object coordinates of the TriaAccessor.

◆ is_level_cell()

template<int structdim, int dim, int spacedim, bool level_dof_access>
bool DoFAccessor< structdim, dim, spacedim, level_dof_access >::is_level_cell ( )
inlinestatic

Tell the caller whether get_active_or_mg_dof_indices() accesses active or level dofs.

Definition at line 2160 of file dof_accessor.h.

◆ child()

template<int structdim, int dim, int spacedim, bool level_dof_access>
TriaIterator<DoFAccessor<structdim, dim, spacedim, level_dof_access> > DoFAccessor< structdim, dim, spacedim, level_dof_access >::child ( const unsigned int  c) const

Return an iterator pointing to the c-th child.

◆ line()

template<int structdim, int dim, int spacedim, bool level_dof_access>
typename ::internal::DoFHandlerImplementation:: Iterators<dim, spacedim, level_dof_access>::line_iterator DoFAccessor< structdim, dim, spacedim, level_dof_access >::line ( const unsigned int  i) const

Pointer to the ith line bounding this object. If the current object is a line itself, then the only valid index is i equals to zero, and the function returns an iterator to itself.

◆ quad()

template<int structdim, int dim, int spacedim, bool level_dof_access>
typename ::internal::DoFHandlerImplementation:: Iterators<dim, spacedim, level_dof_access>::quad_iterator DoFAccessor< structdim, dim, spacedim, level_dof_access >::quad ( const unsigned int  i) const

Pointer to the ith quad bounding this object. If the current object is a quad itself, then the only valid index is i equals to zero, and the function returns an iterator to itself.

◆ get_dof_indices()

template<int structdim, int dim, int spacedim, bool level_dof_access>
void DoFAccessor< structdim, dim, spacedim, level_dof_access >::get_dof_indices ( std::vector< types::global_dof_index > &  dof_indices,
const unsigned int  fe_index = DoFHandler< dim, spacedim >::invalid_fe_index 
) const

Return the global indices of the degrees of freedom located on this object in the standard ordering defined by the finite element (i.e., dofs on vertex 0, dofs on vertex 1, etc, dofs on line 0, dofs on line 1, etc, dofs on quad 0, etc.) This function is only available on active objects (see this glossary entry).

The cells needs to be an active cell (and not artificial in a parallel distributed computation).

The vector has to have the right size before being passed to this function.

The last argument denotes the finite element index. For the standard DoFHandler class, this value must be equal to its default value since that class only supports the same finite element on all cells anyway.

However, when the relevant DoFHandler object has hp-capabilities enabled, different finite element objects may be used on different cells. On faces between two cells, as well as vertices, there may therefore be two sets of degrees of freedom, one for each of the finite elements used on the adjacent cells. In order to specify which set of degrees of freedom to work on, the last argument is used to disambiguate. Finally, if this function is called for a cell object, there can only be a single set of degrees of freedom, and fe_index has to match the result of active_fe_index().

For cells, there is only a single possible finite element index (namely the one for that cell, returned by cell->active_fe_index. Consequently, the derived DoFCellAccessor class has an overloaded version of this function that calls the present function with cell->active_fe_index as last argument.

◆ get_mg_dof_indices()

template<int structdim, int dim, int spacedim, bool level_dof_access>
void DoFAccessor< structdim, dim, spacedim, level_dof_access >::get_mg_dof_indices ( const int  level,
std::vector< types::global_dof_index > &  dof_indices,
const unsigned int  fe_index = DoFHandler< dim, spacedim >::invalid_fe_index 
) const

Return the global multilevel indices of the degrees of freedom that live on the current object with respect to the given level within the multigrid hierarchy. The indices refer to the local numbering for the level this line lives on.

◆ set_mg_dof_indices()

template<int structdim, int dim, int spacedim, bool level_dof_access>
void DoFAccessor< structdim, dim, spacedim, level_dof_access >::set_mg_dof_indices ( const int  level,
const std::vector< types::global_dof_index > &  dof_indices,
const unsigned int  fe_index = DoFHandler< dim, spacedim >::invalid_fe_index 
)

Set the level DoF indices that are returned by get_mg_dof_indices.

◆ vertex_dof_index()

template<int structdim, int dim, int spacedim, bool level_dof_access>
types::global_dof_index DoFAccessor< structdim, dim, spacedim, level_dof_access >::vertex_dof_index ( const unsigned int  vertex,
const unsigned int  i,
const unsigned int  fe_index = DoFHandler< dim, spacedim >::invalid_fe_index 
) const

Global DoF index of the i degree associated with the vertexth vertex of the present cell.

The last argument denotes the finite element index. For the standard DoFHandler class, this value must be equal to its default value since that class only supports the same finite element on all cells anyway.

However, when hp-capabilities are enabled, different finite element objects may be used on different cells. On faces between two cells, as well as vertices, there may therefore be two sets of degrees of freedom, one for each of the finite elements used on the adjacent cells. In order to specify which set of degrees of freedom to work on, the last argument is used to disambiguate. Finally, if this function is called for a cell object, there can only be a single set of degrees of freedom, and fe_index has to match the result of cell->active_fe_index(). Alternatively, if fe_index is left to its default value when this function is called on a cell, then this is interpreted as equal to cell->active_fe_index().

◆ mg_vertex_dof_index()

template<int structdim, int dim, int spacedim, bool level_dof_access>
types::global_dof_index DoFAccessor< structdim, dim, spacedim, level_dof_access >::mg_vertex_dof_index ( const int  level,
const unsigned int  vertex,
const unsigned int  i,
const unsigned int  fe_index = DoFHandler< dim, spacedim >::invalid_fe_index 
) const

Return the global DoF index of the ith degree of freedom associated with the vertexth vertex on level level. Also see vertex_dof_index().

◆ dof_index()

template<int structdim, int dim, int spacedim, bool level_dof_access>
types::global_dof_index DoFAccessor< structdim, dim, spacedim, level_dof_access >::dof_index ( const unsigned int  i,
const unsigned int  fe_index = DoFHandler< dim, spacedim >::invalid_fe_index 
) const

Index of the ith degree of freedom of this object.

The last argument denotes the finite element index. For the standard DoFHandler class, this value must be equal to its default value since that class only supports the same finite element on all cells anyway.

However, when hp-capabilities are enabled, different finite element objects may be used on different cells. On faces between two cells, as well as vertices, there may therefore be two sets of degrees of freedom, one for each of the finite elements used on the adjacent cells. In order to specify which set of degrees of freedom to work on, the last argument is used to disambiguate. Finally, if this function is called for a cell object, there can only be a single set of degrees of freedom, and fe_index has to match the result of active_fe_index().

Note
While the get_dof_indices() function returns an array that contains the indices of all degrees of freedom that somehow live on this object (i.e. on the vertices, edges or interior of this object), the current dof_index() function only considers the DoFs that really belong to this particular object's interior. In other words, as an example, if the current object refers to a quad (a cell in 2d, a face in 3d) and the finite element associated with it is a bilinear one, then the get_dof_indices() will return an array of size 4 while dof_index() will produce an exception because no degrees are defined in the interior of the face.

◆ mg_dof_index()

template<int structdim, int dim, int spacedim, bool level_dof_access>
types::global_dof_index DoFAccessor< structdim, dim, spacedim, level_dof_access >::mg_dof_index ( const int  level,
const unsigned int  i 
) const

Return the dof_index on the given level. Also see dof_index.

◆ n_active_fe_indices()

template<int structdim, int dim, int spacedim, bool level_dof_access>
unsigned int DoFAccessor< structdim, dim, spacedim, level_dof_access >::n_active_fe_indices ( ) const

Return the number of finite elements that are active on a given object.

When hp-capabilities are disabled the answer is, of course, always one. However, when hp-capabilities are enabled, this isn't the case: If this is a cell, the answer is of course one. If it is a face, the answer may be one or two, depending on whether the two adjacent cells use the same finite element or not. If it is an edge in 3d, the possible return value may be one or any other value larger than that.

◆ nth_active_fe_index()

template<int structdim, int dim, int spacedim, bool level_dof_access>
unsigned int DoFAccessor< structdim, dim, spacedim, level_dof_access >::nth_active_fe_index ( const unsigned int  n) const

Return the n-th active FE index on this object. For cells and all non- hp-objects, there is only a single active FE index, so the argument must be equal to zero. For lower-dimensional hp-objects, there are n_active_fe_indices() active finite elements, and this function can be queried for their indices.

◆ get_active_fe_indices()

template<int structdim, int dim, int spacedim, bool level_dof_access>
std::set<unsigned int> DoFAccessor< structdim, dim, spacedim, level_dof_access >::get_active_fe_indices ( ) const

Returns all active FE indices on this object.

The size of the returned set equals the number of finite elements that are active on this object.

◆ fe_index_is_active()

template<int structdim, int dim, int spacedim, bool level_dof_access>
bool DoFAccessor< structdim, dim, spacedim, level_dof_access >::fe_index_is_active ( const unsigned int  fe_index) const

Return true if the finite element with given index is active on the present object. When the current DoFHandler does not have hp- capabilities, this is of course the case only if fe_index equals zero. For cells, it is the case if fe_index equals active_fe_index() of this cell. For faces and other lower- dimensional objects, there may be more than one fe_index that are active on any given object (see n_active_fe_indices()).

◆ get_fe()

template<int structdim, int dim, int spacedim, bool level_dof_access>
const FiniteElement<dim, spacedim>& DoFAccessor< structdim, dim, spacedim, level_dof_access >::get_fe ( const unsigned int  fe_index) const

Return a reference to the finite element used on this object with the given fe_index. fe_index must be used on this object, i.e. fe_index_is_active(fe_index) must return true.

◆ operator==()

template<int structdim, int dim, int spacedim, bool level_dof_access>
template<int structdim2, int dim2, int spacedim2, bool level_dof_access2>
bool DoFAccessor< structdim, dim, spacedim, level_dof_access >::operator== ( const DoFAccessor< structdim2, dim2, spacedim2, level_dof_access2 > &  ) const

Compare for equality. Return true if the two accessors refer to the same object.

The template parameters of this function allow for a comparison of very different objects. Therefore, some of them are disabled. Namely, if the dimension, or the dof handler of the two objects differ, an exception is generated. It can be expected that this is an unwanted comparison.

The template parameter level_dof_access2 is ignored, such that an iterator with level access can be equal to one with access to the active degrees of freedom.

◆ operator!=()

template<int structdim, int dim, int spacedim, bool level_dof_access>
template<int structdim2, int dim2, int spacedim2, bool level_dof_access2>
bool DoFAccessor< structdim, dim, spacedim, level_dof_access >::operator!= ( const DoFAccessor< structdim2, dim2, spacedim2, level_dof_access2 > &  ) const

Compare for inequality. The boolean not of operator==().

◆ set_dof_handler()

template<int structdim, int dim, int spacedim, bool level_dof_access>
void DoFAccessor< structdim, dim, spacedim, level_dof_access >::set_dof_handler ( DoFHandler< dim, spacedim > *  dh)
protected

Reset the DoF handler pointer.

◆ set_dof_index()

template<int structdim, int dim, int spacedim, bool level_dof_access>
void DoFAccessor< structdim, dim, spacedim, level_dof_access >::set_dof_index ( const unsigned int  i,
const types::global_dof_index  index,
const unsigned int  fe_index = DoFHandler< dim, spacedim >::invalid_fe_index 
) const
protected

Set the index of the ith degree of freedom of this object to index.

The last argument denotes the finite element index. For the standard DoFHandler class, this value must be equal to its default value since that class only supports the same finite element on all cells anyway.

However, when the relevant DoFHandler has hp-capabilities, different finite element objects may be used on different cells. On faces between two cells, as well as vertices, there may therefore be two sets of degrees of freedom, one for each of the finite elements used on the adjacent cells. In order to specify which set of degrees of freedom to work on, the last argument is used to disambiguate. Finally, if this function is called for a cell object, there can only be a single set of degrees of freedom, and fe_index has to match the result of active_fe_index().

◆ set_mg_dof_index()

template<int structdim, int dim, int spacedim, bool level_dof_access>
void DoFAccessor< structdim, dim, spacedim, level_dof_access >::set_mg_dof_index ( const int  level,
const unsigned int  i,
const types::global_dof_index  index 
) const
protected

◆ set_vertex_dof_index()

template<int structdim, int dim, int spacedim, bool level_dof_access>
void DoFAccessor< structdim, dim, spacedim, level_dof_access >::set_vertex_dof_index ( const unsigned int  vertex,
const unsigned int  i,
const types::global_dof_index  index,
const unsigned int  fe_index = DoFHandler< dim, spacedim >::invalid_fe_index 
) const
protected

Set the global index of the i degree on the vertex-th vertex of the present cell to index.

The last argument denotes the finite element index. For the standard DoFHandler class, this value must be equal to its default value since that class only supports the same finite element on all cells anyway.

However, when the relevant DoFHandler has hp-capabilities, different finite element objects may be used on different cells. On faces between two cells, as well as vertices, there may therefore be two sets of degrees of freedom, one for each of the finite elements used on the adjacent cells. In order to specify which set of degrees of freedom to work on, the last argument is used to disambiguate. Finally, if this function is called for a cell object, there can only be a single set of degrees of freedom, and fe_index has to match the result of active_fe_index().

◆ set_mg_vertex_dof_index()

template<int structdim, int dim, int spacedim, bool level_dof_access>
void DoFAccessor< structdim, dim, spacedim, level_dof_access >::set_mg_vertex_dof_index ( const int  level,
const unsigned int  vertex,
const unsigned int  i,
const types::global_dof_index  index,
const unsigned int  fe_index = DoFHandler< dim, spacedim >::invalid_fe_index 
) const
protected

Friends And Related Function Documentation

◆ TriaRawIterator

template<int structdim, int dim, int spacedim, bool level_dof_access>
template<typename >
friend class TriaRawIterator
friend

Definition at line 762 of file dof_accessor.h.

◆ DoFAccessor

template<int structdim, int dim, int spacedim, bool level_dof_access>
template<int , int , int , bool >
friend class DoFAccessor
friend

Definition at line 764 of file dof_accessor.h.

◆ DoFHandler

template<int structdim, int dim, int spacedim, bool level_dof_access>
template<int , int >
friend class DoFHandler
friend

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 770 of file dof_accessor.h.

◆ ::internal::DoFHandlerImplementation::Policy::Implementation

template<int structdim, int dim, int spacedim, bool level_dof_access>
friend struct ::internal::DoFHandlerImplementation::Policy:: Implementation
friend

Definition at line 773 of file dof_accessor.h.

◆ ::internal::DoFHandlerImplementation::Implementation

template<int structdim, int dim, int spacedim, bool level_dof_access>
friend struct ::internal::DoFHandlerImplementation::Implementation
friend

Definition at line 774 of file dof_accessor.h.

◆ ::internal::hp::DoFHandlerImplementation::Implementation

template<int structdim, int dim, int spacedim, bool level_dof_access>
friend struct ::internal::hp::DoFHandlerImplementation::Implementation
friend

Definition at line 775 of file dof_accessor.h.

◆ ::internal::DoFCellAccessorImplementation::Implementation

template<int structdim, int dim, int spacedim, bool level_dof_access>
friend struct ::internal::DoFCellAccessorImplementation::Implementation
friend

Definition at line 776 of file dof_accessor.h.

◆ ::internal::DoFAccessorImplementation::Implementation

template<int structdim, int dim, int spacedim, bool level_dof_access>
friend struct ::internal::DoFAccessorImplementation::Implementation
friend

Definition at line 777 of file dof_accessor.h.

Member Data Documentation

◆ dimension

template<int structdim, int dim, int spacedim, bool level_dof_access>
const unsigned int DoFAccessor< structdim, dim, spacedim, level_dof_access >::dimension = dim
static

A static variable that allows users of this class to discover the value of the second template argument.

Definition at line 219 of file dof_accessor.h.

◆ space_dimension

template<int structdim, int dim, int spacedim, bool level_dof_access>
const unsigned int DoFAccessor< structdim, dim, spacedim, level_dof_access >::space_dimension = spacedim
static

A static variable that allows users of this class to discover the value of the third template argument.

Definition at line 225 of file dof_accessor.h.

◆ dof_handler

template<int structdim, int dim, int spacedim, bool level_dof_access>
DoFHandler<dim, spacedim>* DoFAccessor< structdim, dim, spacedim, level_dof_access >::dof_handler
protected

Store the address of the DoFHandler object to be accessed.

Definition at line 661 of file dof_accessor.h.


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