Edit on GitHub

Gridap.ReferenceFEs

Gridap.ReferenceFEs — Module

The exported names are

source

Polytopes

Interface

Gridap.ReferenceFEs.Polytope — Type
abstract type Polytope{D} <: GridapType

Abstract type representing a polytope (i.e., a polyhedron in arbitrary dimensions). D is the environment dimension (typically, 0, 1, 2, or 3). This type parameter is needed since there are functions in the Polytope interface that return containers with Point{D} objects. We adopt the usual nomenclature for polytope-related objects. All objects in a polytope (from vertices to the polytope itself) are called n-faces or simply faces. The notation n-faces is used only when it is needed to refer to the object dimension n. Otherwise we simply use face. In addition, we say

  • vertex (pl. vertices): for 0-faces
  • edge: for 1-faces
  • facet: for (D-1)-faces

The Polytope interface is defined by overloading the following functions

And optionally these ones:

The interface can be tested with the function

source
Gridap.ReferenceFEs.get_faces — Method
get_faces(p::Polytope) -> Vector{Vector{Int}}

Given a polytope p the function returns a vector of vectors defining the incidence relation of the faces in the polytope.

Each face in the polytope receives a unique integer id. The id 1 is assigned to the first 0-face. Consecutive increasing ids are assigned to the other 0-faces, then to 1-faces, and so on. The polytope itself receives the largest id which coincides with num_faces(p). For a face id iface, get_faces(p)[iface] is a vector of face ids, corresponding to the faces that are incident with the face labeled with iface. That is, faces that are either on its boundary or the face itself. In this vector of incident face ids, faces are ordered by dimension, starting with 0-faces. Within each dimension, the labels are ordered in a consistent way with the polyope object for the face iface itself.

Examples

using Gridap.ReferenceFEs

faces = get_faces(SEGMENT)
println(faces)

# output
Array{Int64,1}[[1], [2], [1, 2, 3]]

The constant SEGMENT is bound to a predefined instance of polytope that represents a segment. The face labels associated with a segment are [1,2,3], being 1 and 2 for the vertices and 3 for the segment itself. In this case, this function returns the vector of vectors [[1],[2],[1,2,3]] meaning that vertex 1 is incident with vertex 1 (idem for vertex 2), and that the segment (id 3) is incident with the vertices 1 and 2 and the segment itself.

source
Gridap.ReferenceFEs.get_dimranges — Method
get_dimranges(p::Polytope) -> Vector{UnitRange{Int}}

Given a polytope p it returns a vector of ranges. The entry d+1 in this vector contains the range of face ids for the faces of dimension d.

Examples

using Gridap.ReferenceFEs

ranges = get_dimranges(SEGMENT)
println(ranges)

# output
UnitRange{Int64}[1:2, 3:3]

Face ids for the vertices in the segment range from 1 to 2 (2 vertices), the face ids for edges in the segment range from 3 to 3 (only one edge with id 3).

source
Gridap.ReferenceFEs.Polytope — Method
Polytope{N}(p::Polytope,faceid::Integer) where N

Returns a Polytope{N} object representing the "reference" polytope of the N-face with id faceid. The value faceid refers to the numeration restricted to the dimension N (it starts with 1 for the first N-face).

source
Base.:== — Method
(==)(a::Polytope{D},b::Polytope{D}) where D

Returns true if the polytopes a and b are equivalent. Otherwise, it returns false. Note that the operator == returns false by default for polytopes of different dimensions. Thus, this function has to be overloaded only for the case of polytopes a and b of same dimension.

source
Gridap.ReferenceFEs.get_edge_tangents — Method
get_edge_tangents(p::Polytope) -> Vector{VectorValue{D,Float64}}

Given a polytope p, returns a vector of VectorValue objects representing the unit tangent vectors to the polytope edges.

source
Gridap.ReferenceFEs.get_facet_normals — Method
get_facet_normals(p::Polytope) -> Vector{VectorValue{D,Float64}}

Given a polytope p, returns a vector of VectorValue objects representing the unit outward normal vectors to the polytope facets.

source
Gridap.ReferenceFEs.get_facet_orientations — Method
get_facet_orientations(p::Polytope) -> Vector{Int}

