"""Voronoi and Laguerre (power) tessellations of Poisson germs.
A grain-boundary phase of thickness ``t`` can be added between the cells: the points
closer than ``t / 2`` to a face shared by their cell and another. The faces of the cell
of germ ``g_i`` containing ``x`` lie in the planes where the power distances
``p_j(x) = |x - g_j|^2 - w_j`` of two germs are equal; ``x`` is at distance
``(p_j(x) - p_i(x)) / (2 |g_j - g_i|)`` from the plane of germ ``j``, and the smallest of
these distances is its distance to the boundary of its (convex) cell. The germs whose
plane is closer than ``r`` are among those of lifted distance below ``l_i + 2 r``
(``l_i``: lifted distance to the own germ), so that the nearest germs suffice.
"""
from __future__ import annotations
import math
import warnings
from dataclasses import dataclass
from typing import ClassVar
import numpy as np
from scipy.spatial import cKDTree
from morphogen import settings, theory
from morphogen._utils import check_positive
from morphogen.distributions import Constant, Distribution
from morphogen.domain import Domain, Grid
from morphogen.image import VoxelImage
from morphogen.kernels.collective import stealthy_points
from morphogen.kernels.rsa import random_sequential_addition
from morphogen.models.affine import ANISOTROPY, Anisotropy, anisotropic
from morphogen.models.base import Microstructure, Model, param, register, register_kind
from morphogen.orientations import (
OrientationDistribution,
fibre_orientations,
random_orientations,
)
from morphogen.seeding import SeedLike, make_rng
#: Points processed per k-d tree query (bounds the memory of large grids).
_CHUNK = 1 << 21
[docs]
@register_kind
class Tessellation(Microstructure):
"""Cells of germs ``g_i`` with weights ``w_i``: x belongs to the cell minimizing the
power distance ``|x - g_i|^2 - w_i`` (Voronoi when all weights vanish).
Each cell carries a phase index and optionally crystal orientations (Bunge Euler
angles in degrees). The cell label of a voxel is the index of its germ. With a
``boundary_thickness``, the points closer than half of it to a face shared by two
cells are of phase ``boundary_phase`` (they keep the label of their cell).
"""
kind = "tessellation"
has_labels = True
def __init__(
self,
domain: Domain,
germs,
weights=None,
cell_phases=None,
orientations=None,
boundary_thickness: float = 0.0,
boundary_phase: int = 0,
**kwargs,
) -> None:
super().__init__(domain, **kwargs)
self.boundary_thickness = float(boundary_thickness)
self.boundary_phase = int(boundary_phase)
self.germs = np.ascontiguousarray(germs, dtype=float).reshape(-1, 3)
n = len(self.germs)
self.weights = None if weights is None else np.asarray(weights, dtype=float).reshape(n)
self.cell_phases = (
np.ones(n, dtype=np.uint8)
if cell_phases is None
else np.asarray(cell_phases, dtype=np.uint8).reshape(n)
)
self.orientations = (
None if orientations is None else np.asarray(orientations, dtype=float).reshape(n, 3)
)
self._tree = None
self._by_phase = None
self._complex = None
self._whole = None
self._wmax = 0.0 if self.weights is None else float(self.weights.max(initial=0.0))
self.margin = float(self.metadata.get("germ_margin", math.inf))
@property
def n_cells(self) -> int:
return len(self.germs)
# -- cell assignment -------------------------------------------------------------
def _lift(self, points: np.ndarray) -> np.ndarray:
"""Coordinates for the k-d tree (4D lifting turns power cells into Voronoi cells)."""
p = points - self.domain.lower
if self.domain.periodic:
p = np.mod(p, self.domain.lengths)
p[p >= self.domain.lengths] = 0.0
return p
def _get_tree(self) -> cKDTree:
if self._tree is None:
data = self._lift(self.germs)
boxsize = None
if self.weights is not None:
extra = np.sqrt(np.maximum(self._wmax - self.weights, 0.0))[:, None]
data = np.hstack([data, extra])
if self.domain.periodic:
boxsize = list(self.domain.lengths)
if self.weights is not None:
# effectively non-periodic 4th coordinate
boxsize.append(4.0 * (math.sqrt(self._wmax) + 1.0) + 1.0)
self._tree = cKDTree(data, boxsize=boxsize)
return self._tree
[docs]
def cell_of(self, points) -> np.ndarray:
"""Label (germ index) of the cell containing each point."""
pts = np.asarray(points, dtype=float).reshape(-1, 3)
tree = self._get_tree()
labels = np.empty(len(pts), dtype=np.int64)
worst = 0.0
for start in range(0, len(pts), _CHUNK):
q = self._lift(pts[start : start + _CHUNK])
if self.weights is not None:
q = np.hstack([q, np.zeros((len(q), 1))])
dist, idx = tree.query(q, k=1, workers=settings.workers())
labels[start : start + len(q)] = idx
if len(q):
worst = max(worst, float(np.max(dist)))
self._check_margin(worst)
return labels
[docs]
def boundary_distance(self, points, reach: float = math.inf) -> np.ndarray:
"""Distance from each point to the nearest face shared by its cell and another
(``inf`` for a single cell); exact up to ``reach``, at least ``reach`` beyond."""
pts = np.asarray(points, dtype=float).reshape(-1, 3)
out = np.full(len(pts), np.inf)
n = self.n_cells
if n < 2 or not len(pts):
return out
tree = self._get_tree()
lengths = self.domain.lengths
k0 = min(n, 16)
for start in range(0, len(pts), max(1, _CHUNK // k0)):
todo = np.arange(start, min(len(pts), start + max(1, _CHUNK // k0)))
k = k0
while todo.size:
q = self._lift(pts[todo])
if self.weights is not None:
q = np.hstack([q, np.zeros((len(q), 1))])
dist, idx = tree.query(q, k=k, workers=settings.workers())
v = self.germs[idx] - pts[todo, None, :] # germs seen from the points
if self.domain.periodic:
v -= lengths * np.round(v / lengths)
gap = np.linalg.norm(v[:, 1:] - v[:, :1], axis=2)
d = (dist[:, 1:] ** 2 - dist[:, :1] ** 2) / (2.0 * np.maximum(gap, 1e-300))
out[todo] = d.min(axis=1)
# the farthest germ found must be beyond l_i + 2 min(d, reach)
bound = dist[:, :1].ravel() + 2.0 * np.minimum(out[todo], reach)
again = (dist[:, -1] <= bound) & (k < n)
todo, k = todo[again], min(n, 2 * k)
return out
def _check_margin(self, worst: float) -> None:
"""Warn if germs outside the generation window could own some points."""
if self.domain.periodic or not math.isfinite(self.margin):
return
# lifted distance^2 = |x - g|^2 + w_max - w: a germ outside the window (farther than
# the margin from every point of the domain) has a lifted distance above the margin
if worst > self.margin:
warnings.warn(
"tessellation: some points are farther from their germ than the germ "
"window margin; cells near the boundary may be inexact",
RuntimeWarning,
stacklevel=3,
)
[docs]
def labels(self, shape=None, *, voxel_size=None, grid: Grid | None = None) -> VoxelImage:
"""Image of cell labels (int32 germ indices)."""
grid = self.grid(shape, voxel_size=voxel_size, grid=grid)
nx, ny, nz = grid.shape
out = np.empty(grid.shape, dtype=np.int32)
k_step = max(1, _CHUNK // (nx * ny))
for k0 in range(0, nz, k_step):
k1 = min(nz, k0 + k_step)
lab = self.cell_of(grid.center_points(k0, k1))
out[:, :, k0:k1] = lab.reshape(nx, ny, k1 - k0)
return VoxelImage.from_grid(out, grid, name="cell", metadata=self.image_metadata())
def _boundary_image(self, grid: Grid, reach: float) -> np.ndarray:
"""Distance of the voxel centres to the grain boundaries (exact up to ``reach``)."""
nx, ny, nz = grid.shape
out = np.empty(grid.shape)
k_step = max(1, _CHUNK // (16 * nx * ny))
for k0 in range(0, nz, k_step):
k1 = min(nz, k0 + k_step)
d = self.boundary_distance(grid.center_points(k0, k1), reach)
out[:, :, k0:k1] = d.reshape(nx, ny, k1 - k0)
return out
def _phases_on(self, grid: Grid) -> np.ndarray:
data = self.cell_phases[self.labels(grid=grid).data]
if self.boundary_thickness > 0:
half = 0.5 * self.boundary_thickness
inside = self._boundary_image(grid, half) < half
data[inside] = self.boundary_phase
return data
[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) == 1).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 contains(self, points) -> np.ndarray:
phase = self.cell_phases[self.cell_of(points)]
if self.boundary_thickness > 0:
half = 0.5 * self.boundary_thickness
phase = np.where(
self.boundary_distance(points, half) < half, self.boundary_phase, phase
)
return phase == 1
[docs]
def level_set(self, shape=None, *, voxel_size=None, grid: Grid | None = None) -> VoxelImage:
"""Grains of phase 1 in a grain-boundary phase 0: half the thickness of the
boundaries minus the distance to them (negative in the grains); the cells of
phase 1 among cells of other phases: :meth:`phase_level_set`."""
if (
self.boundary_thickness > 0
and self.boundary_phase == 0
and np.all(self.cell_phases == 1)
):
grid = self.grid(shape, voxel_size=voxel_size, grid=grid)
half = 0.5 * self.boundary_thickness
reach = half + 4.0 * float(np.max(grid.spacing)) # exact around the interface
data = (half - self._boundary_image(grid, reach)).astype(np.float32)
return VoxelImage.from_grid(
data, grid, name="level_set", metadata=self.image_metadata()
)
if 1 in self.implicit_phases() and len(self.implicit_phases()) > 1:
return self.phase_level_set(1, shape, voxel_size=voxel_size, grid=grid)
return super().level_set(shape, voxel_size=voxel_size, grid=grid)
[docs]
def implicit_phases(self) -> list[int]:
phases = {int(k) for k in np.unique(self.cell_phases)}
if self.boundary_thickness > 0:
phases.add(self.boundary_phase)
return sorted(phases)
def _phase_trees(self) -> dict:
"""A k-d tree of the lifted germs of each phase of the cells."""
if getattr(self, "_by_phase", None) is None:
tree = self._get_tree()
self._by_phase = {
int(k): cKDTree(tree.data[self.cell_phases == k], boxsize=tree.boxsize)
for k in np.unique(self.cell_phases)
}
return self._by_phase
[docs]
def phase_level_set(
self, phase: int, shape=None, *, voxel_size=None, grid: Grid | None = None
) -> VoxelImage:
"""The implicit function of a phase (see :meth:`Microstructure.phase_level_set`):
for the cells of a phase, the smallest power distance to their germs minus the
smallest to the germs of the cells of the other phases, over twice the mean
spacing of the germs: zero on the faces between cells of the phase and cells of
another (the planes where the two power distances are equal), near which it is
the distance to the face times the ratio of the distance between their germs to
the mean spacing. A grain-boundary phase is the layer within half its thickness
of the faces of the cells, which the cells lose."""
phase = int(phase)
phases = self.implicit_phases()
if phase not in phases:
raise ValueError(f"phase {phase}: the phases of this tessellation are {phases}")
from morphogen.models.implicit import band_of
grid = self.grid(shape, voxel_size=voxel_size, grid=grid)
band = band_of(grid)
trees = self._phase_trees()
scale = 2.0 * (self.domain.volume / max(self.n_cells, 1)) ** (1.0 / 3.0)
nx, ny, nz = grid.shape
cells = None
if phase in trees:
cells = np.full(grid.shape, -band, dtype=np.float32)
if len(trees) > 1:
k_step = max(1, _CHUNK // (nx * ny))
for k0 in range(0, nz, k_step):
k1 = min(nz, k0 + k_step)
q = self._lift(grid.center_points(k0, k1))
if self.weights is not None:
q = np.hstack([q, np.zeros((len(q), 1))])
own = other = None
for k, tree in trees.items():
d2 = tree.query(q, k=1, workers=settings.workers())[0] ** 2
if k == phase:
own = d2
else:
other = d2 if other is None else np.minimum(other, d2)
cells[:, :, k0:k1] = ((own - other) / scale).reshape(nx, ny, k1 - k0)
np.clip(cells, -band, band, out=cells)
data = cells
if self.boundary_thickness > 0:
half = 0.5 * self.boundary_thickness
layer = (self._boundary_image(grid, half + band) - half).astype(np.float32)
np.clip(layer, -band, band, out=layer)
if phase == self.boundary_phase:
data = layer if cells is None else np.minimum(cells, layer)
else:
data = np.maximum(cells, -layer)
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:
"""Grains of phase 1 in a grain-boundary phase 0: half the thickness of the
boundaries minus the distance to them at the points; the other tessellations of
several phases: the function of phase 1 (:meth:`phase_level_sets_at`)."""
if not (self.boundary_thickness > 0 and self.boundary_phase == 0
and np.all(self.cell_phases == 1)): # fmt: skip
if 1 not in self.implicit_phases():
return super().level_set_at(points, reach)
return self.phase_level_sets_at(points, reach)[1]
half = 0.5 * self.boundary_thickness
reach = float(min(reach, float(self.domain.diagonal))) + half
return half - self.boundary_distance(np.asarray(points, dtype=float).reshape(-1, 3), reach)
[docs]
def phase_level_sets_at(self, points, reach: float = np.inf) -> dict[int, np.ndarray]:
"""The functions of :meth:`phase_level_set` at the points: for the cells of a
phase, the smallest power distance to their germs minus the smallest to the germs
of the other phases, over twice the mean spacing of the germs (zero on the faces
between cells of the phase and cells of another); a grain-boundary phase, the layer
within half its thickness of the faces of the cells. A tessellation of one phase
without a boundary phase has no interface (and none: its exact geometry is that of
its cells)."""
phases = self.implicit_phases()
if len(phases) < 2:
raise NotImplementedError("a tessellation of one phase has no interface")
pts = np.asarray(points, dtype=float).reshape(-1, 3)
spacing = (self.domain.volume / max(self.n_cells, 1)) ** (1.0 / 3.0)
reach = float(spacing) if not np.isfinite(reach) else float(reach)
trees = self._phase_trees()
cells: dict[int, np.ndarray] = {}
if len(trees) > 1:
q = self._lift(pts)
if self.weights is not None:
q = np.hstack([q, np.zeros((len(q), 1))])
d2 = {k: tree.query(q, k=1, workers=settings.workers())[0] ** 2
for k, tree in trees.items()} # fmt: skip
for k in trees:
other = np.minimum.reduce([d2[j] for j in trees if j != k])
cells[k] = np.clip((d2[k] - other) / (2.0 * spacing), -reach, reach)
else:
cells = {k: np.full(len(pts), -reach) for k in trees}
if not self.boundary_thickness > 0:
return {k: cells[k] for k in phases}
half = 0.5 * self.boundary_thickness
layer = np.clip(self.boundary_distance(pts, half + reach) - half, -reach, reach)
out = {}
for k in phases:
if k == self.boundary_phase:
out[k] = layer if k not in cells else np.minimum(cells[k], layer)
else:
out[k] = np.maximum(cells[k], -layer)
return out
[docs]
def cell_complex(self, whole: bool = False):
"""Exact cells restricted to the domain: convex pieces with shared facets
(:class:`morphogen.mesh.polyhedra.CellComplex`), computed once. With ``whole``
(periodic tessellations), the whole cells, uncut by the faces of the box."""
from morphogen.mesh.polyhedra import periodic_cells, power_complex
if whole:
if not self.domain.periodic:
raise ValueError("whole cells: a periodic tessellation")
if self._whole is None:
self._whole = periodic_cells(
self.germs, self.weights, self.domain.lower, self.domain.upper
)
return self._whole
if self._complex is None:
self._complex = power_complex(
self.germs, self.weights, self.domain.lower, self.domain.upper, self.domain.periodic
)
return self._complex
# -- description -------------------------------------------------------------------
[docs]
def cell_table(self) -> dict[str, np.ndarray]:
"""Per-cell attributes: id, germ coordinates, weight, phase, orientation."""
table = {
"id": np.arange(self.n_cells),
"x": self.germs[:, 0],
"y": self.germs[:, 1],
"z": self.germs[:, 2],
"phase": self.cell_phases.astype(int),
}
if self.weights is not None:
table["weight"] = self.weights
if self.orientations is not None:
table["phi1"] = self.orientations[:, 0]
table["Phi"] = self.orientations[:, 1]
table["phi2"] = self.orientations[:, 2]
return table
[docs]
def summary(self) -> dict:
return {"n_cells": self.n_cells}
def _geometry(self) -> dict:
geo = {"germs": self.germs.tolist(), "cell_phases": self.cell_phases.tolist()}
if self.weights is not None:
geo["weights"] = self.weights.tolist()
if self.orientations is not None:
geo["orientations"] = self.orientations.tolist()
if self.boundary_thickness > 0:
geo["boundary_thickness"] = self.boundary_thickness
geo["boundary_phase"] = self.boundary_phase
return geo
@classmethod
def _from_geometry(cls, domain, geometry, **kwargs):
return cls(
domain,
geometry["germs"],
geometry.get("weights"),
geometry.get("cell_phases"),
geometry.get("orientations"),
boundary_thickness=geometry.get("boundary_thickness", 0.0),
boundary_phase=geometry.get("boundary_phase", 0),
**kwargs,
)
@dataclass(frozen=True)
class _TessellationModel(Model):
phases: ClassVar[dict[int, str]] = {0: "phase 0", 1: "phase 1"}
count_label = "cells"
#: (the orientation map of a measured texture)
path_parameters: ClassVar[tuple[str, ...]] = ("texture.file",)
n_cells: int | None = param(
None,
doc="Number of cells: exactly this many germs in a periodic box, Poisson germs "
"of intensity n_cells / volume otherwise",
kind="int",
)
intensity: float | None = param(None, doc="Germs per unit volume", unit="1/length^3")
phase_fractions: tuple[float, ...] | None = param(
None,
doc="Probabilities of phases 0, 1, ... for each cell (default: every cell is phase 1)",
kind="floats",
)
crystal_orientations: bool = param(
False, doc="Draw a uniformly random crystal orientation per cell", kind="bool"
)
texture: OrientationDistribution | None = param(
None,
doc="The texture of the crystal orientations. A fibre texture: the law of the "
"third axis of the crystals (the axis c of hexagonal ones), which are turned at "
"random about it, e.g. {type: von_mises_fisher, kappa: 30, axis: [0, 0, 1]}. A "
"measured texture: the orientations of the grains of an orientation map (EBSD), "
"drawn with their areas, e.g. {type: measured, file: map.ctf, spread: 2.0} "
"(default: uniform orientations)",
kind="orientation",
kw_only=True,
)
boundary_thickness: float = param(
0.0,
doc="Thickness of a grain-boundary phase: the points closer than half of it to a "
"face shared by two cells (0: none)",
unit="length",
)
boundary_phase: int | None = param(
None,
doc="Phase of the grain boundaries (default: 0 when every cell is phase 1, the "
"phase after those of the cells otherwise)",
kind="int",
)
def _validate(self) -> None:
if (self.n_cells is None) == (self.intensity is None):
raise ValueError("give exactly one of 'n_cells' and 'intensity'")
if self.n_cells is not None and self.n_cells < 1:
raise ValueError("n_cells: must be a positive integer")
if self.intensity is not None:
check_positive(self.intensity, "intensity")
if self.phase_fractions is not None:
p = np.asarray(self.phase_fractions, dtype=float)
if p.ndim != 1 or len(p) < 1 or np.any(p < 0) or abs(p.sum() - 1.0) > 1e-9:
raise ValueError("phase_fractions: non-negative probabilities summing to 1")
if len(p) > 255:
raise ValueError("phase_fractions: at most 255 phases")
check_positive(self.boundary_thickness, "boundary_thickness", allow_zero=True)
if self.boundary_phase is not None and not 0 <= self.boundary_phase <= 255:
raise ValueError("boundary_phase: a phase index from 0 to 255")
@property
def grain_boundary_phase(self) -> int | None:
"""Phase of the grain boundaries (None without them)."""
if not self.boundary_thickness > 0:
return None
if self.boundary_phase is not None:
return self.boundary_phase
return 0 if self.phase_fractions is None else len(self.phase_fractions)
@property
def has_level_set(self) -> bool:
"""Grains of phase 1 in a grain-boundary phase 0 have a level-set function."""
return self.phase_fractions is None and self.grain_boundary_phase == 0
@property
def meshed_by_grains(self) -> bool:
"""Cells meshed grain by grain, unless a grain-boundary phase separates them or an
anisotropy maps them (their voxel images only)."""
mapped = not getattr(getattr(self, "anisotropy", None), "is_identity", True)
return self.grain_boundary_phase is None and not mapped
def active_phases(self) -> dict[int, str]:
if self.phase_fractions is None:
out = {1: "cells"}
else:
out = {i: f"phase {i}" for i, p in enumerate(self.phase_fractions) if p > 0}
if self.grain_boundary_phase is not None:
out[self.grain_boundary_phase] = "grain boundaries"
return out
def theta(self, domain: Domain | None) -> float:
"""Intensity of the germs (``n_cells / volume`` when the number is given)."""
if self.intensity is not None:
return self.intensity
if domain is None:
raise ValueError("the intensity implied by n_cells depends on the domain")
return self.n_cells / domain.volume
def expected_count(self, domain: Domain) -> float:
"""Mean number of germs (cells) in the domain."""
return self.theta(domain) * domain.volume
def _germs(self, rng, window: Domain, n: int):
"""Germs (uniform in the window) and their weights."""
return window.lower + rng.random((n, 3)) * window.lengths, self._weights(rng, n)
def _count(self, rng, mean: float) -> int:
"""The number of germs of mean ``mean`` in a window (Poisson)."""
return int(rng.poisson(mean))
def _weights(self, rng, n):
return None
def _max_weight(self, theta: float) -> float:
return 0.0
def generate(self, domain: Domain, seed: SeedLike = None) -> Tessellation:
rng, seed_info = make_rng(seed)
theta = self.theta(domain)
if domain.periodic:
window, margin = domain, math.inf
mean = theta * domain.volume
n = self.n_cells if self.n_cells is not None else self._count(rng, mean)
else:
margin = 3.0 * theta ** (-1.0 / 3.0) + 2.0 * math.sqrt(self._max_weight(theta))
window = domain.dilated(margin)
n = self._count(rng, theta * window.volume)
germs, weights = self._germs(rng, window, n)
if self.phase_fractions is None:
phases = np.ones(n, dtype=np.uint8)
else:
p = np.asarray(self.phase_fractions, dtype=float)
phases = rng.choice(len(p), size=n, p=p / p.sum()).astype(np.uint8)
orientations = None
if self.crystal_orientations and self.texture is not None:
orientations = fibre_orientations(rng, n, self.texture)
elif self.crystal_orientations:
orientations = random_orientations(rng, n)
return Tessellation(
domain,
germs,
weights,
phases,
orientations,
boundary_thickness=self.boundary_thickness,
boundary_phase=self.grain_boundary_phase or 0,
model=self,
seed=seed_info,
metadata={"germ_margin": margin} if math.isfinite(margin) else None,
)
[docs]
@register
@anisotropic
@dataclass(frozen=True)
class Voronoi(_TessellationModel):
"""Voronoi tessellation (mosaic): each point belongs to its nearest germ. The germs
are Poisson points, or a stealthy hyperuniform pattern (``germs: stealthy``: the
collective coordinates of Torquato and coworkers, :mod:`morphogen.kernels.collective`),
a fixed number of them in the box, whose cells are disordered but far more regular."""
name = "voronoi"
germs: str = param(
"poisson",
doc="Germs: poisson (independent points) or stealthy (a stealthy hyperuniform pattern)",
kind="str",
)
stealthiness: float = param(
0.3,
doc="Stealthy germs: the constrained wave vectors per degree of freedom (chi, below "
"0.5: disordered ground states; more: more regular cells)",
kind="fraction",
)
anisotropy: Anisotropy | None = param(None, doc=ANISOTROPY, kind="anisotropy", kw_only=True)
def _validate(self) -> None:
super()._validate()
if self.germs not in ("poisson", "stealthy"):
raise ValueError(f"germs: poisson or stealthy, got {self.germs!r}")
if not 0.0 < self.stealthiness < 0.5:
raise ValueError("stealthiness: in (0, 0.5), the disordered ground states")
def _count(self, rng, mean: float) -> int:
return super()._count(rng, mean) if self.germs == "poisson" else round(mean)
def _germs(self, rng, window: Domain, n: int):
if self.germs == "poisson":
return super()._germs(rng, window, n)
points, _, _ = stealthy_points(n, window.lengths, self.stealthiness, rng)
return window.lower + points, None
[docs]
def theory(self, domain: Domain | None = None) -> dict[str, float]:
if self.germs == "stealthy": # the constants of the Poisson germs do not hold
out = {}
if self.intensity is not None or domain is not None:
theta = self.theta(domain)
out.update(intensity=theta, mean_cell_volume=1.0 / theta)
if self.phase_fractions is not None and not self.boundary_thickness > 0:
for i, p in enumerate(self.phase_fractions):
out[f"volume_fraction_{i}"] = float(p)
return out
out = {
"mean_faces": theory.VORONOI_MEAN_FACES,
"cell_volume_cv2": theory.VORONOI_VOLUME_CV2,
}
if self.intensity is not None or domain is not None:
theta = self.theta(domain)
out.update(
{
"intensity": theta,
"mean_cell_volume": 1.0 / theta,
"integral_range": (1.0 + theory.VORONOI_VOLUME_CV2) / theta,
"boundary_surface_density": theory.VORONOI_SURFACE_COEFF * theta ** (1 / 3),
}
)
if self.boundary_thickness > 0: # S_V t: exact to first order in t
out["boundary_fraction_first_order"] = (
out["boundary_surface_density"] * self.boundary_thickness
)
else:
out["integral_range_in_cells"] = 1.0 + theory.VORONOI_VOLUME_CV2
if self.phase_fractions is not None and not self.boundary_thickness > 0:
for i, p in enumerate(self.phase_fractions):
out[f"volume_fraction_{i}"] = float(p)
return out
[docs]
@register
@anisotropic
@dataclass(frozen=True)
class Laguerre(_TessellationModel):
"""Laguerre (power) tessellation of germ spheres, the weights being their ``r^2``.
The germs are Poisson points with independent radii, or the centres of a packing of
non-overlapping spheres (random sequential addition, the largest first) whose radii
follow the distribution up to a common factor filling ``packing_fraction`` of the
box: the cells then follow the sizes of the spheres closely (e.g. Fan et al. 2004).
"""
name = "laguerre"
radius: Distribution = param(
Constant(1.0),
doc="Radius r of the germ spheres (weight r^2; relative sizes for packed germs)",
kind="distribution",
unit="length",
)
germs: str = param(
"poisson", doc="Germs: poisson (independent points) or packing (hard spheres)", kind="str"
)
packing_fraction: float = param(
0.3,
doc="Packed germs: volume fraction of the spheres (random sequential addition jams "
"near 0.38 for equal spheres)",
kind="fraction",
)
anisotropy: Anisotropy | None = param(None, doc=ANISOTROPY, kind="anisotropy", kw_only=True)
def _validate(self) -> None:
super()._validate()
if self.germs not in ("poisson", "packing"):
raise ValueError(f"germs: poisson or packing, got {self.germs!r}")
if not 0.0 < self.packing_fraction < 0.6:
raise ValueError("packing_fraction: between 0 and 0.6")
def _scale(self, theta: float) -> float:
"""Factor of the radii of packed germs (expected value, given the intensity)."""
return (self.packing_fraction / (theta * 4.0 / 3.0 * math.pi * self.radius.moment(3))) ** (
1.0 / 3.0
)
def _germs(self, rng, window: Domain, n: int):
if self.germs == "poisson":
return super()._germs(rng, window, n)
radii = np.sort(self.radius.sample(rng, n))[::-1]
if n:
radii = radii * (
self.packing_fraction * window.volume / (4.0 / 3.0 * math.pi * np.sum(radii**3))
) ** (1.0 / 3.0)
if n and 2.0 * radii[0] >= 0.5 * float(np.min(window.lengths)):
raise ValueError("laguerre: the packed spheres are too large for the box")
local = random_sequential_addition(radii, window.lengths, 0.0, rng, 10_000 * max(n, 1))
return window.lower + local, radii**2
def _weights(self, rng, n):
return self.radius.sample(rng, n) ** 2
def _max_weight(self, theta: float) -> float:
if self.germs == "packing": # cells close to their spheres: a few mean radii
return (3.0 * self._scale(theta) * self.radius.mean()) ** 2
return self.radius.upper() ** 2