face_to_subface_idcs

iskra.topology.face_to_subface_idcs(face_dim: int, subface_dim: int = -1) → list[tuple[int, ...]][SOURCE]

Returns canonical indices for subfaces within faces.

When requesting subfaces one dimension lower than the faces (e.g., triangles from tets or edges from triangles), the function ensures that the subfaces are oriented correctly and that the \(i^{\text{th}}\) subface is opposite to vertex \(i\).

Tip

A pattern you might need at some point is using this function to get the face-subfaces-vertices tensor:

idcs: list[tuple[int, ...]] = face_to_subface_idcs(face_dim, subface_dim)
half_subfaces = torch.stack([faces[:, nbh_idx] for nbh_idx in idcs], -2)

For example using this pattern with face_dim=2, subface_dim=1 would create a [F, 3, 2] tensor with the “triangle to half-edge vertices” relationship. Ideally, this should only be necessary in rare occasions.

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:

• face_dim (int) – Intrinsic dimension of face to be indexed into.

• subface_dim (int) – Intrinsic dimension of desired subface. 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:

​ (list[tuple[int, ...]]) – List of the indices used to get each subface.

Example

Description	face_dim	subface_dim	idcs
tet → triangles (oriented/opposite vertex \(i\) convention)	3	2 (default)	[(1,2,3), (0,3,2), (0,1,3), (0,2,1)]
tet → edges (Heron’s formula / opposite edge \(i\))	3	1	[(0,1), (1,2), (2,0), (2,3), (0,3), (1,3)]
triangle → edges (oriented/opposite vertex \(i\) convention)	2	1 (default)	[(1,2), (2,0), (0,1)]
triangle → vertices	2	0	[(0,), (1,), (2,)]
edge → vertices (opposite vertex \(i\) convention)	1	0 (default)	[(1,), (0,)]
other dims (fallback)	d	k	combinations(range(d+1), k+1)