Given a polytope p returns a vector of integers of length num_facets(p). Facets, whose vertices are ordered consistently with the outwards normal vector, receive value 1 in this vector. Otherwise, facets receive value -1.

source
Gridap.ReferenceFEs.get_vertex_permutations — Method
get_vertex_permutations(p::Polytope) -> Vector{Vector{Int}}

Given a polytope p, returns a vector of vectors containing all admissible permutations of the polytope vertices. An admissible permutation is one such that, if the vertices of the polytope are re-labeled according to this permutation, the resulting polytope preserves the shape of the original one.

Examples

using Gridap.ReferenceFEs

perms = get_vertex_permutations(SEGMENT)
println(perms)

# output
Array{Int64,1}[[1, 2], [2, 1]]

The first admissible permutation for a segment is [1,2],i.e., the identity. The second one is [2,1], i.e., the first vertex is relabeled as 2 and the second vertex is relabeled as 1.

source
Gridap.ReferenceFEs.test_polytope — Method
test_polytope(p::Polytope{D}; optional::Bool=false) where D

Function that stresses out the functions in the Polytope interface. It tests whether the function in the polytope interface are defined for the given object, and whether they return objects of the expected type. With optional=false (the default), only the mandatory functions are checked. With optional=true, the optional functions are also tested.

source
Gridap.ReferenceFEs.get_facedims — Method
get_facedims(p::Polytope) -> Vector{Int}

Given a polytope p, returns a vector indicating the dimension of each face in the polytope

Examples

using Gridap.ReferenceFEs

dims = get_facedims(SEGMENT)
println(dims)

# output
[0, 0, 1]

The first two faces in the segment (the two vertices) have dimension 0 and the third face (the segment itself) has dimension 1

source
Gridap.ReferenceFEs.get_offsets — Method
get_offsets(p::Polytope) -> Vector{Int}

Given a polytope p, it returns a vector of integers. The position in the d+1 entry in this vector is the offset that transforms a face id in the global numeration in the polytope to the numeration restricted to faces to dimension d.

Examples

using Gridap.ReferenceFEs

offsets = get_offsets(SEGMENT)
println(offsets)

# output
[0, 2]
source
Gridap.ReferenceFEs.get_faces — Method
get_faces(p::Polytope,dimfrom::Integer,dimto::Integer) -> Vector{Vector{Int}}

For dimfrom >= dimto returns a vector that for each face of dimension dimfrom stores a vector of the ids of faces of dimension dimto on its boundary.

For dimfrom < dimto returns a vector that for each face of dimfrom stores a vector of the face ids of faces of dimension dimto that touch it.

The numerations used in this funcitons are the ones restricted to each dimension.

using Gridap.ReferenceFEs

edge_to_vertices = get_faces(QUAD,1,0)
println(edge_to_vertices)

vertex_to_edges_around = get_faces(QUAD,0,1)
println(vertex_to_edges_around)

# output
Array{Int64,1}[[1, 2], [3, 4], [1, 3], [2, 4]]
Array{Int64,1}[[1, 3], [1, 4], [2, 3], [2, 4]]
source
Gridap.ReferenceFEs.get_reffaces — Method
get_reffaces(::Type{Polytope{d}},p::Polytope) where d -> Vector{Polytope{d}}

Get a vector of the unique polytopes for the faces of dimension d.

Examples

Get the unique polytopes for the facets of a wedge.

using Gridap.ReferenceFEs

reffaces = get_reffaces(Polytope{2},WEDGE)

println(reffaces)

# output
Gridap.ReferenceFEs.ExtrusionPolytope{2}[TRI, QUAD]
source
Gridap.ReferenceFEs.get_face_type — Method
get_face_type(p::Polytope,d::Integer) -> Vector{Int}

Return a vector of integers denoting, for each face of dimension d, an index to the vector get_reffaces(Polytope{d},p)

Examples

Get the unique polytopes for the facets of a wedge and identify of which type each face is.

using Gridap.ReferenceFEs

reffaces = get_reffaces(Polytope{2},WEDGE)

face_types = get_face_type(WEDGE,2)

println(reffaces)
println(face_types)

