Intrepid2
Cell tools

Table of contents

Cell topologies

The range of admissible cell shapes in Intrepid is restricted to d-dimensional polytopes, d=1,2,3. A polytope is defined by a set of its vertices $ \{ {\bf v}_0,\ldots {\bf v}_V\} $ and a base topology BT that defines how these verices are connected into k-dimensional, k < d facets (k-subcells) of that polytope.

The base topology of any polytope can be extended by augmenting the set of its vertices by an additional set of points $\{ {\bf p}_0,\ldots {\bf p}_P\} $. The extended topology ET is defined by specifying the connectivity of the set $ \{ {\bf v}_0,\ldots {\bf v}_V\}\cup \{ {\bf p}_0,\ldots {\bf p}_P\} $ relative to the subcells specified by its base topology BT. The vertices and the extra points are collectively referred to as nodes. Thus, a polytope with extended topology ET is defined by a set of nodes $\{{\bf q}_0,\ldots,{\bf q}_N\}$, where $N = V + P$, and a connectivity rule for these nodes.

Intrepid requires any cell to have a valid base topology. The nodes of the cell should always be ordered by listing its vertices first, i.e.,

\[ \{{\bf q}_0,\ldots,{\bf q}_N\} = \{ {\bf v}_0,\ldots {\bf v}_V,{\bf p}_0,\ldots {\bf p}_P\} \]

To manage cell topologies Intrepid uses the Shards package http://trilinos.org/packages/shards . Shards provides definitions for a standard set of base and extended cell topologies plus tools to construct custom, user defined cell topologies, such as arbitrary polyhedral cells. For further details see Shards documentation.

Reference cells

For some cell topologies there exist simple, e.g., polynomial, mappings that allow to obtain any cell having that topology as an image of a single "standard" cell. We refer to such standard cells as reference cells.

Just like in the general case, a reference cell with a base topology BT is defined by a set of vertices, and a reference cell with extended topology ET is defined by a set of nodes that include the original vertices and some additional points.

The actual vertex and node coordinates for the reference cells can be chosen arbitrarily; however, once selected they should not be changed because in many cases, e.g., in finite element reconstructions, all calculations are done on a reference cell and then transformed to physical cells by an appropriate pullback (see Section Pullbacks).

In Intrepid base and extended reference cell topologies are defined using the following selections of vertex and node coordinates:

