TPMS and lattice catalog#

pyvcad_metamaterials supplies nine periodic implicit cells, twenty-five graph cells, and eleven face/plate cells. This guide compares those cells on consistent rectangular maps, then uses ordinary CSG to fill more familiar part geometries.

Build a finite rectangular map#

Every catalog builder receives a CellMap first:

import pyvcad as pv
import pyvcad_metamaterials as mm

cell_map = mm.rectangular_cell_map(
    (pv.Vec3(-15.0, -15.0, -15.0), pv.Vec3(15.0, 15.0, 15.0)),
    cells=(3, 3, 3),
)

Use cells=(nu, nv, nw) when exact repetition count and phase matter. Use cell_size=... when approximate world spacing is more convenient. cell_size is converted to integer counts by rounding upward, so the requested world bounds remain exact and the realized spacing adjusts slightly to fit them.

TPMS catalog#

The names in mm.TPMS_NAMES can be passed to mm.tpms(...), and each also has a named helper such as mm.gyroid(...) or mm.schwarz_p(...).

Gyroid TPMS
Gyroid
Fischer-Koch S TPMS
Fischer-Koch S
F-RD TPMS
F-RD
I-WP TPMS
I-WP
Lidinoid TPMS
Lidinoid
Neovius TPMS
Neovius
Schwarz-D TPMS
Schwarz-D
Schwarz-P TPMS
Schwarz-P
Split-P TPMS
Split-P

These cells are periodic trigonometric level-set approximations. They provide repeatable engineering surfaces, but the approximation itself is not a proof of zero mean curvature everywhere.

Fischer-Koch S and F-RD use the published level-set definitions summarized by Abdelaal and Eldesouky. The catalog provides geometry; it does not attach a topology-independent stiffness, strength, Poisson ratio, or energy-absorption claim.

The complete interactive gallery is 02_tpms_gallery.py.

Sheet and solid modes#

sheet = mm.gyroid(cell_map, mode="sheet", wall_thickness=1.6)
solid = mm.gyroid(cell_map, mode="solid", level=0.0)
Gyroid sheet mode
Sheet mode: a wall around the level surface
Gyroid solid mode
Solid mode: one labyrinth side of the level surface

In sheet mode, wall_thickness is the requested wall thickness in millimetres. In solid mode, level shifts the dividing surface and changes the retained labyrinth. Standard TPMS cells use the local map metric so those controls remain world-unit quantities when the cells are deformed.

See 01_tpms_gyroid.py for the side-by-side interactive example.

Graph lattice catalog#

Graph lattices use normalized vertices and edges, then map each repeated segment into world space. mm.LATTICE_NAMES lists the built-in catalog.

Cubic graph lattice
Cubic
BCC graph lattice
BCC
FCC graph lattice
FCC
Kelvin graph lattice
Kelvin
Octet graph lattice
Octet
Diamond graph lattice
Diamond
Isotruss graph lattice
Isotruss (SC+BCC+SCC)
Fluorite graph lattice
Fluorite
Hexagonal prism edge lattice
Hex-prism edge
Re-entrant hexagonal prism lattice
Re-entrant hex prism
lattice = mm.octet(
    cell_map,
    beam_radius=0.8,
    node_radius=0.9,
    curve_tolerance=0.05,
)

beam_radius controls strut radius in millimetres. node_radius optionally overrides the joint radius; if omitted, joints follow the beam field. curve_tolerance controls subdivision of beams that become curved under a non-linear map.

See 03_strut_lattices.py for the complete interactive catalog. To define your own normalized vertices and edges, continue with Custom unit cells.

isotruss names the SC+BCC+SCC graph. Equal beam radii do not by themselves guarantee an isotropic effective material. That claim requires an appropriate member-radius ratio and mechanical characterization.

The new graph presets retain explicit junctions:

Name

Vertices

Edges

Construction

isotruss

15

26

cube edges + center-to-corner + center-to-face-center

fluorite

22

32

FCC sites joined to eight tetrahedral sites

hex_prism_edge

32

42

extruded regular-hexagonal edge network

reentrant_hex_prism

32

42

extruded re-entrant hexagonal edge network

The counts describe one authored cell before neighboring periodic vertices are welded.

The two prism cells use a rectangular honeycomb supercell. For regular hexagons or the default re-entrant geometry, preserve the reference U/V pitch ratio:

ratio = mm.hex_prism_reference_aspect_ratio()
cell_map = mm.rectangular_cell_map(
    (pv.Vec3(0.0, 0.0, 0.0), pv.Vec3(30.0 * ratio, 30.0, 18.0)),
    cells=(3, 3, 3),
)
root = mm.hex_prism_edge(cell_map, beam_radius=0.6)

