Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Topological tools

Figures use PyVista; verbose plotting boilerplate is omitted.

The tools below all rest on one idea: the subentities of an element — its faces, edges and vertices. descend decomposes every element into subentities; boundaries keeps only those on the outside (owned by a single element); and connected_components / crack relate elements that share a lower-dimensional subentity. Two elements are neighbours when they share such a subentity — two volumes sharing a face, two faces sharing an edge, and so on. Everything here assumes a topologically valid mesh (see The mesh model).

import numpy as np

import mefikit as mf

Descending connectivity

Every topological tool here builds and returns a new mesh; the *_update variants turn them into in-place operations (below). descend computes the descending connectivity of a mesh: it decomposes each element into its boundary (cells into faces, faces into edges, edges into vertices) and returns a new mesh of the requested dimension.

Start from the structured volumes built below:

x = range(3)
y = np.linspace(0.0, 3.0, 5, endpoint=True)
z = np.logspace(-0.5, 1, 4, endpoint=True)
volumes = mf.build_cmesh(x, y, z)

Simple descending

Chaining .descend() walks down one dimension at a time — volumes, faces, edges, vertices:

faces = volumes.descend()
edges = faces.descend()
vertex = edges.descend()

Submesh in one go

target_dim jumps straight to the wanted dimension, without chaining:

  • descend(target_dim=1) returns the edges directly,
  • descend(target_dim=0) returns the vertices directly.
edges = volumes.descend(target_dim=1)
vertex = volumes.descend(target_dim=0)

Boundaries computation

boundaries is the closure of a mesh: it keeps only the elements on the outside, not shared with any neighbour — exactly the ones you need for boundary conditions. It differs from descend, which returns every face of the mesh:

face_bounds = volumes.boundaries()
edge_bounds = volumes.boundaries(target_dim=1)
vertex_bounds = volumes.boundaries(target_dim=0)

Descend / boundaries update

Both operations come in an in-place flavour: descend_update / boundaries_update modify the mesh instead of returning a new one.

volumes.boundaries_update()
volumes.boundaries_update(target_dim=1)
volumes.to_pyvista(dim="all").shrink(0.8).plot(show_edges=True)

When using the _update version, the elements of the same dimension of the generated mesh are returned as a new mesh.

old_face_mesh = volumes.descend_update()
volumes.to_pyvista(dim="all").shrink(0.8).plot(show_edges=True)

old_face_mesh.to_pyvista().shrink(0.8).plot(show_edges=True)

Connected components

connected_components() splits a mesh into its connected parts. The link_dim argument decides what glues two elements together: sharing an edge (link_dim=1) or sharing a node (link_dim=0). Below, a small ribbon of QUAD4 cells is a single component when glued by edge, but falls apart as soon as only two cells touch at a corner:

x, y = np.meshgrid(np.linspace(0.0, 1.0, 5), np.linspace(0.0, 1.0, 5))
coords = np.c_[x.flatten(), y.flatten()]
conn = np.array(
    [
        [0, 1, 6, 5],
        [6, 7, 12, 11],
        # [2, 3, 8, 7],
        [11, 12, 17, 16],
    ],
    dtype=np.uint,
)
mesh = mf.UMesh(coords)
mesh.add_regular_block("QUAD4", conn)
mesh.add_regular_block("VERTEX", np.arange(len(coords), dtype=np.uint)[..., np.newaxis])
compos_link_edge = mesh.connected_components(link_dim=1)
compos_link_node = mesh.connected_components(link_dim=0)

print(f"{len(compos_link_edge)=}")
print(f"{len(compos_link_node)=}")
len(compos_link_edge)=2
len(compos_link_node)=1

Crack

crack is the exact opposite of merge_nodes: it duplicates the nodes that sit on a given (descending) mesh, so that the result is dis-connected there — each element along the crack line gets its own copy of those nodes. Here the hexahedral stack is cracked along all its faces, growing from 1 to several connected components:

