Source code for morphogen.models.design

"""Microstructures from combinatorial design: tile assemblies and random strut lattices.

``tile_assembly``
    Compatible assemblies of building blocks (polarized blocks of combinatorial
    metamaterials, pipe networks) drawn by wave function collapse or uniformly by
    transfer matrices; their voxels form a lattice microstructure.
``random_lattice``
    Strut lattices with defects: struts removed at random down to a mean coordination,
    nodes displaced at random; the rigidity of the pin-jointed framework (mechanisms,
    self-stresses, floppy strains) is analysed.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import ClassVar

import numpy as np

from morphogen._utils import check_fraction, check_positive
from morphogen.design.csp import sample_uniform, wave_function_collapse
from morphogen.design.frames import Framework
from morphogen.design.tiles import TILE_SETS, pipe_tiles, polarized_blocks
from morphogen.domain import Domain
from morphogen.models.affine import ANISOTROPY, Anisotropy, anisotropic
from morphogen.models.base import Model, param, register
from morphogen.models.foam import FRAME_STIFFNESS, frame_summary
from morphogen.models.lattice import CELLS
from morphogen.models.lattice_field import LatticeField, _encode
from morphogen.models.union import PrimitiveUnion
from morphogen.primitives import Segments
from morphogen.seeding import SeedLike, make_rng

ASSEMBLY_METHODS = ("wfc", "uniform", "random")

#: Mean coordination of the intact lattices.
PARENT_COORDINATION = {"cubic": 6.0, "bcc": 8.0, "fcc": 6.0, "octet": 12.0}

#: Largest framework (nodes) whose rigidity is analysed.
MAX_RIGIDITY_NODES = 1000


[docs] @register @dataclass(frozen=True) class TileAssembly(Model): """Compatible assemblies of building blocks with matching faces. ``polarized`` blocks (combinatorial metamaterials after Coulais et al. 2016) or ``pipes`` (networks without dead ends at the tile boundaries). """ name = "tile_assembly" phases: ClassVar[dict[int, str]] = {0: "void", 1: "solid"} count_label = "tiles" tiles: str = param("polarized", doc="Tile set: polarized or pipes", kind="str") tile_length: float = param(1.0, doc="Edge of a tile", unit="length") tile_cells: int = param(8, doc="Lattice cells per tile edge", kind="int") dimension: int = param(3, doc="3, or 2 for planar assemblies", kind="int") method: str = param( "wfc", doc="wfc (wave function collapse), uniform (exact uniform sampling, narrow " "boxes only) or random (independent tiles, ignoring compatibility)", kind="str", ) channel_radius: float = param( 0.25, doc="polarized: radius of the channel along the block axis (tile edges)" ) pipe_radius: float = param(0.2, doc="pipes: radius of the pipes (tile edges)") open_probability: float = param( 0.5, doc="pipes: probability that a face is open", kind="fraction" ) degrees: tuple[float, ...] | None = param( None, doc="pipes: allowed numbers of open faces per tile (default: all)", kind="floats" ) boundary: int | None = param( None, doc="Label the outer faces of non-periodic boxes must match (pipes: 0 closes the network)", kind="int", ) smoothing: float = param( 0.0, doc="Gaussian smoothing (in cells) of the interface off the lattice", unit="cells" ) def _validate(self) -> None: if self.tiles not in TILE_SETS: raise ValueError(f"tiles: one of {list(TILE_SETS)}") check_positive(self.tile_length, "tile_length") if self.tile_cells < 2: raise ValueError("tile_cells: at least 2") if self.dimension not in (2, 3): raise ValueError("dimension: 2 or 3") if self.method not in ASSEMBLY_METHODS: raise ValueError(f"method: one of {ASSEMBLY_METHODS}") if not 0.0 <= self.channel_radius < 0.5: raise ValueError("channel_radius: in [0, 0.5)") if not 0.0 < self.pipe_radius < 0.5: raise ValueError("pipe_radius: in (0, 0.5)") check_fraction(self.open_probability, "open_probability") if self.degrees is not None and any( d != int(d) or not 0 <= d <= 2 * self.dimension for d in self.degrees ): raise ValueError(f"degrees: integers from 0 to {2 * self.dimension}") check_positive(self.smoothing, "smoothing", allow_zero=True)
[docs] def tile_set(self): if self.tiles == "polarized": return polarized_blocks(self.tile_cells, self.channel_radius, self.dimension) degrees = None if self.degrees is None else [int(d) for d in self.degrees] return pipe_tiles( self.tile_cells, self.pipe_radius, self.dimension, open_probability=self.open_probability, degrees=degrees, )
[docs] def tile_grid(self, domain: Domain) -> tuple[int, int, int]: n = np.maximum(1, np.rint(domain.lengths / self.tile_length)).astype(int) if self.dimension == 2: n[2] = 1 return tuple(int(v) for v in n)
[docs] def expected_count(self, domain: Domain) -> float: return float(np.prod(self.tile_grid(domain)))
[docs] def generate(self, domain: Domain, seed: SeedLike = None) -> LatticeField: rng, seed_info = make_rng(seed) tiles = self.tile_set() shape = self.tile_grid(domain) periodic = domain.periodic if self.tiles == "polarized" and periodic and any(n % 2 for n in shape[: self.dimension]): raise ValueError( "polarized blocks alternate along every line: a periodic domain needs an " f"even number of tiles along each axis (got {shape[: self.dimension]})" ) if self.method == "wfc": assembly = wave_function_collapse( tiles, shape, rng, periodic=periodic, boundary=self.boundary ) elif self.method == "uniform": if self.boundary is not None: raise ValueError("boundary labels are only used by the wfc method") assembly = sample_uniform(tiles, shape, rng, periodic=periodic) else: p = tiles.weights / tiles.weights.sum() assembly = rng.choice(tiles.n_tiles, size=shape, p=p) voxels = tiles.assemble(assembly) return LatticeField( domain, voxels, smoothing=self.smoothing, model=self, seed=seed_info, attributes={ "tile_grid": list(shape), "assembly": _encode(np.asarray(assembly, dtype=np.int16)), "tile_names": list(tiles.names), "mismatches": tiles.mismatches(assembly, periodic), }, )
[docs] @register @anisotropic @dataclass(frozen=True) class RandomLattice(Model): """Strut lattices with defects: missing struts and displaced nodes. Struts of a cubic, bcc, fcc or octet lattice are removed at random, down to a mean coordination or by a fraction, and nodes are displaced at random. The rigidity of the pin-jointed framework tells whether it is stretching-dominated (no floppy macroscopic strain; Maxwell's count needs a coordination of at least 6), and with ``frame_stiffness`` the stiffness of its frame of beams (rigid joints) is added to the summary. """ name = "random_lattice" phases: ClassVar[dict[int, str]] = {0: "void", 1: "struts"} count_label = "unit cells" cell: str = param("octet", doc="Parent unit cell: cubic, bcc, fcc or octet", kind="str") cell_size: float = param(1.0, doc="Edge of the cubic unit cell", unit="length") strut_radius: float = param(0.08, doc="Strut radius", unit="length") coordination: float | None = param( None, doc="Target mean number of struts per node: struts are removed at random, " "keeping min_degree struts at every node", ) removal_fraction: float | None = param( None, doc="Fraction of the struts removed at random (then dangling struts)", kind="fraction", ) min_degree: int = param( 3, doc="Fewest struts per node when diluting to a coordination", kind="int" ) perturbation: float = param( 0.0, doc="Random displacement of the nodes, in cell sizes (uniform in a ball)" ) rigidity: bool = param( True, doc=f"Analyse the rigidity of the pin-jointed framework (up to {MAX_RIGIDITY_NODES} nodes)", kind="bool", ) anisotropy: Anisotropy | None = param(None, doc=ANISOTROPY, kind="anisotropy", kw_only=True) frame_stiffness: bool = param(False, doc=FRAME_STIFFNESS, kind="bool", kw_only=True) def _validate(self) -> None: if self.cell not in CELLS: raise ValueError(f"cell: one of {list(CELLS)}") check_positive(self.cell_size, "cell_size") check_positive(self.strut_radius, "strut_radius") if self.strut_radius >= 0.5 * self.cell_size: raise ValueError("strut_radius: smaller than half the cell size") if self.coordination is not None and self.removal_fraction is not None: raise ValueError("give at most one of 'coordination' and 'removal_fraction'") if self.coordination is not None: check_positive(self.coordination, "coordination") if self.removal_fraction is not None: check_fraction(self.removal_fraction, "removal_fraction") if self.min_degree < 1: raise ValueError("min_degree: at least 1") if not 0.0 <= self.perturbation < 0.5: raise ValueError("perturbation: in [0, 0.5) cell sizes")
[docs] def theory(self, domain: Domain | None = None) -> dict[str, float]: out = {"parent_coordination": PARENT_COORDINATION[self.cell], "isostatic_coordination": 6.0} if self.coordination is not None: out["coordination"] = float(self.coordination) return out
[docs] def expected_count(self, domain: Domain) -> float: return domain.volume / self.cell_size**3
[docs] def framework(self, n_cells, rng: np.random.Generator) -> Framework: """The random framework of ``n_cells`` unit cells.""" frame = Framework.lattice(self.cell, n_cells, self.cell_size) if self.coordination is not None: frame = frame.diluted(rng, coordination=self.coordination, min_degree=self.min_degree) elif self.removal_fraction is not None: frame = frame.diluted(rng, fraction=self.removal_fraction) if self.perturbation > 0: frame = frame.perturbed(rng, self.perturbation * self.cell_size) return frame
[docs] def generate(self, domain: Domain, seed: SeedLike = None) -> PrimitiveUnion: rng, seed_info = make_rng(seed) a = self.cell_size ratio = domain.lengths / a if domain.periodic: if np.any(np.abs(ratio - np.rint(ratio)) > 1e-6 * np.maximum(ratio, 1.0)): raise ValueError( "random_lattice: a periodic domain must contain a whole number of cells" ) n_cells = np.rint(ratio).astype(int) origin = domain.lower else: # a window of a larger periodic lattice n_cells = np.ceil(ratio).astype(int) + 2 origin = domain.lower - a frame = self.framework(n_cells, rng) segments = frame.segments(self.strut_radius, origin) if not domain.periodic: lo, hi = segments.bounds() keep = np.all((hi >= domain.lower) & (lo <= domain.upper), axis=1) segments = Segments( segments.start[keep], segments.end[keep], segments.radii[keep], round_caps=True ) summary = { "n_nodes": frame.n_nodes, "n_struts": frame.n_bars, "coordination": round(frame.coordination(), 6), } if self.rigidity and domain.periodic and frame.n_nodes <= MAX_RIGIDITY_NODES: r = frame.rigidity() summary.update( mechanisms=r["mechanisms"], self_stresses=r["self_stresses"], floppy_strains=r["floppy_strains"], ) if self.frame_stiffness: # the periodic lattice (larger than a window) summary.update(frame_summary(frame, self.strut_radius)) return PrimitiveUnion( domain, segments=segments, model=self, seed=seed_info, metadata={"summary": summary, "framework": frame.to_dict()}, )