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"], }