"""Closed-form results of stochastic geometry used by the models (see docs/theory.md)."""
from __future__ import annotations
import math
import numpy as np
from scipy import integrate, special, stats
#: Poisson-Voronoi tessellation in R^3 (intensity theta of germs):
#: squared coefficient of variation of the cell volume (Gilbert 1962),
VORONOI_VOLUME_CV2 = 0.1790
#: mean number of faces of the typical cell (Meijering 1953), 2 + 48 pi^2 / 35,
VORONOI_MEAN_FACES = 2.0 + 48.0 * math.pi**2 / 35.0
#: and cell-boundary area per unit volume S_V = c * theta^(1/3), with
#: c = (256 pi / 3)^(1/3) Gamma(5/3) / 2 (Meijering 1953).
VORONOI_SURFACE_COEFF = (256.0 * math.pi / 3.0) ** (1.0 / 3.0) * math.gamma(5.0 / 3.0) / 2.0
#: Jamming (saturation) volume fraction of random sequential addition of equal spheres.
RSA_JAMMING_FRACTION = 0.3841
#: Fraction of the maximally random jammed packings of equal spheres (Torquato, Truskett
#: & Debenedetti 2000), which fast Lubachevsky–Stillinger compressions approach.
MRJ_FRACTION = 0.64
[docs]
def sphere_covariogram(h, r):
"""Volume of ``B(0, r) ∩ B(h, r)`` for ``|h| = h`` (broadcasts)."""
h = np.asarray(h, dtype=float)
r = np.asarray(r, dtype=float)
v = np.pi / 12.0 * (4.0 * r + h) * (2.0 * r - h) ** 2
return np.where(h < 2.0 * r, v, 0.0)
[docs]
def disk_intersection_area(d, r):
"""Area of the intersection of two disks of radius ``r`` whose centres are ``d`` apart."""
d = np.asarray(d, dtype=float)
x = np.clip(d / (2.0 * r), 0.0, 1.0)
a = 2.0 * r * r * np.arccos(x) - 0.5 * d * np.sqrt(np.maximum(4.0 * r * r - d * d, 0.0))
return np.where(d < 2.0 * r, a, 0.0)
[docs]
def lens_area(d, r1, r2):
"""Area of the intersection of two disks of radii ``r1`` and ``r2`` whose centres are
``d`` apart (broadcasts): the smaller disk when it lies in the other, else the two
circular segments cut by their common chord."""
d, r1, r2 = np.broadcast_arrays(*(np.asarray(x, dtype=float) for x in (d, r1, r2)))
inside = d <= np.abs(r1 - r2)
out = np.where(inside, np.pi * np.minimum(r1, r2) ** 2, 0.0)
part = ~inside & (d < r1 + r2)
if np.any(part):
dd, a, b = d[part], r1[part], r2[part]
ca = np.clip((dd * dd + a * a - b * b) / (2.0 * dd * a), -1.0, 1.0)
cb = np.clip((dd * dd + b * b - a * a) / (2.0 * dd * b), -1.0, 1.0)
k = (-dd + a + b) * (dd + a - b) * (dd - a + b) * (dd + a + b)
out[part] = (
a * a * np.arccos(ca) + b * b * np.arccos(cb) - 0.5 * np.sqrt(np.maximum(k, 0.0))
)
return out
[docs]
def cylinder_covariogram(along, across, radius, length):
"""Volume of ``K ∩ (K + h)`` for the cylinder ``K`` of ``radius`` and ``length`` (flat
caps), ``h`` of components ``along = |h·u|`` and ``across = |h × u|`` relative to its
axis ``u`` (broadcasts): ``(l - along)+ lens(across)`` (Peyrega et al. 2009, eq. 15)."""
along = np.abs(np.asarray(along, dtype=float))
return np.maximum(length - along, 0.0) * disk_intersection_area(across, radius)
#: Gauss-Legendre nodes per piece of the integrals along the axis of spherocylinders
_CAPSULE_NODES = 24
[docs]
def spherocylinder_covariogram(along, across, radius, length):
"""Volume of ``K ∩ (K + h)`` for the spherocylinder ``K`` (round caps) of ``radius``
around an axis of ``length``, ``h`` of components ``along`` and ``across`` its axis
(broadcasts): the integral along the axis of the lens of the two sections, disks of
the radii ``rho(z)`` and ``rho(z - along)`` of the profile (``r`` on the axis, ``sqrt(r^2
- z^2)`` over the caps), ``across`` apart, by Gauss-Legendre over the pieces between
the ends of the axes and of the caps and the height where the facing caps have equal
sections (exact on the cylinders: ``(l - along)+ lens``)."""
a = np.abs(np.asarray(along, dtype=float))
a, d, r, ell = np.broadcast_arrays(
a, *(np.asarray(x, dtype=float) for x in (across, radius, length))
)
lo, hi = a - r, ell + r # the axis of K from 0 to l, that of K + h from a to a + l
cuts = np.stack([lo, np.zeros_like(a), ell, a, a + ell, 0.5 * (ell + a), hi], axis=-1)
cuts = np.sort(np.clip(cuts, lo[..., None], np.maximum(lo, hi)[..., None]), axis=-1)
x, w = np.polynomial.legendre.leggauss(_CAPSULE_NODES)
half = 0.5 * np.diff(cuts, axis=-1) # (..., 6)
z = 0.5 * (cuts[..., 1:] + cuts[..., :-1])[..., None] + half[..., None] * x # (..., 6, m)
def profile(t): # the radius of the section of K at the height t
out = np.sqrt(
np.maximum(r[..., None, None] ** 2 - np.maximum(-t, t - ell[..., None, None]) ** 2, 0.0)
)
return np.where((t >= 0.0) & (t <= ell[..., None, None]), r[..., None, None], out)
area = lens_area(d[..., None, None], profile(z), profile(z - a[..., None, None]))
return np.sum(half * np.sum(w * area, axis=-1), axis=-1)
[docs]
def oriented_covariance(q: float, rate: float, covariogram, h, orientation, direction=None):
"""``C(h) = 1 - 2 q + Q(h)`` of a Boolean model of grains of axes drawn from
``orientation`` (fibres, or the cylinders of Poisson lines): ``Q(h) = q^2 exp(rate
E_u[covariogram(|h|, b)])``, ``covariogram(h, b)`` (broadcasting, ``b`` the angle between
``h`` and the axis of a grain) its mean geometric covariogram over the sizes of the
grains, averaged over the angles of :func:`morphogen.orientations.angle_weights`. Along
``direction`` (a vector), or, for isotropic axes, along any; without a direction, the
covariance of anisotropic axes averaged over the directions of ``h`` (72 directions of
a half sphere: 6 Gauss-Legendre cosines and 12 azimuths), the mean taken of ``Q``."""
from morphogen.orientations import ANGLE_GRID, Isotropic, angle_weights, half_sphere
h = np.asarray(h, dtype=float)
flat = np.abs(h.reshape(-1))
if direction is not None or isinstance(orientation, Isotropic):
b, w = angle_weights(orientation, direction)
big_q = q * q * np.exp(rate * (covariogram(flat[:, None], b[None, :]) @ w))
else: # the mean over the directions of h: the angles on the grid
grid = np.linspace(0.0, 0.5 * np.pi, ANGLE_GRID)
table = covariogram(flat[:, None], grid[None, :])
big_q = np.zeros(len(flat))
for u, wu in zip(*half_sphere(6), strict=True):
big_q += (
wu * q * q * np.exp(rate * (table @ angle_weights(orientation, u, grid=True)[1]))
)
return (1.0 - 2.0 * q + big_q).reshape(h.shape)
[docs]
def boolean_intensity(volume_fraction: float, mean_grain_volume: float) -> float:
"""Intensity theta of a Boolean model: p = 1 - exp(-theta * E[V])."""
return -math.log1p(-volume_fraction) / mean_grain_volume
[docs]
def boolean_volume_fraction(intensity: float, mean_grain_volume: float) -> float:
"""The volume fraction ``1 - exp(-θ V̄)`` of a Boolean model of intensity θ and mean grain
volume V̄."""
return -math.expm1(-intensity * mean_grain_volume)
[docs]
def bivariate_normal_upper(level, rho):
"""P(X > level, Y > level) for standard normals X, Y of correlation ``rho``.
Uses P = (1 - Phi(l))^2 + 1/(2 pi) int_0^asin(rho) exp(-l^2 / (1 + sin t)) dt.
"""
rho = np.asarray(rho, dtype=float)
q = stats.norm.sf(level)
x, w = np.polynomial.legendre.leggauss(64)
a = np.arcsin(np.clip(rho, -1.0, 1.0))[..., None]
t = 0.5 * a * (x + 1.0)
f = np.exp(-(level**2) / (1.0 + np.sin(t)))
return q * q + 0.5 * a[..., 0] * np.sum(w * f, axis=-1) / (2.0 * math.pi)
[docs]
def radial_integral(f, upper: float) -> float:
"""``int_{|h| < upper} f(|h|) dh`` in R^3 for an isotropic function ``f``."""
value, _ = integrate.quad(lambda h: 4.0 * math.pi * h * h * f(h), 0.0, upper, limit=200)
return float(value)
[docs]
def normal_quantile(p: float) -> float:
"""The quantile of order ``p`` of the standard normal distribution."""
return float(special.ndtri(p))