Dof Handler

InterpolationInfo

Gathers all the information needed to distribute dofs for a given interpolation. Note that this cache is of the same type no matter the interpolation: the purpose is to make dof-distribution type-stable.

PathOrientationInfo

Orientation information for 1D entities.

The orientation for 1D entities is defined by the indices of the grid nodes associated to the vertices. To give an example, the oriented path

1 ---> 2

is called regular, indicated by regular=true, while the oriented path

2 ---> 1

is called inverted, indicated by regular=false.

SurfaceOrientationInfo

Orientation information for 2D entities. Such an entity can be possibly flipped (i.e. the defining vertex order is reverse to the spanning vertex order) and the vertices can be rotated against each other. Take for example the faces

1---2 2---3
| A | | B |
4---3 1---4

which are rotated against each other by 90° (shift index is 1) or the faces

1---2 2---1
| A | | B |
4---3 3---4

which are flipped against each other. Any combination of these can happen. The combination to map this local face to the defining face is encoded with this data structure via $rotate \circ flip$ where the rotation is indiced by the shift index. !!!NOTE TODO implement me.

__close!(dh::DofHandler)

Internal entry point for dof distribution.

Dofs are distributed as follows: For the DofHandler each SubDofHandler is visited in the order they were added. For each field in the SubDofHandler create dofs for the cell. This means that dofs on a particular cell will be numbered in groups for each field, so first the dofs for field 1 are distributed, then field 2, etc. For each cell dofs are first distributed on its vertices, then on the interior of edges (if applicable), then on the interior of faces (if applicable), and finally on the cell interior. The entity ordering follows the geometrical ordering found in vertices, faces and edges.

get_grid(dh::AbstractDofHandler)

Access some grid representation for the dof handler.

find_field(dh::DofHandler, field_name::Symbol)::NTuple{2,Int}

Return the index of the field with name field_name in a DofHandler. The index is a NTuple{2,Int}, where the 1st entry is the index of the SubDofHandler within which the field was found and the 2nd entry is the index of the field within the SubDofHandler.

See also: find_field(sdh::SubDofHandler, field_name::Symbol), _find_field(sdh::SubDofHandler, field_name::Symbol).

_close_subdofhandler!(dh::DofHandler{sdim}, sdh::SubDofHandler, sdh_index::Int, nextdof::Int, vertexdicts, edgedicts, facedicts) where {sdim}

Main entry point to distribute dofs for a single SubDofHandler on its subdomain.

_distribute_dofs_for_cell!(dh::DofHandler{sdim}, cell::AbstractCell, ip_info::InterpolationInfo, nextdof::Int, vertexdict, edgedict, facedict) where {sdim}

Main entry point to distribute dofs for a single cell.

permute_and_push!

For interpolations with more than one interior dof per edge it may be necessary to adjust the dofs. Since dofs are (initially) enumerated according to the local edge direction there can be a direction mismatch with the neighboring element. For example, in the following nodal interpolation example, with three interior dofs on each edge, the initial pass have distributed dofs 4, 5, 6 according to the local edge directions:

+-----------+
|     A     |
+--4--5--6->+    local edge on element A

 ---------->     global edge

+<-6--5--4--+    local edge on element B
|     B     |
+-----------+

For most scalar-valued interpolations we can simply compensate for this by reversing the numbering on all edges that do not match the global edge direction, i.e. for the edge on element B in the example.

In addition, we also have to preserve the ordering at each dof location.

For more details we refer to Scroggs et al. [8] as we follow the methodology described therein.

References

• [8] Scroggs et al. ACM Trans. Math. Softw. 48 (2022).

!!!NOTE TODO implement me.

For more details we refer to [1] as we follow the methodology described therein.

[1] Scroggs, M. W., Dokken, J. S., Richardson, C. N., & Wells, G. N. (2022). Construction of arbitrary order finite element degree-of-freedom maps on polygonal and polyhedral cell meshes. ACM Transactions on Mathematical Software (TOMS), 48(2), 1-23.

!!!TODO citation via software.

!!!TODO Investigate if we can somehow pass the interpolation into this function in a typestable way.

cross_element_coupling!(dh::DofHandler, topology::ExclusiveTopology, sym::Bool, keep_constrained::Bool, couplings::Union{AbstractVector{<:AbstractMatrix{Bool}},Nothing}, cnt::Int, I::Vector{Int}, J::Vector{Int})

Mutates I, J to account for cross-element coupling by calling _add_cross_coupling. Returns the updated value of cnt.

Used internally for sparsity patterns with cross-element coupling.

_add_cross_coupling(coupling_sdh, dof_i, dof_j, cell_field_dofs, neighbor_field_dofs, i, j, sym, keep_constrained, ch, cnt, I, J)

Helper function used to mutate I and J to add cross-element coupling.