Source code for morphogen.analysis.correlation

"""Statistical descriptors of random heterogeneous materials (Torquato 2002).

* *Lineal-path function* ``L(z)`` (Lu & Torquato 1992): the probability that a segment
  of length ``z`` lies entirely in the phase, along the axes of the grid (segments of
  ``k + 1`` voxel centres at the lag ``k``). ``L(0)`` is the volume fraction; ``L`` keeps
  the connectedness along lines that the covariance ``S_2`` ignores.
* *Two-point cluster function* ``C_2(r)`` (Torquato, Beasley & Chiew 1988): the
  probability that ``x`` and ``x + r`` lie in the same cluster of the phase (connected
  components, merged across the faces of periodic images); ``C_2 <= S_2``, and ``C_2``
  keeps a long-range part only beyond the percolation threshold.
* *Pore-size function* (Prager 1963; Torquato & Avellaneda 1991): the law of the distance
  ``δ`` from a point of the phase to the nearest point of the other phase: its
  exceedance ``F(δ)`` (``F(0) = 1``), density ``P(δ) = -F'(δ)`` and moments; the mean
  pore size is ``∫ F(δ) dδ``. On voxels, ``δ`` is the distance between voxel centres less
  half a voxel (the interface lies between the centres), exact for interfaces along the
  axes and of the first order in the voxel size otherwise (the mean pore size of a
  Boolean model of spheres of five voxels about 4 % low).
* *Radial distribution function* ``g(r)`` and *structure factor* ``S(k)`` of points in a
  periodic box (the centres of packings): ``g`` is the density of the pairs at the
  distance ``r`` over that of independent points; ``S(k) = |Σ_j e^{-i k·x_j}|² / N`` on
  the wave vectors of the box, whose limit ``S(k → 0) = 0`` defines hyperuniform point
  patterns (Torquato & Stillinger 2003).
"""

from __future__ import annotations

import math
from dataclasses import dataclass

import numpy as np
from scipy.spatial import cKDTree

from morphogen.analysis.basic import indicator
from morphogen.analysis.connectivity import connected_components
from morphogen.analysis.covariance import AxisFunction
from morphogen.analysis.morphology import _distance, _periodic, _spacing


def _runs(lines: np.ndarray, periodic: bool) -> tuple[np.ndarray, int]:
    """The lengths of the runs of ones of the rows of a boolean array, and the number of
    rows full of ones (periodic rows: the runs wrap around)."""
    n = lines.shape[1]
    full = 0
    if periodic:
        is_full = lines.all(axis=1)
        full = int(is_full.sum())
        lines = lines[~is_full]
        if not len(lines):
            return np.zeros(0, dtype=np.int64), full
        # start every row on a zero: no run wraps around
        shift = np.argmin(lines, axis=1)
        lines = np.take_along_axis(lines, (np.arange(n)[None, :] + shift[:, None]) % n, axis=1)
    d = np.diff(np.pad(lines, ((0, 0), (1, 1))).astype(np.int8), axis=1)
    return (np.nonzero(d == -1)[1] - np.nonzero(d == 1)[1]).astype(np.int64), full


