Source code for morphogen.models.reconstruction

"""Stochastic reconstruction of two-phase microstructures from their statistical
descriptors (Yeong & Torquato 1998).

A realization is a periodic lattice of cells of edge ``cell_size`` covering the domain
(a :class:`~morphogen.models.lattice_field.LatticeField`), annealed from random cells of
the volume fraction (:mod:`morphogen.kernels.annealing`): the two-point probability
``S_2`` of phase 1 along the axes of the lattice, and its lineal-path function ``L``
with the weight ``lineal_path``, approach their targets, those of

* a Debye random medium (``correlation_length`` ``a``, Debye, Anderson & Brumberger
  1957): ``S_2(r) = p^2 + p (1 - p) e^{-r/a}``, specific surface ``4 p (1 - p) / a``;
* a realization of another model (``reference``) on the same lattice, periodic;
* a phase image (``image``: a file), its descriptors measured at its own voxels and
  interpolated at the lags of the lattice (``p^2`` and 0 beyond its half size).

``S_2`` alone does not determine a microstructure: two microstructures with the same
``S_2`` can differ in their connectivity, which ``L`` (and the chords) retains in part.
"""

from __future__ import annotations

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

import numpy as np

from morphogen._utils import check_fraction, check_positive
from morphogen.domain import Domain, Grid
from morphogen.kernels.annealing import anneal
from morphogen.models.base import Model, param, register
from morphogen.models.lattice_field import LatticeField, lattice_shape
from morphogen.seeding import SeedLike, make_rng


def _measured(image, rmax: int, lags: np.ndarray, n_axes: int):
    """``S_2`` and ``L`` of phase 1 of an image at the physical ``lags`` of each axis (rows),
    interpolated from its own lags, and its volume fraction."""
    from morphogen.analysis.correlation import lineal_path
    from morphogen.analysis.covariance import covariance

    cov = covariance(image, 1)
    lp = lineal_path(image, 1)
    p = cov.volume_fraction
    s = np.full((3, rmax + 1), p * p)
    line = np.zeros((3, rmax + 1))
    for a, name in enumerate("xyz"[:n_axes]):
        s[a] = np.interp(lags[a], cov.lags[name], cov.values[name], right=p * p)
        line[a] = np.interp(lags[a], lp.lags[name], lp.values[name], right=0.0)
    return s, line, p


