"""Nested models: structures placed in, or around, the phases of others.
* ``cox_spheres``: spheres clustered in the phase 1 of another model (aggregates of
particles in nanocomposites, at any number of scales): a Cox (doubly stochastic)
Boolean model, or hard-core spheres placed among its germs.
* ``coating``: a layer of constant thickness around the phase 1 of a model (an
interphase), or a shell inside it (hollow members: spheres, fibres, struts).
* ``fractal_sponge``: the attractor of an iterated function system on a cubic grid (the
Menger sponge, Cantor dust, the Vicsek fractal, or any set of sub-cubes), iterated a
finite number of times.
Hierarchical lattices of hollow tubes are in :mod:`morphogen.models.hierarchical`, and
the ``nested`` operation of :mod:`morphogen.models.combination` fills the phase 1 of a
structure with another.
"""
from __future__ import annotations
import math
from dataclasses import dataclass
from typing import ClassVar
import numpy as np
from scipy import ndimage
from morphogen import theory
from morphogen._utils import check_fraction, check_positive
from morphogen.distributions import Constant, Distribution
from morphogen.domain import Domain, Grid
from morphogen.image import VoxelImage
from morphogen.kernels.rsa import rsa_insert
from morphogen.models.affine import ANISOTROPY, Anisotropy, anisotropic
from morphogen.models.base import Microstructure, Model, param, register, register_kind
from morphogen.models.implicit import band_of
from morphogen.models.union import PrimitiveUnion
from morphogen.primitives import Segments, Spheres
from morphogen.seeding import SeedLike, make_rng, seed_from_description
def _child_seeds(rng, seed_info, n: int) -> list:
"""Seeds of the parts of a nested realization, derived from its own seed."""
if seed_info is not None:
return list(seed_from_description(seed_info).spawn(n))
return list(rng.spawn(n))
def _supersampled(fine: np.ndarray, grid: Grid, ss: int) -> np.ndarray:
nx, ny, nz = grid.shape
return fine.reshape(nx, ss, ny, ss, nz, ss).mean(axis=(1, 3, 5), dtype=np.float32)
# -- clustered spheres ----------------------------------------------------------------------
[docs]
@register_kind
class ClusteredSpheres(PrimitiveUnion):
"""Spheres (phase 1) clustered in aggregates, a realization of another model; the
aggregates outside the spheres may form a phase of their own."""
kind = "clustered_spheres"
def __init__(self, domain, spheres, aggregates: Microstructure, aggregate_phase=None, **kw):
super().__init__(domain, spheres=spheres, **kw)
self.aggregates = aggregates
self.aggregate_phase = None if aggregate_phase is None else int(aggregate_phase)
@property
def phase_names(self) -> dict[int, str]:
return self.model.active_phases() if self.model is not None else super().phase_names
[docs]
def voxelize(self, shape=None, *, voxel_size=None, grid: Grid | None = None, supersampling=1):
image = super().voxelize(
shape, voxel_size=voxel_size, grid=grid, supersampling=supersampling
)
if self.aggregate_phase is None or supersampling != 1:
return image
inside = self.aggregates.voxelize(grid=image.grid()).data == 1
data = image.data.copy()
data[(data == 0) & inside] = self.aggregate_phase
return image.with_data(data)
[docs]
def implicit_phases(self) -> list[int]:
phases = {0, 1}
if self.aggregate_phase is not None:
phases.add(self.aggregate_phase)
return sorted(phases)
[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`):
the spheres by their signed distance; the aggregates, when a phase of their own,
by the level set of their structure outside the spheres."""
phase = int(phase)
if phase not in self.implicit_phases():
raise ValueError(f"phase {phase}: the phases are {self.implicit_phases()}")
if self.aggregate_phase in (None, 0):
return Microstructure.phase_level_set(self, phase, shape, voxel_size=voxel_size,
grid=grid) # fmt: skip
grid = self.grid(shape, voxel_size=voxel_size, grid=grid)
spheres = np.asarray(self.level_set(grid=grid).data, dtype=np.float32)
zone = np.asarray(self.aggregates.level_set(grid=grid).data, dtype=np.float32)
if self.aggregate_phase == 1: # one phase with the spheres
data = np.minimum(spheres, zone)
data = data if phase == 1 else -data
elif phase == 1:
data = spheres
elif phase == self.aggregate_phase:
data = np.maximum(zone, -spheres)
else:
data = -np.minimum(spheres, zone)
return VoxelImage.from_grid(data, grid, name="level_set", metadata=self.image_metadata())
[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: the signed distance to
the spheres, and the point-wise level set of the aggregates when they form a phase
of their own."""
if self.aggregate_phase in (None, 0):
phi = PrimitiveUnion.level_set_at(self, points, reach)
return {0: -phi, 1: phi}
spheres = PrimitiveUnion.level_set_at(self, points, reach)
zone = np.asarray(self.aggregates.level_set_at(points, reach), dtype=float)
if self.aggregate_phase == 1: # one phase with the spheres
phi = np.minimum(spheres, zone)
return {0: -phi, 1: phi}
return {
0: -np.minimum(spheres, zone),
1: spheres,
self.aggregate_phase: np.maximum(zone, -spheres),
}
[docs]
def level_set_at(self, points, reach: float = np.inf) -> np.ndarray:
"""The function of phase 1 (:meth:`phase_level_sets_at`)."""
return self.phase_level_sets_at(points, reach)[1]
[docs]
def implicit_pieces(self, depth: float = 0.0) -> tuple[list, int] | None:
"""The pieces of the spheres (:meth:`PrimitiveUnion.implicit_pieces`), when the
aggregates are not a phase of their own nor of the spheres; None otherwise."""
if self.aggregate_phase not in (None, 0):
return None
return super().implicit_pieces(depth)
[docs]
def summary(self) -> dict:
out = super().summary()
out.update({f"aggregates_{k}": v for k, v in self.aggregates.summary().items()})
return out
def _geometry(self) -> dict:
geo = super()._geometry()
geo["aggregates"] = self.aggregates.to_dict()
if self.aggregate_phase is not None:
geo["aggregate_phase"] = self.aggregate_phase
return geo
@classmethod
def _from_geometry(cls, domain, geometry, **kwargs):
spheres = Spheres.from_dict(geometry["spheres"]) if "spheres" in geometry else None
aggregates = Microstructure.from_dict(geometry["aggregates"])
return cls(domain, spheres, aggregates, geometry.get("aggregate_phase"), **kwargs)
[docs]
@register
@anisotropic
@dataclass(frozen=True)
class CoxSpheres(Model):
"""Spheres clustered in the phase 1 of another model: a Cox Boolean model.
The centres of the spheres are Poisson points of intensity ``theta_1`` in the
aggregates (the phase 1 of ``aggregates``, any model, Cox spheres included) and
``theta_0`` outside, the spheres being whole (Jeulin & Moreaud 2007; Jean, Jeulin,
Forest et al. 2011 for carbon black in rubber). With ``hardcore``, non-overlapping
spheres are placed among such germs by random sequential addition instead. The
fractions are local: that of the spheres within the aggregates and outside them.
"""
name = "cox_spheres"
phases: ClassVar[dict[int, str]] = {0: "matrix", 1: "spheres"}
count_label = "spheres"
aggregates: Model = param(
doc="Model whose phase 1 holds the spheres (aggregates)", kind="model"
)
radius: Distribution = param(
Constant(1.0), doc="Sphere radius (number or distribution)", kind="distribution",
unit="length",
) # fmt: skip
local_fraction: float | None = param(
None, doc="Volume fraction of the spheres in the aggregates", kind="fraction"
)
intensity: float | None = param(
None, doc="Number of sphere centres per unit volume of the aggregates", unit="1/length^3"
)
outside_fraction: float = param(
0.0, doc="Volume fraction of the spheres outside the aggregates", kind="fraction"
)
hardcore: bool = param(
False, doc="Non-overlapping spheres (random sequential addition)", kind="bool"
)
min_gap: float = param(0.0, doc="Hard-core spheres: minimal gap between them", unit="length")
aggregate_phase: int | None = param(
None, doc="Phase of the aggregates outside the spheres (default: the matrix)", kind="int"
)
anisotropy: Anisotropy | None = param(None, doc=ANISOTROPY, kind="anisotropy", kw_only=True)
def _validate(self) -> None:
if (self.local_fraction is None) == (self.intensity is None):
raise ValueError("give exactly one of 'local_fraction' and 'intensity'")
if self.local_fraction is not None:
check_fraction(self.local_fraction, "local_fraction")
else:
check_positive(self.intensity, "intensity")
if self.hardcore:
raise ValueError("hard-core spheres: give their local_fraction")
if not 0.0 <= self.outside_fraction < 1.0:
raise ValueError("outside_fraction: in [0, 1)")
check_positive(self.min_gap, "min_gap", allow_zero=True)
if self.aggregate_phase is not None and not 2 <= self.aggregate_phase <= 255:
raise ValueError("aggregate_phase: a phase index from 2 to 255")
@property
def has_level_set(self) -> bool:
return self.aggregate_phase is None
@property
def supports_periodic(self) -> bool:
return self.aggregates.supports_periodic
[docs]
def active_phases(self) -> dict[int, str]:
out = dict(self.phases)
if self.aggregate_phase is not None:
out[self.aggregate_phase] = f"aggregates ({self.aggregates.name})"
return out
@property
def mean_volume(self) -> float:
return 4.0 / 3.0 * math.pi * self.radius.moment(3)
@property
def intensities(self) -> tuple[float, float]:
"""Intensities of the germs in and out of the aggregates (Boolean spheres)."""
inside = (
self.intensity
if self.intensity is not None
else theory.boolean_intensity(self.local_fraction, self.mean_volume)
)
outside = theory.boolean_intensity(self.outside_fraction, self.mean_volume)
return inside, outside
[docs]
def generate(self, domain: Domain, seed: SeedLike = None) -> ClusteredSpheres:
self._check_domain(domain)
rng, seed_info = make_rng(seed)
seeds = _child_seeds(rng, seed_info, 2)
rmax = self.radius.upper()
reach = (2.0 * rmax + self.min_gap) if self.hardcore else rmax
if domain.periodic:
if 2.0 * reach >= min(domain.size):
raise ValueError("cox_spheres: spheres too large for the periodic box")
window = domain
else:
window = domain.dilated(reach)
aggregates = self.aggregates.generate(window, seeds[0])
local = np.random.default_rng(seeds[1])
if self.hardcore:
centers, radii = self._hardcore(window, aggregates, local)
else:
inside, outside = self.intensities
top = max(inside, outside)
n = local.poisson(top * window.volume)
centers = window.lower + local.random((n, 3)) * window.lengths
rate = np.where(aggregates.contains(centers), inside, outside)
centers = centers[local.random(n) * top < rate]
radii = self.radius.sample(local, len(centers))
spheres = Spheres(centers, radii)
if not domain.periodic:
spheres = spheres.subset(domain.distance_to_box(spheres.centers) <= spheres.radii)
return ClusteredSpheres(
domain, spheres, aggregates, self.aggregate_phase, model=self, seed=seed_info
)
def _hardcore(self, window: Domain, aggregates: Microstructure, rng):
"""Random sequential addition among the germs of the Cox process (a periodic box,
cropped later for non-periodic domains)."""
probe = window.lower + rng.random((20000, 3)) * window.lengths
p_in = float(aggregates.contains(probe).mean())
target = window.volume * (p_in * self.local_fraction + (1 - p_in) * self.outside_fraction)
radii = np.empty(0)
while np.sum(4.0 / 3.0 * math.pi * radii**3) < target:
more = self.radius.sample(rng, int(0.2 * target / self.mean_volume) + 16)
radii = np.concatenate([radii, more])
if radii.size == 0:
return np.zeros((0, 3)), radii
cum = np.cumsum(4.0 / 3.0 * math.pi * radii**3)
radii = np.sort(radii[: int(np.searchsorted(cum, target)) + 1])[::-1].copy()
top = max(self.local_fraction, self.outside_fraction)
box = window.lengths
reach = 2.0 * radii.max() + self.min_gap if radii.size else 1.0
cell_n = np.maximum(1, np.floor(box / reach)).astype(np.int64)
cell_h = box / cell_n
head = np.full(int(np.prod(cell_n)), -1, dtype=np.int64)
nxt = np.full(len(radii), -1, dtype=np.int64)
pos = np.zeros((len(radii), 3))
placed, attempts, budget = 0, 0, 20_000 * max(len(radii), 1)
while placed < len(radii) and attempts < budget:
cand = rng.random((8192, 3)) * box
rate = np.where(
aggregates.contains(window.lower + cand), self.local_fraction, self.outside_fraction
)
cand = np.ascontiguousarray(cand[rng.random(len(cand)) * top < rate])
placed, _ = rsa_insert(
radii, float(self.min_gap), box, cell_h, cell_n, head, nxt, pos, placed, cand
)
attempts += 8192
if placed < len(radii):
raise RuntimeError(
f"cox_spheres: {placed} of {len(radii)} hard-core spheres placed; lower the "
"local fraction (random sequential addition jams near 0.38 for equal spheres)"
)
return window.lower + pos, radii
[docs]
def expected_count(self, domain: Domain) -> float | None:
"""Mean number of sphere centres in the domain (Boolean spheres)."""
try:
p = self.aggregates.theory(domain)["volume_fraction"]
except (KeyError, ValueError, NotImplementedError):
return None
if self.hardcore:
return (
domain.volume
* (p * self.local_fraction + (1 - p) * self.outside_fraction)
/ (self.mean_volume)
)
inside, outside = self.intensities
return (inside * p + outside * (1.0 - p)) * domain.volume
[docs]
def theory(self, domain: Domain | None = None) -> dict[str, float]:
"""Fractions when the spheres are small compared with the aggregates (a sphere
rarely straddles their boundary): ``1 - p exp(-theta_1 V) - (1 - p) exp(-theta_0
V)`` for Boolean spheres, ``p f_1 + (1 - p) f_0`` for hard-core ones, ``p`` being
the fraction of the aggregates."""
try:
p = self.aggregates.theory(domain).get("volume_fraction")
except (ValueError, NotImplementedError):
p = None
inside, outside = self.intensities
out = {"intensity_inside": inside, "intensity_outside": outside}
if p is None:
return out
out["aggregate_fraction"] = p
if self.hardcore:
out["volume_fraction"] = p * self.local_fraction + (1 - p) * self.outside_fraction
return out
v = self.mean_volume
q_in, q_out = math.exp(-inside * v), math.exp(-outside * v)
out["volume_fraction"] = 1.0 - p * q_in - (1.0 - p) * q_out
area = 4.0 * math.pi * self.radius.moment(2)
out["specific_surface"] = area * (inside * p * q_in + outside * (1.0 - p) * q_out)
return out
# -- coatings and shells ---------------------------------------------------------------------
def _signed_distance(inner: Microstructure, grid: Grid, band: float) -> tuple:
"""Phases of a structure on a grid and the signed distance to its phase 1 (negative
inside): exact for unions of spheres and segments, from the Euclidean distance
transform of the voxels otherwise."""
phases = inner.voxelize(grid=grid).data
if isinstance(inner, PrimitiveUnion):
return phases, inner.level_set(grid=grid, band=band).data.astype(np.float64)
solid = phases == 1
h = grid.spacing
wrap = "wrap" if inner.domain.periodic else "nearest"
outside = _edt(~solid, h, wrap, band)
inside = _edt(solid, h, wrap, band)
half = 0.5 * float(np.min(h)) # from voxel centres to the interface between them
return phases, np.where(solid, -(inside - half), outside - half)
def _edt(mask: np.ndarray, spacing, mode: str, band: float = math.inf) -> np.ndarray:
"""Distance from the voxels of ``mask`` to the nearest voxel outside it, exact up to
``band`` and at least ``band`` beyond (periodic: on a copy wrapped over the band)."""
if not mask.any():
return np.zeros(mask.shape)
if mask.all():
return np.full(mask.shape, np.inf)
if mode == "wrap":
h = np.broadcast_to(np.asarray(spacing, dtype=float), (mask.ndim,))
pad = [min(n, math.ceil(band / s) + 1) for n, s in zip(mask.shape, h, strict=True)]
tiled = np.pad(mask, [(p, p) for p in pad], mode="wrap")
d = ndimage.distance_transform_edt(tiled, sampling=spacing)
return d[tuple(slice(p, p + n) for p, n in zip(pad, mask.shape, strict=True))]
return ndimage.distance_transform_edt(mask, sampling=spacing)
[docs]
@register_kind
class CoatedStructure(Microstructure):
"""A structure with a layer around its phase 1 (outside) or a shell inside it."""
kind = "coated"
def __init__(self, domain, inner, thickness, side, phase, core_phase, bores=None, **kw):
super().__init__(domain, **kw)
self.inner = inner
self.thickness = float(thickness)
self.side = side
self.phase = int(phase)
self.core_phase = int(core_phase)
self.bores = bores # hollow unions of spheres and segments: the same, thinner
@property
def phase_names(self) -> dict[int, str]:
return self.model.active_phases() if self.model is not None else super().phase_names
def _phases_on(self, grid: Grid) -> np.ndarray:
if self.bores is not None: # union of the members minus the union of their bores
outer = self.inner.voxelize(grid=grid).data == 1
bore = self.bores.voxelize(grid=grid).data == 1
out = np.zeros(grid.shape, dtype=np.uint8)
out[outer] = 1
out[outer & bore] = self.core_phase
return out
band = self.thickness + 2.0 * float(np.max(grid.spacing))
phases, dist = _signed_distance(self.inner, grid, band)
out = phases.astype(np.uint8, copy=True)
if self.side == "outside":
out[(phases == 0) & (dist <= self.thickness)] = self.phase
else:
out[(phases == 1) & (dist < -self.thickness)] = self.core_phase
return out
[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())
fine = Grid(grid.domain, tuple(n * ss for n in grid.shape))
data = _supersampled((self._phases_on(fine) == 1).astype(np.float32), grid, ss)
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:
"""Hollow members (a void core): the union minus the bores (exact sets), or the
shell ``-t <= d <= 0`` of the signed distance; a coating leaves phase 1 as is."""
grid = self.grid(shape, voxel_size=voxel_size, grid=grid)
if self.side == "outside":
return self.inner.level_set(grid=grid)
if self.core_phase != 0:
raise NotImplementedError("a shell with a filled core has three phases")
if self.bores is not None:
outer = self.inner.level_set(grid=grid).data.astype(np.float32)
bore = self.bores.level_set(grid=grid).data.astype(np.float32)
data = np.maximum(outer, -bore)
else:
band = self.thickness + 4.0 * float(np.max(grid.spacing))
_, dist = _signed_distance(self.inner, grid, band)
data = np.maximum(dist, -dist - self.thickness).astype(np.float32)
return VoxelImage.from_grid(data, grid, name="level_set", metadata=self.image_metadata())
[docs]
def implicit_phases(self) -> list[int]:
if self.side == "outside":
return sorted({0, 1, self.phase})
return sorted({0, 1, self.core_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`),
from the signed distance ``d`` to the phase 1 of the structure: a coating of
thickness ``t`` is ``0 < d < t``, a shell ``-t < d < 0`` and its core ``d < -t``
(hollow unions of spheres and segments: the union minus the bores, and the
bores). The distance is exact for unions of spheres and segments; for the other
structures it is that of their voxels on the grid (as in their images)."""
phase = int(phase)
if phase not in self.implicit_phases():
raise ValueError(f"phase {phase}: the phases are {self.implicit_phases()}")
grid = self.grid(shape, voxel_size=voxel_size, grid=grid)
clip = band_of(grid)
t = self.thickness
if self.bores is not None:
outer = np.asarray(self.inner.level_set(grid=grid).data, dtype=np.float64)
bore = np.asarray(self.bores.level_set(grid=grid).data, dtype=np.float64)
regions = {1: np.maximum(outer, -bore), self.core_phase: np.maximum(outer, bore)}
outside = -outer
else:
_, d = _signed_distance(self.inner, grid, t + clip)
if self.side == "outside":
regions = {1: d, self.phase: np.maximum(-d, d - t)}
outside = t - d
else:
regions = {1: np.maximum(d, -d - t), self.core_phase: d + t}
outside = -d
# the phases that share an index are one (a core of the phase of the matrix...)
fields: dict[int, np.ndarray] = {0: outside}
for k in (1, *(q for q in regions if q != 1)):
fields[k] = np.minimum(fields[k], regions[k]) if k in fields else regions[k]
data = np.clip(fields[phase], -clip, clip).astype(np.float32)
return VoxelImage.from_grid(data, grid, name="level_set", metadata=self.image_metadata())
def _exact_distance(self) -> bool:
"""Whether the distance to the phase 1 of the structure is known at any point: a
union of spheres and segments of two phases (the distance of the other structures
is that of their voxels, :func:`_signed_distance`)."""
return isinstance(self.inner, PrimitiveUnion) and self.inner.implicit_phases() == [0, 1]
[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 coatings and
shells of a union of spheres and segments (whose signed distance is exact
there): the same functions of that distance, or of those of the union and of its
bores. The coatings of the other structures, whose distance is that of their
voxels, have none."""
if not self._exact_distance():
raise NotImplementedError(
"the coatings and shells of a structure that is not a union of spheres and "
"segments: the distance to its phase 1 is that of its voxels"
)
pts = np.asarray(points, dtype=float).reshape(-1, 3)
t = self.thickness
if not np.isfinite(reach):
reach = 0.1 * float(self.domain.lengths.min()) + t
reach = float(reach)
if self.bores is not None:
outer = self.inner.signed_distance(pts, reach)
bore = self.bores.signed_distance(pts, reach)
regions = {1: np.maximum(outer, -bore), self.core_phase: np.maximum(outer, bore)}
outside = -outer
else:
d = self.inner.signed_distance(pts, reach + t)
if self.side == "outside":
regions = {1: d, self.phase: np.maximum(-d, d - t)}
outside = t - d
else:
regions = {1: np.maximum(d, -d - t), self.core_phase: d + t}
outside = -d
# the phases that share an index are one (a core of the phase of the matrix...)
fields: dict[int, np.ndarray] = {0: outside}
for k in (1, *(q for q in regions if q != 1)):
fields[k] = np.minimum(fields[k], regions[k]) if k in fields else regions[k]
return {k: np.clip(fields[k], -reach, reach) for k in self.implicit_phases()}
[docs]
def implicit_pieces(self, depth: float = 0.0) -> tuple[list, int] | None:
"""The pieces of a coated union of spheres and segments, or of its hollow
members (see :mod:`morphogen.models.pieces`): the primitives, then the same with
their radii increased by the thickness of the coating; the bores of hollow
members, then the primitives. None for the other structures."""
from morphogen.models.pieces import Piece, union_pieces
inner = self.inner
if not isinstance(inner, PrimitiveUnion) or inner.implicit_phases() != [0, 1]:
return None
if self.side == "outside":
pieces = [Piece(1, part) for part in union_pieces(inner, 0.0, depth)]
pieces += [
Piece(self.phase, part) for part in union_pieces(inner, self.thickness, depth)
]
return pieces, 0
if self.bores is None:
return None
pieces = [Piece(self.core_phase, part) for part in union_pieces(self.bores, 0.0, depth)]
pieces += [Piece(1, part) for part in union_pieces(inner, 0.0, depth)]
return pieces, 0
@property
def lipschitz(self) -> float:
parts = [self.inner] + ([self.bores] if self.bores is not None else [])
return max(float(getattr(p, "lipschitz", 1.0)) for p in parts)
[docs]
def level_set_at(self, points, reach: float = np.inf) -> np.ndarray:
"""As :meth:`level_set`, at the points: the level set of the structure (coating),
or the function of phase 1 of :meth:`phase_level_sets_at` (the members of a union
less their bores, the shell of its signed distance)."""
if self.side == "outside":
return self.inner.level_set_at(points, reach)
return self.phase_level_sets_at(points, reach)[1]
[docs]
def contains(self, points) -> np.ndarray:
"""Phase 1: that of the structure (coating), or its shell (hollow members of
unions of spheres and segments)."""
if self.side == "outside":
return self.inner.contains(points)
if self.bores is None:
raise NotImplementedError("point queries of shells need unions of spheres or segments")
inside = self.inner.contains(points)
return inside & ~self.bores.contains(points) if self.core_phase != 1 else inside
[docs]
def summary(self) -> dict:
return {f"inner_{k}": v for k, v in self.inner.summary().items()}
def _geometry(self) -> dict:
geo = {
"inner": self.inner.to_dict(),
"thickness": self.thickness,
"side": self.side,
"phase": self.phase,
"core_phase": self.core_phase,
}
if self.bores is not None:
geo["bores"] = self.bores.to_dict()
return geo
@classmethod
def _from_geometry(cls, domain, geometry, **kwargs):
bores = geometry.get("bores")
return cls(
domain,
Microstructure.from_dict(geometry["inner"]),
geometry["thickness"],
geometry["side"],
geometry["phase"],
geometry["core_phase"],
None if bores is None else Microstructure.from_dict(bores),
**kwargs,
)
[docs]
def bores_of(union: PrimitiveUnion, thickness: float) -> PrimitiveUnion:
"""The same spheres and segments, thinner by ``thickness`` (those thinner than it
are left out: they stay full)."""
sph, seg = union.spheres, union.segments
keep_s = sph.radii > thickness
keep_g = seg.radii > thickness
spheres = Spheres(sph.centers[keep_s], sph.radii[keep_s] - thickness)
segments = Segments(
seg.start[keep_g], seg.end[keep_g], seg.radii[keep_g] - thickness,
round_caps=seg.round_caps,
) # fmt: skip
return PrimitiveUnion(union.domain, spheres=spheres, segments=segments)
[docs]
@register
@dataclass(frozen=True)
class Coating(Model):
"""A layer of constant thickness on the phase 1 of a model.
``outside``: a coating (an interphase) of phase ``phase`` around it, within the
distance ``thickness``. ``inside``: a shell of that thickness, the core becoming the
phase ``core_phase`` (0: hollow members). Unions of spheres and segments (Boolean
and hard-core spheres, fibres, strut lattices...) are coated exactly, and their
members are hollowed one by one (each minus a thinner copy: bores join where members
meet); other structures through the distance transform of their voxels.
"""
name = "coating"
phases: ClassVar[dict[int, str]] = {0: "matrix", 1: "phase 1 of the model", 2: "coating"}
model: Model = param(doc="Model whose phase 1 is coated or hollowed", kind="model")
thickness: float = param(doc="Thickness of the layer", unit="length")
side: str = param(
"outside", doc="outside (a coating around phase 1) or inside (a shell)", kind="str"
)
phase: int = param(2, doc="Phase of the coating (outside)", kind="int")
core_phase: int = param(
0, doc="Phase of the core within the shell (inside; 0: hollow)", kind="int"
)
def _validate(self) -> None:
check_positive(self.thickness, "thickness")
if self.side not in ("outside", "inside"):
raise ValueError("side: 'outside' (a coating) or 'inside' (a shell)")
if not 2 <= self.phase <= 255:
raise ValueError("phase: a phase index from 2 to 255")
if self.core_phase == 1 or not 0 <= self.core_phase <= 255:
raise ValueError("core_phase: 0 (hollow) or a phase index from 2 to 255")
@property
def has_level_set(self) -> bool: # two phases: hollow members
return self.side == "inside" and self.core_phase == 0 and self.model.has_level_set
@property
def supports_periodic(self) -> bool:
return self.model.supports_periodic
[docs]
def active_phases(self) -> dict[int, str]:
if self.side == "outside":
return {0: "matrix", 1: f"phase 1 ({self.model.name})", self.phase: "coating"}
out = {0: "matrix", 1: "shell"}
if self.core_phase != 0:
out[self.core_phase] = "core"
return out
[docs]
def generate(self, domain: Domain, seed: SeedLike = None) -> CoatedStructure:
self._check_domain(domain)
rng, seed_info = make_rng(seed)
inner = self.model.generate(domain, _child_seeds(rng, seed_info, 1)[0])
bores = None
if self.side == "inside" and isinstance(inner, PrimitiveUnion):
bores = bores_of(inner, self.thickness)
return CoatedStructure(
domain,
inner,
self.thickness,
self.side,
self.phase,
self.core_phase,
bores,
model=self,
seed=seed_info,
)
[docs]
def theory(self, domain: Domain | None = None) -> dict[str, float]:
"""Boolean spheres: their coating is the dilation of a Boolean model, the Boolean
model of the spheres of radii ``R + t``."""
from morphogen.models.boolean import BooleanSpheres
m = self.model
if not isinstance(m, BooleanSpheres) or self.side != "outside":
return {}
theta, t = m.theta, self.thickness
nodes, weights = m.radius.quadrature(64)
dilated = float(np.sum(weights * 4.0 / 3.0 * math.pi * (nodes + t) ** 3))
p = 1.0 - math.exp(-theta * m.mean_grain_volume)
return {
"volume_fraction": p,
"coating_fraction": 1.0 - math.exp(-theta * dilated) - p,
}
# -- fractal sponges ---------------------------------------------------------------------------
#: Sub-cubes kept by the classical patterns of a 3 x 3 x 3 subdivision.
_CENTRE_AND_FACES = {(1, 1, 1), (0, 1, 1), (2, 1, 1), (1, 0, 1), (1, 2, 1), (1, 1, 0), (1, 1, 2)}
PATTERNS = {
"menger": sorted(set(np.ndindex(3, 3, 3)) - _CENTRE_AND_FACES),
"vicsek": sorted(_CENTRE_AND_FACES),
"cantor_dust": sorted(c for c in np.ndindex(3, 3, 3) if 1 not in c),
}
[docs]
@register_kind
class FractalStructure(Microstructure):
"""Periodic tiling of the cube kept by an iterated function system."""
kind = "fractal_sponge"
def __init__(self, domain, cell_size, subdivisions, kept, level, **kw):
super().__init__(domain, **kw)
self.cell_size = float(cell_size)
self.subdivisions = int(subdivisions)
self.kept = [tuple(int(v) for v in c) for c in kept]
self.level = int(level)
k = self.subdivisions
self._mask = np.zeros(k**3, dtype=bool)
for i, j, m in self.kept:
self._mask[(i * k + j) * k + m] = True
[docs]
def contains(self, points) -> np.ndarray:
pts = np.asarray(points, dtype=float).reshape(-1, 3)
k = self.subdivisions
u = np.mod((pts - self.domain.lower) / self.cell_size, 1.0)
inside = np.ones(len(pts), dtype=bool)
for _ in range(self.level):
d = np.minimum((u * k).astype(np.int64), k - 1)
inside &= self._mask[(d[:, 0] * k + d[:, 1]) * k + d[:, 2]]
u = u * k - d
return inside
[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)
fine = grid if ss == 1 else Grid(grid.domain, tuple(n * ss for n in grid.shape))
data = np.empty(fine.shape, dtype=bool)
for k0 in range(0, fine.shape[2], 16):
k1 = min(fine.shape[2], k0 + 16)
data[:, :, k0:k1] = self.contains(fine.center_points(k0, k1)).reshape(
fine.shape[0], fine.shape[1], k1 - k0
)
if ss == 1:
return VoxelImage.from_grid(
data.astype(np.uint8), grid, name="phase", metadata=self.image_metadata()
)
frac = _supersampled(data.astype(np.float32), grid, ss)
return VoxelImage.from_grid(frac, grid, name="fraction", metadata=self.image_metadata())
[docs]
def level_set(self, shape=None, *, voxel_size=None, grid: Grid | None = None) -> VoxelImage:
"""The signed distance to the solid in the maximum norm (negative inside),
clipped to a band of four voxels and to the edge of the smallest cubes: the
solid is a union of such cubes, and the distance from a point to the nearest
cube of the other state among the 26 around its own is the largest of its
distances to the faces that separate them."""
grid = self.grid(shape, voxel_size=voxel_size, grid=grid)
k = self.subdivisions
h = self.cell_size / k**self.level
band = min(h, band_of(grid))
nx, ny, nz = grid.shape
out = np.empty(grid.shape, dtype=np.float32)
offsets = [o for o in np.ndindex(3, 3, 3) if o != (1, 1, 1)]
step = max(1, (1 << 18) // (nx * ny))
for k0 in range(0, nz, step):
k1 = min(nz, k0 + step)
pts = grid.center_points(k0, k1)
u = (pts - self.domain.lower) / h
cell = np.floor(u)
frac = u - cell
centre = (cell + 0.5) * h + self.domain.lower
own = self.contains(centre)
dist = np.full(len(pts), band)
for o in offsets:
shift = np.array(o, dtype=float) - 1.0
other = self.contains(centre + shift * h) != own
if not other.any():
continue
# to the faces towards that cube, along the axes where it is shifted
gaps = np.where(shift > 0, 1.0 - frac, frac) * h
d = np.where(shift != 0, gaps, 0.0).max(axis=1)
dist = np.where(other, np.minimum(dist, d), dist)
out[:, :, k0:k1] = np.where(own, -dist, dist).reshape(nx, ny, k1 - k0)
return VoxelImage.from_grid(out, grid, name="level_set", metadata=self.image_metadata())
[docs]
def convex_pieces(self):
"""The structure as boxes of one phase each (the cubes of the finest level, merged
greedily), clipped to the box: the pieces, their phases and their cells (the
phases), for :func:`morphogen.mesh.exact.polyhedral_mesh`."""
from morphogen.mesh.exact import grid_boxes
step = self.cell_size / self.subdivisions**self.level
lo, hi = self.domain.lower, self.domain.upper
edges = []
for d in range(3):
n = int(np.ceil((hi[d] - lo[d]) / step - 1e-9))
e = lo[d] + step * np.arange(n + 1)
e[-1] = hi[d]
edges.append(e)
centres = [0.5 * (e[1:] + e[:-1]) for e in edges]
grid = np.stack(np.meshgrid(*centres, indexing="ij"), axis=-1)
labels = self.contains(grid.reshape(-1, 3)).reshape(grid.shape[:3]).astype(np.int64)
pieces, phase = grid_boxes(labels, edges)
return pieces, phase, phase.copy()
[docs]
def summary(self) -> dict:
return {"kept_cubes": len(self.kept) ** self.level, "level": self.level}
def _geometry(self) -> dict:
return {
"cell_size": self.cell_size,
"subdivisions": self.subdivisions,
"kept": [list(c) for c in self.kept],
"level": self.level,
}
@classmethod
def _from_geometry(cls, domain, geometry, **kwargs):
return cls(
domain,
geometry["cell_size"],
geometry["subdivisions"],
geometry["kept"],
geometry["level"],
**kwargs,
)
[docs]
@register
@dataclass(frozen=True)
class FractalSponge(Model):
"""Iterated function system on a cubic grid: the Menger sponge and its kin.
The cube of edge ``cell_size`` is divided into ``subdivisions^3`` sub-cubes, of which
the pattern keeps some (``menger``: all but the centre and the face centres, 20 of
27; ``vicsek``: the centre and the face centres; ``cantor_dust``: the 8 corners; or
``kept``: indices (i, j, k)); each kept sub-cube is divided alike, ``level`` times.
The attractor has the similarity dimension ``log N / log k`` (N cubes kept of k^3);
the domain is tiled by the cube.
"""
name = "fractal_sponge"
phases: ClassVar[dict[int, str]] = {0: "void", 1: "solid"}
count_label = "unit cells"
pattern: str = param("menger", doc="menger, vicsek or cantor_dust (or 'kept')", kind="str")
kept: tuple | None = param(
None, doc="Sub-cubes kept, as [i, j, k] indices (overrides the pattern)", kind="json"
)
subdivisions: int = param(3, doc="Sub-cubes per edge at each level", kind="int")
level: int = param(3, doc="Number of iterations", kind="int")
cell_size: float = param(1.0, doc="Edge of the cube of the sponge", unit="length")
def _validate(self) -> None:
check_positive(self.cell_size, "cell_size")
if not 2 <= self.subdivisions <= 9:
raise ValueError("subdivisions: from 2 to 9")
if not 1 <= self.level <= 8:
raise ValueError("level: from 1 to 8")
if self.kept is None:
if self.pattern not in PATTERNS:
raise ValueError(f"pattern: one of {sorted(PATTERNS)}, or give 'kept'")
if self.subdivisions != 3:
raise ValueError("the named patterns divide the cube in 3 x 3 x 3")
else:
cubes = {tuple(int(v) for v in c) for c in self.kept}
k = self.subdivisions
if not cubes or any(len(c) != 3 or not all(0 <= v < k for v in c) for c in cubes):
raise ValueError(f"kept: sub-cube indices [i, j, k] from 0 to {k - 1}")
@property
def cubes(self) -> list[tuple]:
if self.kept is not None:
return sorted({tuple(int(v) for v in c) for c in self.kept})
return list(PATTERNS[self.pattern])
[docs]
def generate(self, domain: Domain, seed: SeedLike = None) -> FractalStructure:
_, seed_info = make_rng(seed)
if domain.periodic:
ratio = domain.lengths / self.cell_size
if np.any(np.abs(ratio - np.rint(ratio)) > 1e-6 * np.maximum(ratio, 1.0)):
raise ValueError("fractal_sponge: a periodic domain holds whole cubes")
return FractalStructure(
domain,
self.cell_size,
self.subdivisions,
self.cubes,
self.level,
model=self,
seed=seed_info,
)
[docs]
def expected_count(self, domain: Domain) -> float:
return domain.volume / self.cell_size**3
[docs]
def theory(self, domain: Domain | None = None) -> dict[str, float]:
n, k = len(self.cubes), self.subdivisions
return {
"volume_fraction": (n / k**3) ** self.level,
"fractal_dimension": math.log(n) / math.log(k),
"smallest_cube": self.cell_size / k**self.level,
}