# output
Gridap.ReferenceFEs.ExtrusionPolytope{2}[TRI, QUAD]
[1, 1, 2, 2, 2]

The three first facets are of type 1, i.e, QUAD, and the last ones of type 2, i.e., TRI.

source

Extrusion polytopes

Gridap.ReferenceFEs.ExtrusionPolytope — Method
ExtrusionPolytope(extrusion::Int...)

Generates an ExtrusionPolytope from the tuple extrusion. The values in extrusion are either equal to the constant HEX_AXIS or the constant TET_AXIS.

Examples

Creating a quadrilateral, a triangle, and a wedge

using Gridap.ReferenceFEs

quad = ExtrusionPolytope(HEX_AXIS,HEX_AXIS)

tri = ExtrusionPolytope(TET_AXIS,TET_AXIS)

wedge = ExtrusionPolytope(TET_AXIS,TET_AXIS,HEX_AXIS)

println(quad == QUAD)
println(tri == TRI)
println(wedge == WEDGE)

# output
true
true
true
source

Pre-defined polytope instances

Degrees of freedom

Interface

Gridap.ReferenceFEs.Dof — Type
abstract type Dof <: Kernel

Abstract type representing a degree of freedom (DOF), a basis of DOFs, and related objects. These different cases are distinguished by the return type obtained when evaluating the Dof object on a Field object. See function evaluate_dof! for more details.

The following functions needs to be overloaded

The following functions can be overloaded optionally

The interface is tested with

In most of the cases it is not strictly needed that types that implement this interface inherit from Dof. However, we recommend to inherit from Dof, when possible.

source
Gridap.ReferenceFEs.evaluate_dof! — Method
evaluate_dof!(cache,dof,field)

Evaluates the dof dof with the field field. It can return either an scalar value or an array of scalar values depending the case. The cache object is computed with function dof_cache.

When a mathematical dof is evaluated on a physical field, a scalar number is returned. If either the Dof object is a basis of DOFs, or the Field object is a basis of fields, or both objects are bases, then the returned object is an array of scalar numbers. The first dimensions in the resulting array are for the Dof object and the last ones for the Field object. E.g, a basis of nd DOFs evaluated at physical field returns a vector of nd entries. A basis of nd DOFs evaluated at a basis of nf fields returns a matrix of size (nd,nf).

source
Gridap.ReferenceFEs.test_dof — Method
test_dof(dof,field,v,comp::Function=(==))

Test that the Dof interface is properly implemented for object dof. It also checks if the object dof when evaluated at the field field returns the same value as v. Comparison is made with the comp function.

source

Working with arrays of DOFs

Gridap.ReferenceFEs.evaluate_dof_array — Method
evaluate_dof_array(dof::AbstractArray,field::AbstractArray)

Evaluates the Dof objects in the array dof at the Field objects at the array field element by element.

The result is numerically equivalent to

map(evaluate_dof, dof, field)

but it is described with a more memory-friendly lazy type.

source

Lagrangian dof bases

Gridap.ReferenceFEs.LagrangianDofBasis — Type
struct LagrangianDofBasis{P,V} <: Dof
  nodes::Vector{P}
  dof_to_node::Vector{Int}
  dof_to_comp::Vector{Int}
  node_and_comp_to_dof::Vector{V}
end

Type that implements a Lagrangian dof basis.

Fields:

  • nodes::Vector{P} vector of points (P<:Point) storing the nodal coordinates
  • node_and_comp_to_dof::Vector{V} vector such that node_and_comp_to_dof[node][comp] returns the dof associated with node node and the component comp in the type V.
  • dof_to_node::Vector{Int} vector of integers such that dof_to_node[dof] returns the node id associated with dof id dof.
  • dof_to_comp::Vector{Int} vector of integers such that dof_to_comp[dof] returns the component id associated with dof id dof.
source
Gridap.ReferenceFEs.LagrangianDofBasis — Method
LagrangianDofBasis(::Type{T},nodes::Vector{<:Point}) where T

Creates a LagrangianDofBasis for fields of value type T associated with the vector of nodal coordinates nodes.

source

Reference Finite Elements

Interface

Gridap.ReferenceFEs.ReferenceFE — Type
abstract type ReferenceFE{D} <: GridapType

