Source code for morphogen.models.nacre

"""Nacre: brick-and-mortar stacks of mineral tablets in an organic matrix.

Nacre (mother of pearl) is about 95 % of aragonite tablets, some 0.5 um thick and 5 to
10 um wide, in layers bonded by some 20 to 30 nm of biopolymers (the mortar); the
tablets of consecutive layers overlap, and the load passes from one to the next by
shear of the mortar between them (Jackson, Vincent and Turner 1988; Barthelat et al.
2007). Its toughness, far above that of aragonite, inspires brick-and-mortar composites.

The model stacks layers of tablets along an axis, with the period ``t + m`` (``t``: the
thickness of the tablets, ``m``: that of the mortar between layers). In each layer the
tablets are the cells of a planar tessellation shrunk by half the gap ``g`` between
neighbouring tablets:

* ``voronoi``: polygonal tablets, the cells of germs at least a fraction ``regularity``
  of the jamming distance of their random sequential addition apart (Poisson germs for
  0), independent from one layer to the next (sheet nacre);
* ``brick``: rectangles of area ``w^2`` and aspect ratio ``a/b``, each layer shifted by
  ``overlap`` tablet from the previous one, along both axes of the plane (each tablet
  over four, ``stagger: uv``) or along the first (over two, ``stagger: u``). A periodic
  box one tablet wide along an axis makes the tablets continuous across it: with
  ``stagger: u``, the two-dimensional brick-and-mortar model, extruded.

Volume fraction of tablets: ``t / (t + m)`` times the fraction of each layer they cover,
``(a - g)(b - g) / (a b)`` for bricks, and ``1 - 2 sqrt(lambda) g`` to first order in
``g`` for the cells of Poisson germs of intensity ``lambda = 1 / w^2`` (their sides are
``2 sqrt(lambda)`` long per unit area).
"""

from __future__ import annotations

import math
from dataclasses import dataclass
from typing import ClassVar

import numpy as np

from morphogen._utils import check_positive
from morphogen.domain import Domain, Grid
from morphogen.image import VoxelImage
from morphogen.models.base import Microstructure, Model, param, register, register_kind
from morphogen.models.planar import (
    PlanarCells,
    axis_centres,
    hardcore_germs,
    jamming_distance,
    pixel_centres,
    plane_axes,
)
from morphogen.seeding import SeedLike, make_rng

ARRANGEMENTS = ("voronoi", "brick")
STAGGERS = ("uv", "u")


