Source code for morphogen.models.scale_rich

"""Scale-rich networks: ligaments of power-law thicknesses grown one after another until
they meet (Both, Chen, Gao, Mooij, Charara, Wadhwa, Portela & Barabási 2026).

Mechanical metamaterials are usually ruled by one length, that of their cell. Scale-rich
networks give up that length: their ligaments span orders of magnitude in thickness,
length and connectivity within one sample, as the veins of leaves and dragonfly wings, the
threads of spider webs or the roads of a city. Both et al. (Nature 659, 345, 2026) grow
them from two parameters:

* the ligament ``t = 1, 2, ..., T`` is ``lambda_t = lambda_0 t^-alpha`` thick
  (``initial_thickness`` and ``decay``);
* it nucleates at a point drawn uniformly in the voids left by the ligaments before it,
  along an angle ``theta_t``, and grows both ways until it meets the face of another
  ligament or the boundary of the box.

The voids are convex cells (at first the rectangle of the box), each bounded by faces of
ligaments and of the box. A ligament lies in the cell of its nucleation point: it is the
strip of width ``lambda_t`` along its line clipped by that cell, which it splits into two
convex cells (the scheme of the reference implementation of the authors). The point is
drawn uniformly in the box until it falls in a void, the same law as a void drawn in
proportion to its area then a point uniform in it. Ligaments and voids partition the box
exactly, so that the relative density ``1 - sum(void areas) / A`` is exact; the ligaments
never overlap. A ligament fits when its cell holds the two points at
``(lambda_t + epsilon) / 2`` on either side of its nucleation point (``epsilon``:
``min_spacing``, the least width of the voids beside a new ligament); when
``max_attempts`` draws in a row do not fit, the network is jammed and stops growing. The
length of a ligament is that of its centre line in its cell; its neighbours are the
ligaments (or the box) on which its two ends lie. As roads in the dual graphs of road
networks (Rosvall et al. 2005), the ligaments are the nodes of the network and their
junctions its links: the degree ``k`` of a ligament counts the ligaments on which it ends
and those that end on it.

Laws (Both et al. 2026): the thicknesses follow ``P(lambda) ~ lambda^-(1 + 1/alpha)``
exactly; a ligament splits a cell of area about ``A_t / t``, so that its length decays
as ``t^-1/2`` (``A_t``: the area of the voids) and the lengths have the tail ``P(l) ~
l^-3``; a long ligament is met by the ligaments that end on it in proportion to its
length (a spatial preferential attachment), and the degrees have the tail ``P(k) ~ k^-3``.
The relative density is ``sum_t lambda_t l_t / A`` (``l_t`` the length of ``t``), see
:meth:`ScaleRichNetwork.theory`.

Orientations: uniform (the scale-rich networks of the paper), drawn among ``angles``
(aligned networks, e.g. ``[0, 90]``), or polarized by a ``pole`` (the ligaments along the
direction of the pole turned by ``pole_angle``: radial, tangential or spiral, for the
``polarized_fraction`` first of them), each spread by ``angle_spread`` (a normal law).
The nucleation density may follow a gradient along an axis of the plane or away from the
pole (``nucleation_gradient``). Their combinations draw the designs of Fig. 6 of the
paper, as the radial gradient of the pomelo peel protecting a payload.

The network lies in the plane of the two axes other than ``axis`` and is extruded along
it through the box: the prismatic specimens of the paper (plane strain), one voxel thick
for planar images. Its ligaments end on the faces of the box, which is not periodic; a
``frame`` of material around the network, on which they end, makes the sample the cell of
a periodic medium (FFT solvers, Bloch waves), stiffened by the frame.

With ``dimension: 3``, the network grows in space: plates that split convex polyhedral
voids (closed cells), or beams (open cells), see :mod:`morphogen.models.scale_rich_3d`.
"""

from __future__ import annotations

import itertools
import math
from dataclasses import dataclass
from statistics import NormalDist
from typing import ClassVar

import numpy as np
from numba import njit, prange

from morphogen._utils import check_fraction, check_positive, exactly_one
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 pixel_centres, plane_axes
from morphogen.models.scale_rich_3d import (
    AREA_CONSTANT,
    BOX,
    ScaleRichBeams,
    ScaleRichPlates,
    area_sum,
    beam_density_estimate,
    beam_thickness_estimate,
    first_area,
    grow_beams,
    grow_plates,
)
from morphogen.orientations import OrientationDistribution, orthonormal_basis, uniform_unit_vectors
from morphogen.seeding import SeedLike, make_rng

#: Tolerance on the relative density of a realization solved for a ``volume_fraction``
DENSITY_TOL = 2e-4
#: ``lim sqrt(t / A) E[l_t]``: the mean length of the ligament ``t`` of a thin network
#: (``lambda_0 -> 0``) in a box of area ``A``, measured with uniform orientations: 1.1663
#: and 1.1658 (standard errors 0.0004) over the ligaments ``t >= 2000`` of 120
#: realizations of 20,000 in a square and in a 2 x 1 rectangle. The first ligament is
#: ``l_0`` (:func:`first_length`, 0.9464 in a square), the next ones approach the limit
#: (1.05, 1.09, 1.12 at ``t`` = 2, 3, 5)
LENGTH_CONSTANT = 1.166
#: Uniform draws of a nucleation point: its two coordinates, its rejection by the density
#: of nucleation, and two for its angle (the angle, and the normal of its spread)
_DRAWS = 5

# -- convex polygons (counter-clockwise vertices, the label of the face of each edge) -------


