"""Excursion sets of stationary Gaussian random fields."""
from __future__ import annotations
import math
from dataclasses import dataclass
from typing import ClassVar
import numpy as np
from scipy import fft as sfft
from scipy import stats
from morphogen import settings, theory
from morphogen._utils import check_fraction, check_positive, exactly_one
from morphogen.domain import Domain, Grid
from morphogen.image import VoxelImage
from morphogen.models.affine import (
ANISOTROPY,
Anisotropy,
anisotropy_from_config,
invariant_theory,
)
from morphogen.models.base import Microstructure, Model, param, register, register_kind
from morphogen.seeding import SeedLike, make_rng, seed_from_description
#: Spectral cut-off: modes with ``|k| * correlation_length`` above this are dropped
#: (the Gaussian spectrum is then below exp(-18) of its maximum).
K_CUTOFF = 6.0
#: Margin (in correlation lengths) added around non-periodic domains.
MARGIN = 3.0
def _half_space_modes(n_max: np.ndarray, box: np.ndarray, kmax: float):
"""Integer wave vectors m (one of each pair ±m, m != 0) with |2 pi m / box| <= kmax."""
axes = [np.arange(-n, n + 1) for n in n_max]
mx, my, mz = np.meshgrid(*axes, indexing="ij")
m = np.stack([mx.ravel(), my.ravel(), mz.ravel()], axis=1)
half = (
(m[:, 0] > 0)
| ((m[:, 0] == 0) & (m[:, 1] > 0))
| ((m[:, 0] == 0) & (m[:, 1] == 0) & (m[:, 2] > 0))
)
m = m[half]
k = 2.0 * np.pi * m / box
keep = np.einsum("ij,ij->i", k, k) <= kmax * kmax
return m[keep], k[keep]
[docs]
@register_kind
class GaussianField(Microstructure):
"""Phase 1 = {Y > threshold} for a unit-variance Gaussian field Y.
Y is a finite sum of Fourier modes on the generation box (the domain if periodic,
the domain enlarged by 3 correlation lengths otherwise), so the same realization
can be evaluated exactly at any resolution.
"""
kind = "gaussian_field"
def __init__(
self,
domain,
correlation_length,
threshold,
box_lower,
box_lengths,
mode_seed,
anisotropy=None,
**kwargs,
):
super().__init__(domain, **kwargs)
#: The affine anisotropy of the covariance ``rho(|A^-1 h|)`` (None: isotropic)
self.anisotropy = anisotropy
self.correlation_length = float(correlation_length)
self.threshold = float(threshold)
self.box_lower = np.asarray(box_lower, dtype=float)
self.box_lengths = np.asarray(box_lengths, dtype=float)
self.mode_seed = mode_seed
self._modes = None
[docs]
def modes(self):
"""Integer wave vectors and complex amplitudes C_m: Y(x) = Re sum C_m exp(i k_m.x)."""
if self._modes is None:
ell = self.correlation_length
kmax = K_CUTOFF / ell
if self.anisotropy is None:
n_max = np.floor(kmax * self.box_lengths / (2.0 * np.pi)).astype(int)
m, k = _half_space_modes(n_max, self.box_lengths, kmax)
else: # the spectrum of Y(A^-1 x) at k is that of Y at A^T k, |A^T k| >= s_min |k|
reach = kmax / float(self.anisotropy.principal.min())
n_max = np.floor(reach * self.box_lengths / (2.0 * np.pi)).astype(int)
m, k = _half_space_modes(n_max, self.box_lengths, reach)
k = k @ self.anisotropy.matrix
keep = np.einsum("ij,ij->i", k, k) <= kmax * kmax
m, k = m[keep], k[keep]
spectrum = np.exp(-0.5 * ell * ell * np.einsum("ij,ij->i", k, k))
var = spectrum / spectrum.sum()
rng = np.random.default_rng(seed_from_description(self.mode_seed))
a = rng.standard_normal(len(m))
b = rng.standard_normal(len(m))
# A cos + B sin = Re[(A - iB) e^{i k.x}]
amplitudes = np.sqrt(var) * (a - 1j * b)
self._modes = (m, amplitudes)
return self._modes
[docs]
def field(self, shape=None, *, voxel_size=None, grid: Grid | None = None) -> VoxelImage:
"""Values of the unit-variance Gaussian field at the voxel centres (float32)."""
grid = self.grid(shape, voxel_size=voxel_size, grid=grid)
m, amp = self.modes()
if len(m) == 0:
raise ValueError("gaussian_excursion: correlation length too large for the box")
x0 = grid.origin + 0.5 * grid.spacing - self.box_lower
aligned = self.domain.periodic and np.all(np.array(grid.shape) > 2 * np.abs(m).max(axis=0))
if aligned:
data = self._field_fft(grid, m, amp, x0)
else:
data = self._field_separable(grid, m, amp, x0)
return VoxelImage.from_grid(data, grid, name="field", metadata=self.image_metadata())
def _field_fft(self, grid, m, amp, x0):
# Y_j = Re sum_m C_m e^{i k_m.x0} e^{2 i pi m.j / n}: one inverse FFT on the grid
k = 2.0 * np.pi * m / self.box_lengths
coef = amp * np.exp(1j * (k @ x0))
n = np.array(grid.shape)
spec = np.zeros(tuple(n), dtype=np.complex128)
idx = np.mod(m, n)
np.add.at(spec, (idx[:, 0], idx[:, 1], idx[:, 2]), coef)
y = sfft.ifftn(spec, workers=settings.workers()) * spec.size
return np.ascontiguousarray(y.real, dtype=np.float32)
def _field_separable(self, grid, m, amp, x0):
# dense coefficient block, contracted axis by axis with exp(i k_a x_a), the axes of
# fewest voxels first: a plane contracts its normal first, which keeps the blocks
# to the size of the plane (x, y, z in turn for a cube)
n_max = np.abs(m).max(axis=0)
dense = np.zeros(tuple(2 * n_max + 1), dtype=np.complex128)
dense[m[:, 0] + n_max[0], m[:, 1] + n_max[1], m[:, 2] + n_max[2]] = amp
order = [int(a) for a in np.argsort(grid.shape, kind="stable")]
out = np.transpose(dense, order)
for axis in order:
ma = np.arange(-n_max[axis], n_max[axis] + 1)
xa = x0[axis] + np.arange(grid.shape[axis]) * grid.spacing[axis]
e = np.exp(2j * np.pi * np.outer(ma, xa) / self.box_lengths[axis])
out = np.tensordot(out, e, axes=([0], [0])) # contracted axis moves to the end
return np.ascontiguousarray(np.transpose(out.real, np.argsort(order)), dtype=np.float32)
[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.field(grid=grid).data > self.threshold).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.field(grid=fine).data > self.threshold).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 values_at(self, points) -> np.ndarray:
"""The Gaussian field ``Y`` at points of space (rows): the sum of its modes."""
from morphogen.kernels.implicit import fourier_points
m, amp = self.modes()
if len(m) == 0:
raise ValueError("gaussian_excursion: correlation length too large for the box")
pts = np.ascontiguousarray(points, dtype=float).reshape(-1, 3)
out = np.empty(len(pts))
fourier_points(np.ascontiguousarray(m, dtype=np.int64), np.ascontiguousarray(amp.real),
np.ascontiguousarray(amp.imag), self.box_lengths, self.box_lower, pts,
out) # fmt: skip
return out
[docs]
def contains(self, points) -> np.ndarray:
return self.values_at(points) > self.threshold
[docs]
def level_set_at(self, points, reach: float = np.inf) -> np.ndarray:
"""``(threshold - Y) * correlation_length`` at the points, as :meth:`level_set`."""
return (self.threshold - self.values_at(points)) * self.correlation_length
@property
def lipschitz(self) -> float:
"""A bound of the slope of :meth:`level_set_at` (three times the root mean square
of the gradient of ``Y``, times the correlation length)."""
m, amp = self.modes()
k = 2.0 * np.pi * m / self.box_lengths
rms = np.sqrt(np.sum(np.abs(amp) ** 2 * np.einsum("ij,ij->i", k, k)))
return float(3.0 * rms * self.correlation_length)
[docs]
def level_set(self, shape=None, *, voxel_size=None, grid: Grid | None = None) -> VoxelImage:
"""``(threshold - Y) * correlation_length``: negative in phase 1, roughly a distance
near the interface."""
f = self.field(shape, voxel_size=voxel_size, grid=grid)
data = (self.threshold - f.data) * np.float32(self.correlation_length)
return f.with_data(data.astype(np.float32), name="level_set")
[docs]
def summary(self) -> dict:
return {"n_modes": len(self.modes()[0])}
def _geometry(self) -> dict:
out = {
"correlation_length": self.correlation_length,
"threshold": self.threshold,
"box_lower": self.box_lower.tolist(),
"box_lengths": self.box_lengths.tolist(),
"mode_seed": self.mode_seed,
}
if self.anisotropy is not None:
out["anisotropy"] = self.anisotropy.to_config()
return out
@classmethod
def _from_geometry(cls, domain, geometry, **kwargs):
return cls(
domain,
geometry["correlation_length"],
geometry["threshold"],
geometry["box_lower"],
geometry["box_lengths"],
geometry["mode_seed"],
anisotropy_from_config(geometry.get("anisotropy")),
**kwargs,
)
[docs]
@register
@dataclass(frozen=True)
class GaussianExcursion(Model):
"""Excursion set {Y > threshold} of a Gaussian field with covariance exp(-h^2 / 2 l^2).
Give the volume fraction ``p`` of the excursion (threshold ``Phi^-1(1 - p)``) or the
threshold itself. Periodic boxes should be at least ~10 correlation lengths wide. An
``anisotropy`` puts the metric of :mod:`morphogen.models.affine` in the covariance,
``rho(|A^-1 h|)``: correlation lengths ``s_i l`` along its principal axes, in periodic
boxes too, whatever the axes (the modes of the box weighted by the spectrum at
``A^T k``).
"""
name = "gaussian_excursion"
phases: ClassVar[dict[int, str]] = {0: "phase 0", 1: "excursion"}
correlation_length: float = param(
1.0, doc="Correlation length l of the Gaussian covariance", unit="length"
)
volume_fraction: float | None = param(
None, doc="Volume fraction of the excursion", kind="fraction"
)
threshold: float | None = param(None, doc="Level of the excursion {Y > threshold}")
anisotropy: Anisotropy | None = param(None, doc=ANISOTROPY, kind="anisotropy", kw_only=True)
def _validate(self) -> None:
check_positive(self.correlation_length, "correlation_length")
exactly_one("volume_fraction", self.volume_fraction, "threshold", self.threshold)
if self.volume_fraction is not None:
check_fraction(self.volume_fraction, "volume_fraction")
@property
def level(self) -> float:
if self.threshold is not None:
return self.threshold
return float(stats.norm.isf(self.volume_fraction))
[docs]
def generate(self, domain: Domain, seed: SeedLike = None) -> GaussianField:
rng, seed_info = make_rng(seed)
ell = self.correlation_length
a = None if self.anisotropy is None or self.anisotropy.is_identity else self.anisotropy
reach = ell if a is None else ell * float(a.principal.max())
if domain.periodic:
lower, lengths = domain.lower, domain.lengths
else:
lower = domain.lower - MARGIN * reach
lengths = domain.lengths + 2.0 * MARGIN * reach
# the modes are drawn from a child seed so that they can be regenerated lazily
mode_seed = {"entropy": int(rng.integers(0, 2**63)), "spawn_key": []}
return GaussianField(
domain, ell, self.level, lower, lengths, mode_seed, a, model=self, seed=seed_info
)
[docs]
def theory(self, domain: Domain | None = None) -> dict[str, float]:
lam = self.level
p = float(stats.norm.sf(lam))
# second spectral moment -rho''(0) of the covariance: 1 / l^2
lam2 = 1.0 / self.correlation_length**2
g = math.exp(-0.5 * lam**2)
out = {
"threshold": lam,
"volume_fraction": p,
"specific_surface": 2.0 / math.pi * math.sqrt(lam2) * g,
# Adler's Gaussian kinematic formulae: 2 pi times the Euler density of the
# plane sections, and the Euler density of the excursion
"mean_curvature_density": lam2 / math.sqrt(2.0 * math.pi) * lam * g,
"euler_density": lam2**1.5 / (4.0 * math.pi**2) * (lam**2 - 1.0) * g,
"integral_range": self.integral_range(),
"variance_exponent": 1.0,
}
if self.anisotropy is not None and not self.anisotropy.is_identity:
out = invariant_theory(out)
return out
[docs]
def covariance(self, h) -> np.ndarray:
"""C(h) = P(Y(x) > l, Y(x + h) > l) with rho(h) = exp(-h^2 / 2 l^2)."""
h = np.asarray(h, dtype=float)
rho = np.exp(-0.5 * (h / self.correlation_length) ** 2)
return theory.bivariate_normal_upper(self.level, rho)
[docs]
def integral_range(self) -> float:
lam = self.level
p = float(stats.norm.sf(lam))
def f(h):
return float(self.covariance(h)) - p * p
return theory.radial_integral(f, 8.0 * self.correlation_length) / (p * (1.0 - p))