Changing that map ratio deliberately stretches the cell. For a parameterized re-entrant cell, use mm.reentrant_hex_prism_reference_aspect_ratio(...) with the same angle and rib ratio. The default (h/l=2), (-30^\circ) geometry follows the conventional re-entrant hexagonal parameterization described by Zhang and Yang.

Foams, prisms and tessellation cells#

The rest of the graph catalog adds foams, prism lattices, crystal lattices and a few more. You use them exactly like the cells above. Each one has its own builder, such as mm.weaire_phelan(...) or mm.hex_prism_diamond(...), and you can also pass its name to mm.graph_lattice(...).

Most of these cells were generated rather than typed in by hand, in one of three ways:

  • Foams come from Voronoi cells. Scatter a few points, called seeds, through the cell. Each seed’s Voronoi cell is the region of space closer to it than to any other seed. The edges where those regions meet become the struts.

  • Crystal lattices join neighbouring atom sites of a crystal with struts.

  • Prism and honeycomb lattices apply a rule, such as “keep every edge”, to a tessellation: a set of solid shapes that fill space with no gaps.

Custom unit cells shows how to use the same builders to make cells of your own.

Rhombic dodecahedron foam
Rhombic dodecahedron
Weaire-Phelan foam
Weaire-Phelan
Truncated cube lattice
Truncated cube
Column lattice
Column
Two-column lattice
Columns
Three-dimensional re-entrant lattice
3D re-entrant
Triangular prism edge lattice
Triangular prism
Rotated triangular prism lattice
Rotated triangular prism
Rotated square prism lattice
Rotated square prism
Hexagonal prism vertex centroid lattice
Hex-prism vertex-centroid
Hexagonal prism central axis lattice
Hex-prism central axis
Hexagonal diamond lattice
Hex-prism diamond (lonsdaleite)
Hexagonal Laves phase lattice
Hex-prism Laves
Tetrahedral-octahedral vertex centroid lattice
Tet-oct vertex-centroid
Octahedral face vertex centroid lattice
Oct vertex-centroid

The table lists how each cell is made. As in the table above, the counts are for one cell.

Name

Vertices

Edges

Construction

rhombic_dodecahedron

21

32

Voronoi edges of FCC sites

weaire_phelan

88

122

Voronoi edges of the eight A15 sites; four struts at every node

truncated_cube

24

36

edges of truncated cubes and octahedra; every strut in a cell face

column

11

10

a W column through the centre, tied to the cell corners by X struts in the top and bottom faces

columns

22

32

the column rule on squares turned 45°: two columns per cell, tied by a half-pitch square grid

reentrant_3d

56

60

the planar re-entrant pattern in U-W and V-W walls that share their W ribs

triangular_prism_edge

14

21

edges of triangular prisms, one edge family along U

rotated_triangular_prism_edge

14

21

the same turned 90°, one edge family along V

rotated_square_prism_edge

10

13

edges of square prisms turned 45° about W

hex_prism_vertex_centroid

27

52

each hexagonal prism’s centre joined to its twelve corners

hex_prism_central_axis

53

108

hexagonal-prism edges plus a W column per prism, joined to the cap corners by spokes

hex_prism_diamond

37

42

hexagonal diamond (lonsdaleite): tetrahedral bonds, puckered hexagons joined along W

hex_prism_laves

71

112

the small-atom net of the hexagonal (C14) Laves phase: corner- and face-sharing tetrahedra

tet_oct_vertex_centroid

35

86

every tetrahedron’s and octahedron’s centre in the tet-oct honeycomb joined to its corners

oct_vertex_centroid

46

96

the face centres of the tet-oct honeycomb’s octahedra joined to their three corners

Some familiar shapes are already in the catalog under another name. A lattice of truncated octahedra is the kelvin cell, and a square honeycomb made of struts is cubic. The Voronoi foams of simple cubic (SC) and body-centred cubic (BCC) seeds are cubic and kelvin as well.

mm.reentrant_3d(...) takes the same angle_degrees and rib_ratio as mm.reentrant_hex_prism(...). When you compress it along W, its walls fold inward along both U and V.

Some of these cells only keep their intended shape when the map’s cells have the right proportions: hexagons and triangles stay regular, crystal bonds meet at their ideal angles, and re-entrant cells show the requested angle. mm.reference_cell_size(name) returns those proportions as three numbers, one each for U, V and W. Scale them to the size you want and build the map from them:

u, v, w = mm.reference_cell_size("hex_prism_diamond")
pitch = 10.0 / v   # 10 mm along V
cell_map = mm.rectangular_cell_map(
    (pv.Vec3(0.0, 0.0, 0.0), pv.Vec3(3 * u * pitch, 3 * v * pitch, 3 * w * pitch)),
    cells=(3, 3, 3),
)
root = mm.hex_prism_diamond(cell_map, beam_radius=0.6)

