Source code for morphogen.models.lattice

"""Strut (beam) lattices: periodic arrangements of cylindrical struts."""

from __future__ import annotations

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

import numpy as np
from scipy import optimize

from morphogen._utils import check_fraction, check_positive
from morphogen.domain import Domain
from morphogen.kernels.union import UnionAccelerator
from morphogen.models.affine import ANISOTROPY, Anisotropy, anisotropic
from morphogen.models.base import Model, param, register
from morphogen.models.union import PrimitiveUnion
from morphogen.primitives import Segments, with_periodic_images
from morphogen.seeding import SeedLike, make_rng

_CORNERS = np.array(list(itertools.product((0.0, 1.0), repeat=3)))
_FACE_CENTERS = np.array(
    [
        [0.5, 0.5, 0.0],
        [0.5, 0.5, 1.0],
        [0.5, 0.0, 0.5],
        [0.5, 1.0, 0.5],
        [0.0, 0.5, 0.5],
        [1.0, 0.5, 0.5],
    ]
)
_BODY_CENTER = np.array([[0.5, 0.5, 0.5]])


def _pairs_at(nodes_a, nodes_b, distance, same: bool):
    """Pairs of nodes (one from each set) at the given distance, in the unit cell."""
    out = []
    for i, p in enumerate(nodes_a):
        for j, q in enumerate(nodes_b):
            if same and j <= i:
                continue
            if abs(np.linalg.norm(p - q) - distance) < 1e-9:
                out.append((p, q))
    return out