[docs] @njit(cache=True) def polygon_area(xy) -> float: """Area of a polygon (counter-clockwise: positive) by the shoelace formula.""" m = xy.shape[0] s = 0.0 for j in range(m): k = (j + 1) % m s += xy[j, 0] * xy[k, 1] - xy[k, 0] * xy[j, 1] return 0.5 * s
@njit(cache=True) def _merged(xy, faces, tol): """The polygon without its edges shorter than ``tol`` (a vertex that coincides with the next one goes, the next one keeping the face of its outgoing edge).""" m = xy.shape[0] keep = np.ones(m, dtype=np.bool_) for j in range(m): k = (j + 1) % m if abs(xy[j, 0] - xy[k, 0]) <= tol and abs(xy[j, 1] - xy[k, 1]) <= tol: keep[j] = False if keep.all(): return xy, faces if not keep.any(): return xy[:1].copy(), faces[:1].copy() return xy[keep].copy(), faces[keep].copy()
[docs] @njit(cache=True) def clip_polygon(xy, faces, nx, ny, c, label, tol): """The part of a convex polygon where ``nx x + ny y <= c``: its vertices and the faces of its edges, the edge along the line labelled ``label`` (Sutherland-Hodgman).""" m = xy.shape[0] out = np.empty((m + 2, 2)) out_faces = np.empty(m + 2, dtype=np.int64) k = 0 for j in range(m): jn = (j + 1) % m dj = nx * xy[j, 0] + ny * xy[j, 1] - c dn = nx * xy[jn, 0] + ny * xy[jn, 1] - c if dj <= 0.0: out[k, 0], out[k, 1] = xy[j, 0], xy[j, 1] out_faces[k] = faces[j] k += 1 if dn > 0.0: # leaves the half-plane: the rest of the edge, then the line t = dj / (dj - dn) out[k, 0] = xy[j, 0] + t * (xy[jn, 0] - xy[j, 0]) out[k, 1] = xy[j, 1] + t * (xy[jn, 1] - xy[j, 1]) out_faces[k] = label k += 1 elif dn <= 0.0: # enters it: the rest of the edge t = dj / (dj - dn) out[k, 0] = xy[j, 0] + t * (xy[jn, 0] - xy[j, 0]) out[k, 1] = xy[j, 1] + t * (xy[jn, 1] - xy[j, 1]) out_faces[k] = faces[j] k += 1 return _merged(out[:k], out_faces[:k], tol)
[docs] @njit(cache=True) def chord(xy, faces, px, py, dx, dy): """Where the line ``p + s d`` leaves a convex polygon holding ``p``: ``s0 <= 0 <= s1``, and the faces of the edges it leaves by.""" m = xy.shape[0] s0, s1 = -np.inf, np.inf f0, f1 = BOX, BOX for j in range(m): jn = (j + 1) % m mx = -(xy[jn, 1] - xy[j, 1]) # the inward normal of the edge (not unit) my = xy[jn, 0] - xy[j, 0] h = mx * (px - xy[j, 0]) + my * (py - xy[j, 1]) md = mx * dx + my * dy if md < 0.0: s = -h / md if s < s1: s1, f1 = s, faces[j] elif md > 0.0: s = -h / md if s > s0: s0, f0 = s, faces[j] return s0, s1, f0, f1
[docs] @njit(cache=True) def fits(xy, px, py, nx, ny, half) -> bool: """Whether a convex polygon holds the points ``p +- half n``.""" m = xy.shape[0] for j in range(m): jn = (j + 1) % m ex, ey = xy[jn, 0] - xy[j, 0], xy[jn, 1] - xy[j, 1] mx, my = -ey, ex h = mx * (px - xy[j, 0]) + my * (py - xy[j, 1]) if h - half * abs(mx * nx + my * ny) < 0.0: return False return True
[docs] @njit(cache=True) def inside_polygon(xy, px, py) -> bool: """Whether a convex polygon (counter-clockwise) holds the point ``p``.""" m = xy.shape[0] for j in range(m): jn = (j + 1) % m cross = (xy[jn, 0] - xy[j, 0]) * (py - xy[j, 1]) - (xy[jn, 1] - xy[j, 1]) * (px - xy[j, 0]) if cross < 0.0: return False return True
class _Voids: """The voids of a growing network registered in a grid of buckets of the rectangle, to find the void that holds a point (or none: the point lies in a ligament).""" def __init__(self, lower, upper, n_buckets: int) -> None: self.lo = np.asarray(lower, dtype=float) size = np.asarray(upper, dtype=float) - self.lo g = np.clip(np.ceil(math.sqrt(max(n_buckets, 1)) * size / math.sqrt(np.prod(size))), 1, 256) # fmt: skip self.g0, self.g1 = int(g[0]), int(g[1]) self.h0, self.h1 = float(size[0] / g[0]), float(size[1] / g[1]) self.buckets: list[set[int]] = [set() for _ in range(self.g0 * self.g1)] self.boxes: dict[int, tuple] = {} self.cells: list[np.ndarray] = [] def _range(self, v, lo, h, n) -> int: return min(max(math.floor((v - lo) / h), 0), n - 1) def put(self, cid: int, xy: np.ndarray) -> None: """Registers the void ``cid`` (a new one, or in place of the old ``cid``).""" if cid < len(self.cells): self.drop(cid) self.cells[cid] = xy else: self.cells.append(xy) x0, y0 = xy.min(axis=0) x1, y1 = xy.max(axis=0) i0, i1 = ( self._range(x0, self.lo[0], self.h0, self.g0), self._range(x1, self.lo[0], self.h0, self.g0), ) j0, j1 = ( self._range(y0, self.lo[1], self.h1, self.g1), self._range(y1, self.lo[1], self.h1, self.g1), ) self.boxes[cid] = (x0, y0, x1, y1, i0, i1, j0, j1) for i in range(i0, i1 + 1): for j in range(j0, j1 + 1): self.buckets[i * self.g1 + j].add(cid) def drop(self, cid: int) -> None: *_, i0, i1, j0, j1 = self.boxes.pop(cid) for i in range(i0, i1 + 1): for j in range(j0, j1 + 1): self.buckets[i * self.g1 + j].discard(cid) def locate(self, px: float, py: float) -> int: i = self._range(px, self.lo[0], self.h0, self.g0) j = self._range(py, self.lo[1], self.h1, self.g1) for cid in self.buckets[i * self.g1 + j]: x0, y0, x1, y1 = self.boxes[cid][:4] if x0 <= px <= x1 and y0 <= py <= y1 and inside_polygon(self.cells[cid], px, py): return cid return -1 # -- the growth --------------------------------------------------------------------------
[docs] @dataclass class Growth: """The ligaments and voids of a scale-rich network (coordinates of the plane).""" nucleation: np.ndarray # (N, 2) the nucleation points angle: np.ndarray # (N,) radians, of the centre lines thickness: np.ndarray # (N,) ends: np.ndarray # (N, 2, 2) the ends of the centre lines neighbours: np.ndarray # (N, 2) the ligaments of the ends (BOX: the boundary) body_offsets: np.ndarray # (N + 1,) CSR of the vertices of the ligaments body_vertices: np.ndarray # (M, 2) cell_offsets: np.ndarray # (C + 1,) CSR of the vertices of the voids cell_vertices: np.ndarray # (K, 2) cell_faces: np.ndarray # (K,) the face of each edge (ligament index or BOX) jammed: bool = False attempts: int = 0 @property def n(self) -> int: return len(self.thickness) @property def n_cells(self) -> int: return len(self.cell_offsets) - 1
[docs] def bodies(self) -> list[np.ndarray]: """The vertices of each ligament (convex polygons, counter-clockwise).""" o = self.body_offsets return [self.body_vertices[o[i] : o[i + 1]] for i in range(self.n)]
[docs] def cells(self) -> list[np.ndarray]: """The vertices of each void (convex polygons, counter-clockwise).""" o = self.cell_offsets return [self.cell_vertices[o[i] : o[i + 1]] for i in range(self.n_cells)]
[docs] def body_areas(self) -> np.ndarray: return np.array([polygon_area(b) for b in self.bodies()])
[docs] def cell_areas(self) -> np.ndarray: return np.array([polygon_area(c) for c in self.cells()])
@property def lengths(self) -> np.ndarray: """The lengths of the centre lines of the ligaments.""" return np.linalg.norm(self.ends[:, 1] - self.ends[:, 0], axis=1)
[docs] def degrees(self) -> np.ndarray: """The number of ligaments each ligament meets (its degree in the dual graph).""" e = self.links() return np.bincount(e.ravel(), minlength=self.n).astype(np.int64)
[docs] def orientation_tensor(self) -> np.ndarray: """``M = sum A_t d_t d_t / sum A_t``: the directions ``d_t`` of the ligaments weighted by their areas ``A_t`` (Both et al. 2026, eq. 1, normalized).""" a = self.body_areas() d = np.column_stack([np.cos(self.angle), np.sin(self.angle)]) if not a.sum() > 0: return np.full((2, 2), np.nan) return np.einsum("t,ti,tj->ij", a, d, d) / a.sum()
def _csr(items: list[np.ndarray]) -> tuple[np.ndarray, np.ndarray]: offsets = np.zeros(len(items) + 1, dtype=np.int64) offsets[1:] = np.cumsum([len(a) for a in items]) data = np.concatenate(items) if items else np.empty((0, 2)) return offsets, data
[docs] def grow( lower, upper, n_ligaments: int, thickness, entropy: int, *, orientation=None, density=None, min_spacing: float = 0.0, max_attempts: int = 1000, ) -> Growth: """Grow a scale-rich network in the rectangle ``[lower, upper]`` of the plane. ``thickness(t)`` is the thickness of the ligament ``t = 1, 2, ...``; ``orientation(t, x, y, u, v)`` its angle (radians) at its nucleation point from two uniform numbers (default: ``pi u``, uniform); ``density(x, y)`` the relative density of nucleation in ``[0, 1]`` (default: uniform), by rejection. A nucleation point is drawn uniformly in the rectangle until it falls in a void (the law of a void drawn in proportion to its area, then a point uniform in it); each ligament draws from its own generator (``SeedSequence(entropy, spawn_key=(t,))``): its draws do not depend on the ligaments before it, so that a small change of the thicknesses changes the network only where a point or an end falls close to a moved side (the relative density of :class:`ScaleRichNetwork` is solved on realizations of the same seed). The growth stops, jammed, after ``max_attempts`` nucleation points in a row where the ligament does not fit, or when the voids vanish. """ lo = np.asarray(lower, dtype=float).reshape(2) hi = np.asarray(upper, dtype=float).reshape(2) size = hi - lo area = float(np.prod(size)) tol = 1e-12 * float(np.max(size)) box = np.array([[lo[0], lo[1]], [hi[0], lo[1]], [hi[0], hi[1]], [lo[0], hi[1]]]) voids = _Voids(lo, hi, n_buckets=max(1, int(n_ligaments) // 2)) voids.put(0, box) cells_faces = [np.full(4, BOX, dtype=np.int64)] void_area = area nucleation, angle, lam, ends, neighbours, bodies = [], [], [], [], [], [] attempts = 0 jammed = False for t in range(1, int(n_ligaments) + 1): width = float(thickness(t)) half = 0.5 * (width + min_spacing) gen = np.random.Generator(np.random.PCG64(np.random.SeedSequence(entropy, spawn_key=(t,)))) failures = k = 0 block = gen.random((16, _DRAWS)) while True: if k == len(block): if void_area <= 1e-12 * area: jammed = True break block, k = gen.random((256, _DRAWS)), 0 draw = block[k] k += 1 px, py = lo[0] + draw[0] * size[0], lo[1] + draw[1] * size[1] if density is not None and draw[2] >= density(px, py): continue i = voids.locate(px, py) if i < 0: continue # in a ligament attempts += 1 if orientation is None: theta = math.pi * draw[3] else: theta = orientation(t, px, py, draw[3], draw[4]) dx, dy = math.cos(theta), math.sin(theta) nx, ny = -dy, dx if fits(voids.cells[i], px, py, nx, ny, half): break failures += 1 if failures >= max_attempts: jammed = True break if jammed: break xy, faces = voids.cells[i], cells_faces[i] s0, s1, f0, f1 = chord(xy, faces, px, py, dx, dy) c = nx * px + ny * py label = t - 1 minus_xy, minus_f = clip_polygon(xy, faces, nx, ny, c - 0.5 * width, label, tol) plus_xy, plus_f = clip_polygon(xy, faces, -nx, -ny, -(c + 0.5 * width), label, tol) body, body_f = clip_polygon(xy, faces, nx, ny, c + 0.5 * width, label, tol) body, _ = clip_polygon(body, body_f, -nx, -ny, -(c - 0.5 * width), label, tol) void_area += polygon_area(minus_xy) + polygon_area(plus_xy) - polygon_area(xy) voids.put(i, minus_xy) cells_faces[i] = minus_f voids.put(len(voids.cells), plus_xy) cells_faces.append(plus_f) nucleation.append((px, py)) angle.append(math.atan2(dy, dx) % math.pi) lam.append(width) ends.append(((px + s0 * dx, py + s0 * dy), (px + s1 * dx, py + s1 * dy))) neighbours.append((f0, f1)) bodies.append(body) body_offsets, body_vertices = _csr(bodies) cell_offsets, cell_vertices = _csr(voids.cells) n = len(lam) return Growth( nucleation=np.asarray(nucleation, dtype=float).reshape(n, 2), angle=np.asarray(angle, dtype=float), thickness=np.asarray(lam, dtype=float), ends=np.asarray(ends, dtype=float).reshape(n, 2, 2), neighbours=np.asarray(neighbours, dtype=np.int64).reshape(n, 2), body_offsets=body_offsets, body_vertices=body_vertices, cell_offsets=cell_offsets, cell_vertices=cell_vertices, cell_faces=np.concatenate(cells_faces).astype(np.int64), jammed=jammed, attempts=attempts, )
# -- theory ------------------------------------------------------------------------------
[docs] def first_length(a: float, b: float) -> float: """The mean length of the first ligament in an ``a x b`` rectangle: the chord through a uniform point along a uniform direction, ``int l^2 dG / (pi a b)`` over the lines ``G``. With ``d = sqrt(a^2 + b^2)``:: l_0 = (2 / pi) (a asinh(b / a) + b asinh(a / b) - (a^2 (d - a) + b^2 (d - b)) / (3 a b)) 0.946402 for the unit square (Kellerer 1971).""" a, b = float(a), float(b) d = math.hypot(a, b) corners = (a * a * (d - a) + b * b * (d - b)) / (3.0 * a * b) return (2.0 / math.pi) * (a * math.asinh(b / a) + b * math.asinh(a / b) - corners)
[docs] def length_sum(decay: float, n_ligaments: int, a: float, b: float) -> float: """``sum_t l_t t^-alpha / sqrt(A)`` of a thin network of ``T`` ligaments in an ``a x b`` rectangle: ``l_0 / sqrt(A) + c sum_{t=2..T} t^-(alpha + 1/2)`` (:data:`LENGTH_CONSTANT`), the relative density per unit of ``lambda_0 / sqrt(A)``.""" area = a * b tail = 0.0 if n_ligaments >= 2: t = np.arange(2, int(n_ligaments) + 1, dtype=float) tail = float(np.sum(t ** (-(decay + 0.5)))) return first_length(a, b) / math.sqrt(area) + LENGTH_CONSTANT * tail
[docs] def density_estimate(first_order: float, dimension: int = 2) -> float: """The relative density of a network from its first order ``rho_1 = sum_t lambda_t E[l_t] / A`` (thin ligaments): a ligament splits a void of area ``A_v / t`` (``A_v`` the area of the voids), so that ``dA_v/dt = -lambda_t c sqrt(A_v / t)`` and ``sqrt(A_v / A) = 1 - rho_1 / 2``: ``rho = rho_1 (1 - rho_1 / 4)``, jammed (1) from ``rho_1 = 2`` on. In ``d`` dimensions (plates in 3D: ``rho_1 = sum_t lambda_t E[a_t] / V``, the area ``a_t`` of a plate about ``c_3 (V_v / t)^(2/3)``), ``(V_v / V)^(1/d) = 1 - rho_1 / d``: ``rho = 1 - (1 - rho_1 / d)^d``, jammed from ``rho_1 = d`` on.""" r, d = float(first_order), int(dimension) return 1.0 if r >= d else 1.0 - (1.0 - r / d) ** d
# -- the field of the ligaments on points of the plane: a grid of buckets ------------------ @njit(cache=True) def _half_planes(vertices, offsets): """Outward unit normals ``n`` and offsets ``c`` of the edges of convex polygons (counter-clockwise): ``phi(x) = max_e (n_e . x - c_e)``, negative inside.""" m = vertices.shape[0] nx = np.zeros(m) ny = np.zeros(m) c = np.full(m, np.inf) # degenerate edges: no constraint for p in range(offsets.shape[0] - 1): a, b = offsets[p], offsets[p + 1] k = b - a for j in range(k): i0, i1 = a + j, a + (j + 1) % k ex, ey = vertices[i1, 0] - vertices[i0, 0], vertices[i1, 1] - vertices[i0, 1] length = math.hypot(ex, ey) if length > 0.0: nx[i0], ny[i0] = ey / length, -ex / length c[i0] = nx[i0] * vertices[i0, 0] + ny[i0] * vertices[i0, 1] return nx, ny, c @njit(cache=True) def _register(boxes, reach, lo0, lo1, h0, h1, g0, g1): """The polygons of each bucket of a ``g0 x g1`` grid: those whose box, widened by ``reach``, meets it (compressed rows).""" n = boxes.shape[0] counts = np.zeros(g0 * g1, dtype=np.int64) for pass_ in range(2): if pass_ == 1: offsets = np.zeros(g0 * g1 + 1, dtype=np.int64) for b in range(g0 * g1): offsets[b + 1] = offsets[b] + counts[b] items = np.empty(offsets[-1], dtype=np.int64) fill = offsets[:-1].copy() for p in range(n): i0 = min(max(math.floor((boxes[p, 0] - reach - lo0) / h0), 0), g0 - 1) i1 = min(max(math.floor((boxes[p, 2] + reach - lo0) / h0), 0), g0 - 1) j0 = min(max(math.floor((boxes[p, 1] - reach - lo1) / h1), 0), g1 - 1) j1 = min(max(math.floor((boxes[p, 3] + reach - lo1) / h1), 0), g1 - 1) for i in range(i0, i1 + 1): for j in range(j0, j1 + 1): if pass_ == 0: counts[i * g1 + j] += 1 else: items[fill[i * g1 + j]] = p fill[i * g1 + j] += 1 return offsets, items @njit(parallel=True, cache=True) def _field(px, py, reach, boxes, offsets, nx, ny, c, b_off, b_items, lo0, lo1, h0, h1, g0, g1): """``min(reach, min_p phi_p(x))`` at points of the plane: negative in the ligaments, the distance to the nearest one near them (``reach``: far from every one).""" out = np.empty(px.shape[0]) for q in prange(px.shape[0]): x, y = px[q], py[q] i = min(max(math.floor((x - lo0) / h0), 0), g0 - 1) j = min(max(math.floor((y - lo1) / h1), 0), g1 - 1) b = i * g1 + j best = reach for k in range(b_off[b], b_off[b + 1]): p = b_items[k] if (x < boxes[p, 0] - reach or x > boxes[p, 2] + reach or y < boxes[p, 1] - reach or y > boxes[p, 3] + reach): # fmt: skip continue phi = -np.inf for e in range(offsets[p], offsets[p + 1]): v = nx[e] * x + ny[e] * y - c[e] if v > phi: phi = v if phi >= best: break if phi < best: best = phi out[q] = best return out class _Index: """The ligaments of a network registered in a grid of buckets of the plane, to evaluate their field (:func:`_field`) within ``reach`` of them.""" def __init__(self, growth: Growth, lower, upper, reach: float) -> None: self.reach = float(reach) v, o = growth.body_vertices, growth.body_offsets self.offsets = o self.nx, self.ny, self.c = _half_planes(v, o) n = growth.n boxes = np.empty((n, 4)) for p in range(n): pts = v[o[p] : o[p + 1]] boxes[p, :2], boxes[p, 2:] = pts.min(axis=0), pts.max(axis=0) self.boxes = boxes lo, hi = np.asarray(lower, dtype=float), np.asarray(upper, dtype=float) size = hi - lo cells = max(1.0, math.sqrt(max(n, 1))) g = np.clip(np.ceil(cells * size / math.sqrt(float(np.prod(size)))), 1, 1024) self.g = (int(g[0]), int(g[1])) self.lo = lo self.h = size / g self.b_off, self.b_items = _register( boxes, self.reach, lo[0], lo[1], self.h[0], self.h[1], *self.g ) def field(self, points) -> np.ndarray: pts = np.ascontiguousarray(np.asarray(points, dtype=float).reshape(-1, 2)) if not len(self.boxes): return np.full(len(pts), self.reach) return _field(pts[:, 0].copy(), pts[:, 1].copy(), self.reach, self.boxes, self.offsets, self.nx, self.ny, self.c, self.b_off, self.b_items, self.lo[0], self.lo[1], self.h[0], self.h[1], *self.g) # fmt: skip # -- the microstructure ------------------------------------------------------------------ def _array(value, shape_tail, dtype=float) -> np.ndarray: return np.asarray(value, dtype=dtype).reshape(-1, *shape_tail)
[docs] @register_kind class ScaleRichStructure(Microstructure): """A scale-rich network extruded along ``axis``: its ligaments (phase 1, convex polygons of the plane of the two other axes, which never overlap) and its voids (phase 0, convex cells), which partition the face of the box exactly (:func:`grow`); or, with a ``frame``, the face within a frame of that thickness (phase 1 too), on which the ligaments end.""" kind = "scale_rich_structure" def __init__(self, domain: Domain, axis: int, growth: Growth, frame: float = 0.0, **kwargs) -> None: # fmt: skip super().__init__(domain, **kwargs) self.axis = int(axis) self.growth = growth self.frame = float(frame) self._indices: dict[float, _Index] = {} # -- the network ------------------------------------------------------------------- @property def plane(self) -> tuple[np.ndarray, np.ndarray]: """The lower and upper corners of the face of the box in the plane.""" b, c = plane_axes(self.axis) d = self.domain return d.lower[[b, c]], d.upper[[b, c]] @property def area(self) -> float: lo, hi = self.plane return float(np.prod(hi - lo)) @property def n_ligaments(self) -> int: return self.growth.n @property def thicknesses(self) -> np.ndarray: return self.growth.thickness @property def lengths(self) -> np.ndarray: """The lengths of the centre lines of the ligaments in their voids.""" return self.growth.lengths
[docs] def degrees(self) -> np.ndarray: """The degree of each ligament in the dual graph: the ligaments it meets.""" return self.growth.degrees()
@property def volume_fraction(self) -> float: """The fraction of the face in the ligaments and the frame, exact (``1 - sum(void areas) / A``).""" return float(1.0 - self.growth.cell_areas().sum() / self.area)
[docs] def orientation_tensor(self) -> np.ndarray: """The orientation tensor of the ligaments (2 x 2, trace 1, axes of the plane).""" return self.growth.orientation_tensor()
@property def geometric_anisotropy(self) -> float: """``mu_1 / mu_2``, the ratio of the eigenvalues of the orientation tensor: 1 for ligaments of isotropic directions, 0 when they are all parallel (Both et al. 2026).""" mu = np.linalg.eigvalsh(self.orientation_tensor()) return float(mu[0] / mu[1]) if mu[1] > 0 else math.nan
[docs] def statistics(self, min_tail: int = 50) -> dict: """The power-law tails of the thicknesses, lengths and degrees of the ligaments (:func:`morphogen.analysis.power_laws.power_law_tail`, degrees as integers): Both et al. find ``1 + 1/alpha``, 3 and 3 for their exponents. No thicknesses with a decay of 0 (one thickness).""" from morphogen.analysis.power_laws import power_law_tail tail = min(int(min_tail), max(2, self.n_ligaments // 2)) out = {} if np.ptp(self.thicknesses) > 0: # a decay of 0: one thickness, no tail out["thickness"] = power_law_tail(self.thicknesses, min_tail=tail) out["length"] = power_law_tail(self.lengths, min_tail=tail) out["degree"] = power_law_tail(self.degrees(), discrete=True, min_tail=tail) return out
[docs] def convex_pieces(self) -> tuple[list[tuple], np.ndarray, np.ndarray]: """The convex pieces that partition the box: the ligaments (phase 1, cells 1 to N) and the voids (phase 0, cell 0) extruded along the axis into prisms, and the frame (phase 1, cell N + 1), for the exact meshes of :func:`morphogen.mesh.exact.polyhedral_mesh`.""" from morphogen.models.scale_rich_3d import prism g = self.growth axes = plane_axes(self.axis) z0, z1 = float(self.domain.lower[self.axis]), float(self.domain.upper[self.axis]) pieces, phase, cells = [], [], [] for t, body in enumerate(g.bodies()): if len(body) >= 3 and polygon_area(body) > 0: pieces.append(prism(body, axes, self.axis, z0, z1)) phase.append(1) cells.append(t + 1) for cell in g.cells(): if len(cell) >= 3 and polygon_area(cell) > 0: pieces.append(prism(cell, axes, self.axis, z0, z1)) phase.append(0) cells.append(0) if self.frame > 0: (u0, v0), (u1, v1) = self.plane f = self.frame for (a0, b0), (a1, b1) in (((u0, v0), (u0 + f, v1)), ((u1 - f, v0), (u1, v1)), ((u0 + f, v0), (u1 - f, v0 + f)), ((u0 + f, v1 - f), (u1 - f, v1))): # fmt: skip rect = [(a0, b0), (a1, b0), (a1, b1), (a0, b1)] pieces.append(prism(rect, axes, self.axis, z0, z1)) phase.append(1) cells.append(g.n + 1) return pieces, np.asarray(phase, dtype=np.int64), np.asarray(cells, dtype=np.int64)
# -- the phases on points and voxels ------------------------------------------------- def _index(self, reach: float) -> _Index: key = round(float(reach), 12) if key not in self._indices: lo, hi = self.plane self._indices.clear() self._indices[key] = _Index(self.growth, lo, hi, reach) return self._indices[key]
[docs] def plane_field(self, points, reach: float = 0.0) -> np.ndarray: """At points of the plane: ``max_e (n_e . x - c_e)`` of the ligament holding them (negative: the distance to its nearest side, or less), or the least such value of the ligaments within ``reach`` (the distance to the nearest one, or less), capped at ``reach``; with a frame, the least of this and the signed distance to the inner side of the frame.""" out = self._index(reach).field(points) if self.frame > 0: pts = np.asarray(points, dtype=float).reshape(-1, 2) lo, hi = self.plane inner = np.minimum(pts - lo, hi - pts).min(axis=1) out = np.minimum(out, inner - self.frame) return out
[docs] def contains(self, points) -> np.ndarray: pts = np.asarray(points, dtype=float).reshape(-1, 3) b, c = plane_axes(self.axis) out = self.plane_field(pts[:, [b, c]]) < 0 return out & np.all((pts >= self.domain.lower) & (pts <= self.domain.upper), axis=1)
[docs] def level_set_at(self, points, reach: float = np.inf) -> np.ndarray: """:meth:`plane_field` of the points within ``reach`` (default: the diagonal of the box), the network extruded along the axis.""" if not np.isfinite(reach): reach = float(self.domain.diagonal) pts = np.asarray(points, dtype=float).reshape(-1, 3) b, c = plane_axes(self.axis) return self.plane_field(pts[:, [b, c]], float(reach))
def _image(self, grid: Grid, reach: float) -> np.ndarray: plane, shape = pixel_centres(grid, plane_axes(self.axis)) return self.plane_field(plane, reach).astype(np.float32).reshape(shape) def _extruded(self, image2d: np.ndarray, grid: Grid) -> np.ndarray: out = np.broadcast_to(image2d[:, :, None], (*image2d.shape, grid.shape[self.axis])) return np.ascontiguousarray(np.moveaxis(out, 2, 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._extruded((self._image(grid, 0.0) < 0).astype(np.uint8), 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") b, c = plane_axes(self.axis) fine_shape = list(grid.shape) fine_shape[b] *= ss fine_shape[c] *= ss fine = Grid(grid.domain, tuple(fine_shape)) inside = (self._image(fine, 0.0) < 0).astype(np.float32) nb, nc = grid.shape[b], grid.shape[c] coarse = inside.reshape(nb, ss, nc, ss).mean(axis=(1, 3), dtype=np.float32) data = self._extruded(coarse, grid) 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: """Negative in the ligaments, positive in the voids: the distance to the sides of the ligaments near them (a lower bound near their corners), within the largest half thickness and four voxels of them.""" grid = self.grid(shape, voxel_size=voxel_size, grid=grid) thick = float(self.thicknesses.max()) if self.n_ligaments else 0.0 reach = 0.5 * thick + 4.0 * float(np.max(grid.spacing)) data = self._extruded(self._image(grid, reach), grid) return VoxelImage.from_grid(data, grid, name="level_set", metadata=self.image_metadata())
# -- description --------------------------------------------------------------------
[docs] def summary(self) -> dict: """The counts, thicknesses, lengths, degrees and anisotropy of the network (the columns of the tables of results).""" g = self.growth out = {"ligaments": g.n, "jammed": int(g.jammed), "volume_fraction": self.volume_fraction} if g.n: deg = g.degrees() out.update( { "initial_thickness": float(g.thickness[0]), "final_thickness": float(g.thickness[-1]), "mean_length": float(g.lengths.mean()), "mean_degree": float(deg.mean()), "max_degree": int(deg.max()), "geometric_anisotropy": self.geometric_anisotropy, } ) return out
def _geometry(self) -> dict: g = self.growth return { "axis": self.axis, "nucleation": g.nucleation.tolist(), "angle": g.angle.tolist(), "thickness": g.thickness.tolist(), "ends": g.ends.tolist(), "neighbours": g.neighbours.tolist(), "bodies": {"offsets": g.body_offsets.tolist(), "vertices": g.body_vertices.tolist()}, "cells": { "offsets": g.cell_offsets.tolist(), "vertices": g.cell_vertices.tolist(), "faces": g.cell_faces.tolist(), }, "jammed": bool(g.jammed), "attempts": int(g.attempts), "frame": self.frame, } @classmethod def _from_geometry(cls, domain, geometry, **kwargs): bodies, cells = geometry["bodies"], geometry["cells"] growth = Growth( nucleation=_array(geometry["nucleation"], (2,)), angle=np.asarray(geometry["angle"], dtype=float).reshape(-1), thickness=np.asarray(geometry["thickness"], dtype=float).reshape(-1), ends=_array(geometry["ends"], (2, 2)), neighbours=_array(geometry["neighbours"], (2,), np.int64), body_offsets=np.asarray(bodies["offsets"], dtype=np.int64), body_vertices=_array(bodies["vertices"], (2,)), cell_offsets=np.asarray(cells["offsets"], dtype=np.int64), cell_vertices=_array(cells["vertices"], (2,)), cell_faces=np.asarray(cells["faces"], dtype=np.int64), jammed=bool(geometry.get("jammed", False)), attempts=int(geometry.get("attempts", 0)), ) return cls(domain, geometry["axis"], growth, geometry.get("frame", 0.0), **kwargs)
# -- the model ---------------------------------------------------------------------------
[docs] @register @dataclass(frozen=True) class ScaleRichNetwork(Model): """Scale-rich network (Both et al. 2026): ligaments ``lambda_0 t^-alpha`` thick grown one after another from points of the voids until they meet: by default (``dimension: 2``) in the plane of the axes other than ``axis`` and extruded along it (see :mod:`morphogen.models.scale_rich`); with ``dimension: 3``, plates or beams in the box (see :mod:`morphogen.models.scale_rich_3d`). The initial thickness is given, or solved on each realization for a relative density (``volume_fraction``). Orientations uniform, among ``angles`` (2D) or drawn from a law (3D), or polarized by a ``pole``; a gradient of the nucleation density. Non-periodic: the ligaments end on the boundary of the box (or on a frame).""" name = "scale_rich_network" phases: ClassVar[dict[int, str]] = {0: "voids", 1: "ligaments"} supports_periodic: ClassVar[bool] = False count_label = "ligaments" n_ligaments: int = param(500, doc="Number of ligaments T, plates or beams in 3D (fewer if " "the network jams)", kind="int") # fmt: skip dimension: int = param( 2, doc="2: a network of the plane extruded along axis (prisms); 3: plates or beams " "in the box", kind="int", ) # fmt: skip element: str = param( "plates", doc="The ligaments in 3D: plates (closed cells) or beams (open cells, " "struts)", kind="str", ) # fmt: skip decay: float = param(0.5, doc="Exponent alpha of the thicknesses lambda_0 t^-alpha") initial_thickness: float | None = param( None, doc="Thickness lambda_0 of the first ligament (the diameter of a beam)", unit="length", ) # fmt: skip volume_fraction: float | None = param( None, doc="Relative density, reached on each realization (solves lambda_0)", kind="fraction", ) # fmt: skip min_spacing: float = param( 0.0, doc="Least width epsilon of the voids beside a new ligament, at its nucleation " "point", unit="length", ) # fmt: skip angles: tuple[float, ...] | None = param( None, doc="In 2D: angles of the ligaments in the plane, drawn among these (degrees; " "default: uniform)", kind="floats", unit="deg", ) # fmt: skip orientation: OrientationDistribution | None = param( None, doc="In 3D: law of the normals of the plates or of the axes of the beams " "(default: isotropic)", kind="orientation", ) # fmt: skip angle_spread: float = param( 0.0, doc="Standard deviation of the angles (3D: of the tilt of the directions) about " "those given or polarized", unit="deg", ) # fmt: skip pole: tuple[float, ...] | None = param( None, doc="Point polarizing the ligaments (two coordinates of the plane in 2D, three " "in 3D): they make pole_angle with the direction of the pole", kind="floats", unit="length", ) # fmt: skip pole_angle: float = param( 0.0, doc="Angle of the polarized ligaments to the direction of the pole (0: radial, " "90: tangential; 3D: plates through it or on spheres about it, beams along it or " "around it, at a uniform azimuth)", unit="deg", ) # fmt: skip polarized_fraction: float = param( 1.0, doc="Fraction of the ligaments, the first ones, polarized by the pole", kind="fraction", ) # fmt: skip nucleation_gradient: tuple[float, ...] | None = param( None, doc="Relative nucleation densities at the lower and upper faces along " "gradient_axis (at the pole and the farthest corner with radial_gradient)", kind="floats", ) # fmt: skip gradient_axis: int | None = param( None, doc="Axis of the gradient of nucleation (in 2D, of the plane; default: the " "first axis of the plane, x in 3D)", kind="int", ) # fmt: skip radial_gradient: bool = param( False, doc="The gradient of nucleation away from the pole", kind="bool" ) frame: float = param( 0.0, doc="Thickness of a frame of material around the network, on which its " "ligaments end (0: none): the sample as the cell of a periodic medium", unit="length", ) # fmt: skip axis: int = param(2, doc="In 2D: axis of the prisms (0: x, 1: y, 2: z)", kind="int") max_attempts: int = param( 1000, doc="Draws in a row that do not fit, after which the network is jammed", kind="int", ) # fmt: skip def _validate(self) -> None: if self.n_ligaments < 1: raise ValueError("n_ligaments: at least one ligament") if self.dimension not in (2, 3): raise ValueError("dimension: 2 (a planar network extruded) or 3") if self.element not in ("plates", "beams"): raise ValueError("element: plates or beams") if self.dimension == 2 and self.element != "plates": raise ValueError("element: beams in 3D only (dimension: 3); the ligaments of a " "planar network are extruded into plates") # fmt: skip check_positive(self.decay, "decay", allow_zero=True) check_positive(self.frame, "frame", allow_zero=True) exactly_one("initial_thickness", self.initial_thickness, "volume_fraction", self.volume_fraction) # fmt: skip if self.initial_thickness is not None: check_positive(self.initial_thickness, "initial_thickness") if self.volume_fraction is not None: check_fraction(self.volume_fraction, "volume_fraction") check_positive(self.min_spacing, "min_spacing", allow_zero=True) if self.angles is not None: if self.dimension == 3: raise ValueError("angles: in 2D only; in 3D, an orientation law") if not self.angles or not all(math.isfinite(a) for a in self.angles): raise ValueError("angles: a list of finite angles in degrees") if self.orientation is not None and self.dimension == 2: raise ValueError("orientation: in 3D only; in 2D, angles") check_positive(self.angle_spread, "angle_spread", allow_zero=True) if self.pole is not None: d = self.dimension if len(self.pole) != d or not all(math.isfinite(v) for v in self.pole): where = "of the plane" if d == 2 else "of space" raise ValueError(f"pole: the {d} coordinates of a point {where}") if not math.isfinite(self.pole_angle): raise ValueError("pole_angle: a finite angle in degrees") if not 0.0 <= self.polarized_fraction <= 1.0: raise ValueError("polarized_fraction: from 0 to 1") if self.polarized_fraction < 1.0 and self.pole is None: raise ValueError("polarized_fraction: the fraction polarized by a pole") if self.axis not in (0, 1, 2): raise ValueError("axis: 0, 1 or 2") if self.gradient_axis is not None: axes = plane_axes(self.axis) if self.dimension == 2 else (0, 1, 2) if self.gradient_axis not in axes: where = "of the plane" if self.dimension == 2 else "of space" raise ValueError(f"gradient_axis: an axis {where}, {tuple(axes)}") if self.nucleation_gradient is not None: w = self.nucleation_gradient if len(w) != 2 or not all(math.isfinite(v) and v >= 0 for v in w) or max(w) <= 0: raise ValueError("nucleation_gradient: two non-negative densities, not both 0") if self.radial_gradient and (self.pole is None or self.nucleation_gradient is None): raise ValueError("radial_gradient: a pole and a nucleation_gradient") if self.max_attempts < 1: raise ValueError("max_attempts: at least 1") @property def isotropic(self) -> bool: """Uniform orientations and nucleation: the laws of :meth:`theory` hold.""" return (self.angles is None and self.orientation is None and self.pole is None and self.nucleation_gradient is None) # fmt: skip @property def plates(self) -> bool: """Plates in 3D (closed cells), or the extruded ligaments of a planar network.""" return self.element == "plates" # -- the growth ----------------------------------------------------------------------- def _orientation(self): """The angles of the ligaments of a planar network (:func:`grow`).""" if self.angles is None and self.pole is None: return None spread = math.radians(self.angle_spread) angles = None if self.angles is None else [math.radians(a) for a in self.angles] polar = 0 if self.pole is None else math.ceil(self.polarized_fraction * self.n_ligaments) turn = math.radians(self.pole_angle) pole = self.pole normal = NormalDist() def orientation(t, x, y, u, v): if t <= polar: base = math.atan2(pole[1] - y, pole[0] - x) + turn elif angles is not None: base = angles[min(int(u * len(angles)), len(angles) - 1)] else: return math.pi * u if spread > 0.0: base += spread * normal.inv_cdf(min(max(v, 1e-16), 1.0 - 1e-16)) return base return orientation def _directions(self): """The normals of the plates or the axes of the beams in 3D (:func:`grow_plates`): polarized by the pole, at the angle ``beta`` (``pole_angle``) to its direction ``r`` and a uniform azimuth (plates: ``n . r = sin beta``, beams: ``d . r = cos beta``), drawn from the orientation law or uniform; tilted by a normal law of ``angle_spread``.""" if self.orientation is None and self.pole is None: return None spread = math.radians(self.angle_spread) law = self.orientation polar = 0 if self.pole is None else math.ceil(self.polarized_fraction * self.n_ligaments) beta = math.radians(self.pole_angle) # the share of the direction of the pole in the normal of a plate, the axis of a beam along, side = math.cos(beta), math.sin(beta) if self.plates: along, side = side, along pole = None if self.pole is None else np.asarray(self.pole, dtype=float) def directions(t, points, gen): k = len(points) if t <= polar: r = pole - points norm = np.linalg.norm(r, axis=1, keepdims=True) r = np.where(norm > 0, r / np.where(norm > 0, norm, 1.0), (0.0, 0.0, 1.0)) e1, e2 = orthonormal_basis(r) psi = 2.0 * np.pi * gen.random(k)[:, None] d = along * r + side * (np.cos(psi) * e1 + np.sin(psi) * e2) elif law is not None: d = np.asarray(law.sample(gen, k), dtype=float).reshape(k, 3) else: d = uniform_unit_vectors(gen, k) if spread > 0.0: e1, e2 = orthonormal_basis(d) g = spread * gen.standard_normal((k, 2)) tilt = np.hypot(g[:, 0], g[:, 1])[:, None] way = (g[:, :1] * e1 + g[:, 1:] * e2) / np.where(tilt > 0, tilt, 1.0) d = np.cos(tilt) * d + np.sin(tilt) * way return d / np.linalg.norm(d, axis=1, keepdims=True) return directions def _density(self, lower, upper): """The relative density of nucleation at a point (2 or 3 coordinates).""" if self.nucleation_gradient is None: return None w0, w1 = (float(w) for w in self.nucleation_gradient) top = max(w0, w1) lower = [float(v) for v in lower] upper = [float(v) for v in upper] if self.radial_gradient: pole = [float(v) for v in self.pole] corners = itertools.product(*zip(lower, upper, strict=True)) far = max(math.dist(c, pole) for c in corners) def density(*x): s = min(math.dist(x, pole) / far, 1.0) if far > 0 else 0.0 return (w0 + (w1 - w0) * s) / top return density if self.dimension == 2: axes = plane_axes(self.axis) k = axes.index(axes[0] if self.gradient_axis is None else self.gradient_axis) else: k = 0 if self.gradient_axis is None else int(self.gradient_axis) lo, span = lower[k], upper[k] - lower[k] def density(*x): s = (x[k] - lo) / span return (w0 + (w1 - w0) * s) / top return density def _grow(self, lower, upper, thickness: float, entropy: int): decay = float(self.decay) def law(t): return thickness * t ** (-decay) common = { "density": self._density(lower, upper), "min_spacing": float(self.min_spacing), "max_attempts": int(self.max_attempts), } if self.dimension == 2: return grow(lower, upper, self.n_ligaments, law, entropy, orientation=self._orientation(), **common) # fmt: skip grow3 = grow_plates if self.plates else grow_beams return grow3(lower, upper, self.n_ligaments, law, entropy, directions=self._directions(), **common) # fmt: skip def _region(self, domain: Domain) -> tuple[np.ndarray, np.ndarray]: """The corners of the region of the network within the frame: the face of the box in the plane (2D), or the box.""" if self.dimension == 2: b, c = plane_axes(self.axis) lower, upper = domain.lower[[b, c]], domain.upper[[b, c]] else: lower, upper = domain.lower, domain.upper lower, upper = lower + self.frame, upper - self.frame if not np.all(upper > lower): raise ValueError("frame: thinner than half the sides of the box") return lower, upper def _sides(self, domain: Domain) -> tuple[float, ...]: """The sides of the region of the network (within the frame).""" lower, upper = self._region(domain) return tuple(float(v) for v in upper - lower) def _total(self, domain: Domain) -> float: """The area of the face of the box (2D), or its volume.""" if self.dimension == 2: b, c = plane_axes(self.axis) return float(domain.lengths[b] * domain.lengths[c]) return float(domain.volume) def _relative_density(self, growth, domain: Domain) -> float: total = self._total(domain) if self.dimension == 2: return float(1.0 - growth.cell_areas().sum() / total) if self.plates: return float(1.0 - growth.cell_volumes().sum() / total) return ScaleRichBeams(domain, growth, frame=self.frame).volume_fraction
[docs] def thickness_estimate(self, domain: Domain) -> float: """The initial thickness of the ``volume_fraction`` by the theory (uniform orientations and nucleation), ``rho`` the density of the network within the frame (of area ``A``, volume ``V``): in 2D, ``lambda_0 = 2 sqrt(A) (1 - sqrt(1 - rho)) / S`` (:func:`density_estimate`, :func:`length_sum`); with plates, ``lambda_0 = 3 V^(1/3) (1 - (1 - rho)^(1/3)) / S`` (:func:`area_sum`); with beams, the mean field of :func:`beam_density_estimate`.""" if self.volume_fraction is None: return float(self.initial_thickness) sides = self._sides(domain) inner = float(np.prod(sides)) rho = 1.0 - (1.0 - self.volume_fraction) * self._total(domain) / inner if rho <= 0: raise ValueError("volume_fraction: below the fraction of the frame alone") if self.dimension == 2: s = length_sum(self.decay, self.n_ligaments, *sides) return 2.0 * math.sqrt(inner) * (1.0 - math.sqrt(1.0 - rho)) / s if self.plates: s = area_sum(self.decay, self.n_ligaments, *sides) return 3.0 * inner ** (1.0 / 3.0) * (1.0 - (1.0 - rho) ** (1.0 / 3.0)) / s return beam_thickness_estimate(rho, self.decay, self.n_ligaments, sides)
def _solve(self, entropy: int, domain: Domain): """The initial thickness of the realization of ``entropy`` at the relative density: regula falsi (Illinois) from the estimate of the theory, to :data:`DENSITY_TOL`. The draws of each ligament do not depend on the thicknesses (:func:`grow`), but a nucleation point or an end close to a moved side may change the network from it on: the density may jump where the tolerance is not met, and the side of the jump closer to the target is kept.""" target = float(self.volume_fraction) lower, upper = self._region(domain) size = float(np.max(domain.lengths)) runs: dict[float, tuple] = {} def excess(lam: float) -> float: if lam not in runs: g = self._grow(lower, upper, lam, entropy) runs[lam] = (self._relative_density(g, domain) - target, g) return runs[lam][0] guess = self.thickness_estimate(domain) a, b = 0.9 * guess, 1.1 * guess while excess(a) > 0: a *= 0.7 while excess(b) < 0: if runs[b][1].jammed or b > size: raise ValueError( f"volume_fraction: {target} is beyond the network, which jams at about " f"{excess(b) + target:.3f} (fewer ligaments, a smaller decay or no " "min_spacing)" ) a, b = b, 1.4 * b fa, fb = excess(a), excess(b) side = 0 for _ in range(60): if min(abs(excess(a)), abs(excess(b))) <= DENSITY_TOL or b - a <= 1e-9 * guess: break c = (a * fb - b * fa) / (fb - fa) if not a < c < b: c = 0.5 * (a + b) fc = excess(c) if fc > 0: b, fb = c, fc if side == 1: fa *= 0.5 # Illinois: the stale end weighs less side = 1 else: a, fa = c, fc if side == -1: fb *= 0.5 side = -1 lam = min((a, b), key=lambda x: abs(excess(x))) return float(lam), runs[lam][1]
[docs] def generate(self, domain: Domain, seed: SeedLike = None) -> Microstructure: self._check_domain(domain) rng, seed_info = make_rng(seed) entropy = int(rng.integers(0, 2**63)) if self.initial_thickness is not None: lam0 = float(self.initial_thickness) growth = self._grow(*self._region(domain), lam0, entropy) else: lam0, growth = self._solve(entropy, domain) if self.dimension == 2: micro = ScaleRichStructure(domain, self.axis, growth, frame=self.frame, model=self, seed=seed_info) # fmt: skip micro.metadata["summary"] = self._summary(micro, lam0) return micro kind = ScaleRichPlates if self.plates else ScaleRichBeams micro = kind(domain, growth, frame=self.frame, model=self, seed=seed_info) micro.metadata["summary"] = self._summary_3d(micro, lam0) return micro
@staticmethod def _summary(micro: ScaleRichStructure, lam0: float) -> dict: g = micro.growth out = { "ligaments": g.n, "jammed": int(g.jammed), "attempts": g.attempts, "initial_thickness": lam0, "volume_fraction": micro.volume_fraction, "voids": g.n_cells, "boundary_ends": int(np.count_nonzero(g.neighbours == BOX)), } if not g.n: return out lengths, degrees = g.lengths, g.degrees() mu, vectors = np.linalg.eigh(g.orientation_tensor()) main = vectors[:, 1] # the direction of the larger eigenvalue out.update( { "final_thickness": float(g.thickness[-1]), "mean_length": float(lengths.mean()), "max_length": float(lengths.max()), "mean_degree": float(degrees.mean()), "max_degree": int(degrees.max()), "geometric_anisotropy": float(mu[0] / mu[1]), "principal_angle": float(math.degrees(math.atan2(main[1], main[0])) % 180.0), } ) return out @staticmethod def _summary_3d(micro, lam0: float) -> dict: g = micro.growth plates = isinstance(micro, ScaleRichPlates) out = { "ligaments": g.n, "jammed": int(g.jammed), "attempts": g.attempts, "initial_thickness": lam0, "volume_fraction": micro.volume_fraction, } if plates: out["voids"] = g.n_cells out["boundary_plates"] = int(np.count_nonzero(g.boundary_contacts())) else: out["boundary_ends"] = int(np.count_nonzero(g.neighbours == BOX)) if not g.n: return out sizes = g.areas if plates else g.lengths degrees = g.degrees() mu = np.linalg.eigvalsh(g.orientation_tensor()) name = "area" if plates else "length" out.update( { "final_thickness": float(g.thickness[-1]), f"mean_{name}": float(sizes.mean()), f"max_{name}": float(sizes.max()), "mean_degree": float(degrees.mean()), "max_degree": int(degrees.max()), "geometric_anisotropy": float(mu[0] / mu[2]), } ) return out # -- theory ------------------------------------------------------------------------
[docs] def expected_count(self, domain: Domain) -> float: return float(self.n_ligaments)
[docs] def theory(self, domain: Domain | None = None) -> dict[str, float]: """The exponent ``1 + 1/alpha`` of the law of the thicknesses (exact, ``alpha > 0``), and the asymptotic exponents of the tails of the sizes and degrees: 3 for the lengths and degrees of a planar network (Both et al. 2026), 5/2 for the areas and degrees of plates (``(2d - 1) / (d - 1)`` in ``d`` dimensions). With the domain, for uniform orientations and nucleation: in 2D, the mean length of the first ligament (:func:`first_length`, exact), the first order ``rho_1 = lambda_0 S / sqrt(A)`` of the relative density (:func:`length_sum`), its mean-field estimate ``rho_1 (1 - rho_1 / 4)`` (:func:`density_estimate`), the initial thickness at which ``T`` ligaments jam (``rho_1 = 2``) and, for ``alpha > 1/2``, at which an endless growth jams (``S`` with ``zeta(alpha + 1/2)``: the boundary of the phase diagram of the paper); with plates, the mean area of the first plate (:func:`first_area`, exact), ``rho_1 = lambda_0 S / V^(1/3)`` (:func:`area_sum`), ``1 - (1 - rho_1 / 3)^3``, jammed at ``rho_1 = 3``, endless for ``alpha > 1/3`` (``zeta(alpha + 2/3)``); with beams, the mean-field estimate of :func:`beam_density_estimate`. With a ``volume_fraction``, the initial thickness that the theory gives it. With a frame, the network fills the region within it, and the relative densities count the frame.""" out: dict[str, float] = {} if self.decay > 0: out["thickness_exponent"] = 1.0 + 1.0 / self.decay if self.dimension == 2: out.update({"length_exponent": 3.0, "degree_exponent": 3.0}) elif self.plates: out.update({"area_exponent": 2.5, "degree_exponent": 2.5}) if domain is None or not self.isotropic: return out sides = self._sides(domain) inner = float(np.prod(sides)) / self._total(domain) # the share within the frame lam0 = self.thickness_estimate(domain) if self.volume_fraction is not None: out["initial_thickness"] = lam0 if self.dimension == 3 and not self.plates: rho = beam_density_estimate(lam0, self.decay, self.n_ligaments, sides) out["volume_fraction"] = 1.0 - inner + inner * rho return out d = self.dimension root = float(np.prod(sides)) ** (1.0 / d) # sqrt(A) or V^(1/3) if d == 2: s = length_sum(self.decay, self.n_ligaments, *sides) out["first_length"] = first_length(*sides) first, constant, shift = out["first_length"] / root, LENGTH_CONSTANT, 0.5 else: s = area_sum(self.decay, self.n_ligaments, *sides) out["first_area"] = first_area(*sides) first, constant, shift = out["first_area"] / root**2, AREA_CONSTANT, 1.0 - 1.0 / d out["jamming_thickness"] = d * root / s if self.decay > 1.0 - shift: from scipy.special import zeta endless = first + constant * (zeta(self.decay + shift) - 1.0) out["endless_jamming_thickness"] = float(d * root / endless) rho1 = lam0 * s / root out["volume_fraction_first_order"] = 1.0 - inner + inner * rho1 if rho1 < d: out["volume_fraction"] = 1.0 - inner + inner * density_estimate(rho1, d) return out