"""Periodic pin-jointed frameworks: strut lattices with defects, and their rigidity.
A framework is a set of nodes in a periodic box and of bars joining pairs of nodes, the
second end possibly in a neighbouring copy of the box (``shift``). Lattices are built
from the unit cells of :mod:`morphogen.models.lattice`; defects are struts removed at
random (dilution) and nodes displaced at random (perturbation).
Rigidity (Maxwell 1864, Calladine 1978, Pellegrino and Calladine 1986; periodic
frameworks: Guest and Hutchinson 2003). The compatibility matrix ``A`` maps periodic
node displacements to bar extensions, and ``B`` maps a macroscopic strain ``E`` to the
extensions ``n . E L`` it imposes on the bars. Then
* mechanisms (periodic displacement modes extending no bar, rigid translations
excluded): ``m = 3 j - 3 - rank(A)``;
* states of self-stress (bar tensions in equilibrium without load):
``s = b - rank(A)``, so that ``m - s = 3 j - 3 - b`` (Maxwell-Calladine);
* floppy macroscopic strains (accommodated by some displacement without extending any
bar): ``6 - rank([A B]) + rank(A)``.
A lattice whose macroscopic strains all stretch bars is stretching-dominated: its
stiffness scales with the relative density, against its square for bending-dominated
lattices (Deshpande, Ashby and Fleck 2001). Maxwell's count requires a mean coordination
of at least 6 in 3D for large frameworks.
"""
from __future__ import annotations
from dataclasses import dataclass
import numpy as np
from scipy.sparse import coo_matrix
from scipy.sparse.csgraph import connected_components
from morphogen.primitives import Segments
[docs]
@dataclass
class Framework:
"""Nodes in a periodic box and bars from ``nodes[p]`` to ``nodes[q] + shift * box``."""
nodes: np.ndarray
bars: np.ndarray
shifts: np.ndarray
box: np.ndarray
def __post_init__(self) -> None:
self.nodes = np.asarray(self.nodes, dtype=float).reshape(-1, 3)
self.bars = np.asarray(self.bars, dtype=np.int64).reshape(-1, 2)
self.shifts = np.asarray(self.shifts, dtype=np.int64).reshape(-1, 3)
self.box = np.asarray(self.box, dtype=float).reshape(3)
if len(self.bars) != len(self.shifts):
raise ValueError("bars and shifts: same length")
if len(self.bars) and (self.bars.min() < 0 or self.bars.max() >= len(self.nodes)):
raise ValueError("bars: node indices out of range")
# -- construction --------------------------------------------------------------------
[docs]
@classmethod
def lattice(cls, cell: str, n_cells=1, cell_size: float = 1.0) -> Framework:
"""The periodic lattice of ``n_cells`` unit cells (cubic, bcc, fcc, octet, kelvin,
diamond or pyrochlore: :data:`morphogen.models.lattice.CELLS`)."""
from morphogen.models.lattice import CELLS, unit_cell_struts # (models import us)
if cell not in CELLS:
raise ValueError(f"cell: one of {CELLS}")
n = np.broadcast_to(np.asarray(n_cells, dtype=int), (3,))
if np.any(n < 1):
raise ValueError("n_cells: at least one cell along each axis")
unit = unit_cell_struts(cell) # fractional coordinates, (s, 2, 3)
offsets = np.stack(np.meshgrid(*[np.arange(k) for k in n], indexing="ij"), -1)
ends = (offsets.reshape(-1, 1, 1, 3) + unit[None]).reshape(-1, 2, 3)
# the nodes of the cells are multiples of 1/8 of their edge (1/2 for the cubic
# lattices, 1/4 for the Kelvin and diamond cells, 1/8 for the pyrochlore)
keys = np.mod(np.rint(ends * 8).astype(np.int64), 8 * n)
wrapped = keys / 8.0
flat = keys.reshape(-1, 3)
uniq, inverse = np.unique(flat, axis=0, return_inverse=True)
ids = inverse.reshape(-1, 2)
shifts = np.rint((ends[:, 1] - wrapped[:, 1]) / n).astype(np.int64) - np.rint(
(ends[:, 0] - wrapped[:, 0]) / n
).astype(np.int64)
frame = cls(uniq / 8.0 * cell_size, ids, shifts, n * float(cell_size))
return frame._deduplicated()
def _deduplicated(self) -> Framework:
"""Remove repeated bars (a bar p-q with shift s is the bar q-p with shift -s)."""
p, q = self.bars[:, 0], self.bars[:, 1]
s = self.shifts
# orient each bar canonically: p < q, or p == q with a positive first non-zero shift
first = np.argmax(s != 0, axis=1)
neg = s[np.arange(len(s)), first] < 0
flip = (p > q) | ((p == q) & neg)
pp = np.where(flip, q, p)
qq = np.where(flip, p, q)
ss = np.where(flip[:, None], -s, s)
key = np.column_stack([pp, qq, ss])
_, idx = np.unique(key, axis=0, return_index=True)
idx.sort()
keep = idx[~((pp[idx] == qq[idx]) & np.all(ss[idx] == 0, axis=1))] # no zero bars
return Framework(self.nodes, np.column_stack([pp, qq])[keep], ss[keep], self.box)
# -- description ---------------------------------------------------------------------
@property
def n_nodes(self) -> int:
return len(self.nodes)
@property
def n_bars(self) -> int:
return len(self.bars)
[docs]
def degrees(self) -> np.ndarray:
return np.bincount(self.bars.ravel(), minlength=self.n_nodes)
[docs]
def coordination(self) -> float:
"""Mean number of bars per node, ``Z = 2 b / j``."""
return 2.0 * self.n_bars / self.n_nodes if self.n_nodes else 0.0
[docs]
def vectors(self) -> np.ndarray:
"""Bar vectors ``(b, 3)``."""
p, q = self.bars[:, 0], self.bars[:, 1]
return self.nodes[q] + self.shifts * self.box - self.nodes[p]
[docs]
def components(self) -> np.ndarray:
"""Connected component of every node (through the periodic boundaries)."""
p, q = self.bars[:, 0], self.bars[:, 1]
graph = coo_matrix((np.ones(len(p)), (p, q)), shape=(self.n_nodes, self.n_nodes))
return connected_components(graph, directed=False)[1]
# -- transformations -----------------------------------------------------------------
[docs]
def with_bars(self, keep) -> Framework:
"""The framework with the selected bars only (same nodes)."""
keep = np.asarray(keep)
return Framework(self.nodes, self.bars[keep], self.shifts[keep], self.box)
[docs]
def without_isolated_nodes(self) -> Framework:
used = np.zeros(self.n_nodes, dtype=bool)
used[self.bars.ravel()] = True
index = np.cumsum(used) - 1
return Framework(self.nodes[used], index[self.bars], self.shifts, self.box)
[docs]
def pruned(self, min_degree: int = 2) -> Framework:
"""Remove, repeatedly, the bars at nodes of fewer than ``min_degree`` bars."""
frame = self
while frame.n_bars:
deg = frame.degrees()
weak = deg < min_degree
bad = weak[frame.bars[:, 0]] | weak[frame.bars[:, 1]]
if not bad.any():
break
frame = frame.with_bars(~bad)
return frame.without_isolated_nodes()
[docs]
def largest_component(self) -> Framework:
if self.n_bars == 0:
return self.without_isolated_nodes()
comp = self.components()
sizes = np.bincount(comp[self.bars[:, 0]], minlength=comp.max() + 1)
keep = comp[self.bars[:, 0]] == np.argmax(sizes)
return self.with_bars(keep).without_isolated_nodes()
[docs]
def diluted(
self,
rng: np.random.Generator,
*,
coordination: float | None = None,
fraction: float | None = None,
min_degree: int = 3,
) -> Framework:
"""Struts removed at random.
With ``coordination``: until the mean coordination reaches the target, never
below ``min_degree`` bars at a node (the target may not be reached). With
``fraction``: that fraction of the bars, then dangling bars are pruned. The
largest connected component is kept.
"""
if (coordination is None) == (fraction is None):
raise ValueError("give exactly one of 'coordination' and 'fraction'")
if fraction is not None:
if not 0.0 <= fraction < 1.0:
raise ValueError("fraction: in [0, 1)")
keep = np.ones(self.n_bars, dtype=bool)
keep[rng.permutation(self.n_bars)[: round(fraction * self.n_bars)]] = False
return self.with_bars(keep).pruned(2).largest_component()
target = round(float(coordination) * self.n_nodes / 2.0)
deg = self.degrees().copy()
keep = np.ones(self.n_bars, dtype=bool)
n_bars = self.n_bars
for k in rng.permutation(self.n_bars):
if n_bars <= target:
break
p, q = self.bars[k]
need = 2 if p == q else 1 # a self-bar counts twice at its node
if deg[p] - need >= min_degree and deg[q] - need >= min_degree:
keep[k] = False
deg[p] -= 1
deg[q] -= 1
n_bars -= 1
return self.with_bars(keep).largest_component()
[docs]
def perturbed(self, rng: np.random.Generator, amplitude: float) -> Framework:
"""Nodes displaced uniformly in balls of radius ``amplitude``."""
v = rng.standard_normal((self.n_nodes, 3))
v /= np.linalg.norm(v, axis=1, keepdims=True)
r = amplitude * rng.random(self.n_nodes) ** (1.0 / 3.0)
return Framework(self.nodes + v * r[:, None], self.bars, self.shifts, self.box)
[docs]
def segments(self, radius: float, origin=(0.0, 0.0, 0.0)) -> Segments:
"""Struts as round-capped cylinders (periodic images are added when needed)."""
start = self.nodes[self.bars[:, 0]] + np.asarray(origin, dtype=float)
return Segments(
start, start + self.vectors(), np.full(self.n_bars, float(radius)), round_caps=True
)
# -- rigidity ------------------------------------------------------------------------
[docs]
def compatibility(self) -> tuple[np.ndarray, np.ndarray]:
"""Dense matrices ``A (b, 3 j)`` and ``B (b, 6)`` (strains 11, 22, 33, 23, 13, 12,
shear components counted twice)."""
v = self.vectors()
length = np.linalg.norm(v, axis=1)
if np.any(length <= 0):
raise ValueError("bars of zero length")
n = v / length[:, None]
a = np.zeros((self.n_bars, 3 * self.n_nodes))
rows = np.arange(self.n_bars)
for d in range(3):
np.add.at(a, (rows, 3 * self.bars[:, 1] + d), n[:, d])
np.add.at(a, (rows, 3 * self.bars[:, 0] + d), -n[:, d])
b = np.column_stack(
[
n[:, 0] * v[:, 0],
n[:, 1] * v[:, 1],
n[:, 2] * v[:, 2],
n[:, 1] * v[:, 2] + n[:, 2] * v[:, 1],
n[:, 0] * v[:, 2] + n[:, 2] * v[:, 0],
n[:, 0] * v[:, 1] + n[:, 1] * v[:, 0],
]
)
return a, b / np.mean(length)
[docs]
def rigidity(self, tol: float = 1e-9) -> dict:
"""Mechanisms, states of self-stress and floppy macroscopic strains (SVD ranks)."""
a, b = self.compatibility()
def rank(m):
if m.size == 0:
return 0
s = np.linalg.svd(m, compute_uv=False)
return int(np.sum(s > tol * max(1.0, s[0])))
ra = rank(a)
rab = rank(np.hstack([a, b]))
mechanisms = 3 * self.n_nodes - 3 - ra
floppy = 6 - (rab - ra)
return {
"n_nodes": self.n_nodes,
"n_bars": self.n_bars,
"coordination": self.coordination(),
"mechanisms": int(mechanisms),
"self_stresses": int(self.n_bars - ra),
"floppy_strains": int(floppy),
"stretching_dominated": bool(floppy == 0),
}
[docs]
def to_dict(self) -> dict:
return {
"nodes": self.nodes.tolist(),
"bars": self.bars.tolist(),
"shifts": self.shifts.tolist(),
"box": self.box.tolist(),
}
@classmethod
def from_dict(cls, data: dict) -> Framework:
return cls(data["nodes"], data["bars"], data["shifts"], data["box"])