get_subfaces#

iskra.topology.get_subfaces(faces: Tensor, subface_dim: int = -1) → tuple[Tensor, Tensor, Tensor][SOURCE]#

Finds all subface_dim-dimensional subfaces contained in a set of faces.

The function constructs one level of the face-subface hierarchy via the three tensors connecting faces to subfaces: subface-vertex, face-subface, and subface-orientation. It assigns each subface element a unique index. subface_vertex[i, 0] is the index of the first vertex of subface \(i\); thus, \(i\) is the unique index assigned to the subface with those vertices. face_subface[j, 0] is said unique index of the first subface in face \(j\). Now, notice that subface \(i\) has a canonical orientation assigned to it via the vertex ordering in subface_vertex, which may be flipped when the subface appears as a part of face \(j\). Therefore, subface_orientation[j, 0] tells us whether the subface at face_subface[j, 0] is flipped (-1) or not (+1) as it appears in face \(j\).

Hint

The function obtains the list of unique subfaces by getting all of the half-subface vertices via face_to_subface_idcs(), sorting the vertex indices and then picking out the unique ones. It finds the orientation using simplex_parity().

Tip

This function is one of the three building blocks of iskra’s scatter-gather framework, together with iskra.topology.reduce_on_subface() which performs the scatter-reduce operation and iskra.topology.face_index(), which performs the gather operation.

This function constructs the face hierarchy.

See Scatter-Gather Dataflow in iskra ✨ for an explanation of iskra’s tensor-based scatter-gather framework.

Caution

The dimension of a face is one less than the number of vertices in the face, e.g., edges are 1-faces, triangles 2-faces, etc.

Parameters:

  • faces (Tensor[Int64, [F, FV]]) – Face-vertex indices.

  • subface_dim (int) – The dimension of the requested subfaces. Passing a negative value makes the subface dimension relative to the face dimension: on a k-dimensional mesh, passing subface_dim=-1 asks for (k-1)-dimensional simplices.

Returns:

  • subface_vertex (Tensor[Int64, [S, SV]]) – Subface-vertex indices.

  • face_subface (Tensor[Int64, [F, FS]]) – Face-subface indices.

  • subface_orientation (Tensor[Float, [F, FS]]) – Sign (-1 or +1) signaling a subface in the face-subface indices is flipped with regards to its canonical orientation as dictated by the subface-vertex indices. The sign for vertex subfaces is always +1, as they can only have one canonical orientation. This is a different notion of orientation from DEC’s d_{0, 1} operator.

On this page