|=======================|==============================================================================|
| Topology family       |    reference cell vertices/additional nodes defining extended topology       |
|=======================|==============================================================================|
| Line<2>               |                                                                              |
| Beam<2>               | {(-1,0,0),(1,0,0)}                                                           |
| ShellLine<2>          |                                                                              |
|-----------------------|------------------------------------------------------------------------------|
| Line<3>               |                                                                              |
| Beam<3>               | {(0,0,0)}                                                                    |
| ShellLine<3>          |                                                                              |
|=======================|==============================================================================|
| Triangle<3>           | {(0,0,0),(1,0,0),(0,1,0)}                                                    |
| ShellTriangle<3>      |                                                                              |
|-----------------------|------------------------------------------------------------------------------|
| Triangle<4>           | {(1/3,1/3,0)}                                                                |
|.......................|..............................................................................|
| Triangle<6>           | {(1/2,0,0),(1/2,1/2,0),(0,1/2,0)}                                            |
| ShellTriangle<6>      |                                                                              |
|=======================|==============================================================================|
| Quadrilateral<4>      | {(-1,-1,0),(1,-1,0), (1,1,0),(-1,1,0)}                                       |
| ShellQuadrilateral<4> |                                                                              |
|-----------------------|------------------------------------------------------------------------------|
| Quadrilateral<8>      | {(0,-1,0),(1,0,0),(0,1,0),(-1,0,0)}                                          |
| ShellQuadrilateral<8> |                                                                              |
|.......................|..............................................................................|
| Quadrilateral<9>      | {(0,-1,0),(1,0,0),(0,1,0),(-1,0,0),(0,0,0)}                                  |
| ShellQuadrilateral<9> |                                                                              |
|=======================|==============================================================================|
| Tetrahedron<4>        | {(0,0,0),(1,0,0),(0,1,0),(0,0,1)}                                            |
|-----------------------|------------------------------------------------------------------------------|
| Tetrahedron<8>        | {(1/2,0,0),(1/2,1/2,0),(0,1/2,0),(1/3,1/3,1/3)}                              |
| Tetrahedron<10>       | {(1/2,0,0),(1/2,1/2,0),(0,1/2,0),(0,0,1/2),(1/2,0,1/2),(0,1/2,1/2)}          |
|=======================|==============================================================================|
| Pyramid<5>            | {(-1,-1,0),(1,-1,0),(1,1,0),(-1,1,0),(0,0,1)}                                |
|-----------------------|------------------------------------------------------------------------------|
| Pyramid<13>           | {(0,-1,0),(1,0,0),(0,1,0),(-1,0,0), 1/2((-1,-1,1),(1,-1,1),(1,1,1),(-1,1,1))}|
| Pyramid<14>           | all of the above and (0,0,0)                                                 |
|=======================|==============================================================================|
| Wedge<6>              | {(0,0,-1),(1,0,-1),(0,1,-1),(0,0,1),(1,0,1),(0,1,1)}                         |
|-----------------------|------------------------------------------------------------------------------|
| Wedge<15>             | {(1/2,0,-1),(1/2,1/2,-1),(0,1/2,-1), (0,0,0),(1,0,0),(0,1,0),                |  
|                       |  (1/2,0, 1),(1/2,1/2, 1),(0,1/2, 1)                                          |
|.......................|..............................................................................|
| Wedge<18>             | All of the above plus {(1/2,0,0),(1/2,1/2,0),(0,1/2,0)}                      |
|=======================|==============================================================================|
| Hexahedron<8>         | {(-1,-1,-1),(1,-1,-1),(1,1,-1),(-1,1,-1),(-1,-1,1),(1,-1,1),(1,1,1),(-1,1,1)}|
|-----------------------|------------------------------------------------------------------------------|
| Hexahedron<20>        | {(0,-1,-1),(1,0,-1),(0,1,-1),(-1,0,-1), (0,-1,0),(1,0,0),(0,1,0),(-1,0,0),   |
|                       |  (0,-1, 1),(1,0, 1),(0,1, 1),(-1,0, 1) }                                     |
|.......................|..............................................................................|
| Hexahedron<27>        | All of the above plus center point and face midpoints:                       |
|                       | {(0,0,0), (0,0,-1),(0,0,1), (-1,0,0),(1,0,0), (0,-1,0),(0,1,0)}              |
|=======================|==============================================================================|

Finite element reconstruction methods based on pullbacks (see Section Pullbacks) are restricted to the above cell topologies.

Reference-to-physical cell mapping

The mapping that takes a given reference cell to a physical cell with the same topology is defined using a nodal Lagrangian basis corresponding to the nodes of the reference cell. In other words, the mapping is constructed using basis functions that are dual to the nodes of the reference cell. Implementation details are as follows.

Assume that $ \hat{\mathcal{C}} $ is a reference cell with topology T and nodes $\{\hat{{\bf q}}_0,\ldots,\hat{{\bf q}}_{N}\}$, and that $ \{\hat{\phi}_i\}_{i=0}^{N} $ is the Lagrangian basis dual to these nodes, i.e., $ \hat{\phi}_i( \hat{{\bf q}}_j)=\delta_{ij} $. A physical cell $\mathcal{C}$ with the same topology T as $\hat{\mathcal{C}}$ is then defined as the image of $ \hat{\mathcal{C}} $ under the mapping

\[ F_\mathcal{C}(\hat{\bf x}) = \sum_{m=0}^{N} {\bf q}_m(\mathcal{C}) \hat{\phi}_m(\hat{\bf x}) \]

where $\{{\bf q}_0(\mathcal{C}),\ldots,{\bf q}_N(\mathcal{C})\}$ is the set of physical nodes that defines $\mathcal{C}$. The number of physical nodes is required to match the number of reference nodes in the specified cell topology T. The i-th coordinate function of the reference-to-physical mapping is given by

\[ \big(F_{\mathcal{C}}(\hat{\bf x})\big)_i = \sum_{m=0}^{N} \big({\bf q}_m(\mathcal{C})\big)_i\hat{\phi}_m(\hat{\bf x}) \]

where $ \big({\bf q}_m(\mathcal{C})\big)_i $ is the i-th spatial coordinate of the m-th node.

For simplicity, unless there's a chance for confusion, the cell symbol will be ommitted from the designations of physical points and reference-to-physical maps, i.e., we shall simply write $F(\hat{\bf x})\ \mbox{and}\ {\bf q}_m$.

Summary
Warning
Intrepid2::CellTools does not check for non-degeneracy of the physical cell obtained from a given set of physical nodes. As a result, F is not guaranteed to be a diffeomorphism, i.e., it may not have a continuously differentiable inverse. In this case some Intrepid2::CellTools methods, such as Intrepid2::CellTools::setJacobianInv, and Intrepid2::CellTools::mapToReferenceFrame will fail.

Jacobian of the reference-to-physical cell mapping

Intrepid follows the convention that the rows of the Jacobian are the transposed gradients of the coordinate functions of the mapping, i.e.,

\[ DF_{ij}(\hat{{\bf x}}) = \frac{\partial F_i(\hat{{\bf x}})}{\partial\hat{{\bf x}}_j} \]

In light of the definition of F in Section Reference-to-physical cell mapping, it follows that

\[ DF_{ij}(\hat{{\bf x}}) = \sum_{m=0}^{N} ({\bf q}_m)_i\frac{\partial\hat{\phi}_m(\hat{{\bf x}})}{\partial\hat{{\bf x}}_j} \,. \]

Summary

Parametrization of physical 1- and 2-subcells

Parametrization of a given physical k-subcell $\mathcal{S}_i$, k=1,2, is a map from a k-dimensional parametrization domain R to that subcell:

\[ \Phi : R \mapsto \mathcal{S} \,. \]

Parametrization domains play role similar to that of reference cells in the sense that they allow computation of line and surface integrals on 1- and 2-subcells (edges and faces) to be reduced to computation of integrals on R .

Parametrization maps are supported for 1- and 2-subcells (edges and faces) that belong to physical cells with reference cells. The reason is that these maps are defined by the composition of the parametrization maps for reference edges and faces with the mapping F defined in Reference-to-physical cell mapping. As a result, parametrization of a given physical k-subcell requires selection of a parent cell that contains the subcell.

Remarks
Because a given k-subcell may belong to more than one physical cell, its parent cell is not unique. For a single k-subcell the choice of a parent cell is not important, however, when dealing with subcell worksets parent cells must all have the same topology (see Subcell worksets for details about subcell worksets).

Implementation of subcell parametrization is as follows. Assume that $\mathcal{S}_i$ is a k-subcell with parent cell $\mathcal{C}$; $\mathcal{\hat{C}}$ is the associated reference cell and i is the local ordinal of the subcell relative to the reference cell. To this physical subcell corresponds a reference subcell $\hat{\mathcal{S}}_i$ having the same local ordinal. Parametrization of the reference k-subcell is a map from the k-dimensional parametrization domain R to that subcell:

\[ \hat{\Phi} : R \mapsto \hat{\mathcal{S}}_i \,. \]

Parametrization of $\mathcal{S}_i$ is then defined as

\[ \Phi = F\circ \hat{\Phi} \,, \]

where F is the reference-to-physical mapping between the parent cell and its reference cell.

A 1-subcell (edge) always has Line<N> topology and so, the parametrization domain for edges is the standard 1-cube:

\[ R = [-1,1]\,. \]

On the other hand, faces of reference cells can have Triangle<N> and/or Quadrilateral<N> topologies. Thus, the parametrization domain for a 2-subcell depends on its topology and is either the standard 2-simplex or the standard 2-cube:

\[ R = \left\{\begin{array}{rl} \{(0,0),(1,0),(0,1)\} & \mbox{if the face is Triangle} \\[1ex] [-1,1]\times [-1,1] & \mbox{if the face is Quadrilateral} \end{array}\right. \]

Summary

Subcell worksets

A subcell workset comprises of 1- or 2-subcells and associated parent cells that satisfy the following conditions

Therefore, a subcell workset is defined by

  1. collecting a set of 1- or 2-subcells having the same topology
  2. selecting a parent cell for every subcell in such a way that

    1. all parent cells have the same cell topology
    2. all subcells in the workset have the same local ordinal relative to the parent cell topology

    Obviously, a subcell can have multiple parent cells. For example, in a mesh consisiting of Triangle<3> cells, every edge is shared by 2 triangle cells. To define an edge workset we can use either one of the two traingles sharing the cell.

    Suppose now that the mesh comprises of Triangle<3> and Quadrilateral<4> cells and we want to define an edge workset. Let's say the first few edges in our workset happen to be shared by 2 triangles and so we select one of them as the parent cell. Now suppose the next edge is shared by a traingle and a quadrilateral. Because all parent cells in the workset must have the same cell topology we cannot use the quadrilateral as a parent cell and so we choose the triangle. Finally suppose that one of the candidate edges for our workset is shared by 2 quadrilaterals. Because of the requirement that all parent cells have the same topology, we will have to reject this edge because it does not posses a potential parent cell with the same topology as the rest of the edges in our workset.

    A subcell workset is denoted by $ \{\mathcal{S}_{c,i}\}_{c=0}^N $, where

    • c is parent cell ordinal;
    • i is the local subcell ordinal (relative to the topology of the parent cell) shared by all subcells in the workset.