vibe-sketcherDocumentation
Source code for vibesketcher.document.porosity
"""Probe-defined porosity plans and a bounded reference geometric estimate (#206).
A *porosity plan* states everything a geometric pore analysis depends on:
the probe (species label and radius), the atom-radius table with its name
and version, the volume and surface definitions, the sampling grid as a
convergence ladder of spacings, the window-sensitivity delta, the random
seed and the engine. :func:`plan_porosity` validates a plan against a
document's periodic structure and returns the planning record with stable
refusal codes; nothing is changed.
Calculation engines own production porosity. Zeo++, PoreBlazer and similar
programs are *candidates only*, pending dependency, executable and licence
review; a plan that names one is refused (``porosity.engine_unavailable``).
The ``reference`` engine here is a small pure-numpy grid estimate, bounded
and deterministic, written for planning and for tiny analytic checks. It is
a geometric planning estimate: geometric void is not adsorption capacity, and
an accessible surface area is not a BET surface area.
Definitions and methods (primary literature, cited beside the code below):
* Largest included sphere ``Di`` and largest free sphere ``Df`` follow
Willems, Rycroft, Kazi, Meza and Haranczyk, *Microporous Mesoporous
Mater.* 149, 134-141 (2012), doi:10.1016/j.micromeso.2011.08.020 (the
Zeo++ definitions). Here ``Df`` is the bottleneck (maximin) value of a
periodic path on the grid.
* Probe-centre, probe-occupiable, accessible and non-accessible volumes
follow Ongari, Boyd, Barthel, Witman, Haranczyk and Smit, *Langmuir* 33,
14529-14538 (2017), doi:10.1021/acs.langmuir.7b01682.
* Connectivity is Hoshen-Kopelman cluster labelling (*Phys. Rev. B* 14,
3438 (1976), doi:10.1103/PhysRevB.14.3438) done as a union-find on the
torus whose unions carry integer lattice offsets; a closed loop with a
nonzero offset (a winding) is a percolating path, and the rank of the
windings of a component is its channel dimensionality.
* The pore-size distribution is the geometric one of Gelb and Gubbins,
*Langmuir* 15, 305-308 (1999), doi:10.1021/la9808418: each void point
is assigned the largest void sphere that contains it, computed as the
morphological opening of the void by balls of increasing radius (periodic
FFT convolution on the grid).
* The accessible surface is the probe-centre surface of Lee and Richards,
*J. Mol. Biol.* 55, 379-400 (1971), doi:10.1016/0022-2836(71)90324-X,
sampled as in Shrake and Rupley, *J. Mol. Biol.* 79, 351-371 (1973),
doi:10.1016/0022-2836(73)90011-9, and applied to frameworks by Duren,
Millange, Ferey, Walton and Snurr, *J. Phys. Chem. C* 111, 15350-15356
(2007), doi:10.1021/jp074723h.
* The Connolly (solvent-excluded, molecular) surface is that of M. L.
Connolly, *J. Appl. Cryst.* 16, 548-558 (1983),
doi:10.1107/S0021889883010985, after Richards' molecular surface (*Annu.
Rev. Biophys. Bioeng.* 6, 151-176 (1977),
doi:10.1146/annurev.bb.06.060177.001055): the boundary of the region
probe spheres can occupy, contact patches on the atoms and re-entrant
patches on the probe. The reference engine computes it as the level set
``D = r_probe`` of the distance ``D`` to the probe-centre region ``C``
(``C`` dilated by the probe is the probe-occupiable region), on the grid;
see :func:`_connolly`. The surface area and the excluded volume follow from
regularised delta and Heaviside functions (Engquist, Tornberg and Tsai,
*J. Comput. Phys.* 207, 28-51 (2005), doi:10.1016/j.jcp.2004.09.018) with
the smoothing bias removed through the parallel-surface (Steiner)
expansion.
These papers are cited from the primary literature; they are not yet in the
project's literature library.
The distance field ``d(x)`` is the distance from ``x`` to the nearest atom
surface, ``min_j (abs(x - x_j - T) - r_j)`` over all lattice translations
``T``. The image set is complete: every point lies within the covering bound
``D`` (half the longest of the cell's body diagonals) of an image of every
atom, and fractional shifts are bounded by ``D`` over the interplanar
spacings. ``d`` is 1-Lipschitz, so sampled maxima are within the grid
covering radius ``h`` of the continuum value.
"""
from __future__ import annotations
import itertools
import math
from typing import Any, Literal, Self
import numpy as np
from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, model_validator
from vibesketcher.document.guest_loading import content_digest, radius_of
from vibesketcher.document.model import Document, PeriodicStructure
from vibesketcher.elements import ATOMIC_NUMBER
PLAN_SCHEMA = "vibesketcher.porosity-plan/1"
RESULT_SCHEMA = "vibesketcher.porosity-estimate/1"
HANDOFF_SCHEMA = "vibesketcher.porosity-handoff/1"
LABEL = "geometric planning estimate"
NOTE = (
"Geometric planning estimate on a sampled grid: geometric void is not adsorption "
"capacity, the accessible surface area is not a BET surface area, and near-threshold "
"windows are reported as uncertain rather than open or closed."
)
#: Grid points one ladder level may sample.
MAX_GRID_POINTS = 262_144
#: Point-image distance evaluations one analysis may make (all levels).
MAX_WORK = 150_000_000
#: Surface samples one analysis may draw.
MAX_SURFACE_SAMPLES = 200_000
#: Band-point x stencil-offset distance evaluations one Connolly region may make.
MAX_CONNOLLY_WORK = 250_000_000
#: Smoothing half-width of the Connolly delta/Heaviside functions, in grid steps.
CONNOLLY_SMOOTHING_STEPS = 2.0
MAX_PSD_BINS = 200
_AVOGADRO = 6.02214076e23 # CODATA 2018, exact
_EPS = 1e-9
#: Engines named in plans. Only ``reference`` runs here.
ENGINES: dict[str, str] = {
"reference": "vibe-sketcher reference grid estimate (pure numpy, bounded)",
"zeopp": "Zeo++: candidate only, pending dependency, executable and licence review",
"poreblazer": "PoreBlazer: candidate only, pending dependency and licence review",
"raspa": "RASPA geometric tools: candidate only, pending dependency and licence review",
}
DEFINITIONS: dict[str, str] = {
"geometric_void_fraction": "fraction of the cell outside every atom sphere (d >= 0); "
"a zero-radius probe; the total pore volume",
"probe_centre_fraction": "fraction of the cell where a probe centre fits (d >= r_probe)",
"probe_occupiable_fraction": "fraction of the cell covered by probe spheres centred where "
"they fit (Ongari et al. 2017)",
"accessible_fraction": "probe-occupiable fraction of components that percolate (channel "
"dimensionality >= 1); the accessible pore volume",
"nonaccessible_fraction": "probe-occupiable fraction of isolated pockets (dimensionality 0)",
"di": "largest included sphere diameter, 2 max d (Willems et al. 2012)",
"df": "largest free sphere diameter: 2 t*, t* the largest d threshold at which {d >= t} "
"percolates (Willems et al. 2012)",
"accessible_surface": "probe-centre surface: spheres of radius r_atom + r_probe minus their "
"overlaps, counted where the probe centre lies in a percolating component (Lee and Richards "
"1971; Duren et al. 2007)",
"connolly_surface": "solvent-excluded (molecular) surface traced by the probe's contact and "
"re-entrant patches (Connolly 1983): the boundary of the probe-occupiable region; total over "
"every probe-centre component and accessible over the percolating ones",
"excluded_volume": "volume inside the Connolly surface (atoms and the crevices no probe "
"reaches): the cell volume minus the probe-occupiable volume",
"psd": "geometric pore-size distribution: each point is assigned the diameter of the "
"largest void sphere containing it (Gelb and Gubbins 1999)",
"channel_dimensionality": "rank of the lattice windings of a connected probe-centre "
"component on the periodic grid (0 pocket, 1-3 channel)",
}
REFERENCES = [
"T. F. Willems, C. H. Rycroft, M. Kazi, J. C. Meza, M. Haranczyk, Microporous "
"Mesoporous Mater. 149, 134 (2012), doi:10.1016/j.micromeso.2011.08.020 (Zeo++ terms)",
"D. Ongari et al., Langmuir 33, 14529 (2017), doi:10.1021/acs.langmuir.7b01682",
"J. Hoshen, R. Kopelman, Phys. Rev. B 14, 3438 (1976), doi:10.1103/PhysRevB.14.3438",
"L. D. Gelb, K. E. Gubbins, Langmuir 15, 305 (1999), doi:10.1021/la9808418",
"B. Lee, F. M. Richards, J. Mol. Biol. 55, 379 (1971), doi:10.1016/0022-2836(71)90324-X",
"A. Shrake, J. A. Rupley, J. Mol. Biol. 79, 351 (1973), doi:10.1016/0022-2836(73)90011-9",
"T. Duren et al., J. Phys. Chem. C 111, 15350 (2007), doi:10.1021/jp074723h",
"M. L. Connolly, J. Appl. Cryst. 16, 548 (1983), doi:10.1107/S0021889883010985",
"F. M. Richards, Annu. Rev. Biophys. Bioeng. 6, 151 (1977), "
"doi:10.1146/annurev.bb.06.060177.001055",
"B. Engquist, A.-K. Tornberg, R. Tsai, J. Comput. Phys. 207, 28 (2005), "
"doi:10.1016/j.jcp.2004.09.018",
]
#: Stable refusal and outcome codes.
CODES: dict[str, str] = {
"porosity.periodicity_unsupported": "the structure is not 3D periodic and no slab policy "
"was stated",
"porosity.engine_unavailable": "the named engine is not available here",
"porosity.definition_unsupported": "the engine does not compute the planned definition",
"porosity.partial_occupancy": "partially occupied sites have no single geometry",
"porosity.unknown_override": "a radius override names no element of the structure",
"porosity.too_large": "the grid, image or surface work exceeds the bound",
"porosity.open": "the probe percolates robustly within the window delta",
"porosity.window_uncertain": "a percolation threshold lies within the window delta of the "
"probe radius; open/closed is not decided",
"porosity.blocked": "the probe fits only in isolated pockets (no percolating channel)",
"porosity.zero_accessible": "the probe fits nowhere in the cell",
"porosity.not_converged": "the two finest ladder levels differ beyond the tolerances",
"porosity.empty_distribution": "the pore-size distribution has no volume to draw",
"porosity.stale_estimate": "the stored estimate belongs to another version of the structure",
"porosity.revision_conflict": "the document changed since the revision the edit is based on",
"porosity.nothing_to_undo": "no stored porosity estimate to remove",
"porosity.no_estimate": "the structure holds no stored porosity estimate",
}
[docs]
class PorosityRefused(ValueError):
"""A plan, analysis or writer refused with stable codes."""
def __init__(self, refusals: list[dict[str, str]]) -> None:
self.refusals = refusals
super().__init__("; ".join(f"{r['code']}: {r['message']}" for r in refusals))
def _refusal(code: str, message: str) -> dict[str, str]:
return {"code": code, "message": message}
class _Model(BaseModel):
model_config = ConfigDict(extra="forbid")
[docs]
class Probe(_Model):
"""The probe: a species label as given and its hard-sphere radius."""
species: str = Field(min_length=1, max_length=40)
radius_angstrom: float = Field(ge=0, le=10, allow_inf_nan=False)
#: Where the radius comes from (e.g. a kinetic diameter source), kept as given.
radius_source: str | None = Field(default=None, max_length=300)
[docs]
class RadiusTable(_Model):
"""The atom radii: RDKit's van der Waals or covalent table, as in guest loading (#203)."""
name: Literal["vdw", "covalent"] = "vdw"
overrides: dict[str, float] = Field(default_factory=dict, max_length=118)
@model_validator(mode="after")
def _check(self) -> Self:
for symbol, radius in self.overrides.items():
if symbol not in ATOMIC_NUMBER:
raise ValueError(f"unknown element {symbol!r} in radius overrides")
if not (math.isfinite(radius) and 0.1 <= radius <= 4.0):
raise ValueError("override radii must be between 0.1 and 4 angstrom")
return self
[docs]
class Sampling(_Model):
"""The grid as a convergence ladder of spacings (coarse to fine) and the tolerances."""
spacings_angstrom: list[float] = Field(
default_factory=lambda: [0.4, 0.2], min_length=1, max_length=4
)
tolerance_diameter_angstrom: float = Field(default=0.1, gt=0, le=5, allow_inf_nan=False)
tolerance_fraction: float = Field(default=0.01, gt=0, le=1, allow_inf_nan=False)
surface_samples_per_atom: int = Field(default=400, ge=0, le=20_000)
#: Relative tolerance of the Connolly surface area between the two finest levels.
tolerance_area_relative: float = Field(default=0.03, gt=0, le=1, allow_inf_nan=False)
seed: int = Field(default=0, ge=0, lt=2**63)
@model_validator(mode="after")
def _ladder(self) -> Self:
steps = self.spacings_angstrom
if any(not (math.isfinite(s) and 0.02 <= s <= 2.0) for s in steps):
raise ValueError("grid spacings must be between 0.02 and 2 angstrom")
if any(b >= a for a, b in itertools.pairwise(steps)):
raise ValueError("the spacing ladder must decrease strictly (coarse to fine)")
return self
[docs]
class PsdSettings(_Model):
"""Pore-size distribution binning, region and normalisation."""
bin_width_angstrom: float = Field(default=0.2, ge=0.02, le=5, allow_inf_nan=False)
#: ``total``: the whole geometric void; ``accessible``: spheres centred in percolating
#: probe-centre components, from the probe diameter up.
region: Literal["total", "accessible"] = "total"
#: ``cell_fraction``: fraction of the cell volume per bin; ``region_fraction``: fraction
#: of the region's volume (bins sum to 1).
normalisation: Literal["cell_fraction", "region_fraction"] = "cell_fraction"
[docs]
class PorosityPlan(_Model):
"""Everything a geometric pore analysis depends on, stated."""
structure: str = Field(min_length=1, max_length=64)
engine: str = Field(default="reference", min_length=1, max_length=40)
probe: Probe
radii: RadiusTable = Field(default_factory=RadiusTable)
surface: Literal["accessible", "connolly", "none"] = "accessible"
sampling: Sampling = Field(default_factory=Sampling)
#: Re-evaluate the channel dimensionality at r_probe - delta and r_probe + delta;
#: a change inside that window is reported uncertain. Raised to the grid resolution.
window_delta_angstrom: float = Field(default=0.1, ge=0, le=2, allow_inf_nan=False)
psd: PsdSettings = Field(default_factory=PsdSettings)
#: For a structure that is not 3D periodic: ``refuse`` (default), or ``cell_box``
#: (the stated cell bounds each nonperiodic direction: no images, connections or
#: windings across its faces, and any vacuum inside the cell counts as void).
slab_policy: Literal["refuse", "cell_box"] = "refuse"
[docs]
def parse_plan(data: dict[str, Any]) -> PorosityPlan:
"""A validated plan (raises pydantic.ValidationError)."""
return TypeAdapter(PorosityPlan).validate_python(data)
# --- geometry helpers ------------------------------------------------------------------
def _radius_table(structure: PeriodicStructure, table: RadiusTable) -> dict[str, Any]:
import rdkit
symbols = sorted({s.symbol for s in structure.sites})
radii = {s: radius_of(s, table.name, table.overrides) for s in symbols}
source = {
"vdw": "RDKit periodic table van der Waals radii (GetRvdw)",
"covalent": "RDKit periodic table covalent radii (GetRcovalent)",
}[table.name]
return {
"name": table.name,
"source": source,
"version": f"RDKit {rdkit.__version__}",
"shared_with": "guest loading (#203) collision radii",
"radii_angstrom": radii,
"overridden": sorted(set(table.overrides) & set(symbols)),
}
def _grid_shape(lattice: np.ndarray, spacing: float) -> tuple[int, int, int]:
"""Points per axis: length / spacing rounded up to an even number (half points sampled)."""
out = []
for row in lattice:
n = max(2, math.ceil(float(np.linalg.norm(row)) / spacing - 1e-9))
out.append(n + (n % 2))
return (out[0], out[1], out[2])
def _corner_bound(vectors: np.ndarray) -> float:
"""Half the longest of the body diagonals of the parallelepiped spanned by the rows."""
return 0.5 * max(
float(np.linalg.norm(s0 * vectors[0] + s1 * vectors[1] + s2 * vectors[2]))
for s0, s1, s2 in itertools.product((-1, 1), repeat=3)
)
def _spacings(lattice: np.ndarray) -> np.ndarray:
"""Interplanar spacings 1 / norm(b_i) of the lattice planes."""
return 1.0 / np.linalg.norm(np.linalg.inv(lattice).T, axis=1)
def _shift_range(reach: float, lattice: np.ndarray, periodic: tuple[bool, ...]) -> list[range]:
"""Integer shifts n with abs(n) <= floor(reach / h_i) + 1 on periodic axes."""
h = _spacings(lattice)
return [
range(-(int(reach / h[i]) + 1), int(reach / h[i]) + 2) if periodic[i] else range(0, 1)
for i in range(3)
]
def _images(
frac: np.ndarray, radii: np.ndarray, lattice: np.ndarray, shifts: list[range]
) -> tuple[np.ndarray, np.ndarray]:
cells = np.array(list(itertools.product(*shifts)), dtype=float)
cart = ((frac[None, :, :] + cells[:, None, :]).reshape(-1, 3)) @ lattice
return cart, np.tile(radii, len(cells))
def _nearest_surface(points: np.ndarray, centres: np.ndarray, radii: np.ndarray) -> np.ndarray:
"""min_j (abs(p - c_j) - r_j) for each point, in chunks."""
out = np.empty(len(points))
chunk = max(1, 4_000_000 // max(1, len(centres)))
for start in range(0, len(points), chunk):
p = points[start : start + chunk]
dist = np.sqrt(((p[:, None, :] - centres[None, :, :]) ** 2).sum(axis=2))
out[start : start + chunk] = (dist - radii[None, :]).min(axis=1)
return out
class _Torus:
"""Union-find on the periodic grid; unions carry integer lattice offsets.
``off[x]`` is the cell offset of ``x`` relative to its parent; a cycle whose
offsets do not close is a winding, and each root keeps an independent basis
of its windings (Hoshen and Kopelman 1976, with periodic offsets).
"""
def __init__(self, count: int) -> None:
self.parent = list(range(count))
self.size = [1] * count
self.off = [(0, 0, 0)] * count
self.basis: dict[int, list[tuple[int, int, int]]] = {}
def find(self, x: int) -> tuple[int, tuple[int, int, int]]:
parent, off = self.parent, self.off
path = []
while parent[x] != x:
path.append(x)
x = parent[x]
root = x
total = (0, 0, 0)
for node in reversed(path):
o = off[node]
total = (o[0] + total[0], o[1] + total[1], o[2] + total[2])
off[node] = total
parent[node] = root
return root, (off[path[0]] if path else (0, 0, 0))
def _add(self, root: int, w: tuple[int, int, int]) -> bool:
basis = self.basis.setdefault(root, [])
if len(basis) == 3:
return False
if np.linalg.matrix_rank(np.array([*basis, w], dtype=float)) > len(basis):
basis.append(w)
return True
return False
def union(self, u: int, v: int, shift: tuple[int, int, int]) -> bool:
"""Join u and v (v lies at u + shift cells); True when a basis grew."""
ru, a = self.find(u)
rv, b = self.find(v)
if ru == rv:
w = (a[0] + shift[0] - b[0], a[1] + shift[1] - b[1], a[2] + shift[2] - b[2])
return w != (0, 0, 0) and self._add(ru, w)
rel = (a[0] + shift[0] - b[0], a[1] + shift[1] - b[1], a[2] + shift[2] - b[2])
if self.size[ru] < self.size[rv]:
ru, rv = rv, ru
rel = (-rel[0], -rel[1], -rel[2])
self.parent[rv] = ru
self.off[rv] = rel
self.size[ru] += self.size[rv]
moved = self.basis.pop(rv, [])
before = len(self.basis.get(ru, []))
for w in moved:
self._add(ru, w)
return len(self.basis.get(ru, [])) > before
def rank(self, root: int) -> int:
return len(self.basis.get(root, []))
def axes(self, root: int) -> list[int]:
basis = self.basis.get(root, [])
return [i for i in range(3) if any(w[i] for w in basis)]
def _neighbours(shape: tuple[int, int, int], periodic: tuple[bool, ...]) -> list[Any]:
"""Six face neighbours per point: (index array, shift) with -1 across closed faces."""
n = shape
idx = np.arange(n[0] * n[1] * n[2]).reshape(n)
out = []
for axis in range(3):
for step in (1, -1):
rolled = np.roll(idx, -step, axis=axis).copy()
edge = [slice(None)] * 3
edge[axis] = slice(n[axis] - 1, n[axis]) if step == 1 else slice(0, 1)
shift = [0, 0, 0]
shift[axis] = step
if not periodic[axis]:
rolled[tuple(edge)] = -1
wrapped = np.zeros(n, dtype=bool)
wrapped[tuple(edge)] = True
out.append((rolled.ravel(), wrapped.ravel(), tuple(shift)))
return out
def _percolation(
field: np.ndarray, shape: tuple[int, int, int], periodic: tuple[bool, ...], probe: float
) -> dict[str, Any]:
"""Activate void points by decreasing d (a maximum spanning forest, as in Kruskal's
algorithm): the d at which a component's winding rank first reaches k is t_k, the
bottleneck of a k-dimensional channel; components are labelled at d = probe."""
flat = field.ravel()
order = np.argsort(-flat, kind="stable")
nbrs = [(nb.tolist(), wr.tolist(), s) for nb, wr, s in _neighbours(shape, periodic)]
torus = _Torus(len(flat))
active = bytearray(len(flat))
thresholds: list[float | None] = [None, None, None]
axis_t: list[float | None] = [None, None, None]
taken: tuple[np.ndarray, dict[int, int], dict[int, list[int]]] | None = None
zero = (0, 0, 0)
def snapshot() -> tuple[np.ndarray, dict[int, int], dict[int, list[int]]]:
lab = np.full(len(flat), -1, dtype=np.int64)
for node in np.flatnonzero(flat >= probe).tolist():
lab[node] = torus.find(node)[0]
roots = np.unique(lab[lab >= 0]).tolist()
return lab, {r: torus.rank(r) for r in roots}, {r: torus.axes(r) for r in roots}
values = flat[order].tolist()
for node, value in zip(order.tolist(), values, strict=True):
if value < 0:
break
if taken is None and value < probe:
taken = snapshot()
active[node] = 1
grew = False
for nb, wr, shift in nbrs:
v = nb[node]
if v >= 0 and active[v]:
grew |= torus.union(node, v, shift if wr[node] else zero)
if grew:
root = torus.find(node)[0]
for k in range(torus.rank(root)):
if thresholds[k] is None:
thresholds[k] = value
for axis in torus.axes(root):
if axis_t[axis] is None:
axis_t[axis] = value
labels, ranks, axes = taken if taken is not None else snapshot()
return {
"thresholds": thresholds,
"axis_thresholds": axis_t,
"labels": labels,
"ranks": ranks,
"axes": axes,
}
def _dimensionality(thresholds: list[float | None], radius: float) -> int:
return sum(1 for t in thresholds if t is not None and t >= radius - 1e-12)
def _offset_distance(
shape: tuple[int, ...],
n: tuple[int, int, int],
lattice: np.ndarray,
periodic: tuple[bool, ...],
reach: float,
) -> np.ndarray:
"""Length of each grid offset, minimised over the lattice images within ``reach``."""
axes = []
for i in range(3):
g = shape[i]
k = np.arange(g)
k = np.where(k >= (g + 1) // 2, k - g, k)
axes.append(k / n[i])
f = np.stack(np.meshgrid(*axes, indexing="ij"), axis=-1)
best = np.full(shape, np.inf)
for cell in itertools.product(*_shift_range(reach, lattice, periodic)):
cart = (f + np.asarray(cell, dtype=float)) @ lattice
best = np.minimum(best, np.sqrt((cart**2).sum(axis=-1)))
return best
class _Opening:
"""Points within a radius of a set of centres: periodic FFT convolution with a ball,
nonperiodic axes zero-padded so nothing wraps across a closed face."""
def __init__(
self,
n: tuple[int, int, int],
lattice: np.ndarray,
periodic: tuple[bool, ...],
reach: float,
) -> None:
self.n = n
self.shape = tuple(n[i] if periodic[i] else 2 * n[i] for i in range(3))
self.offsets = _offset_distance(self.shape, n, lattice, periodic, reach)
def covered(self, centres: np.ndarray, radius: float) -> np.ndarray:
n = self.n
if not centres.any():
return np.zeros(n, dtype=bool)
grid = np.zeros(self.shape)
grid[: n[0], : n[1], : n[2]] = centres
kernel = (self.offsets <= radius + _EPS).astype(float)
conv = np.fft.irfftn(
np.fft.rfftn(grid) * np.fft.rfftn(kernel), s=self.shape, axes=(0, 1, 2)
)
return np.asarray(conv[: n[0], : n[1], : n[2]] > 0.5)
def _connolly_smoothing(lattice: np.ndarray, n: tuple[int, int, int]) -> float:
"""Half-width of the regularised delta: CONNOLLY_SMOOTHING_STEPS of the longest grid step.
The cosine kernel at an integer number of steps meets the discrete zeroth and first
moment conditions exactly for grid-aligned surfaces (Engquist et al. 2005)."""
step = max(float(np.linalg.norm(lattice[i])) / n[i] for i in range(3))
return CONNOLLY_SMOOTHING_STEPS * step
def _connolly_stencil(lattice: np.ndarray, n: tuple[int, int, int], probe: float) -> dict[str, Any]:
"""Integer grid offsets within ``reach`` of a point, and their lengths (angstrom)."""
eps = _connolly_smoothing(lattice, n)
cap = _corner_bound(lattice / np.asarray(n, dtype=float)[:, None])
reach = probe + 2 * eps + cap
h = _spacings(lattice)
# Nonperiodic axes keep their offsets too; the caller drops those that leave the box.
ranges = [
np.arange(-math.ceil(reach * n[i] / h[i]), math.ceil(reach * n[i] / h[i]) + 1)
for i in range(3)
]
grid = np.stack(np.meshgrid(*ranges, indexing="ij"), axis=-1).reshape(-1, 3)
lengths = np.linalg.norm((grid / np.asarray(n, dtype=float)) @ lattice, axis=1)
keep = lengths <= reach + _EPS
return {
"smoothing": eps,
"cap": cap,
"reach": reach,
"offsets": grid[keep],
"lengths": lengths[keep],
}
def _connolly(
field: np.ndarray,
inside: np.ndarray,
lattice: np.ndarray,
periodic: tuple[bool, ...],
probe: float,
) -> dict[str, Any]:
"""Connolly (solvent-excluded) surface area and occupiable volume of one region.
``inside`` is the probe-centre region ``C`` (or its percolating part). The
probe-occupiable region is ``O = {D <= r_probe}`` with ``D`` the distance to
``C``; its boundary is the Connolly surface (Connolly 1983; Richards 1977): on
contact patches ``D`` is measured to the probe-centre sphere of an atom, on
re-entrant patches to a crease of ``C``.
``D`` is evaluated near the surface from the grid without staircase error. The
exact clearance of a probe-centre point ``c`` is ``m(c) = d(c) - r_probe`` (the
distance to a union of spheres from outside), so the ball of radius ``m(c)``
about ``c`` lies in ``C`` and ``D(x) = min_c (abs(x - c) - m(c))``. Along the
inward normal of ``C`` this is constant, so candidates are capped at one grid
covering radius of clearance and the stencil reaches ``r_probe + 2 eps + cap``;
the error is second order in the lateral grid offset. Points the plain probe
covering already places deeper than ``r_probe - 2 eps`` are inside, points more
than ``2 eps`` inside an atom are outside (``D >= r_probe - d``, d 1-Lipschitz).
With regularised delta and Heaviside functions of half-width ``eps`` (cosine
kernel, second moment ``sigma2 = eps**2 (1/3 - 2/pi**2)``; Engquist, Tornberg
and Tsai 2005) the smoothed estimates are ``A(s) + sigma2/2 A''(s)`` and
``V(s) + sigma2/2 A'(s)``, the expansion of a parallel-surface family
``O(s)`` whose area is ``A(s) = V'(s)`` (Steiner). The bias is removed with
central differences of the smoothed area at ``s = r_probe +/- eps``, exact for
a sphere, whose area is quadratic in ``s``.
"""
n = (int(field.shape[0]), int(field.shape[1]), int(field.shape[2]))
stencil = _connolly_stencil(lattice, n, probe)
eps = float(stencil["smoothing"])
eta = eps
lo = max(probe - eps - eta, 0.0)
clearance = field - probe
candidates = inside & (clearance <= stencil["cap"])
values = np.where(candidates, clearance, -np.inf).ravel()
if lo > 0 and inside.any():
deep = _Opening(n, lattice, periodic, lo).covered(inside, lo) | inside
else:
deep = inside.copy()
band = np.flatnonzero((~deep & (field >= -(eps + eta))).ravel())
offsets = np.asarray(stencil["offsets"], dtype=np.int64)
lengths = np.asarray(stencil["lengths"], dtype=float)
work = len(band) * len(offsets)
if work > MAX_CONNOLLY_WORK:
raise PorosityRefused(
[
_refusal(
"porosity.too_large",
f"the Connolly estimate needs {work} band evaluations, above "
f"{MAX_CONNOLLY_WORK}; coarsen the ladder or use an engine",
)
]
)
ijk = np.stack(np.unravel_index(band, n), axis=1)
shape = np.asarray(n, dtype=np.int64)
distance = np.full(len(band), np.inf)
chunk = max(1, 2_000_000 // max(1, len(band)))
for start in range(0, len(offsets), chunk):
near = ijk[:, None, :] + offsets[None, start : start + chunk, :]
valid = np.ones(near.shape[:2], dtype=bool)
for axis in range(3):
if periodic[axis]:
near[..., axis] %= shape[axis]
else:
valid &= (near[..., axis] >= 0) & (near[..., axis] < shape[axis])
near[..., axis] = np.clip(near[..., axis], 0, shape[axis] - 1)
flat = (near[..., 0] * shape[1] + near[..., 1]) * shape[2] + near[..., 2]
found = np.where(valid, values[flat], -np.inf)
np.minimum(
distance, (lengths[None, start : start + chunk] - found).min(axis=1), out=distance
)
volume = abs(float(np.linalg.det(lattice)))
dv = volume / math.prod(n)
def phi(level: float) -> np.ndarray:
return np.clip(distance - level, -2 * eps, 2 * eps)
def area(level: float) -> float:
p = phi(level)
near = np.abs(p) < eps
return float(((1 + np.cos(np.pi * p[near] / eps)) / (2 * eps)).sum() * dv)
def occupied(level: float) -> float:
p = phi(level)
heaviside = np.where(
p <= -eps,
1.0,
np.where(p >= eps, 0.0, 0.5 * (1 - p / eps - np.sin(np.pi * p / eps) / np.pi)),
)
return float(deep.sum() * dv + heaviside.sum() * dv)
sigma2 = eps * eps * (1 / 3 - 2 / math.pi**2)
a0, a_plus, a_minus = area(probe), area(probe + eta), area(probe - eta)
smoothed_v = occupied(probe)
surface = a0 - sigma2 / 2 * (a_plus - 2 * a0 + a_minus) / eta**2
occupiable = smoothed_v - sigma2 / 2 * (a_plus - a_minus) / (2 * eta)
return {
"area_angstrom2": max(surface, 0.0),
"occupiable_angstrom3": min(max(occupiable, 0.0), volume),
"smoothed_area_angstrom2": a0,
"smoothed_occupiable_angstrom3": smoothed_v,
"smoothing_angstrom": eps,
"band_points": len(band),
"stencil_offsets": len(offsets),
}
def _cell_mass(structure: PeriodicStructure) -> float:
"""Cell mass in grams (RDKit standard atomic weights)."""
from rdkit import Chem
table = Chem.GetPeriodicTable()
daltons = sum(table.GetAtomicWeight(ATOMIC_NUMBER[s.symbol]) for s in structure.sites)
return float(daltons) / _AVOGADRO
# --- plan --------------------------------------------------------------------------------
def _work(structure: PeriodicStructure, plan: PorosityPlan) -> dict[str, Any]:
lattice = np.asarray(structure.lattice_angstrom, dtype=float)
periodic = _periodic(structure, plan)
radii = _radius_table(structure, plan.radii)["radii_angstrom"]
r = [radii[s.symbol] for s in structure.sites]
reach = _corner_bound(lattice) + max(r) - min(r)
images = math.prod(len(x) for x in _shift_range(reach, lattice, periodic))
levels: list[dict[str, Any]] = []
for spacing in plan.sampling.spacings_angstrom:
shape = _grid_shape(lattice, spacing)
level: dict[str, Any] = {
"spacing_angstrom": spacing,
"grid_shape": list(shape),
"points": math.prod(shape),
}
if plan.surface == "connolly":
stencil = _connolly_stencil(lattice, shape, plan.probe.radius_angstrom)
level["connolly_smoothing_angstrom"] = stencil["smoothing"]
level["connolly_stencil_offsets"] = len(stencil["lengths"])
levels.append(level)
distance_work = sum(level["points"] for level in levels) * images * len(structure.sites)
samples = plan.sampling.surface_samples_per_atom * len(structure.sites)
if plan.surface != "accessible":
samples = 0
return {
"levels": levels,
"atom_images": images * len(structure.sites),
"distance_evaluations": distance_work,
"surface_samples": samples,
}
def _periodic(structure: PeriodicStructure, plan: PorosityPlan) -> tuple[bool, bool, bool]:
if all(structure.pbc):
return (True, True, True)
return structure.pbc if plan.slab_policy == "cell_box" else (True, True, True)
def _structure(document: Document, identifier: str) -> PeriodicStructure:
found = {s.id: s for s in document.periodic_structures}
if identifier not in found:
raise KeyError(f"periodic structure {identifier!r} not found")
return found[identifier]
[docs]
def plan_porosity(structure: PeriodicStructure, plan: PorosityPlan) -> dict[str, Any]:
"""The planning record: the stated plan, radius table, grid ladder, work and refusals."""
refusals: list[dict[str, str]] = []
if not all(structure.pbc) and plan.slab_policy == "refuse":
refusals.append(
_refusal(
"porosity.periodicity_unsupported",
f"the structure has PBC {list(structure.pbc)}; a pore analysis "
"needs a 3D periodic cell, or slab_policy='cell_box' stated",
)
)
if plan.engine != "reference":
known = ENGINES.get(plan.engine, "an unknown engine")
refusals.append(
_refusal(
"porosity.engine_unavailable",
f"engine {plan.engine!r} ({known}) is not available; only 'reference' runs here",
)
)
if plan.surface == "connolly" and plan.engine == "reference":
lattice = np.asarray(structure.lattice_angstrom, dtype=float)
widths = [
_connolly_smoothing(lattice, _grid_shape(lattice, s))
for s in plan.sampling.spacings_angstrom
]
if plan.probe.radius_angstrom < 2 * max(widths) - _EPS:
refusals.append(
_refusal(
"porosity.definition_unsupported",
f"the reference Connolly estimate needs a probe radius of at least "
f"{2 * max(widths):.3g} A (twice the smoothing width, "
f"{CONNOLLY_SMOOTHING_STEPS:g} grid steps) at every ladder level; "
"refine the ladder or plan the accessible surface",
)
)
partial = [s.id for s in structure.sites if s.occupancy < 1 or s.disorder_group]
if partial:
refusals.append(
_refusal(
"porosity.partial_occupancy",
f"sites {', '.join(partial[:8])} are partially occupied or "
"disordered; choose an ordered model first",
)
)
present = {s.symbol for s in structure.sites}
stray = sorted(set(plan.radii.overrides) - present)
if stray:
refusals.append(
_refusal(
"porosity.unknown_override",
f"radius overrides name no element of the structure: {', '.join(stray)}",
)
)
work = _work(structure, plan)
if any(level["points"] > MAX_GRID_POINTS for level in work["levels"]):
refusals.append(
_refusal(
"porosity.too_large",
f"a ladder level exceeds {MAX_GRID_POINTS} grid points; use a "
"coarser spacing or an engine",
)
)
if work["distance_evaluations"] > MAX_WORK:
refusals.append(
_refusal(
"porosity.too_large",
f"{work['distance_evaluations']} distance evaluations exceed "
f"{MAX_WORK}; coarsen the ladder or use an engine",
)
)
if work["surface_samples"] > MAX_SURFACE_SAMPLES:
refusals.append(
_refusal(
"porosity.too_large",
f"{work['surface_samples']} surface samples exceed {MAX_SURFACE_SAMPLES}",
)
)
return {
"schema": PLAN_SCHEMA,
"kind": "porosity_plan",
"label": LABEL,
"plan": plan.model_dump(mode="json"),
"source": {
"structure": structure.id,
"structure_sha256": content_digest(structure),
"pbc": list(structure.pbc),
},
"engine": {"name": plan.engine, "description": ENGINES.get(plan.engine, "unknown")},
"radius_table": _radius_table(structure, plan.radii),
"definitions": DEFINITIONS,
"work": work,
"bounds": {
"max_grid_points": MAX_GRID_POINTS,
"max_distance_evaluations": MAX_WORK,
"max_surface_samples": MAX_SURFACE_SAMPLES,
},
"runnable": not refusals,
"refusals": refusals,
"codes": CODES,
"note": NOTE,
"references": REFERENCES,
}
[docs]
def plan_document(document: Document, data: dict[str, Any]) -> dict[str, Any]:
plan = parse_plan(data)
return plan_porosity(_structure(document, plan.structure), plan)
# --- reference estimate ------------------------------------------------------------------
def _level(
structure: PeriodicStructure,
plan: PorosityPlan,
spacing: float,
radii: np.ndarray,
periodic: tuple[bool, bool, bool],
*,
full: bool,
) -> dict[str, Any]:
lattice = np.asarray(structure.lattice_angstrom, dtype=float)
frac = np.asarray([s.fractional for s in structure.sites], dtype=float)
for i in range(3):
if periodic[i]:
frac[:, i] -= np.floor(frac[:, i])
n = _grid_shape(lattice, spacing)
axes = [np.arange(n[i]) / n[i] for i in range(3)]
grid_frac = np.stack(np.meshgrid(*axes, indexing="ij"), axis=-1).reshape(-1, 3)
reach = _corner_bound(lattice) + float(radii.max() - radii.min())
centres, image_r = _images(frac, radii, lattice, _shift_range(reach, lattice, periodic))
field = _nearest_surface(grid_frac @ lattice, centres, image_r).reshape(n)
resolution = _corner_bound(lattice / np.asarray(n, dtype=float)[:, None])
probe = plan.probe.radius_angstrom
perc = _percolation(field, n, periodic, probe)
labels = perc["labels"].reshape(n)
ranks: dict[int, int] = perc["ranks"]
percolating = np.isin(labels, [r for r, k in ranks.items() if k > 0])
pockets = (labels >= 0) & ~percolating
void = field >= 0
centre_mask = field >= probe
if probe > 0:
opening = _Opening(n, lattice, periodic, probe)
occupiable = opening.covered(centre_mask, probe) & void
accessible = opening.covered(percolating, probe) & void
else:
occupiable, accessible = centre_mask, percolating
t = perc["thresholds"]
flat_max = int(np.argmax(field))
level: dict[str, Any] = {
"spacing_angstrom": spacing,
"grid_shape": list(n),
"resolution_angstrom": resolution,
"geometric_void_fraction": float(void.mean()),
"probe_centre_fraction": float(centre_mask.mean()),
"probe_occupiable_fraction": float(occupiable.mean()),
"accessible_fraction": float(accessible.mean()),
"nonaccessible_fraction": float((occupiable & ~accessible).mean()),
"di_angstrom": 2 * float(field.max()),
"di_position_fractional": [float(x) for x in grid_frac[flat_max]],
"df_angstrom": 2 * t[0] if t[0] is not None else 0.0,
"df_axes_angstrom": {
"abc"[i]: (2 * v if v is not None else 0.0)
for i, v in enumerate(perc["axis_thresholds"])
},
"thresholds_angstrom": {str(k + 1): t[k] for k in range(3)},
"dimensionality": _dimensionality(t, probe),
}
if plan.surface == "connolly":
volume = abs(float(np.linalg.det(lattice)))
total = _connolly(field, centre_mask, lattice, periodic, probe)
same = bool(np.array_equal(percolating, centre_mask))
reached = total if same else _connolly(field, percolating, lattice, periodic, probe)
level["connolly_area_angstrom2"] = total["area_angstrom2"]
level["connolly_accessible_area_angstrom2"] = reached["area_angstrom2"]
level["connolly_occupiable_fraction"] = total["occupiable_angstrom3"] / volume
level["connolly_accessible_occupiable_fraction"] = reached["occupiable_angstrom3"] / volume
level["excluded_volume_fraction"] = 1 - total["occupiable_angstrom3"] / volume
level["connolly_method"] = {
"smoothing_angstrom": total["smoothing_angstrom"],
"smoothed_area_angstrom2": total["smoothed_area_angstrom2"],
"smoothed_occupiable_angstrom3": total["smoothed_occupiable_angstrom3"],
"band_points": total["band_points"] + (0 if same else reached["band_points"]),
"stencil_offsets": total["stencil_offsets"],
}
if not full:
return level
flat_labels = labels.ravel()
roots, inverse, counts = np.unique(flat_labels, return_inverse=True, return_counts=True)
best = np.full(len(roots), -np.inf)
np.maximum.at(best, inverse, field.ravel())
components = []
for k in np.argsort(-counts, kind="stable").tolist():
root = int(roots[k])
if root < 0:
continue
rank = ranks[root]
components.append(
{
"kind": "channel" if rank else "pocket",
"dimensionality": rank,
"axes": ["abc"[i] for i in perc["axes"][root]],
"probe_centre_fraction": float(counts[k]) / len(flat_labels),
"included_diameter_angstrom": 2 * float(best[k]),
}
)
level["components"] = components[:200]
level["components_total"] = len(components)
level["_field"] = field
level["_percolating"] = percolating
level["_pockets"] = pockets
level["_void"] = void
return level
def _window(thresholds: list[float | None], probe: float, delta: float) -> dict[str, Any]:
lo, hi = max(probe - delta, 0.0), probe + delta
at = {
"minus": _dimensionality(thresholds, lo),
"probe": _dimensionality(thresholds, probe),
"plus": _dimensionality(thresholds, hi),
}
near = [k + 1 for k, t in enumerate(thresholds) if t is not None and lo - 1e-12 <= t <= hi]
return {
"delta_angstrom": delta,
"radii_angstrom": [lo, probe, hi],
"dimensionality": at,
"thresholds_in_window": near,
"uncertain": at["minus"] != at["plus"],
}
def _outcome(level: dict[str, Any], window: dict[str, Any]) -> dict[str, str]:
if window["uncertain"]:
code = "porosity.window_uncertain"
status = "uncertain"
message = (
f"channel dimensionality is {window['dimensionality']['minus']} at r - delta "
f"and {window['dimensionality']['plus']} at r + delta; not classified as "
"open or closed"
)
elif level["probe_centre_fraction"] == 0:
code, status = "porosity.zero_accessible", "zero"
message = "the probe fits nowhere in the cell (Di below the probe diameter)"
elif level["dimensionality"] == 0:
code, status = "porosity.blocked", "blocked"
message = "the probe fits only in isolated pockets; no accessible volume"
else:
code, status = "porosity.open", "open"
message = f"{level['dimensionality']}D channel system at the probe radius"
return {"status": status, "code": code, "message": message}
def _surface(
structure: PeriodicStructure,
plan: PorosityPlan,
level: dict[str, Any],
radii: np.ndarray,
periodic: tuple[bool, bool, bool],
) -> dict[str, Any]:
"""Accessible surface by random sphere sampling (seeded; Shrake and Rupley 1973)."""
lattice = np.asarray(structure.lattice_angstrom, dtype=float)
probe = plan.probe.radius_angstrom
count = plan.sampling.surface_samples_per_atom
frac = np.asarray([s.fractional for s in structure.sites], dtype=float)
for i in range(3):
if periodic[i]:
frac[:, i] -= np.floor(frac[:, i])
home = frac @ lattice
expanded = radii + probe
reach = float(expanded.max()) * 2 + 1e-6
centres, image_r = _images(frac, radii, lattice, _shift_range(reach, lattice, periodic))
rng = np.random.default_rng(plan.sampling.seed)
n = np.asarray(level["grid_shape"])
percolating = level["_percolating"].ravel()
pockets = level["_pockets"].ravel()
inverse = np.linalg.inv(lattice)
totals = {"accessible": 0.0, "nonaccessible": 0.0, "unresolved": 0.0}
for i in range(len(home)):
# Uniform directions from normalised Gaussian vectors (Muller, Commun. ACM 2, 19 (1959)).
v = rng.normal(size=(count, 3))
v /= np.linalg.norm(v, axis=1)[:, None]
points = home[i] + expanded[i] * v
free = _nearest_surface(points, centres, image_r + probe) >= -1e-9
f = points[free] @ inverse
ijk = np.rint(f * n).astype(np.int64)
hit_acc = np.zeros(len(f), dtype=bool)
hit_pocket = np.zeros(len(f), dtype=bool)
for offset in itertools.product((0, -1, 1), repeat=3):
cell = ijk + np.asarray(offset)
ok = np.ones(len(f), dtype=bool)
for k in range(3):
if periodic[k]:
cell[:, k] %= n[k]
else:
ok &= (cell[:, k] >= 0) & (cell[:, k] < n[k])
flat = np.where(ok, (cell[:, 0] * n[1] + cell[:, 1]) * n[2] + cell[:, 2], 0)
hit_acc |= ok & percolating[flat]
hit_pocket |= ok & pockets[flat]
area = 4 * math.pi * expanded[i] ** 2 / count
totals["accessible"] += area * float(hit_acc.sum())
totals["nonaccessible"] += area * float((~hit_acc & hit_pocket).sum())
totals["unresolved"] += area * float((~hit_acc & ~hit_pocket).sum())
volume = abs(float(np.linalg.det(lattice)))
mass = _cell_mass(structure)
asa = totals["accessible"]
return {
"definition": "accessible",
"accessible_area_angstrom2": asa,
"nonaccessible_area_angstrom2": totals["nonaccessible"],
"unresolved_area_angstrom2": totals["unresolved"],
"accessible_area_m2_per_cm3": asa / volume * 1e4,
"accessible_area_m2_per_g": asa * 1e-20 / mass,
"samples_per_atom": count,
"seed": plan.sampling.seed,
"note": "geometric accessible surface area; not a BET surface area",
}
def _connolly_record(level: dict[str, Any], volume: float, mass: float) -> dict[str, Any]:
"""The Connolly surface and volumes of the finest level, per cell and per mass/volume."""
area = level["connolly_area_angstrom2"]
reached = level["connolly_accessible_area_angstrom2"]
cm3_per_g = volume * 1e-24 / mass
return {
"definition": "connolly",
"connolly_area_angstrom2": area,
"connolly_area_m2_per_cm3": area / volume * 1e4,
"connolly_area_m2_per_g": area * 1e-20 / mass,
"accessible_connolly_area_angstrom2": reached,
"accessible_connolly_area_m2_per_cm3": reached / volume * 1e4,
"accessible_connolly_area_m2_per_g": reached * 1e-20 / mass,
"excluded_volume_angstrom3": level["excluded_volume_fraction"] * volume,
"excluded_volume_fraction": level["excluded_volume_fraction"],
"occupiable_fraction": level["connolly_occupiable_fraction"],
"occupiable_cm3_per_g": level["connolly_occupiable_fraction"] * cm3_per_g,
"accessible_occupiable_fraction": level["connolly_accessible_occupiable_fraction"],
"accessible_occupiable_cm3_per_g": (
level["connolly_accessible_occupiable_fraction"] * cm3_per_g
),
"method": {
**level["connolly_method"],
"estimator": "level set D = r_probe of the distance to the probe-centre region; "
"cosine-regularised delta/Heaviside, smoothing bias removed by the Steiner "
"(parallel-surface) expansion",
"grid_spacing_angstrom": level["spacing_angstrom"],
},
"note": "geometric solvent-excluded (Connolly) surface; not a BET surface area",
}
def _psd(
structure: PeriodicStructure,
plan: PorosityPlan,
level: dict[str, Any],
periodic: tuple[bool, bool, bool],
) -> dict[str, Any]:
"""Gelb-Gubbins geometric PSD: covered(D) = fraction of points inside a void sphere of
diameter >= D; each bin holds covered(D_lo) - covered(D_hi)."""
lattice = np.asarray(structure.lattice_angstrom, dtype=float)
field: np.ndarray = level["_field"]
void: np.ndarray = level["_void"]
g = level["grid_shape"]
n = (int(g[0]), int(g[1]), int(g[2]))
probe = plan.probe.radius_angstrom
settings = plan.psd
width = settings.bin_width_angstrom
start = 2 * probe if settings.region == "accessible" else 0.0
top = level["di_angstrom"]
bins = max(1, math.ceil((top - start) / width - 1e-9)) if top > start else 0
if bins > MAX_PSD_BINS:
raise PorosityRefused(
[
_refusal(
"porosity.too_large", f"{bins} PSD bins exceed {MAX_PSD_BINS}; widen the bins"
)
]
)
edges = [start + k * width for k in range(bins + 1)]
allowed = level["_percolating"] if settings.region == "accessible" else np.ones(n, bool)
covered: list[float] = []
opening = _Opening(n, lattice, periodic, edges[-1] / 2) if edges else None
for d in edges:
rho = d / 2
centres = (field >= rho) & allowed
if rho <= 0:
cov = centres & void
else:
assert opening is not None
cov = opening.covered(centres, rho) & void
covered.append(float(cov.mean()))
covered.append(0.0)
covered = [min(covered[: k + 1]) for k in range(len(covered))] # opening is monotone
region_total = covered[0] if edges else 0.0
volume = abs(float(np.linalg.det(lattice)))
cm3_per_g = volume * 1e-24 / _cell_mass(structure)
rows = []
for k in range(bins):
frac = covered[k] - covered[k + 1]
value = frac / region_total if settings.normalisation == "region_fraction" else frac
value = value if region_total > 0 else 0.0
rows.append(
{
"diameter_lo_angstrom": edges[k],
"diameter_hi_angstrom": edges[k] + width,
"diameter_mid_angstrom": edges[k] + width / 2,
"fraction": value,
"density_per_angstrom": value / width,
"volume_cm3_per_g": frac * cm3_per_g,
"cumulative_fraction": (
covered[k] / region_total
if settings.normalisation == "region_fraction" and region_total > 0
else covered[k]
),
"cumulative_cm3_per_g": covered[k] * cm3_per_g,
}
)
return {
"definition": DEFINITIONS["psd"],
"region": settings.region,
"normalisation": settings.normalisation,
"bin_width_angstrom": width,
"region_fraction_of_cell": region_total,
"units": {
"diameter": "angstrom",
"fraction": (
"fraction of the region volume per bin"
if settings.normalisation == "region_fraction"
else "fraction of the cell volume per bin"
),
"density_per_angstrom": "fraction per angstrom of diameter",
"volume_cm3_per_g": "cm3 per g of framework per bin",
"cumulative": "in pores with diameter >= the bin's lower edge",
},
"bins": rows,
}
[docs]
def analyse(structure: PeriodicStructure, plan: PorosityPlan) -> dict[str, Any]:
"""Run the reference estimate over the ladder; refuses with codes, never guesses."""
record = plan_porosity(structure, plan)
if record["refusals"]:
raise PorosityRefused(record["refusals"])
periodic = _periodic(structure, plan)
table = record["radius_table"]["radii_angstrom"]
radii = np.asarray([table[s.symbol] for s in structure.sites], dtype=float)
steps = plan.sampling.spacings_angstrom
levels = [
_level(structure, plan, s, radii, periodic, full=(k == len(steps) - 1))
for k, s in enumerate(steps)
]
final = levels[-1]
delta = max(plan.window_delta_angstrom, final["resolution_angstrom"])
thresholds = [final["thresholds_angstrom"][str(k)] for k in (1, 2, 3)]
window = _window(thresholds, plan.probe.radius_angstrom, delta)
window["requested_delta_angstrom"] = plan.window_delta_angstrom
window["raised_to_resolution"] = delta > plan.window_delta_angstrom
outcome = _outcome(final, window)
convergence: dict[str, Any] = {"assessed": len(levels) > 1, "converged": None}
if len(levels) > 1:
a, b = levels[-2], levels[-1]
tol_d = plan.sampling.tolerance_diameter_angstrom
tol_f = plan.sampling.tolerance_fraction
deltas = {
k: b[k] - a[k]
for k in (
"di_angstrom",
"df_angstrom",
"geometric_void_fraction",
"accessible_fraction",
)
}
checks = {
"di_angstrom": abs(deltas["di_angstrom"]) <= tol_d,
"df_angstrom": abs(deltas["df_angstrom"]) <= tol_d,
"geometric_void_fraction": abs(deltas["geometric_void_fraction"]) <= tol_f,
"accessible_fraction": abs(deltas["accessible_fraction"]) <= tol_f,
"dimensionality": a["dimensionality"] == b["dimensionality"],
}
if plan.surface == "connolly":
key = "connolly_area_angstrom2"
deltas[key] = b[key] - a[key]
scale = max(abs(b[key]), _EPS)
checks[key] = abs(deltas[key]) / scale <= plan.sampling.tolerance_area_relative
deltas["excluded_volume_fraction"] = (
b["excluded_volume_fraction"] - a["excluded_volume_fraction"]
)
checks["excluded_volume_fraction"] = abs(deltas["excluded_volume_fraction"]) <= tol_f
convergence.update({"deltas": deltas, "checks": checks, "converged": all(checks.values())})
notices = []
if convergence["converged"] is False:
notices.append(_refusal("porosity.not_converged", CODES["porosity.not_converged"]))
if not all(structure.pbc):
notices.append(
_refusal(
"porosity.periodicity_unsupported",
"slab_policy='cell_box': the stated cell bounds the nonperiodic "
"direction and its vacuum counts as void; fractions describe the "
"cell, not the material",
)
)
lattice = np.asarray(structure.lattice_angstrom, dtype=float)
volume = abs(float(np.linalg.det(lattice)))
mass = _cell_mass(structure)
surface: dict[str, Any] | None = None
if plan.surface == "accessible":
surface = _surface(structure, plan, final, radii, periodic)
elif plan.surface == "connolly":
surface = _connolly_record(final, volume, mass)
psd = _psd(structure, plan, final, periodic)
public = [{k: v for k, v in lv.items() if not k.startswith("_")} for lv in levels]
return {
"schema": RESULT_SCHEMA,
"kind": "porosity_estimate",
"label": LABEL,
"note": NOTE,
"engine": {"name": "reference", "description": ENGINES["reference"]},
"plan": record["plan"],
"source": record["source"],
"radius_table": record["radius_table"],
"definitions": DEFINITIONS,
"cell": {
"volume_angstrom3": volume,
"mass_g": mass,
"density_g_per_cm3": mass / (volume * 1e-24),
"periodic_axes": ["abc"[i] for i in range(3) if periodic[i]],
},
"outcome": outcome,
"window": window,
"levels": public,
"result": public[-1],
"convergence": convergence,
"surface": surface,
"psd": psd,
"notices": notices,
"references": REFERENCES,
"codes": CODES,
}
[docs]
def analyse_document(document: Document, data: dict[str, Any]) -> dict[str, Any]:
plan = parse_plan(data)
return analyse(_structure(document, plan.structure), plan)
# --- writers -----------------------------------------------------------------------------
def _check_result(result: dict[str, Any]) -> None:
if result.get("schema") != RESULT_SCHEMA or not result.get("source", {}).get(
"structure_sha256"
):
raise ValueError("not a porosity estimate with a structure digest; refusing to write")
[docs]
def psd_csv(result: dict[str, Any]) -> str:
"""PSD and cumulative data as CSV with the structure digest and definitions."""
_check_result(result)
psd = result["psd"]
plan = result["plan"]
final = result["result"]
lines = [
f"# {result['kind']} ({result['label']}); {result['note']}",
f"# structure {result['source']['structure']} sha256 "
f"{result['source']['structure_sha256']}",
f"# probe {plan['probe']['species']} radius {plan['probe']['radius_angstrom']} A; "
f"radii {result['radius_table']['name']} ({result['radius_table']['source']}, "
f"{result['radius_table']['version']})",
f"# grid {'x'.join(map(str, final['grid_shape']))} spacing "
f"{final['spacing_angstrom']} A resolution {final['resolution_angstrom']:.4f} A; "
f"outcome {result['outcome']['status']} ({result['outcome']['code']})",
f"# psd: {psd['definition']}; region {psd['region']}; normalisation "
f"{psd['normalisation']} ({psd['units']['fraction']}); cumulative "
f"{psd['units']['cumulative']}",
"diameter_lo_angstrom,diameter_hi_angstrom,diameter_mid_angstrom,fraction,"
"density_per_angstrom,volume_cm3_per_g,cumulative_fraction,cumulative_cm3_per_g",
]
for row in psd["bins"]:
lines.append(
",".join(
f"{row[k]:.6g}"
for k in (
"diameter_lo_angstrom",
"diameter_hi_angstrom",
"diameter_mid_angstrom",
"fraction",
"density_per_angstrom",
"volume_cm3_per_g",
"cumulative_fraction",
"cumulative_cm3_per_g",
)
)
)
return "\n".join(lines) + "\n"
[docs]
def viewer_fingerprint(structure: PeriodicStructure) -> str:
"""vibe-viewer's structure fingerprint recipe (SHA-256 prefix of PBC, lattice rounded to
1e-8 angstrom, and each atom's symbol, Z and Cartesian position rounded likewise)."""
import hashlib
digest = hashlib.sha256()
lattice = np.asarray(structure.lattice_angstrom, dtype=float)
digest.update(repr(tuple(bool(x) for x in structure.pbc)).encode())
digest.update(np.round(lattice, 8).tobytes())
for site in structure.sites:
digest.update(f"{site.symbol}:{ATOMIC_NUMBER[site.symbol]};".encode())
position = np.asarray(site.fractional, dtype=float) @ lattice
digest.update(np.round(position, 8).tobytes())
return digest.hexdigest()[:16]
[docs]
def handoff_record(
structure: PeriodicStructure, result: dict[str, Any], files: dict[str, str] | None = None
) -> dict[str, Any]:
"""The Viewer handoff sidecar: grid parameters, results and digests as provenance.
``files`` maps written file names (CSV, SVG) to their SHA-256. The ``viewer_request``
names the parameters of vibe-viewer's own pore grid estimate so the Viewer can redo
the analysis for 3D inspection; nothing here changes vibe-viewer.
"""
_check_result(result)
if result["source"]["structure_sha256"] != content_digest(structure):
raise ValueError("the result belongs to another version of the structure; refusing")
plan = result["plan"]
final = result["result"]
return {
"schema": HANDOFF_SCHEMA,
"kind": "porosity_handoff",
"label": LABEL,
"note": NOTE,
"structure": {
"id": structure.id,
"structure_sha256": content_digest(structure),
"viewer_fingerprint": viewer_fingerprint(structure),
"lattice_angstrom": [list(r) for r in structure.lattice_angstrom],
"pbc": list(structure.pbc),
},
"grid": {
"shape": final["grid_shape"],
"spacing_angstrom": final["spacing_angstrom"],
"resolution_angstrom": final["resolution_angstrom"],
"origin_fractional": [0.0, 0.0, 0.0],
"points": "fractional i/n along each axis, n even",
},
"viewer_request": {
"schema": "vibeviewer.pore-grid-estimate/1",
"probe_radius": plan["probe"]["radius_angstrom"],
"spacing": final["spacing_angstrom"],
"radii": plan["radii"]["name"],
"radius_overrides": plan["radii"]["overrides"],
},
"plan": plan,
"radius_table": result["radius_table"],
"outcome": result["outcome"],
"window": result["window"],
"result": final,
"convergence": result["convergence"],
"surface": result["surface"],
"files": dict(sorted((files or {}).items())),
"references": result["references"],
}