[docs] @register_kind class NacreStructure(Microstructure): """Layers of tablets along ``axis``: layer ``k`` spans ``[z0 + k p, z0 + (k + 1) p)`` (``p``: the period), its tablet the slab of thickness ``t`` in its middle; in the plane, the tablets are the cells of the germs of the layer, shrunk by half the ``gap``. Periodic domains hold a whole number of layers, which wrap around.""" kind = "nacre" def __init__(self, domain, axis, period, thickness, offset, gap, layers, **kwargs): super().__init__(domain, **kwargs) self.axis = int(axis) self.period = float(period) self.thickness = float(thickness) self.offset = float(offset) self.gap = float(gap) self.layers = [np.asarray(g, dtype=float).reshape(-1, 2) for g in layers] self._cells: dict[int, PlanarCells] = {} @property def n_layers(self) -> int: return len(self.layers) @property def axes(self) -> tuple[int, int]: return plane_axes(self.axis)
[docs] def cells(self, layer: int) -> PlanarCells: """Tessellation of the tablets of a layer.""" if layer not in self._cells: b, c = self.axes d = self.domain self._cells[layer] = PlanarCells( self.layers[layer], d.lengths[[b, c]], d.periodic, d.lower[[b, c]] ) return self._cells[layer]
def _layer(self, j: np.ndarray) -> np.ndarray: """Stored layer of the layer indices ``j`` (-1: none).""" if self.domain.periodic: return np.mod(j, self.n_layers) return np.where((j >= 0) & (j < self.n_layers), j, -1) def _slab(self, z: np.ndarray) -> tuple[np.ndarray, np.ndarray]: """Index of the layer around each coordinate and the signed distance to the slab of its tablet (negative inside).""" j = np.floor((z - self.offset) / self.period).astype(np.int64) centre = self.offset + (j + 0.5) * self.period return j, np.abs(z - centre) - 0.5 * self.thickness # -- point classification ----------------------------------------------------------
[docs] def contains(self, points) -> np.ndarray: pts = np.asarray(points, dtype=float).reshape(-1, 3) if self.domain.periodic: pts = self.domain.wrap(pts) b, c = self.axes j, slab = self._slab(pts[:, self.axis]) layer = self._layer(j) out = np.zeros(len(pts), dtype=bool) for k in np.unique(layer[(slab <= 0) & (layer >= 0)]): sel = (layer == k) & (slab <= 0) _, d = self.cells(int(k)).locate(pts[sel][:, [b, c]], reach=0.5 * self.gap) out[sel] = d > 0.5 * self.gap return out
# -- discretization --------------------------------------------------------------- def _phases_on(self, grid: Grid) -> np.ndarray: pts, shape = pixel_centres(grid, self.axes) j, slab = self._slab(axis_centres(grid, self.axis)) layer = self._layer(j) out = np.zeros((len(j), *shape), dtype=np.uint8) tablets: dict[int, np.ndarray] = {} for i in np.flatnonzero((slab <= 0) & (layer >= 0)): k = int(layer[i]) if k not in tablets: _, d = self.cells(k).locate(pts, reach=0.5 * self.gap) tablets[k] = (d > 0.5 * self.gap).reshape(shape).astype(np.uint8) out[i] = tablets[k] return np.moveaxis(out, 0, self.axis)
[docs] def voxelize(self, shape=None, *, voxel_size=None, grid: Grid | None = None, supersampling=1): grid = self.grid(shape, voxel_size=voxel_size, grid=grid) ss = int(supersampling) if ss == 1: data = self._phases_on(grid) return VoxelImage.from_grid(data, grid, name="phase", metadata=self.image_metadata()) if not 1 <= ss <= 6: raise ValueError("supersampling must be an integer between 1 and 6") fine = Grid(grid.domain, tuple(n * ss for n in grid.shape)) ph = self._phases_on(fine).astype(np.float32) nx, ny, nz = grid.shape data = ph.reshape(nx, ss, ny, ss, nz, ss).mean(axis=(1, 3, 5), dtype=np.float32) return VoxelImage.from_grid(data, grid, name="fraction", metadata=self.image_metadata())
[docs] def level_set(self, shape=None, *, voxel_size=None, grid: Grid | None = None) -> VoxelImage: """Minimum over the layers around each point of ``max(slab, g / 2 - d)``: the signed distance to the slab of the tablets and the distance ``d`` to the sides of the cells (negative in the tablets, a distance near their faces).""" grid = self.grid(shape, voxel_size=voxel_size, grid=grid) pts, shape2 = pixel_centres(grid, self.axes) z = axis_centres(grid, self.axis) j0, _ = self._slab(z) reach = 0.5 * self.gap + 4.0 * float(np.max(grid.spacing)) far = np.float32(np.max(grid.domain.lengths)) out = np.full((len(z), *shape2), far, dtype=np.float32) planes: dict[int, np.ndarray] = {} for i, zi in enumerate(z): for j in (j0[i] - 1, j0[i], j0[i] + 1): k = int(self._layer(np.array([j]))[0]) if k < 0: continue if k not in planes: _, d = self.cells(k).locate(pts, reach=reach) planes[k] = (0.5 * self.gap - d).reshape(shape2).astype(np.float32) centre = self.offset + (j + 0.5) * self.period slab = np.float32(abs(zi - centre) - 0.5 * self.thickness) out[i] = np.minimum(out[i], np.maximum(slab, planes[k])) data = np.moveaxis(out, 0, self.axis) return VoxelImage.from_grid(data, grid, name="level_set", metadata=self.image_metadata())
[docs] def level_set_at(self, points, reach: float = np.inf) -> np.ndarray: """As :meth:`level_set`, at the points (the distances to the sides of the cells exact within ``reach`` of them, by default the half gap and a tenth of the period).""" pts = np.asarray(points, dtype=float).reshape(-1, 3) if self.domain.periodic: pts = self.domain.wrap(pts) b, c = self.axes z = pts[:, self.axis] j0, _ = self._slab(z) if not np.isfinite(reach): reach = 0.5 * self.gap + 0.1 * self.period out = np.full(len(pts), float(np.max(self.domain.lengths))) for shift in (-1, 0, 1): j = j0 + shift layer = self._layer(j) centre = self.offset + (j + 0.5) * self.period slab = np.abs(z - centre) - 0.5 * self.thickness for k in np.unique(layer[layer >= 0]): sel = np.flatnonzero(layer == k) _, d = self.cells(int(k)).locate(pts[sel][:, [b, c]], reach=float(reach)) out[sel] = np.minimum(out[sel], np.maximum(slab[sel], 0.5 * self.gap - d)) return out
# -- description -------------------------------------------------------------------
[docs] def summary(self) -> dict: return { "n_layers": self.n_layers, "tablets_per_layer": float(np.mean([len(g) for g in self.layers])), }
def _geometry(self) -> dict: return { "axis": self.axis, "period": self.period, "thickness": self.thickness, "offset": self.offset, "gap": self.gap, "layers": [g.tolist() for g in self.layers], } @classmethod def _from_geometry(cls, domain, geometry, **kwargs): return cls( domain, geometry["axis"], geometry["period"], geometry["thickness"], geometry["offset"], geometry["gap"], geometry["layers"], **kwargs, )
[docs] @register @dataclass(frozen=True) class Nacre(Model): """Nacre: staggered layers of mineral tablets bonded by an organic mortar. Tablets of ``tablet_thickness`` and in-plane ``tablet_size`` (the side of a square of the same area), ``voronoi`` polygons (sheet nacre) or ``brick`` rectangles in a staggered stack, separated by ``mortar_thickness`` between the layers and ``gap`` between the tablets of a layer, stacked along ``axis``. """ name = "nacre" phases: ClassVar[dict[int, str]] = {0: "mortar", 1: "tablets"} count_label = "tablets" tablet_size: float = param( 1.0, doc="In-plane size of the tablets (square root of their area)", unit="length" ) tablet_thickness: float = param(0.2, doc="Thickness of the tablets", unit="length") mortar_thickness: float = param( 0.02, doc="Thickness of the mortar between the layers", unit="length" ) gap: float | None = param( None, doc="Width of the mortar between the tablets of a layer (default: as between " "the layers)", unit="length", ) # fmt: skip arrangement: str = param( "voronoi", doc="voronoi (polygonal tablets) or brick (staggered rectangles)", kind="str" ) regularity: float = param( 0.7, doc="voronoi: least distance of the germs, in jamming distances (0: Poisson)", kind="fraction", ) # fmt: skip aspect: float = param(1.0, doc="brick: length over width of the tablets") overlap: float = param( 0.5, doc="brick: shift of a layer from the previous one, in tablets", kind="fraction" ) stagger: str = param( "uv", doc="brick: shift along both axes of the plane (uv) or the first (u)", kind="str" ) axis: int = param(2, doc="Stacking direction (0: x, 1: y, 2: z)", kind="int") def _validate(self) -> None: check_positive(self.tablet_size, "tablet_size") check_positive(self.tablet_thickness, "tablet_thickness") check_positive(self.mortar_thickness, "mortar_thickness", allow_zero=True) check_positive(self.aspect, "aspect") if self.arrangement not in ARRANGEMENTS: raise ValueError(f"arrangement: one of {list(ARRANGEMENTS)}") if self.stagger not in STAGGERS: raise ValueError(f"stagger: one of {list(STAGGERS)}") if self.axis not in (0, 1, 2): raise ValueError("axis: 0, 1 or 2") if not 0.0 <= self.regularity <= 0.95: raise ValueError("regularity: from 0 (Poisson germs) to 0.95 (near jamming)") if not 0.0 <= self.overlap < 1.0: raise ValueError("overlap: from 0 to 1 (excluded)") g = self.gap_width check_positive(g, "gap", allow_zero=True) a, b = self.brick_sides if g >= (min(a, b) if self.arrangement == "brick" else 0.5 * self.tablet_size): raise ValueError("gap: narrower than the tablets") @property def gap_width(self) -> float: return self.mortar_thickness if self.gap is None else float(self.gap) @property def period(self) -> float: """Thickness of a layer: a tablet and the mortar over it.""" return self.tablet_thickness + self.mortar_thickness @property def brick_sides(self) -> tuple[float, float]: """Sides of the bricks along the two axes of the plane.""" s = math.sqrt(self.aspect) return self.tablet_size * s, self.tablet_size / s # -- generation ---------------------------------------------------------------------- def _layer_count(self, length: float) -> int: """Layers in a periodic box: the closest to its height in whole periods of the staggering (a whole number of tablets of shift).""" n0 = max(1, round(length / self.period)) if self.arrangement != "brick" or self.overlap == 0: return n0 fits = [ n for n in range(1, 4 * n0 + 8) if abs(n * self.overlap - round(n * self.overlap)) < 1e-9 ] # fmt: skip if not fits: raise ValueError( f"nacre: no number of layers repeats a shift of {self.overlap} tablet; " "use a rational overlap (0.5, 0.25, 1/3...) or a non-periodic domain" ) return min(fits, key=lambda n: abs(math.log(length / (n * self.period)))) def _brick_germs(self, k: int, lower, lengths, counts, sides, periodic: bool): """Centres of the bricks of layer ``k``.""" a, b = sides shift = self.overlap * k * np.array([a, b if self.stagger == "uv" else 0.0]) if periodic: # from the corner of the box, which holds whole bricks i, j = np.meshgrid(np.arange(counts[0]), np.arange(counts[1]), indexing="ij") shift = shift + lower else: # the bricks over the box, and a row around it lo = np.floor((lower - shift) / sides).astype(int) - 1 hi = np.ceil((lower + lengths - shift) / sides).astype(int) + 1 i, j = np.meshgrid(np.arange(lo[0], hi[0]), np.arange(lo[1], hi[1]), indexing="ij") return np.column_stack([(i.ravel() + 0.5) * a, (j.ravel() + 0.5) * b]) + shift
[docs] def generate(self, domain: Domain, seed: SeedLike = None) -> NacreStructure: rng, seed_info = make_rng(seed) ax = self.axis b, c = plane_axes(ax) lower, lengths = domain.lower[[b, c]], domain.lengths[[b, c]] height = float(domain.lengths[ax]) scale = 1.0 if domain.periodic: n_layers = self._layer_count(height) scale = height / (n_layers * self.period) # the stack fills the box offset = float(domain.lower[ax] + rng.random() * height) layer_ids = range(n_layers) else: offset = float(domain.lower[ax] - rng.random() * self.period) n_layers = math.ceil((domain.upper[ax] - offset) / self.period) layer_ids = range(n_layers) sides = np.array(self.brick_sides) counts = np.maximum(1, np.rint(lengths / sides)).astype(int) if domain.periodic and self.arrangement == "brick": sides = lengths / counts # whole bricks in the box layers = [] margin = 0.0 if domain.periodic else 3.0 * self.tablet_size window_lo, window = lower - margin, lengths + 2.0 * margin area = float(np.prod(window)) for k in layer_ids: if self.arrangement == "brick": layers.append(self._brick_germs(k, lower, lengths, counts, sides, domain.periodic)) continue if domain.periodic: n = max(1, round(area / self.tablet_size**2)) else: n = max(1, int(rng.poisson(area / self.tablet_size**2))) distance = self.regularity * jamming_distance(n, area) layers.append(window_lo + hardcore_germs(n, window, distance, rng)) metadata = {"scale": {"thickness": scale}} if domain.periodic else {} if domain.periodic and self.arrangement == "brick": metadata.setdefault("scale", {})["tablet_sides"] = (sides / self.brick_sides).tolist() return NacreStructure( domain, ax, self.period * scale, self.tablet_thickness * scale, offset, self.gap_width, layers, model=self, seed=seed_info, metadata=metadata, )
# -- theory ----------------------------------------------------------------------------
[docs] def expected_count(self, domain: Domain) -> float: """Mean number of tablets in the domain.""" return float(domain.volume / (self.tablet_size**2 * self.period))
[docs] def theory(self, domain: Domain | None = None) -> dict[str, float]: layer = self.tablet_thickness / self.period g = self.gap_width out = { "layer_fraction": layer, "tablet_aspect_ratio": self.tablet_size / self.tablet_thickness, } if self.arrangement == "brick": a, b = self.brick_sides out["volume_fraction"] = layer * (a - g) * (b - g) / (a * b) elif self.regularity == 0: # sides 2 sqrt(lambda) long per unit area out["gap_fraction_first_order"] = 2.0 * g / self.tablet_size out["volume_fraction_first_order"] = layer * (1.0 - 2.0 * g / self.tablet_size) return out