"""Tile sets for combinatorial design: cubic building blocks with labelled faces.
A tile is a cubic block of ``k^3`` voxels (its geometry) whose six faces carry integer
labels. Two tiles can be neighbours along an axis when the labels of the faces in
contact match: equal labels (``match="equal"``, Wang tiles), or opposite labels
(``match="opposite"``: a face that moves out against a face that moves in). An
assembly is an array of tile indices; it is compatible when every pair of neighbouring
tiles matches. Faces are numbered ``-x, +x, -y, +y, -z, +z`` (face ``2 a`` is the lower
face along axis ``a``, ``2 a + 1`` the upper one). Planar tile sets (``dims=2``) ignore
the z faces: their assemblies have one tile through the thickness.
Built-in sets:
``polarized_blocks``
The building blocks of combinatorial mechanical metamaterials (after Coulais et al.
2016): each block has a single deformation mode in which it elongates along its axis
and shrinks along the two others, or the reverse. Its faces move out or in
accordingly; neighbouring blocks are compatible when their common face moves the
same way (out of one block, into the other). Six tiles: three axes, two signs.
``pipe_tiles``
Nodes with channels (or struts) towards some of their faces; compatible
assemblies are networks without dead ends at the tile boundaries, with controlled
node degrees.
"""
from __future__ import annotations
import itertools
from dataclasses import dataclass, field
import numpy as np
FACES = ("-x", "+x", "-y", "+y", "-z", "+z")
MATCHES = ("equal", "opposite")
def _signed_permutations(dims: int) -> list[np.ndarray]:
"""Proper rotations of the cube (24), or the 4 rotations about z (dims=2), as
signed permutation matrices."""
out = []
for perm in itertools.permutations(range(3)):
for signs in itertools.product((1, -1), repeat=3):
m = np.zeros((3, 3), dtype=int)
for j in range(3):
m[j, perm[j]] = signs[j]
if round(np.linalg.det(m)) != 1:
continue
if dims == 2 and m[2, 2] != 1:
continue
out.append(m)
return out
def _rotate_faces(faces: np.ndarray, m: np.ndarray) -> np.ndarray:
"""Face labels after the rotation m: the face of direction m e carries the label of
the face of direction e."""
out = np.empty_like(faces)
for a in range(3):
j = int(np.flatnonzero(m[:, a])[0])
s = int(m[j, a])
for side in (0, 1): # 0: lower (-), 1: upper (+)
sigma = -1 if side == 0 else 1
new_side = 0 if sigma * s < 0 else 1
out[..., 2 * j + new_side] = faces[..., 2 * a + side]
return out
def _rotate_block(block: np.ndarray, m: np.ndarray) -> np.ndarray:
"""Voxels of a block after the rotation m (about the centre of the block)."""
perm = [int(np.flatnonzero(m[j])[0]) for j in range(3)]
out = np.transpose(block, perm)
for j in range(3):
if m[j, perm[j]] < 0:
out = np.flip(out, axis=j)
return np.ascontiguousarray(out)
[docs]
@dataclass
class TileSet:
"""Tiles with labelled faces, their geometry and their weights.
Parameters
----------
faces
Integer labels ``(n, 6)`` of the faces ``-x, +x, -y, +y, -z, +z``.
match
``equal`` or ``opposite``: rule for the labels of faces in contact.
voxels
Optional geometry ``(n, k, k, k)`` (``(n, k, k, 1)`` for planar sets): phase of
each voxel of each tile.
weights
Relative frequencies of the tiles in random choices (default: equal).
names
Tile names.
dims
3, or 2 for planar tile sets (z faces ignored).
"""
faces: np.ndarray
match: str = "equal"
voxels: np.ndarray | None = None
weights: np.ndarray | None = None
names: tuple[str, ...] | None = None
dims: int = 3
_compat: np.ndarray | None = field(default=None, init=False, repr=False)
def __post_init__(self) -> None:
self.faces = np.asarray(self.faces, dtype=np.int64).reshape(-1, 6)
n = len(self.faces)
if n < 1:
raise ValueError("a tile set needs at least one tile")
if self.match not in MATCHES:
raise ValueError(f"match: one of {MATCHES}, got {self.match!r}")
if self.dims not in (2, 3):
raise ValueError("dims: 2 or 3")
if self.voxels is not None:
self.voxels = np.ascontiguousarray(self.voxels, dtype=np.uint8)
if self.voxels.ndim != 4 or len(self.voxels) != n:
raise ValueError("voxels: an array (n_tiles, k, k, k)")
k = self.voxels.shape[1]
expected = (k, k, 1) if self.dims == 2 else (k, k, k)
if self.voxels.shape[1:] != expected:
raise ValueError(f"voxels: blocks of shape {expected}")
w = np.ones(n) if self.weights is None else np.asarray(self.weights, dtype=float)
if w.shape != (n,) or np.any(w < 0) or not np.any(w > 0):
raise ValueError("weights: one non-negative weight per tile, not all zero")
self.weights = w
if self.names is None:
self.names = tuple(f"t{i}" for i in range(n))
self.names = tuple(str(s) for s in self.names)
if len(self.names) != n:
raise ValueError("names: one per tile")
@property
def n_tiles(self) -> int:
return len(self.faces)
@property
def tile_size(self) -> int | None:
"""Voxels per tile edge (None without geometry)."""
return None if self.voxels is None else int(self.voxels.shape[1])
[docs]
def label_matches(self, upper, lower):
"""Whether an upper face label (of the lower tile) matches a lower face label."""
upper = np.asarray(upper)
lower = np.asarray(lower)
return upper == lower if self.match == "equal" else upper == -lower
[docs]
def compatibility(self) -> np.ndarray:
"""Boolean array ``(3, n, n)``: ``[a, A, B]`` when tile B may follow tile A along
axis a (planar sets: every pair along z)."""
if self._compat is None:
n = self.n_tiles
c = np.ones((3, n, n), dtype=bool)
for a in range(self.dims):
c[a] = self.label_matches(
self.faces[:, None, 2 * a + 1], self.faces[None, :, 2 * a]
)
self._compat = c
return self._compat
[docs]
def boundary_tiles(self, axis: int, side: int, label: int) -> np.ndarray:
"""Tiles whose face (axis, side) matches a boundary of the given label."""
face = self.faces[:, 2 * axis + side]
if side == 1:
return self.label_matches(face, label)
return self.label_matches(label, face)
[docs]
def mismatches(self, assembly, periodic: bool = True) -> int:
"""Number of incompatible pairs of neighbouring tiles."""
t = np.asarray(assembly, dtype=np.int64)
if t.ndim != 3:
raise ValueError("assembly: a 3D array of tile indices ((n0, n1, 1) in 2D)")
compat = self.compatibility()
bad = 0
for a in range(self.dims):
if t.shape[a] < 2 and not periodic:
continue
if periodic:
nxt = np.roll(t, -1, axis=a)
bad += int(np.count_nonzero(~compat[a][t, nxt]))
else:
lo = np.take(t, range(t.shape[a] - 1), axis=a)
hi = np.take(t, range(1, t.shape[a]), axis=a)
bad += int(np.count_nonzero(~compat[a][lo, hi]))
return bad
[docs]
def is_compatible(self, assembly, periodic: bool = True) -> bool:
return self.mismatches(assembly, periodic) == 0
[docs]
def assemble(self, assembly) -> np.ndarray:
"""Voxels of an assembly: the blocks of its tiles side by side."""
if self.voxels is None:
raise ValueError("this tile set has no geometry (voxels)")
t = np.asarray(assembly, dtype=np.int64)
n0, n1, n2 = t.shape
blocks = self.voxels[t] # (n0, n1, n2, k0, k1, k2)
k0, k1, k2 = self.voxels.shape[1:]
return np.ascontiguousarray(
blocks.transpose(0, 3, 1, 4, 2, 5).reshape(n0 * k0, n1 * k1, n2 * k2)
)
[docs]
def subset(self, keep) -> TileSet:
"""The tiles selected by a boolean mask or an index list."""
idx = np.arange(self.n_tiles)[np.asarray(keep)]
if idx.size == 0:
raise ValueError("subset: no tile left")
return TileSet(
self.faces[idx],
self.match,
None if self.voxels is None else self.voxels[idx],
self.weights[idx],
tuple(self.names[i] for i in idx),
self.dims,
)
[docs]
def with_rotations(self) -> TileSet:
"""The set closed under the rotations of the cube (about z for planar sets),
without duplicates; rotated tiles keep the weight of their original."""
faces, voxels, weights, names = [], [], [], []
seen = set()
for i in range(self.n_tiles):
for r, m in enumerate(_signed_permutations(self.dims)):
f = _rotate_faces(self.faces[i], m)
v = None if self.voxels is None else _rotate_block(self.voxels[i], m)
key = (tuple(f), None if v is None else v.tobytes())
if key in seen:
continue
seen.add(key)
faces.append(f)
voxels.append(v)
weights.append(self.weights[i])
names.append(self.names[i] if r == 0 else f"{self.names[i]}/r{r}")
return TileSet(
np.array(faces),
self.match,
None if self.voxels is None else np.array(voxels),
np.array(weights),
tuple(names),
self.dims,
)
# -- built-in sets -------------------------------------------------------------------------
def _centred_coordinates(k: int, dims: int) -> np.ndarray:
"""Coordinates of the voxel centres of a block, in units of the block edge, centred."""
c = (np.arange(k) + 0.5) / k - 0.5
kz = k if dims == 3 else 1
cz = c if dims == 3 else np.zeros(1)
return np.stack(np.meshgrid(c, c, cz, indexing="ij"), axis=-1).reshape(k, k, kz, 3)
[docs]
def polarized_blocks(size: int = 8, channel: float = 0.25, dims: int = 3) -> TileSet:
"""Blocks with one deformation mode: elongation along their axis and contraction
along the others (sign +), or the reverse (sign -).
The faces normal to the axis carry the sign of the mode, the others its opposite
(+1: the face moves out); faces in contact must move the same way, hence opposite
labels (``match="opposite"``). Along every line of blocks, the strain along the line
alternates in sign. The geometry is a solid block pierced along its axis by a
channel of radius ``channel`` (in block edges), which draws the orientation of the
block; replace it with the geometry of an actual building block if needed.
"""
if not 0.0 <= channel < 0.5:
raise ValueError("channel: a radius in [0, 0.5) block edges")
axes = range(dims)
faces, voxels, names = [], [], []
x = _centred_coordinates(int(size), dims)
for a in axes:
r2 = sum(x[..., b] ** 2 for b in range(dims) if b != a)
block = (r2 > channel**2).astype(np.uint8)
for s in (1, -1):
f = np.empty(6, dtype=np.int64)
for b in range(3):
f[2 * b] = f[2 * b + 1] = s if b == a else -s
if dims == 2:
f[4] = f[5] = 0
faces.append(f)
voxels.append(block)
names.append(f"{'xyz'[a]}{'+' if s > 0 else '-'}")
return TileSet(np.array(faces), "opposite", np.array(voxels), None, tuple(names), dims)
[docs]
def pipe_tiles(
size: int = 8,
radius: float = 0.2,
dims: int = 3,
*,
open_probability: float = 0.5,
degrees=None,
) -> TileSet:
"""Nodes joined to some of their faces by straight pipes (phase 1).
One tile per subset of open faces (64 in 3D, 16 in 2D); open faces carry the label
1 and must face open faces (``match="equal"``). Each open face independently has
probability ``open_probability`` (tile weights ``p^m (1 - p)^(2 d - m)`` for ``m``
open faces); ``degrees`` restricts the numbers of open faces allowed (e.g. no 1 to
forbid dead ends).
"""
if not 0.0 < radius < 0.5:
raise ValueError("radius: in (0, 0.5) block edges")
if not 0.0 < open_probability < 1.0:
raise ValueError("open_probability: in (0, 1)")
n_faces = 2 * dims
x = _centred_coordinates(int(size), dims)
faces, voxels, weights, names = [], [], [], []
for mask in range(2**n_faces):
open_faces = [f for f in range(n_faces) if mask >> f & 1]
m = len(open_faces)
if degrees is not None and m not in set(degrees):
continue
f = np.zeros(6, dtype=np.int64)
block = np.zeros(x.shape[:3], dtype=bool)
for face in open_faces:
f[face] = 1
a, side = divmod(face, 2)
sign = 1.0 if side else -1.0
along = x[..., a] * sign
r2 = sum(x[..., b] ** 2 for b in range(dims) if b != a)
block |= (along >= -radius) & (r2 <= radius**2)
if m:
block |= (x[..., :dims] ** 2).sum(axis=-1) <= radius**2
faces.append(f)
voxels.append(block.astype(np.uint8))
weights.append(open_probability**m * (1.0 - open_probability) ** (n_faces - m))
names.append("".join(FACES[i] for i in open_faces) or "empty")
if not faces:
raise ValueError("degrees: no tile left")
return TileSet(
np.array(faces), "equal", np.array(voxels), np.array(weights), tuple(names), dims
)
TILE_SETS = {"polarized": polarized_blocks, "pipes": pipe_tiles}