Source code for morphogen.models.hierarchical

"""Hierarchical lattices of tubes: frames of generation G (Rayneau-Kirkhope, Mao & Farr,
"Ultralight fractal structures from hollow tubes", Phys. Rev. Lett. 109, 204301, 2012).

A frame of generation 1 between two nodes is a column of ``n`` regular octahedra
(triangular antiprisms: consecutive triangles turned by 60 degrees) closed by two
regular tetrahedra whose apexes are the nodes; its length is ``sqrt(2/3) (n + 2) a``
for an edge ``a``. Under compression along the column, the edges of its triangles carry
tension and its lateral and end edges compression. A frame of generation G replaces
each compressed edge by a frame of generation G - 1 of the same length; a frame of
generation 0 is a tube. The lattice joins the nodes of a face-centred cubic lattice to
their 12 nearest and 6 next-nearest neighbours with such frames, made of solid or
hollow tubes. For hollow tubes, the volume of material that carries a load index ``f``
without buckling scales as ``f^((G+2)/(G+3))``, against ``f^(1/2)`` for solid struts:
the hierarchy makes very light structures stable.
"""

from __future__ import annotations

import itertools
import json
import math
from dataclasses import dataclass
from functools import lru_cache
from typing import ClassVar

import numpy as np

from morphogen._utils import check_positive
from morphogen.domain import Domain
from morphogen.models.base import Model, model_from_config, param, register
from morphogen.models.combination import Combined
from morphogen.models.union import PrimitiveUnion
from morphogen.primitives import Segments
from morphogen.seeding import SeedLike, make_rng

_H = math.sqrt(2.0 / 3.0)  # height of a regular octahedron or tetrahedron, per edge

#: Nodes of the face-centred cubic cell, and half of the bonds of each (the others are
#: those of the neighbouring nodes): nearest neighbours (12) and next-nearest (6).
FCC_NODES = np.array([[0, 0, 0], [0.5, 0.5, 0], [0.5, 0, 0.5], [0, 0.5, 0.5]], dtype=float)
_NN = [
    v
    for v in itertools.product((-0.5, 0.0, 0.5), repeat=3)
    if sum(x != 0 for x in v) == 2 and next(x for x in v if x != 0) > 0
]
NEAREST = np.array(_NN, dtype=float)
NEXT_NEAREST = np.eye(3)
CONNECTIONS = ("nn+nnn", "nn", "nnn")


