face_index#

iskra.topology.face_index(data: Tensor, faces: Tensor, squeeze: bool = True) → Tensor[SOURCE]#

Gathers subface values onto the faces that contain them.

This function collects, i.e., gathers, data (scalar, vector, tensor, etc.) defined on subfaces onto the faces they belong to. So, e.g., triangle faces can gather 3 edge-based values or 3 vertex-based values onto themselves. Alternatively, one can see this function as using the subface indices stored in faces to index into data: given data associated with each subface and a tensor of subface indices, this function outputs a tensor that contains data entries in positions defined by the indices.

Tip

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

This function moves data up the face hierarchy.

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

Parameters:

  • data (Tensor[DType, [S, Ds]]) – Data with shape [Ds] stored on each subface.

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

  • squeeze – If FS == 0 (i.e. the list of faces is just a 1D list of vertices) squeeze dictates whether the output will have the size-1 dimension corresponding to the face vertices squeezed. Default: True.

Returns:

​ (An Tensor with the shape [:abbr:`F (Number of faces), Ds]`.)

Example

values.shape

faces.shape

result.shape

Gathering

[V, 2]

[Tris, 3]

[Tris, 3, 2]

2D triangle positions

[V, 3]

[Tris, 3]

[Tris, 3, 3]

3D triangle positions

[V, 3]

[Tets, 4]

[Tets, 4, 3]

3D tet positions

[V, 4]

[Tets, 4]

[Tets, 4, 4]

4D tet positions

This works with higher dimensional indices too.

On this page