Source code for morphogen.models.levelset_foam

"""Foams as level sets of distance fields (Sonon, François & Massart 2012, 2015; Kilingar,
Sonon & Massart 2019; Degdeg & Dirrenberger 2026).

Seeds: non-overlapping ellipsoids aligned with the axes, of short semi-axis ``a`` (a
distribution) and shape factors ``b/a`` and ``c/a`` (``aspect``): a dense packing of
polydisperse spheres (Lubachevsky–Stillinger) or their random sequential addition,
mapped by the stretch of the y and z axes, so that the packing of the ellipsoids is the
affine image of that of spheres (as the packing of Degdeg & Dirrenberger, whose aligned
ellipsoids fall into a container). Each seed defines the normalized algebraic distance

    D_i(x) = sum_m (x_m - x_im)^2 / r_im^2 - 1

(-1 at its centre, 0 on its surface), and ``D_N1 <= D_N2 <= D_N3 <= D_N4`` are the four
smallest at ``x``. The open foam is the region ``Phi <= 0`` of

    Phi = O_p - t O_s - K_c O_k
    O_p = (D_N3 + D_N2)/2 - D_N1             zero on the edges of the tessellation
    O_s = sqrt(c1 xi^4 + c2 xi^2 + 1)          thickening towards the nodes
    O_k = min(0, (delta^2 - w^2) / (2 w))      delta = (D_N3 - D_N2)/2, w = t O_s

``t`` the thickness (dimensionless; or solved for a ``volume_fraction``), ``K_c`` the
curvature of the cross-sections of the struts (``0 < K_c < 1``: the concave Plateau
borders of drained foams; ``K_c < 0``: convex), ``xi`` the position along the strut (0
at mid-span, 1/2 at the nodes): ``D_N4 - D_N3`` vanishes at the nodes and is largest at
mid-span, and ``xi = (1 - (D_N4 - D_N3)/m)/2`` with ``m`` its largest value near the
axis of the strut (the strut of the three nearest seeds), found on a fine grid at
generation. Closed cells add walls where ``D_N2 = D_N1``:
``Phi = min(Phi, (D_N2 - D_N1)/2 - t_w)``.

:func:`calibrate_seeds` scales the seeds (and, if asked, changes their shape factors)
until the mean radii of the sections of the pores by the planes of the grid match
measured ones, the cells of a packing being larger than its seeds.
"""

from __future__ import annotations

import dataclasses
import math
from dataclasses import dataclass
from typing import ClassVar

import numpy as np
from scipy.spatial import cKDTree

from morphogen._utils import check_fraction, check_positive
from morphogen.distributions import Constant, Distribution, distribution_from_config
from morphogen.domain import Domain, Grid
from morphogen.image import VoxelImage
from morphogen.kernels.rsa import random_sequential_addition
from morphogen.models.base import Microstructure, Model, param, register, register_kind
from morphogen.models.hardcore import grown_packing
from morphogen.seeding import SeedLike, make_rng

_CHUNK = 1 << 18
_NEAR = 1.0  # points of a strut: O_p below this (normalized units)