def _basis(axis: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
    """Two unit vectors orthogonal to ``axis`` (unit) and to each other."""
    ref = np.eye(3)[int(np.argmin(np.abs(axis)))]
    e1 = np.cross(axis, ref)
    e1 /= np.linalg.norm(e1)
    return e1, np.cross(axis, e1)


[docs] def frame(p, q, generation: int, cells) -> tuple[list, list]: """Tubes of a frame of generation ``generation`` from ``p`` to ``q`` (``cells``: octahedra of the frames of each generation, outermost first): their ends, and the generation of the frame that holds each (for radii by generation).""" p, q = np.asarray(p, dtype=float), np.asarray(q, dtype=float) if generation == 0: return [(p, q)], [0] n = int(cells[0]) axis = q - p length = float(np.linalg.norm(axis)) e3 = axis / length e1, e2 = _basis(e3) edge = length / (_H * (n + 2)) radius = edge / math.sqrt(3.0) # of the circle through the corners of a triangle layers = [] for k in range(n + 1): centre = p + _H * edge * (k + 1) * e3 angles = (k % 2) * math.pi / 3.0 + 2.0 * math.pi * np.arange(3) / 3.0 ring = np.cos(angles)[:, None] * e1 + np.sin(angles)[:, None] * e2 layers.append(centre + radius * ring) tubes, owners = [], [] for layer in layers: # the triangles: tension, tubes of this frame for j in range(3): tubes.append((layer[j], layer[(j + 1) % 3])) owners.append(generation) compressed = [(p, v) for v in layers[0]] + [(v, q) for v in layers[-1]] for below, above in itertools.pairwise(layers): for v in below: # to the two nearest corners of the next triangle near = np.argsort(np.linalg.norm(above - v, axis=1))[:2] compressed += [(v, above[i]) for i in near] for a, b in compressed: t, o = frame(a, b, generation - 1, cells[1:]) tubes += t owners += o return tubes, owners
@lru_cache(maxsize=32) def _cell_fraction(config: str, n: int) -> float: """Solid fraction of a unit cell of a hierarchical lattice (voxel estimate).""" model = model_from_config(json.loads(config)) unit = Domain.cube(model.cell_size, periodic=True) micro = model.generate(unit, 0) return float(micro.voxelize((n, n, n)).data.astype(bool).mean())
[docs] @register @dataclass(frozen=True) class HierarchicalLattice(Model): """Hierarchical lattice: frames of generation G of (hollow) tubes on an fcc lattice. The nodes of the face-centred cubic lattice of edge ``cell_size`` are joined to their nearest (``nn``: the octet truss) and next-nearest (``nnn``: the cube edges) neighbours by frames of generation ``generations`` (see the module): columns of ``cells`` regular octahedra whose compressed edges are frames of the generation below, recursively (``cells``: one number, or one per generation from the outermost). Generation 0 is a plain strut lattice. Tubes of ``tube_radius`` (one value, or one per generation of the frames that hold them, from G down to 0), hollow with ``wall_thickness``. """ name = "hierarchical_lattice" phases: ClassVar[dict[int, str]] = {0: "void", 1: "tubes"} count_label = "unit cells" cell_size: float = param(1.0, doc="Edge of the cubic cell of the fcc lattice", unit="length") generations: int = param(1, doc="Generation G of the frames (0: tubes)", kind="int") cells: tuple | int = param( 4, doc="Octahedra per frame: one number, or one per generation (outermost first)", kind="json", ) # fmt: skip tube_radius: tuple | float = param( 0.01, doc="Radius of the tubes, or one per generation (G down to 0)", kind="json" ) wall_thickness: float | None = param( None, doc="Wall thickness of hollow tubes (default: solid)", unit="length" ) connections: str = param( "nn+nnn", doc="Bonds: nn+nnn (nearest and next-nearest), nn or nnn", kind="str" ) def _validate(self) -> None: check_positive(self.cell_size, "cell_size") if not 0 <= self.generations <= 3: raise ValueError("generations: from 0 to 3") if self.connections not in CONNECTIONS: raise ValueError(f"connections: one of {list(CONNECTIONS)}") counts = self.cells_per_generation if len(counts) != self.generations or any(n < 1 for n in counts): raise ValueError("cells: a positive number, or one per generation") radii = self.radii if len(radii) != self.generations + 1 or any(not r > 0 for r in radii): raise ValueError("tube_radius: a positive radius, or one per generation (G to 0)") if self.wall_thickness is not None: check_positive(self.wall_thickness, "wall_thickness") if self.wall_thickness >= min(radii): raise ValueError("wall_thickness: smaller than the tube radius") shortest = self.edges[-1] if 4.0 * radii[-1] > shortest: raise ValueError( f"tube_radius: the finest tubes ({shortest:.4g} long) would merge into " "blobs: thinner tubes, larger cells, fewer octahedra or generations" ) @property def cells_per_generation(self) -> tuple[int, ...]: c = self.cells if np.ndim(c) == 0: return (int(c),) * self.generations return tuple(int(v) for v in c) @property def radii(self) -> tuple[float, ...]: """Tube radius of each generation, from G down to 0.""" r = self.tube_radius if np.ndim(r) == 0: return (float(r),) * (self.generations + 1) return tuple(float(v) for v in r) @property def edges(self) -> list[float]: """Length of the edges of the frames of each generation, from the shortest bond (G) down to the finest tubes (0).""" bond = self.cell_size * (1.0 if self.connections == "nnn" else math.sqrt(0.5)) out = [bond] for n in self.cells_per_generation: out.append(out[-1] / (_H * (n + 2))) return out
[docs] def bonds(self) -> tuple[np.ndarray, np.ndarray]: """Ends of the bonds of one cell, in units of the cell size.""" vectors = [] if self.connections in ("nn+nnn", "nn"): vectors.append(NEAREST) if self.connections in ("nn+nnn", "nnn"): vectors.append(NEXT_NEAREST) v = np.concatenate(vectors) start = np.repeat(FCC_NODES, len(v), axis=0) return start, start + np.tile(v, (len(FCC_NODES), 1))
[docs] def unit_tubes(self) -> Segments: """Tubes of one cell (anchored at the origin), with their radii.""" start, end = self.bonds() tubes, owners = [], [] for p, q in zip(start * self.cell_size, end * self.cell_size, strict=True): t, o = frame(p, q, self.generations, self.cells_per_generation) tubes += t owners += o ends = np.array(tubes) radii = np.array(self.radii[::-1])[np.array(owners)] # owners: generation, 0 finest return Segments(ends[:, 0], ends[:, 1], radii, round_caps=True)
[docs] def generate(self, domain: Domain, seed: SeedLike = None): _, seed_info = make_rng(seed) a = self.cell_size if domain.periodic: ratio = domain.lengths / a if np.any(np.abs(ratio - np.rint(ratio)) > 1e-6 * np.maximum(ratio, 1.0)): raise ValueError( "hierarchical_lattice: a periodic domain must contain a whole number of cells" ) unit = self.unit_tubes() lower = domain.lower - (0.0 if domain.periodic else a) upper = domain.upper + (0.0 if domain.periodic else a) lo = np.floor(lower / a).astype(int) hi = np.ceil(upper / a).astype(int) - 1 shifts = np.array( list(itertools.product(*[range(lo[d], max(hi[d], lo[d]) + 1) for d in range(3)])), dtype=float, ) shifts *= a segments = Segments( (shifts[:, None, :] + unit.start[None]).reshape(-1, 3), (shifts[:, None, :] + unit.end[None]).reshape(-1, 3), np.tile(unit.radii, len(shifts)), round_caps=True, ) if not domain.periodic: seg_lo, seg_hi = segments.bounds() segments = segments.subset( np.all((seg_hi >= domain.lower) & (seg_lo <= domain.upper), axis=1) ) outer = PrimitiveUnion(domain, segments=segments, model=self, seed=seed_info) if self.wall_thickness is None: return outer from morphogen.models.nested import bores_of bores = bores_of(outer, self.wall_thickness) return Combined(domain, "difference", [outer, bores], model=self, seed=seed_info)
[docs] def expected_count(self, domain: Domain) -> float: return domain.volume / self.cell_size**3
[docs] def solid_fraction(self, n: int = 96) -> float: """Solid fraction (voxel estimate on ``n^3`` voxels of a cell).""" return _cell_fraction(json.dumps(self.to_config(), sort_keys=True), int(n))
[docs] def theory(self, domain: Domain | None = None) -> dict[str, float]: """Number and length of the tubes; the volume fraction (estimated on voxels).""" unit = self.unit_tubes() length = float(unit.lengths.sum()) edges = self.edges out = { "tubes_per_cell": float(len(unit)), "tube_length_per_cell": length, "finest_edge": edges[-1], } h = edges[-1] / 6.0 # a few voxels across the finest tubes n = int(min(256, max(48, math.ceil(self.cell_size / max(h, 1e-12))))) out["volume_fraction"] = self.solid_fraction(n) return out