Abstract type representing a Reference finite element. D is the underlying coordinate space dimension. We follow the Ciarlet definition. A reference finite element is defined by a polytope (cell topology), a basis of an interpolation space of top of this polytope (denoted here as the prebasis), and a basis of the dual of this space (i.e. the degrees of freedom). From this information one can compute the shape functions (i.e, the canonical basis of w.r.t. the degrees of freedom) with a simple change of basis. In addition, we also encode in this type information about how the interpolation space in a reference finite element is "glued" with neighbors in order to build conforming cell-wise spaces.

The ReferenceFE interface is defined by overloading these methods:

The interface is tested with

source
Gridap.ReferenceFEs.get_face_dofs — Method
get_face_dofs(reffe::ReferenceFE) -> Vector{Vector{Int}}

Returns a vector of vector that, for each face, stores the dofids in the closure of the face.

source
Gridap.ReferenceFEs.get_shapefuns — Method
get_shapefuns(reffe::ReferenceFE) -> Field

Returns the basis of shape functions (i.e. the canonical basis) associated with the reference FE. The result is encoded as a Field object.

source
Gridap.ReferenceFEs.compute_shapefuns — Method
compute_shapefuns(dofs,prebasis)

Helper function used to compute the shape function basis associated with the dof basis dofs and the basis prebasis.

It is equivalent to

change = inv(evaluate(dofs,prebasis))
change_basis(prebasis,change)
source

Generic reference elements

Gridap.ReferenceFEs.GenericRefFE — Type
struct GenericRefFE{D} <: ReferenceFE{D}
  ndofs::Int
  polytope::Polytope{D}
  prebasis::Field
  dofs::Dof
  face_own_dofs::Vector{Vector{Int}}
  face_own_dofs_permutations::Vector{Vector{Vector{Int}}}
  face_dofs::Vector{Vector{Int}}
  shapefuns::Field
end

This type is a materialization of the ReferenceFE interface. That is, it is a struct that stores the values of all abstract methods in the ReferenceFE interface. This type is useful to build reference FEs from the underlying ingredients without the need to create a new type.

Note that some fields in this struct are type unstable deliberately in order to simplify the type signature. Don't access them in computationally expensive functions, instead extract the required fields before and pass them to the computationally expensive function.

source
Gridap.ReferenceFEs.GenericRefFE — Method
GenericRefFE(
  ndofs::Int,
  polytope::Polytope{D},
  prebasis::Field,
  dofs::Dof,
  face_own_dofs::Vector{Vector{Int}},
  face_own_dofs_permutations::Vector{Vector{Vector{Int}}},
  face_dofs::Vector{Vector{Int}},
  shapefuns::Field=compute_shapefuns(dofs,prebasis)) where D

Constructs a GenericRefFE object with the provided data.

source

Node-based reference Finite Elements

Interface

Gridap.ReferenceFEs.NodalReferenceFE — Type
abstract type NodalReferenceFE{D} <: ReferenceFE{D}

Abstract type representing a node-based reference FE. We understand a node-based reference FE as one that uses the concept of node to locate dofs on the underlying polytope. Here, nodal-based does not necessary mean an interpolatory reference FE. We only assume that each dof is assigned to a node, whereas several dofs can share a same node in general.

The interface for this type is defined with the methods of ReferenceFE plus the following ones

source

GenericNodalRefFE

Gridap.ReferenceFEs.GenericNodalRefFE — Type

struct GenericNodalRefFE{D,T,V} <: NodalReferenceFE{D} reffe::GenericRefFE{D} nodecoordinates::Vector{Point{D,T}} nodeandcomptodof::Vector{V} faceownnodes::Vector{Vector{Int}} faceownnodespermutations::Vector{Vector{Vector{Int}}} face_nodes::Vector{Vector{Int}} end

source

Lagrangian reference elements

Gridap.ReferenceFEs.LagrangianRefFE — Type
struct LagrangianRefFE{D} <: NodalReferenceFE{D}
  # private fields
end

Type representing a Lagrangian finite element.

For this type

  • get_dof_basis(reffe) returns a LagrangianDofBasis
  • get_prebasis(reffe) returns a MonomialBasis