x = range(2)
y = np.linspace(0.0, 3.0, 3, endpoint=True)
z = np.logspace(0.0, 1.0, 3, endpoint=True)
volumes = mf.build_cmesh(x, y, z)
faces = volumes.descend()
cracked = volumes.crack(faces)
edges = faces.descend()
compos_original = volumes.connected_components()
compos_cracked = cracked.connected_components()

assert len(compos_original) == 1

n_compos = len(compos_cracked)

Split

split cuts every cell into 2^n smaller cells of the same element type (n = topological dimension), keeping the domain and its topology unchanged. Each HEX8 of the mesh below becomes 8 sub-cells:

x = np.linspace(0.0, 3.0, 2, endpoint=True)
y = np.logspace(0.0, 1.0, 2, endpoint=True)
z = range(2)
mesh = mf.build_cmesh(x, y, z)
mesh_splitted = mesh.split()

Polyze

polyze re-emits a regular mesh as a polyhedral one: 2D cells become PGON and 3D cells PHED. unpolyze converts them back. Mesh-generation codes often output polyhedra, hence this round-trip:

x = np.linspace(0.0, 3.0, 4, endpoint=True)
y = np.logspace(0.0, 1.0, 4, endpoint=True)
mesh = mf.build_cmesh(x, y)
print(mesh.blocks())
{'QUAD4': array([[ 0,  1,  5,  4],
       [ 1,  2,  6,  5],
       [ 2,  3,  7,  6],
       [ 4,  5,  9,  8],
       [ 5,  6, 10,  9],
       [ 6,  7, 11, 10],
       [ 8,  9, 13, 12],
       [ 9, 10, 14, 13],
       [10, 11, 15, 14]], dtype=uint64)}
mesh_polyzed = mesh.polyze()
print(mesh_polyzed.blocks())
{'PGON': (array([ 0,  1,  5,  4,  1,  2,  6,  5,  2,  3,  7,  6,  4,  5,  9,  8,  5,
        6, 10,  9,  6,  7, 11, 10,  8,  9, 13, 12,  9, 10, 14, 13, 10, 11,
       15, 14], dtype=uint64), array([ 4,  8, 12, 16, 20, 24, 28, 32, 36], dtype=uint64))}
mesh_polyzed.to_pyvista().plot(show_edges=True)

unpolyzed = mesh_polyzed.unpolyze()
print(unpolyzed.blocks())
unpolyzed.to_pyvista().plot(show_edges=True)
{'QUAD4': array([[ 0,  1,  5,  4],
       [ 1,  2,  6,  5],
       [ 2,  3,  7,  6],
       [ 4,  5,  9,  8],
       [ 5,  6, 10,  9],
       [ 6,  7, 11, 10],
       [ 8,  9, 13, 12],
       [ 9, 10, 14, 13],
       [10, 11, 15, 14]], dtype=uint64)}

Stitch

Meshes are often modeled as separate blocks that were meshed independently, so their nodes do not match on the boundaries they share and they cannot be used as a single mesh. mf.stitch makes them conformal: the faces of each block are split to match the faces of its neighbours.

Here a plate made of a single hexahedron sits below a block of four hexahedra. The plate’s top face is one square while the block’s bottom is four squares, so they do not match.

plate = mf.build_cmesh([0.0, 2.0], [0.0, 2.0], [0.0, 1.0])
block = mf.build_cmesh([0.0, 1.0, 2.0], [0.0, 1.0, 2.0], [1.0, 2.0])

stitched = mf.stitch([plate, block])

print(list(stitched.blocks()))
print(f"{stitched.num_elements()=}")
['PHED']
stitched.num_elements()=5

plate = mf.build_cmesh([0.0, 2.0], [0.0, 2.0], [0.0, 1.0])
block = mf.build_cmesh([0.0, 1.0, 2.2], [0.0, 1.0, 1.5], [1.0, 2.0])
other = mf.build_cmesh([0.0, 1.0, 1.9], [1.5, 2.0], [1.0, 2.0])

stitched = mf.stitch([plate, block, other])

print(list(stitched.blocks()))
print(f"{stitched.num_elements()=}")
['PHED']
stitched.num_elements()=7
stitched.to_pyvista().plot(show_edges=True)