[docs] def lineal_path(image, phase: int = 1, *, max_lag: int | None = None, periodic=None): """Lineal-path function of ``phase`` along the three axes, for the lags 0..max_lag voxels (half the image by default): an :class:`AxisFunction`.""" field = indicator(image, phase) spacing = _spacing(image) periodic = _periodic(image, periodic) lags, values = {}, {} for axis, name in enumerate("xyz"): n = field.shape[axis] m = n // 2 if max_lag is None else min(int(max_lag), n - 1) lines = np.moveaxis(field, axis, -1).reshape(-1, n) runs, full = _runs(lines, periodic) counts = np.bincount(runs, minlength=n + 1).astype(np.float64) ell = np.arange(n + 1, dtype=np.float64) # the segments of k + 1 voxels in a run of length l: l - k, for l > k above = np.cumsum((counts * ell)[::-1])[::-1] # sum over l >= k of l n_l number = np.cumsum(counts[::-1])[::-1] k = np.arange(m + 1) inside = above[k + 1] - k * number[k + 1] + full * n positions = lines.shape[0] * (n if periodic else n - k) values[name] = inside / positions lags[name] = k * spacing[axis] return AxisFunction(lags, values, float(np.mean(field, dtype=np.float64)))
[docs] def two_point_cluster(image, phase: int = 1, *, max_lag: int | None = None, periodic=None): """Two-point cluster function of ``phase`` along the three axes (face-connected clusters), for the lags 0..max_lag voxels: an :class:`AxisFunction`.""" periodic = _periodic(image, periodic) labels = connected_components(image, phase, periodic=periodic, return_labels=True).labels spacing = _spacing(image) lags, values = {}, {} for axis, name in enumerate("xyz"): n = labels.shape[axis] m = n // 2 if max_lag is None else min(int(max_lag), n - 1) out = np.empty(m + 1) for k in range(m + 1): if periodic: other = np.roll(labels, -k, axis=axis) out[k] = np.mean((labels == other) & (labels > 0)) else: a = np.take(labels, np.arange(n - k), axis=axis) b = np.take(labels, np.arange(k, n), axis=axis) out[k] = np.mean((a == b) & (a > 0)) values[name] = out lags[name] = np.arange(m + 1) * spacing[axis] return AxisFunction(lags, values, float(np.mean(labels > 0)))
[docs] @dataclass class PoreSizes: """The pore-size function of a phase: the bin edges ``delta``, the exceedance ``F`` at the edges, the density ``P`` in the bins, and the first two moments of ``δ``.""" delta: np.ndarray exceedance: np.ndarray density: np.ndarray mean: float second_moment: float
[docs] def pore_size_function(image, phase: int = 0, *, bins: int = 64, periodic=None) -> PoreSizes: """The pore-size function of ``phase`` (by default the pores, phase 0): the law of the distance from its points to the other phase (see the module).""" mask = indicator(image, phase).astype(bool) if not mask.any(): raise ValueError(f"pore sizes: no voxel of phase {phase}") if mask.all(): raise ValueError(f"pore sizes: the image is all of phase {phase}") spacing = _spacing(image) periodic = _periodic(image, periodic) dist = _distance(mask, spacing, False, 0) if periodic: # through the faces: a margin of the largest distance inside the box pad = min(int(np.ceil(dist.max() / spacing.min())) + 1, max(mask.shape) // 2) dist = _distance(mask, spacing, True, pad) delta = np.maximum(dist[mask] - 0.5 * float(spacing.min()), 0.0) edges = np.linspace(0.0, float(delta.max()) * (1.0 + 1e-12), bins + 1) ordered = np.sort(delta) exceedance = 1.0 - np.searchsorted(ordered, edges, side="left") / len(ordered) density = -np.diff(exceedance) / np.diff(edges) return PoreSizes(edges, exceedance, density, float(delta.mean()), float(np.mean(delta**2)))
def _wrapped(points, box) -> np.ndarray: p = np.mod(np.asarray(points, dtype=float), box) p[p >= box] = 0.0 return p
[docs] def radial_distribution(points, box, *, r_max: float | None = None, bins: int = 100): """The radial distribution function ``g(r)`` of points in a periodic box of edges ``box``: the centres of the bins of ``r`` (up to ``r_max``, a quarter of the smallest edge by default) and ``g`` in them.""" box = np.asarray(box, dtype=float) pts = _wrapped(points, box) n = len(pts) if n < 2: raise ValueError("radial distribution: two points at least") r_max = float(box.min()) / 4.0 if r_max is None else float(r_max) if r_max > box.min() / 2.0: raise ValueError("radial distribution: r_max up to half the box") pairs = cKDTree(pts, boxsize=box).query_pairs(r_max, output_type="ndarray") d = pts[pairs[:, 0]] - pts[pairs[:, 1]] d -= box * np.round(d / box) r = np.linalg.norm(d, axis=1) edges = np.linspace(0.0, r_max, bins + 1) counts = np.histogram(r, bins=edges)[0].astype(np.float64) shells = 4.0 / 3.0 * math.pi * np.diff(edges**3) density = n / float(np.prod(box)) return 0.5 * (edges[1:] + edges[:-1]), 2.0 * counts / (n * density * shells)
[docs] def structure_factor(points, box, *, k_max: float | None = None, bins: int = 40): """The structure factor ``S(k)`` of points in a periodic box, averaged over the wave vectors ``2π n / L`` (``n`` integer, not all zero) in bins of ``|k|`` up to ``k_max`` (twenty times the smallest wave number by default): the centres of the bins with wave vectors and ``S`` in them.""" box = np.asarray(box, dtype=float) pts = _wrapped(points, box) n_pts = len(pts) k0 = 2.0 * math.pi / box k_max = 20.0 * float(k0.min()) if k_max is None else float(k_max) n_max = np.floor(k_max / k0).astype(int) # the density modes, separable along the axes: rho(k) = sum_j prod_a e^{-i k_a x_ja} waves = [np.exp(-1j * np.outer(pts[:, a], k0[a] * np.arange(-n_max[a], n_max[a] + 1))) for a in range(3)] # fmt: skip rho = np.einsum("ja,jb,jc->abc", waves[0], waves[1], waves[2], optimize=True) grids = np.meshgrid(*[k0[a] * np.arange(-n_max[a], n_max[a] + 1) for a in range(3)], indexing="ij") # fmt: skip k = np.sqrt(sum(g**2 for g in grids)) s = np.abs(rho) ** 2 / n_pts keep = (k > 0) & (k <= k_max) edges = np.linspace(0.0, k_max, bins + 1) which = np.digitize(k[keep], edges) - 1 total = np.bincount(which, weights=s[keep], minlength=bins)[:bins] count = np.bincount(which, minlength=bins)[:bins] centres = 0.5 * (edges[1:] + edges[:-1]) filled = count > 0 return centres[filled], total[filled] / count[filled]