source
Gridap.ReferenceFEs.LagrangianRefFE — Method
LagrangianRefFE(
  polytope::Polytope{D},
  prebasis::MonomialBasis,
  dofs::LagrangianDofBasis,
  face_own_nodes::Vector{Vector{Int}},
  own_nodes_permutations::Vector{Vector{Int}},
  reffaces) where D

Low level (inner) constructor of LagrangianRefFE.

source
Gridap.ReferenceFEs.LagrangianRefFE — Method
LagrangianRefFE(::Type{T},p::Polytope,orders) where T
LagrangianRefFE(::Type{T},p::Polytope,order::Int) where T

Builds a LagrangianRefFE object on top of the given polytope. T is the type of the value of the approximation space (e.g., T=Float64 for scalar-valued problems, T=VectorValue{N,Float64} for vector-valued problems with N components). The arguments order or orders are for the polynomial order of the resulting space, which allows isotropic or anisotropic orders respectively (provided that the cell topology allows the given anisotropic order). The argument orders should be an indexable collection of D integers (e.g., a tuple or a vector), being D the number of space dimensions.

In order to be able to use this function, the type of the provided polytope p has to implement the following additional methods. They have been implemented for ExtrusionPolytope in the library. They need to be implemented for new polytope types in order to build Lagangian reference elements on top of them.

The following methods are also used in the construction of the LagrangianRefFE object. A default implementation of them is available in terms of the three previous methods. However, the user can also implement them for new polytope types increasing customization possibilities.

source
Gridap.ReferenceFEs.compute_monomial_basis — Method
compute_monomial_basis(::Type{T},p::Polytope,orders) where T -> MonomialBasis

Returns the monomial basis of value type T and order per direction described by orders on top of the polytope p.

source
Gridap.ReferenceFEs.compute_own_nodes — Method
compute_own_nodes(p::Polytope{D},orders) where D -> Vector{Point{D,Float64}}

Returns the coordinates of the nodes owned by the interior of the polytope associated with a Lagrangian space with the order per direction described by orders.

source
Gridap.ReferenceFEs.compute_face_orders — Method
compute_face_orders(p::Polytope,face::Polytope,iface::Int,orders)

Returns a vector or a tuple with the order per direction at the face face of the polytope p when restricting the order per direction orders to this face. iface is the face id of face in the numeration restricted to the face dimension.

source
Gridap.ReferenceFEs.compute_nodes — Method
compute_nodes(p::Polytope,orders)

When called

node_coords, face_own_nodes = compute_nodes(p,orders)

Returns node_coords, the nodal coordinates of all the Lagrangian nodes associated with the order per direction orders, and face_own_nodes, being a vector of vectors indicating which nodes are owned by each of the faces of the polytope p.

source
Gridap.ReferenceFEs.compute_lagrangian_reffaces — Method
compute_lagrangian_reffaces(::Type{T},p::Polytope,orders) where T

Returns a tuple of length D being the number of space dimensions. The entry d+1 of this tuple contains a vector of LagrangianRefFE one for each face of dimension d on the boundary of the polytope.

source
Base.:== — Method
(==)(a::LagrangianRefFE{D}, b::LagrangianRefFE{D}) where D
source
Gridap.ReferenceFEs.is_affine — Method
is_affine(reffe::NodalReferenceFE) -> Bool

Query if the reffe leads to an afine map (true only for first order spaces on top of simplices)

source

Serendipity reference elements

Gridap.ReferenceFEs.SerendipityRefFE — Function
SerendipityRefFE(::Type{T},p::Polytope,order::Int) where T
SerendipityRefFE(::Type{T},p::Polytope,orders::Tuple) where T

Returns an instance of LagrangianRefFE, whose underlying approximation space is the serendipity space of order order. Implemented for order from 1 to 4. The type of the polytope p has to implement all the queries detailed in the constructor LagrangianRefFE(::Type{T},p::Polytope{D},orders) where {T,D}.

Examples

using Gridap.ReferenceFEs

order = 2
reffe = SerendipityRefFE(Float64,QUAD,order)

println( num_dofs(reffe) )

# output
8
source

PDiscRefFE

RaviartThomasRefFE

Pre-defined ReferenceFE instances