Here pitch scales the proportions so each cell is 10 mm along V. The map holds three such cells along each axis.

Run 06_tessellation_cells.py to compare six of these cells, and a triangular wall honeycomb, side by side in the interactive preview.

Face and plate lattice catalog#

Face lattices thicken tiled center surfaces into walls. This is geometrically different from replacing the same diagram with beams.

Folded plate lattice
Folded plate (legacy `plate`)
Simple cubic plate lattice
Simple-cubic plate
Body-centered cubic plate lattice
Body-centered-cubic plate
Face-centered cubic plate lattice
Face-centered-cubic / octet plate
Cubic and octet hybrid plate lattice
Cubic+octet plate
Hexagonal wall honeycomb
Hexagonal wall honeycomb
Re-entrant wall honeycomb
Re-entrant wall honeycomb
Square wall honeycomb
Square honeycomb
Square wall honeycomb turned 45 degrees
Rotated square honeycomb
Triangular wall honeycomb
Triangular honeycomb
Triangular wall honeycomb turned 90 degrees
Rotated triangular honeycomb

The square and triangular honeycombs are the side walls of square and triangular prisms that fill space. The rotated versions are the same walls turned 45° (square) or 90° (triangular). Custom unit cells shows how they are made. For triangles with three equal sides, build the map with the proportions from mm.reference_cell_size(name), as shown above for the graph cells.

The crystallographic plate cells use the conventional plane families:

Name

Plate family

simple_cubic_plate

three orthogonal {100} families

body_centered_cubic_plate

six {110} families

face_centered_cubic_plate

four {111} families

cubic_octet_plate

combined {100}+{111} families

mm.octet_plate(...) is a documented alias for mm.face_centered_cubic_plate(...). The cubic+octet helper keeps the two wall thicknesses independent:

root = mm.cubic_octet_plate(
    cell_map,
    cubic_wall_thickness=0.75,  # mm
    octet_wall_thickness=0.55,  # mm
)

The independent thicknesses are important: cubic+octet plate studies use the family ratio as a mechanical design variable rather than treating the hybrid as one uniformly thick sheet. See Crook et al. for an experimental cubic+octet system and its manufacturing considerations.

The re-entrant honeycomb exposes its geometric controls directly:

ratio = mm.reentrant_hex_prism_reference_aspect_ratio(
    angle_degrees=-30.0,
    rib_ratio=2.0,
)
root = mm.reentrant_honeycomb(
    cell_map,
    wall_thickness=0.7,  # mm
    angle_degrees=-30.0,
    rib_ratio=2.0,       # h/l
)

Use the returned ratio when constructing the map if the requested member angle must be preserved. See 05_face_lattices.py for a runnable comparison.

Warning

Three-dimensional plate lattices can create closed cells that trap resin, powder, or support material. Confirm drainage and cleaning access for the intended manufacturing process. The catalog topologies do not add drain holes automatically.

Fill ordinary geometry#

Mapped structures are ordinary nodes, so lattice filling is an Intersection. Build a map over the target’s bounds, build the architected material, and clip it with the target geometry.

sphere = pv.Sphere(pv.Vec3(0.0, 0.0, 0.0), 16.0)
cell_map = mm.rectangular_cell_map(
    (pv.Vec3(-17.0, -17.0, -17.0), pv.Vec3(17.0, 17.0, 17.0)),
    cells=(4, 4, 4),
)
root = pv.Intersection(sphere, mm.gyroid(cell_map, wall_thickness=1.4))
Sphere filled with a gyroid
Gyroid clipped to a sphere
3DBenchy filled with a gyroid
3DBenchy with gyroid infill
Utah teapot filled with an octet lattice
Utah teapot with octet infill

For imported meshes, call prepare(...) before querying bounding_box(), then construct the rectangular map from the returned bounds. The complete examples are 04_lattice_in_shape.py, 10_benchy_gyroid_infill.py, and 11_teapot_lattice_infill.py.

Parameter summary#

Structure

Topology

Primary geometric controls

TPMS sheet

ImplicitUnitCell

wall_thickness, level, map cell count/spacing

TPMS solid

ImplicitUnitCell

level, map cell count/spacing

Graph lattice

GraphUnitCell

beam_radius, node_radius, curve_tolerance, map cell count/spacing

Plate or wall lattice

FaceUnitCell

wall_thickness, surface_mode, map pitch/aspect ratio

Re-entrant honeycomb

FaceUnitCell

wall_thickness, angle_degrees, rib_ratio, map pitch/aspect ratio

All of these scalar controls can also change across a design. Continue with Functionally graded metamaterial geometry for thickness, radius, spacing, and topology, or Attribute modeling for named material and process fields.