[docs] def unit_cell_struts(cell: str) -> np.ndarray: """Struts of a unit cell in fractional coordinates, shape (n, 2, 3).""" h = math.sqrt(0.5) if cell == "cubic": pairs = _pairs_at(_CORNERS, _CORNERS, 1.0, True) elif cell == "bcc": pairs = _pairs_at(_BODY_CENTER, _CORNERS, math.sqrt(3.0) / 2.0, False) elif cell == "fcc": pairs = _pairs_at(_CORNERS, _FACE_CENTERS, h, False) elif cell == "octet": pairs = _pairs_at(_CORNERS, _FACE_CENTERS, h, False) pairs += _pairs_at(_FACE_CENTERS, _FACE_CENTERS, h, True) elif cell == "kelvin": # edges of the truncated octahedron around the body centre (Voronoi cell of the # bcc lattice): its vertices are the permutations of (0, +-1/4, +-1/2), its # square faces lie on the faces of the cell signs = itertools.product((-1.0, 1.0), repeat=2) base = {p for a, b in signs for p in itertools.permutations((0.0, 0.25 * a, 0.5 * b))} vertices = 0.5 + np.array(sorted(base)) pairs = _pairs_at(vertices, vertices, 0.25 * math.sqrt(2.0), True) elif cell == "diamond": # two face-centred lattices a quarter of the diagonal apart: each node of one # joined to its four neighbours of the other, at the corners of a tetrahedron # (coordination 4, bending-dominated: the honeycomb of space) sites = np.vstack([_CORNERS, _FACE_CENTERS]) inner = np.array([[0.25, 0.25, 0.25], [0.75, 0.75, 0.25], [0.75, 0.25, 0.75], [0.25, 0.75, 0.75]]) # fmt: skip pairs = _pairs_at(inner, sites, 0.25 * math.sqrt(3.0), False) elif cell == "pyrochlore": # tetrahedra joined by their corners (the middles of the bonds of the diamond # lattice): six struts per node along three straight lines, coordination 6, # stretching-dominated with half the struts of the octet truss: the kagome of # space. The origin is at an eighth of the diagonal: every tetrahedron in the cell pairs = [] centres = np.array([[0.0, 0.0, 0.0], [0.5, 0.5, 0.0], [0.5, 0.0, 0.5], [0.0, 0.5, 0.5]]) even = np.array([[1, 1, 1], [1, -1, -1], [-1, 1, -1], [-1, -1, 1]]) / 8.0 for centre in centres: for origin, corners in ((0.125, even), (0.375, -even)): vertices = centre + origin + corners pairs += _pairs_at(vertices, vertices, 0.25 * math.sqrt(2.0), True) else: raise ValueError(f"cell: expected one of {sorted(CELLS)}, got {cell!r}") return np.array([[p, q] for p, q in pairs], dtype=float)
CELLS = ("cubic", "bcc", "fcc", "octet", "kelvin", "diamond", "pyrochlore") def _unique_segments(start: np.ndarray, end: np.ndarray, scale: float): """Remove duplicated struts (shared by neighbouring cells).""" a = np.round(start / scale, 9) b = np.round(end / scale, 9) # orient each strut so that its first endpoint is the lexicographically smaller one diff = b - a first = np.argmax(diff != 0, axis=1) swap = diff[np.arange(len(diff)), first] < 0 lo = np.where(swap[:, None], b, a) hi = np.where(swap[:, None], a, b) _, idx = np.unique(np.hstack([lo, hi]), axis=0, return_index=True) idx.sort() return start[idx], end[idx]
[docs] def lattice_struts(cell: str, cell_size: float, lower, upper) -> tuple[np.ndarray, np.ndarray]: """All struts of the lattice anchored at the origin whose cells meet [lower, upper].""" unit = unit_cell_struts(cell) * cell_size lo_idx = np.floor(np.asarray(lower) / cell_size).astype(int) hi_idx = np.ceil(np.asarray(upper) / cell_size).astype(int) - 1 ranges = [range(lo_idx[a], max(hi_idx[a], lo_idx[a]) + 1) for a in range(3)] shifts = np.array(list(itertools.product(*ranges)), dtype=float) * cell_size start = (shifts[:, None, :] + unit[None, :, 0, :]).reshape(-1, 3) end = (shifts[:, None, :] + unit[None, :, 1, :]).reshape(-1, 3) return _unique_segments(start, end, cell_size)
#: Offset of the lattice from the voxels of the fraction estimates, in voxels: off the #: symmetries of the cells, so that the voxels sample the struts as if at random. _JITTER = np.array([math.sqrt(2.0) - 1.0, math.sqrt(3.0) - 1.0, math.sqrt(5.0) - 2.0]) / 2.0
[docs] def lattice_fraction(cell: str, radius: float, n: int | None = None) -> float: """Solid volume fraction of a lattice of unit cell size 1 (voxel estimate).""" if n is None: n = int(np.clip(math.ceil(10.0 / radius), 48, 256)) unit = Domain.cube(1.0, periodic=True) start, end = lattice_struts(cell, 1.0, unit.lower, unit.upper) shift = _JITTER / n # voxels aligned with the struts would count them in batches seg = Segments(start - shift, end - shift, np.full(len(start), radius), round_caps=True) seg = with_periodic_images(seg, unit) acc = UnionAccelerator(None, seg, unit.lower, unit.upper, min_cell=2.0 / n) counts = acc.count(unit.lower, np.full(3, 1.0 / n), (n, n, n), 1) return float(counts.mean())
[docs] @lru_cache(maxsize=512) def strut_fraction(cell: str, r: float, t: float = 0.0, n: int | None = None) -> float: """Solid fraction of a lattice of unit cell size 1, struts of radius ``r`` hollow with walls ``t`` (0: solid): the union of the struts minus that of their bores. Exact for the cubic cell, a voxel estimate on ``n^3`` voxels otherwise (default: 8 voxels across the walls of hollow struts, 10 across the radius of solid ones).""" hollow = 0 < t < r if cell == "cubic": # three orthogonal cylinders per node, minus their overlaps def union(x): return 3.0 * math.pi * x * x - 8.0 * math.sqrt(2.0) * x**3 else: if n is None: n = int(np.clip(math.ceil(8.0 / t if hollow else 10.0 / r), 48, 256)) def union(x): return lattice_fraction(cell, x, n) return union(r) - (union(r - t) if hollow else 0.0)
[docs] @lru_cache(maxsize=128) def strut_radius(cell: str, target: float, t: float = 0.0) -> float: """Radius of the struts (unit cell size) of a lattice of solid fraction ``target``, hollow with walls ``t``. The fraction of solid struts grows with their radius; that of hollow struts peaks once their bores start to fill the cell: the radius is taken below the peak.""" lo, hi = max(1e-4, 1.0001 * t), 0.499 if t > 0: radii = np.linspace(lo, hi, 25) k = int(np.argmax([strut_fraction(cell, r, t, 64) for r in radii])) hi = float(radii[max(k, 1)]) top = strut_fraction(cell, hi, t) if top <= target: reach = f"hollow struts with walls of {t:.3g} cell" if t > 0 else "this lattice" raise ValueError(f"volume_fraction: at most {top:.3g} for {reach}") return float(optimize.brentq(lambda r: strut_fraction(cell, r, t) - target, lo, hi, xtol=1e-5))
[docs] @register @anisotropic @dataclass(frozen=True) class StrutLattice(Model): """Lattice of cylindrical struts with spherical nodes (spherocylinders). Cells: ``cubic`` (cube edges), ``bcc`` (body diagonals), ``fcc`` (face diagonals), ``octet`` (face diagonals and inner octahedron), ``kelvin`` (edges of the Kelvin foam: truncated octahedra on a bcc lattice, 24 struts per cell). Give the strut radius or the target relative density (solid volume fraction). With ``wall_thickness``, the struts are hollow tubes: their union minus the union of their bores (which join at the nodes). In non-periodic domains, the lattice may be turned (``rotation``: Bunge angles of its axes in those of the sample; it is then anchored at the centre of the domain) and graded: with ``radius_gradient`` (the radii at the lower and upper faces of the domain along ``gradient_axis``), each strut takes the radius interpolated linearly at its midpoint, a functionally graded lattice. """ name = "strut_lattice" phases: ClassVar[dict[int, str]] = {0: "void", 1: "struts"} count_label = "unit cells" cell: str = param( "octet", doc="Unit cell: cubic, bcc, fcc, octet, kelvin, diamond or pyrochlore", kind="str", ) cell_size: float = param(1.0, doc="Edge of the cubic unit cell", unit="length") strut_radius: float | None = param(None, doc="Strut radius", unit="length") volume_fraction: float | None = param(None, doc="Target relative density", kind="fraction") wall_thickness: float | None = param( None, doc="Wall thickness of hollow struts (default: solid)", unit="length" ) rotation: tuple[float, ...] | None = param( None, doc="Bunge angles (degrees) of the axes of the lattice in those of the sample " "(non-periodic domains)", kind="floats", ) radius_gradient: tuple[float, ...] | None = param( None, doc="Strut radii at the lower and upper faces of the domain along gradient_axis: a " "graded lattice (non-periodic domains)", kind="floats", unit="length", ) gradient_axis: int = param( 0, doc="Axis of the gradient of the strut radius: 0, 1 or 2", kind="int" ) anisotropy: Anisotropy | None = param(None, doc=ANISOTROPY, kind="anisotropy", kw_only=True) def _validate(self) -> None: if self.cell not in CELLS: raise ValueError(f"cell: expected one of {list(CELLS)}, got {self.cell!r}") check_positive(self.cell_size, "cell_size") if self.rotation is not None and len(self.rotation) != 3: raise ValueError("rotation: three Bunge angles (degrees)") if self.gradient_axis not in (0, 1, 2): raise ValueError("gradient_axis: 0, 1 or 2") if self.radius_gradient is not None: if len(self.radius_gradient) != 2: raise ValueError("radius_gradient: the radii at the lower and upper faces") if self.strut_radius is not None or self.volume_fraction is not None: raise ValueError("give the radius_gradient, or the strut_radius or volume_fraction") if self.wall_thickness is not None: raise ValueError("radius_gradient: solid struts only (no wall_thickness)") for r in self.radius_gradient: check_positive(r, "radius_gradient") if r >= 0.5 * self.cell_size: raise ValueError("radius_gradient: radii smaller than half the cell size") return if (self.strut_radius is None) == (self.volume_fraction is None): raise ValueError("give exactly one of 'strut_radius' and 'volume_fraction'") if self.strut_radius is not None: check_positive(self.strut_radius, "strut_radius") if self.strut_radius >= 0.5 * self.cell_size: raise ValueError("strut_radius: must be smaller than half the cell size") else: check_fraction(self.volume_fraction, "volume_fraction") if self.wall_thickness is not None: check_positive(self.wall_thickness, "wall_thickness") if self.strut_radius is not None and self.wall_thickness >= self.strut_radius: raise ValueError("wall_thickness: smaller than the strut radius") @property def radius(self) -> float: """Strut radius (solved numerically from the volume fraction if needed; the mean of the gradient of a graded lattice).""" if self.radius_gradient is not None: return 0.5 * (self.radius_gradient[0] + self.radius_gradient[1]) if self.strut_radius is not None: return self.strut_radius t = 0.0 if self.wall_thickness is None else self.wall_thickness / self.cell_size return strut_radius(self.cell, float(self.volume_fraction), t) * self.cell_size def _struts(self, domain: Domain) -> tuple[np.ndarray, np.ndarray]: """Ends of the struts that may meet the domain (turned by ``rotation``).""" a = self.cell_size margin = 0.0 if domain.periodic else a if self.rotation is None: return lattice_struts(self.cell, a, domain.lower - margin, domain.upper + margin) from morphogen.orientations import euler_to_matrix g = euler_to_matrix(np.asarray(self.rotation, dtype=float))[0] # lattice = g sample box = domain.dilated(margin) corners = np.array([[box.lower[i] if c[i] == 0 else box.upper[i] for i in range(3)] for c in itertools.product((0, 1), repeat=3)]) # fmt: skip local = (corners - domain.center) @ g.T start, end = lattice_struts(self.cell, a, local.min(axis=0), local.max(axis=0)) return domain.center + start @ g, domain.center + end @ g def _radii(self, domain: Domain, start, end) -> np.ndarray: if self.radius_gradient is None: return np.full(len(start), self.radius) axis = self.gradient_axis s = (0.5 * (start + end)[:, axis] - domain.lower[axis]) / domain.lengths[axis] r0, r1 = self.radius_gradient return r0 + (r1 - r0) * np.clip(s, 0.0, 1.0)
[docs] def generate(self, domain: Domain, seed: SeedLike = None) -> PrimitiveUnion: _, seed_info = make_rng(seed) a = self.cell_size if domain.periodic: if self.rotation is not None or self.radius_gradient is not None: raise ValueError( "strut_lattice: rotated and graded lattices need a non-periodic domain" ) ratio = domain.lengths / a if np.any(np.abs(ratio - np.rint(ratio)) > 1e-6 * np.maximum(ratio, 1.0)): raise ValueError( "strut_lattice: a periodic domain must contain a whole number of cells" ) start, end = self._struts(domain) segments = Segments(start, end, self._radii(domain, start, end), round_caps=True) if not domain.periodic: lo, hi = segments.bounds() keep = np.all((hi >= domain.lower) & (lo <= domain.upper), axis=1) segments = segments.subset(keep) struts = PrimitiveUnion(domain, segments=segments, model=self, seed=seed_info) if self.wall_thickness is None: return struts from morphogen.models.combination import Combined from morphogen.models.nested import bores_of bores = bores_of(struts, self.wall_thickness) return Combined(domain, "difference", [struts, bores], model=self, seed=seed_info)
[docs] def expected_count(self, domain: Domain) -> float: """Number of unit cells in the domain.""" return domain.volume / self.cell_size**3
[docs] def theory(self, domain: Domain | None = None) -> dict[str, float]: if self.radius_gradient is not None: # the local density along the gradient, averaged (Gauss-Legendre) x, w = np.polynomial.legendre.leggauss(6) r0, r1 = (r / self.cell_size for r in self.radius_gradient) local = [strut_fraction(self.cell, float(r0 + (r1 - r0) * (1 + xi) / 2)) for xi in x] return { "volume_fraction": float(np.dot(w, local) / 2.0), "volume_fraction_lower": strut_fraction(self.cell, float(r0)), "volume_fraction_upper": strut_fraction(self.cell, float(r1)), } r = self.radius / self.cell_size t = 0.0 if self.wall_thickness is None else self.wall_thickness / self.cell_size # solid struts on fine voxels, hollow ones on the voxels of the radius solve fraction = strut_fraction(self.cell, r, t, None if t else 256) return {"strut_radius": self.radius, "volume_fraction": fraction}