[docs] def nearest_distances(points, centres, radii, box, periodic: bool, k: int = 16): """The four smallest ``|y - y_i|^2 / a_i^2 - 1`` at ``points`` (y-space: the seeds are spheres of radii ``radii``) and the indices of their seeds, from the ``k`` nearest centres (more where the four could hide beyond them).""" n = len(centres) tree = cKDTree(centres, boxsize=box if periodic else None) pts = np.mod(points, box) if periodic else points a2 = radii**2 amax2 = float(a2.max()) dn = np.empty((len(pts), 4)) nn = np.empty((len(pts), 4), dtype=np.int64) todo = np.arange(len(pts)) kk = min(k, n) while todo.size: d, idx = tree.query(pts[todo], k=kk, workers=-1) ds = d * d / a2[idx] - 1.0 order = np.argsort(ds, axis=1)[:, :4] rows = np.arange(len(todo))[:, None] dn[todo] = ds[rows, order] nn[todo] = idx[rows, order] if kk >= n: break bound = d[:, -1] ** 2 / amax2 - 1.0 # no seed beyond the k nearest is closer todo = todo[dn[todo, 3] > bound] kk = min(2 * kk, n) return dn, nn
[docs] def strut_keys(nn: np.ndarray, n: int) -> np.ndarray: """Key of the strut of the three nearest seeds (their sorted indices).""" s = np.sort(nn[:, :3], axis=1) return (s[:, 0] * n + s[:, 1]) * n + s[:, 2]
[docs] @register_kind class DistanceFieldFoam(Microstructure): """A foam, the region ``Phi <= 0`` of the level-set function of its seeds (see the module); the same realization can be evaluated at any resolution and point.""" kind = "distance_field_foam" def __init__( self, domain, centres, axes, box_lower, box_lengths, thickness, *, curvature: float = 0.0, c1: float = 0.0, c2: float = 0.0, cells: str = "open", wall_thickness: float = 0.0, periodic_box: bool = True, struts=None, **kwargs, ): super().__init__(domain, **kwargs) self.centres = np.asarray(centres, dtype=float).reshape(-1, 3) self.axes = np.asarray(axes, dtype=float).reshape(-1, 3) if len(self.centres) < 5: raise ValueError("distance_field_foam: five seeds at least") self.box_lower = np.asarray(box_lower, dtype=float) self.box_lengths = np.asarray(box_lengths, dtype=float) self.thickness = float(thickness) self.curvature = float(curvature) self.c1, self.c2 = float(c1), float(c2) self.cells = cells self.wall_thickness = float(wall_thickness) self.periodic_box = bool(periodic_box) # aligned ellipsoids of equal shapes: spheres in the y-space x / (1, b/a, c/a) self.scale = self.axes[0] / self.axes[0, 0] if not np.allclose(self.axes / self.axes[:, :1], self.scale, rtol=1e-9): raise ValueError("distance_field_foam: seeds of the same shape (aspect) only") self.struts = None if struts is not None: keys, top = struts self.struts = (np.asarray(keys, dtype=np.int64), np.asarray(top, dtype=float)) # -- distance fields ----------------------------------------------------------------
[docs] def distances(self, points) -> tuple[np.ndarray, np.ndarray]: """``D_N1..D_N4`` and the indices of their seeds at ``points`` (n x 3).""" y = (np.asarray(points, dtype=float) - self.box_lower) / self.scale cy = (self.centres - self.box_lower) / self.scale box = self.box_lengths / self.scale dn = np.empty((len(y), 4)) nn = np.empty((len(y), 4), dtype=np.int64) for s in range(0, len(y), _CHUNK): dn[s : s + _CHUNK], nn[s : s + _CHUNK] = nearest_distances( y[s : s + _CHUNK], np.mod(cy, box), self.axes[:, 0], box, self.periodic_box ) return dn, nn
[docs] def learn_struts(self, dn: np.ndarray, nn: np.ndarray) -> None: """Largest ``D_N4 - D_N3`` of each strut, over the points near its axis.""" op = 0.5 * (dn[:, 2] + dn[:, 1]) - dn[:, 0] near = op <= _NEAR keys = strut_keys(nn[near], len(self.centres)) gap = dn[near, 3] - dn[near, 2] uniq, inverse = np.unique(keys, return_inverse=True) top = np.zeros(len(uniq)) np.maximum.at(top, inverse, gap) self.struts = (uniq, top)
def _position(self, dn, nn) -> np.ndarray: """``xi`` along the struts: 0 at mid-span, 1/2 at the nodes.""" if self.struts is None or len(self.struts[0]) == 0 or (self.c1 == 0 and self.c2 == 0): return np.zeros(len(dn)) keys, top = self.struts k = strut_keys(nn, len(self.centres)) i = np.clip(np.searchsorted(keys, k), 0, len(keys) - 1) m = np.where(keys[i] == k, top[i], float(np.median(top))) ratio = np.divide(dn[:, 3] - dn[:, 2], m, out=np.ones(len(dn)), where=m > 0) return 0.5 * (1.0 - np.clip(ratio, 0.0, 1.0))
[docs] def phi(self, dn, nn, thickness: float | None = None) -> np.ndarray: """The level-set function (solid where it is not positive).""" t = self.thickness if thickness is None else float(thickness) xi = self._position(dn, nn) o_s = np.sqrt(self.c1 * xi**4 + self.c2 * xi**2 + 1.0) o_p = 0.5 * (dn[:, 2] + dn[:, 1]) - dn[:, 0] out = o_p - t * o_s if t > 0.0 and self.curvature != 0.0: w = t * o_s delta = 0.5 * (dn[:, 2] - dn[:, 1]) out -= self.curvature * np.minimum(0.0, (delta**2 - w**2) / (2.0 * w)) if self.cells == "closed": out = np.minimum(out, 0.5 * (dn[:, 1] - dn[:, 0]) - self.wall_thickness) return out
[docs] def values(self, points) -> np.ndarray: dn, nn = self.distances(points) return self.phi(dn, nn)
# -- microstructure ------------------------------------------------------------------- def _grid_values(self, grid: Grid) -> np.ndarray: pts = np.stack( np.meshgrid(*[grid.centers(a) for a in range(3)], indexing="ij"), axis=-1 ).reshape(-1, 3) return self.values(pts).reshape(grid.shape)
[docs] def field(self, shape=None, *, voxel_size=None, grid: Grid | None = None) -> VoxelImage: grid = self.grid(shape, voxel_size=voxel_size, grid=grid) data = self._grid_values(grid).astype(np.float32) return VoxelImage.from_grid(data, grid, name="phi", metadata=self.image_metadata())
[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 not 1 <= ss <= 6: raise ValueError("supersampling must be an integer between 1 and 6") if ss == 1: data = (self._grid_values(grid) <= 0.0).astype(np.uint8) return VoxelImage.from_grid(data, grid, name="phase", metadata=self.image_metadata()) fine = Grid(grid.domain, tuple(n * ss for n in grid.shape)) inside = (self._grid_values(fine) <= 0.0).astype(np.float32) nx, ny, nz = grid.shape data = inside.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: """``Phi`` times half the mean short semi-axis: negative in the solid, roughly a distance near its surface (``|grad D_i|`` is about ``2 / a`` there).""" f = self.field(shape, voxel_size=voxel_size, grid=grid) data = f.data * np.float32(0.5 * float(self.axes[:, 0].mean())) return f.with_data(data.astype(np.float32), name="level_set")
[docs] def contains(self, points) -> np.ndarray: return self.values(np.asarray(points, dtype=float).reshape(-1, 3)) <= 0.0
#: ``Phi`` grows at most twice as fast as the distance to the nearest seed lipschitz = 1.5
[docs] def level_set_at(self, points, reach: float = np.inf) -> np.ndarray: """``Phi`` times half the mean short semi-axis at the points, as :meth:`level_set`.""" values = self.values(np.asarray(points, dtype=float).reshape(-1, 3)) return values * 0.5 * float(self.axes[:, 0].mean())
[docs] def summary(self) -> dict: return { "seeds": len(self.centres), "thickness": self.thickness, "struts": 0 if self.struts is None else len(self.struts[0]), }
def _geometry(self) -> dict: return { "centres": self.centres.tolist(), "axes": self.axes.tolist(), "box_lower": self.box_lower.tolist(), "box_lengths": self.box_lengths.tolist(), "thickness": self.thickness, "curvature": self.curvature, "c1": self.c1, "c2": self.c2, "cells": self.cells, "wall_thickness": self.wall_thickness, "periodic_box": self.periodic_box, "struts": None if self.struts is None else [self.struts[0].tolist(), self.struts[1].tolist()], } @classmethod def _from_geometry(cls, domain, geometry, **kwargs): g = dict(geometry) return cls( domain, g.pop("centres"), g.pop("axes"), g.pop("box_lower"), g.pop("box_lengths"), g.pop("thickness"), **g, **kwargs, )
[docs] @register @dataclass(frozen=True) class LevelSetFoam(Model): """Open- or closed-cell foams as level sets of the distance fields of a packing of aligned ellipsoids (Sonon et al. 2012; Kilingar et al. 2019; Degdeg & Dirrenberger 2026): struts with Plateau-border cross-sections of controlled curvature, thickening towards the nodes, cells elongated by the shape of the seeds (see the module).""" name = "level_set_foam" phases: ClassVar[dict[int, str]] = {0: "pores", 1: "solid"} count_label = "seeds" seed_radius: Distribution = param( Constant(0.1), doc="Short semi-axis a of the seed ellipsoids", kind="distribution", unit="length", ) aspect: tuple[float, ...] = param( (1.0, 1.0), doc="Shape factors b/a and c/a of the seeds (semi-axes along y and z)", kind="floats", ) packing: str = param( "dense", doc="Packing of the seeds: dense (Lubachevsky-Stillinger) or rsa (random sequential " "addition)", kind="str", ) packing_fraction: float = param( 0.6, doc="Volume fraction of the seed ellipsoids", kind="fraction" ) thickness: float | None = param( None, doc="Thickness t of the struts (dimensionless; or give volume_fraction)" ) volume_fraction: float | None = param( None, doc="Solid volume fraction, reached by solving for t", kind="fraction" ) curvature: float = param( 0.0, doc="Curvature K_c of the cross-sections: 0 < K_c < 1 concave, K_c < 0 convex" ) c1: float = param(0.0, doc="Node thickening: A(xi) = c1 xi^4 + c2 xi^2 + 1") c2: float = param(0.0, doc="Node thickening: A(xi) = c1 xi^4 + c2 xi^2 + 1") cells: str = param("open", doc="open (struts) or closed (struts and walls)", kind="str") wall_thickness: float = param( 0.05, doc="Thickness of the walls of closed cells (dimensionless)" ) growth_rate: float = param(0.01, doc="Growth rate of the dense packing", unit="") def _validate(self) -> None: if len(self.aspect) != 2 or min(self.aspect) <= 0: raise ValueError("aspect: two positive shape factors, b/a and c/a") if self.packing not in ("dense", "rsa"): raise ValueError("packing: dense or rsa") check_fraction(self.packing_fraction, "packing_fraction") if (self.thickness is None) == (self.volume_fraction is None): raise ValueError("give exactly one of thickness and volume_fraction") if self.thickness is not None: check_positive(self.thickness, "thickness") else: check_fraction(self.volume_fraction, "volume_fraction") if not self.curvature < 1.0: raise ValueError("curvature: K_c < 1") if self.cells not in ("open", "closed"): raise ValueError("cells: open or closed") check_positive(self.wall_thickness, "wall_thickness", allow_zero=True) check_positive(self.growth_rate, "growth_rate") @property def scale(self) -> np.ndarray: return np.array([1.0, *self.aspect]) def _radii(self, rng, volume: float) -> np.ndarray: """Short semi-axes of the seeds filling ``packing_fraction`` of ``volume``.""" shape = float(np.prod(self.scale)) target = self.packing_fraction * volume radii = np.empty(0) while True: m = int(1.2 * target / (4.0 / 3.0 * math.pi * shape * self.seed_radius.moment(3))) + 8 radii = np.concatenate([radii, self.seed_radius.sample(rng, m)]) cum = np.cumsum(4.0 / 3.0 * math.pi * shape * radii**3) if cum[-1] >= target: return radii[: int(np.searchsorted(cum, target)) + 1]
[docs] def seeds(self, domain: Domain, rng) -> tuple[np.ndarray, np.ndarray, Domain]: """Centres and semi-axes of the seed ellipsoids, and their periodic box (the domain if periodic, enlarged by two long semi-axes otherwise).""" reach = 2.0 * float(self.seed_radius.upper()) * float(self.scale.max()) box = domain if domain.periodic else domain.dilated(reach) radii = self._radii(rng, box.volume) lengths = box.lengths / self.scale # the box of the spheres if self.packing == "dense": if np.any(lengths < 6.0 * radii.max()): raise ValueError( "level_set_foam: the dense packing needs a box of three seed diameters along " "each axis (the long ones included): enlarge it or use packing: rsa" ) pos = grown_packing(radii, lengths, rng, growth_rate=self.growth_rate) else: order = np.argsort(-radii, kind="stable") pos = np.empty((len(radii), 3)) pos[order] = random_sequential_addition( radii[order], lengths, 0.0, rng, 10_000 * len(radii) ) centres = box.lower + pos * self.scale return centres, radii[:, None] * self.scale, box
[docs] def generate(self, domain: Domain, seed: SeedLike = None) -> DistanceFieldFoam: rng, seed_info = make_rng(seed) centres, axes, box = self.seeds(domain, rng) foam = DistanceFieldFoam( domain, centres, axes, box.lower, box.lengths, self.thickness if self.thickness is not None else 0.0, curvature=self.curvature, c1=self.c1, c2=self.c2, cells=self.cells, wall_thickness=self.wall_thickness, periodic_box=True, model=self, seed=seed_info, ) # the struts (and the thickness) on a grid of about eight voxels per short semi-axis h = float(self.seed_radius.moment(1)) / 8.0 n = np.maximum(8, np.ceil(domain.lengths / h)).astype(int) while np.prod(n) > 2_000_000: n = np.maximum(8, n // 2 + 1) grid = Grid(domain, tuple(int(v) for v in n)) pts = np.stack(np.meshgrid(*[grid.centers(a) for a in range(3)], indexing="ij"), axis=-1) dn, nn = foam.distances(pts.reshape(-1, 3)) foam.learn_struts(dn, nn) if self.volume_fraction is not None: foam.thickness = self._solve_thickness(foam, dn, nn) return foam
def _solve_thickness(self, foam, dn, nn) -> float: """Bisection of the solid fraction of the generation grid (increasing with t).""" target = self.volume_fraction lo, hi = 0.0, 0.5 while np.mean(foam.phi(dn, nn, hi) <= 0.0) < target: lo, hi = hi, 2.0 * hi if hi > 64.0: raise ValueError("level_set_foam: the volume fraction cannot be reached") for _ in range(50): mid = 0.5 * (lo + hi) if np.mean(foam.phi(dn, nn, mid) <= 0.0) < target: lo = mid else: hi = mid return 0.5 * (lo + hi)
[docs] def expected_count(self, domain: Domain) -> float: shape = float(np.prod(self.scale)) return ( self.packing_fraction * domain.volume / (4.0 / 3.0 * math.pi * shape * self.seed_radius.moment(3)) )
[docs] def theory(self, domain: Domain | None = None) -> dict[str, float]: shape = float(np.prod(self.scale)) return { "seed_packing_fraction": self.packing_fraction, "seed_intensity": self.packing_fraction / (4.0 / 3.0 * math.pi * shape * self.seed_radius.moment(3)), }
#: Keys of the configurations of distributions that are lengths. _LENGTHS = ("value", "low", "high", "mean", "std") #: d log kappa_D / d (log s, log b/a, log c/a) of the sections normal to x, y and z of #: ellipsoids of semi-axes a, b, c along x, y, z (kappa_x = sqrt(bc)/a, kappa_y = sqrt(c/a), #: kappa_z = sqrt(b/a), in units of a). _SECTION_JACOBIAN = np.array([[1.0, 0.5, 0.5], [1.0, 0.0, 0.5], [1.0, 0.5, 0.0]]) def _scaled(distribution: Distribution, factor: float) -> Distribution: """``distribution`` of lengths multiplied by ``factor``.""" cfg = distribution.to_config() if not isinstance(cfg, dict): return Constant(float(cfg) * factor) out = {} for key, value in cfg.items(): if key == "values": out[key] = [factor * float(v) for v in value] elif key in _LENGTHS: out[key] = factor * float(value) else: out[key] = value return distribution_from_config(out)
[docs] @dataclass class SeedCalibration: """The result of :func:`calibrate_seeds`: the calibrated ``model``, the ``scale`` of its seeds relative to the initial model and their ``aspect``, the ``target`` and ``achieved`` mean section radii (axis -> radius), the ``history`` of (scale, aspect, achieved) over the iterations and the ``sections`` of the last foam.""" model: Model scale: float aspect: tuple[float, float] target: dict[int, float] achieved: dict[int, float] history: list sections: list @property def residual(self) -> float: """The largest relative deviation of the achieved mean section radii.""" return max(abs(self.achieved[a] / self.target[a] - 1.0) for a in self.target)
[docs] def calibrate_seeds( model: LevelSetFoam, domain: Domain, target, *, shape=None, voxel_size=None, phase: int = 0, fit_shape: bool = False, separate: bool = True, prominence: float | None = None, min_radius: float = 0.0, iterations: int = 8, tol: float = 0.01, seed: SeedLike = None, ) -> SeedCalibration: """Scale the seeds of a foam, and with ``fit_shape`` change their shape factors, until the mean radii of the sections of its ``phase`` (the pores) by the planes normal to the axes of ``target`` (a mapping axis -> mean radius, or the measured :class:`~morphogen.analysis.stereology.Sections`) match them within ``tol``. Gauss–Newton steps in the logarithms of the scale and of the shape factors with the Jacobian of ellipsoids, ``log r_D = log s + log kappa_D(b/a, c/a)`` (``fit_shape`` needs the three axes; otherwise the step is the mean logarithmic deviation, and the iterations stop when it falls below ``tol / 2``, a shape that does not fit the sections leaving its misfit in :attr:`SeedCalibration.residual`); each foam is generated with the same ``seed`` (drawn once if None) on the grid ``shape`` or ``voxel_size`` and measured as the target should have been (``separate``, ``prominence``, ``min_radius``: see :func:`~morphogen.analysis.stereology.section_sizes`).""" from morphogen.analysis.stereology import section_sizes if isinstance(target, dict): means = {int(a): float(r) for a, r in target.items()} else: means = {s.axis: s.mean_radius() for s in target} axes = sorted(means) if fit_shape and axes != [0, 1, 2]: raise ValueError("calibrate_seeds: fit_shape needs the sections normal to x, y and z") if seed is None: seed = int(np.random.default_rng().integers(2**31)) base = model.seed_radius log_p = np.log([1.0, *model.aspect]) goal = np.log([means[a] for a in axes]) jacobian = _SECTION_JACOBIAN[axes] if fit_shape else np.ones((len(axes), 1)) history = [] for it in range(int(iterations) + 1): scale, aspect = float(np.exp(log_p[0])), tuple(float(v) for v in np.exp(log_p[1:])) current = dataclasses.replace(model, seed_radius=_scaled(base, scale), aspect=aspect) image = current.generate(domain, seed=seed).voxelize(shape, voxel_size=voxel_size) sections = [ section_sizes( image, phase, a, separate=separate, prominence=prominence, min_radius=min_radius ) for a in axes ] got = np.log([s.mean_radius() for s in sections]) achieved = {a: float(np.exp(g)) for a, g in zip(axes, got, strict=True)} history.append((scale, aspect, achieved)) residual = goal - got if np.abs(np.expm1(residual)).max() < tol or it == int(iterations): break step, *_ = np.linalg.lstsq(jacobian, residual, rcond=None) if np.abs(step).max() < 0.5 * tol: break # settled: what remains is the misfit of the shape if fit_shape: log_p += step else: log_p[0] += step[0] return SeedCalibration(current, scale, aspect, means, achieved, history, sections)