[docs] @register @dataclass(frozen=True) class Reconstruction(Model): """Two-phase microstructure annealed to the two-point probability (and the lineal-path function) of a Debye medium, of a model or of an image (Yeong & Torquato 1998).""" name = "reconstruction" phases: ClassVar[dict[int, str]] = {0: "phase 0", 1: "phase 1"} reference: Model | None = param( None, doc="A model whose realization on the lattice gives the targets", kind="model" ) image: str | None = param( None, doc="A phase image (file) whose phase 1 gives the targets", kind="str" ) correlation_length: float | None = param( None, doc="Debye random medium: S2(r) = p^2 + p (1 - p) exp(-r / a)", unit="length", ) volume_fraction: float | None = param( None, doc="Fraction of phase 1 of the Debye medium", kind="fraction" ) lineal_path: float = param( 0.0, doc="Weight of the lineal-path function in the energy (0: S2 alone)" ) max_lag: int | None = param( None, doc="Largest lag of the descriptors, in cells (default: a quarter of the lattice, " "at most 32)", kind="int", ) sweeps: int = param(100, doc="Trial swaps per cell", kind="int") cooling: float = param( 0.98, doc="Factor of the temperature after every tenth of a sweep", kind="fraction" ) tolerance: float = param(1e-10, doc="Energy at which the annealing stops") cell_size: float = param(1.0, doc="Edge of the cells of the lattice", unit="length") dimension: int = param( 3, doc="3, or 2 for planar structures (one cell through the thickness)", kind="int" ) smoothing: float = param( 0.0, doc="Gaussian smoothing (in cells) of the interface for other resolutions and " "conforming meshes (0: trilinear interpolation of the cells)", unit="cells", ) def _validate(self) -> None: given = [k for k in ("reference", "image", "correlation_length") if getattr(self, k) is not None] # fmt: skip if len(given) != 1: raise ValueError( "give one target: reference (a model), image (a file) or correlation_length " "(a Debye medium)" ) if self.correlation_length is not None: check_positive(self.correlation_length, "correlation_length") if self.volume_fraction is None: raise ValueError("volume_fraction: the fraction of phase 1 of the Debye medium") check_fraction(self.volume_fraction, "volume_fraction") if self.lineal_path: raise ValueError("lineal_path: unknown for a Debye medium (give a reference)") elif self.volume_fraction is not None: raise ValueError("volume_fraction: that of the reference or of the image") check_positive(self.lineal_path, "lineal_path", allow_zero=True) if self.max_lag is not None and self.max_lag < 1: raise ValueError("max_lag: a positive number of cells") if self.sweeps < 1: raise ValueError("sweeps: a positive number of swaps per cell") if not 0.0 < self.cooling <= 1.0: raise ValueError("cooling: a factor in (0, 1]") check_positive(self.tolerance, "tolerance", allow_zero=True) check_positive(self.cell_size, "cell_size") if self.dimension not in (2, 3): raise ValueError("dimension: 2 or 3") check_positive(self.smoothing, "smoothing", allow_zero=True) def _lattice(self, domain: Domain) -> tuple[Grid, int, int]: """The periodic lattice of the domain, its axes and the largest lag.""" shape = lattice_shape(domain, self.cell_size, self.dimension) n_axes = 3 if self.dimension == 3 else 2 if self.max_lag is not None: rmax = int(self.max_lag) else: rmax = min(32, max(1, min(shape[:n_axes]) // 4)) if rmax > min(shape[:n_axes]) // 2: raise ValueError(f"max_lag: at most half the lattice ({min(shape[:n_axes]) // 2})") return Grid(dataclasses.replace(domain, periodic=True), shape), n_axes, rmax
[docs] def targets(self, domain: Domain, seed: SeedLike = None): """The target ``S_2`` and ``L`` along the axes (rows, lags 0..max_lag) and the volume fraction, on the lattice of the domain.""" rng, _ = make_rng(seed) return self._targets(domain, rng)
def _targets(self, domain: Domain, rng): lattice, n_axes, rmax = self._lattice(domain) lags = np.arange(rmax + 1)[None, :] * np.asarray(lattice.spacing, dtype=float)[:, None] if self.correlation_length is not None: p = float(self.volume_fraction) s = p * p + p * (1.0 - p) * np.exp(-lags / self.correlation_length) return s, np.zeros_like(s), p if self.reference is not None: ref = self.reference.generate(lattice.domain, seed=rng) image = ref.voxelize(grid=lattice) else: from morphogen import io image = io.load_image(self.image) s, line, p = _measured(image, rmax, lags, n_axes) return s, line, p
[docs] def generate(self, domain: Domain, seed: SeedLike = None) -> LatticeField: rng, seed_info = make_rng(seed) lattice, n_axes, rmax = self._lattice(domain) target_s, target_l, p = self._targets(domain, rng) cells = int(np.prod(lattice.shape)) img = np.zeros(cells, dtype=np.uint8) img[rng.permutation(cells)[: round(p * cells)]] = 1 img = img.reshape(lattice.shape) stage = max(1, cells // 10) initial, energy, trials, accepted = anneal( img, np.ascontiguousarray(target_s), np.ascontiguousarray(target_l), float(self.lineal_path), n_axes, rmax, int(self.sweeps) * cells, float(self.cooling), stage, float(self.tolerance), int(rng.integers(2**31 - 1)), ) attributes = {"initial_energy": float(initial), "energy": float(energy), "trials": int(trials), "accepted": int(accepted), "max_lag": rmax} # fmt: skip return LatticeField(domain, img, smoothing=self.smoothing, attributes=attributes, model=self, seed=seed_info) # fmt: skip
[docs] def theory(self, domain: Domain | None = None) -> dict[str, float]: if self.correlation_length is not None: p, a = float(self.volume_fraction), float(self.correlation_length) return {"volume_fraction": p, "specific_surface": 4.0 * p * (1.0 - p) / a, "integral_range": 8.0 * math.pi * a**3} # fmt: skip if self.reference is not None: ref = self.reference.theory(domain) return {k: ref[k] for k in ("volume_fraction",) if k in ref} return {}