vibe-sketcherDocumentation

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. 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 _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.

Module Attributes

MAX_GRID_POINTS

Grid points one ladder level may sample.

MAX_WORK

Point-image distance evaluations one analysis may make (all levels).

MAX_SURFACE_SAMPLES

Surface samples one analysis may draw.

MAX_CONNOLLY_WORK

Band-point x stencil-offset distance evaluations one Connolly region may make.

CONNOLLY_SMOOTHING_STEPS

Smoothing half-width of the Connolly delta/Heaviside functions, in grid steps.

ENGINES

Engines named in plans.

CODES

Stable refusal and outcome codes.

Functions

analyse(structure, plan)

Run the reference estimate over the ladder; refuses with codes, never guesses.

analyse_document(document, data)

handoff_record(structure, result[, files])

The Viewer handoff sidecar: grid parameters, results and digests as provenance.

parse_plan(data)

A validated plan (raises pydantic.ValidationError).

plan_document(document, data)

plan_porosity(structure, plan)

The planning record: the stated plan, radius table, grid ladder, work and refusals.

psd_csv(result)

PSD and cumulative data as CSV with the structure digest and definitions.

viewer_fingerprint(structure)

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).

Classes

PorosityPlan(*, structure[, engine, radii, ...])

Everything a geometric pore analysis depends on, stated.

Probe(*, species, radius_angstrom[, ...])

The probe: a species label as given and its hard-sphere radius.

PsdSettings(*[, bin_width_angstrom, region, ...])

Pore-size distribution binning, region and normalisation.

RadiusTable(*[, name, overrides])

The atom radii: RDKit's van der Waals or covalent table, as in guest loading (#203).

Sampling(*[, spacings_angstrom, ...])

The grid as a convergence ladder of spacings (coarse to fine) and the tolerances.

Exceptions

PorosityRefused(refusals)

A plan, analysis or writer refused with stable codes.

vibesketcher.document.porosity.MAX_GRID_POINTS = 262144

Grid points one ladder level may sample.

vibesketcher.document.porosity.MAX_WORK = 150000000

Point-image distance evaluations one analysis may make (all levels).

vibesketcher.document.porosity.MAX_SURFACE_SAMPLES = 200000

Surface samples one analysis may draw.

vibesketcher.document.porosity.MAX_CONNOLLY_WORK = 250000000

Band-point x stencil-offset distance evaluations one Connolly region may make.

vibesketcher.document.porosity.CONNOLLY_SMOOTHING_STEPS = 2.0

Smoothing half-width of the Connolly delta/Heaviside functions, in grid steps.

vibesketcher.document.porosity.ENGINES: dict[str, str] = {'poreblazer': 'PoreBlazer: candidate only, pending dependency and licence review', 'raspa': 'RASPA geometric tools: candidate only, pending dependency and licence review', 'reference': 'vibe-sketcher reference grid estimate (pure numpy, bounded)', 'zeopp': 'Zeo++: candidate only, pending dependency, executable and licence review'}

Engines named in plans. Only reference runs here.

vibesketcher.document.porosity.CODES: dict[str, str] = {'porosity.blocked': 'the probe fits only in isolated pockets (no percolating channel)', 'porosity.definition_unsupported': 'the engine does not compute the planned definition', 'porosity.empty_distribution': 'the pore-size distribution has no volume to draw', 'porosity.engine_unavailable': 'the named engine is not available here', 'porosity.no_estimate': 'the structure holds no stored porosity estimate', 'porosity.not_converged': 'the two finest ladder levels differ beyond the tolerances', 'porosity.nothing_to_undo': 'no stored porosity estimate to remove', 'porosity.open': 'the probe percolates robustly within the window delta', 'porosity.partial_occupancy': 'partially occupied sites have no single geometry', 'porosity.periodicity_unsupported': 'the structure is not 3D periodic and no slab policy was stated', 'porosity.revision_conflict': 'the document changed since the revision the edit is based on', 'porosity.stale_estimate': 'the stored estimate belongs to another version of the structure', 'porosity.too_large': 'the grid, image or surface work exceeds the bound', 'porosity.unknown_override': 'a radius override names no element of the structure', 'porosity.window_uncertain': 'a percolation threshold lies within the window delta of the probe radius; open/closed is not decided', 'porosity.zero_accessible': 'the probe fits nowhere in the cell'}

Stable refusal and outcome codes.

exception vibesketcher.document.porosity.PorosityRefused(refusals)[source]

Bases: ValueError

A plan, analysis or writer refused with stable codes.

Parameters:

refusals (list[dict[str, str]])

Return type:

None

class vibesketcher.document.porosity.Probe(*, species, radius_angstrom, radius_source=None)[source]

Bases: _Model

The probe: a species label as given and its hard-sphere radius.

Parameters:
  • species (Annotated[str, MinLen(min_length=1), MaxLen(max_length=40)])

  • radius_angstrom (Annotated[float, Ge(ge=0), Le(le=10), AllowInfNan(allow_inf_nan=False)])

  • radius_source (Annotated[str | None, MaxLen(max_length=300)])

species: str
radius_angstrom: float
radius_source: str | None

Where the radius comes from (e.g. a kinetic diameter source), kept as given.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketcher.document.porosity.RadiusTable(*, name='vdw', overrides=<factory>)[source]

Bases: _Model

The atom radii: RDKit’s van der Waals or covalent table, as in guest loading (#203).

Parameters:
name: Literal['vdw', 'covalent']
overrides: dict[str, float]
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketcher.document.porosity.Sampling(*, spacings_angstrom=<factory>, tolerance_diameter_angstrom=0.1, tolerance_fraction=0.01, surface_samples_per_atom=400, tolerance_area_relative=0.03, seed=0)[source]

Bases: _Model

The grid as a convergence ladder of spacings (coarse to fine) and the tolerances.

Parameters:
  • spacings_angstrom (Annotated[list[float], MinLen(min_length=1), MaxLen(max_length=4)])

  • tolerance_diameter_angstrom (Annotated[float, Gt(gt=0), Le(le=5), AllowInfNan(allow_inf_nan=False)])

  • tolerance_fraction (Annotated[float, Gt(gt=0), Le(le=1), AllowInfNan(allow_inf_nan=False)])

  • surface_samples_per_atom (Annotated[int, Ge(ge=0), Le(le=20000)])

  • tolerance_area_relative (Annotated[float, Gt(gt=0), Le(le=1), AllowInfNan(allow_inf_nan=False)])

  • seed (Annotated[int, Ge(ge=0), Lt(lt=9223372036854775808)])

spacings_angstrom: list[float]
tolerance_diameter_angstrom: float
tolerance_fraction: float
surface_samples_per_atom: int
tolerance_area_relative: float

Relative tolerance of the Connolly surface area between the two finest levels.

seed: int
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketcher.document.porosity.PsdSettings(*, bin_width_angstrom=0.2, region='total', normalisation='cell_fraction')[source]

Bases: _Model

Pore-size distribution binning, region and normalisation.

Parameters:
  • bin_width_angstrom (Annotated[float, Ge(ge=0.02), Le(le=5), AllowInfNan(allow_inf_nan=False)])

  • region (Literal['total', 'accessible'])

  • normalisation (Literal['cell_fraction', 'region_fraction'])

bin_width_angstrom: float
region: Literal['total', 'accessible']

the whole geometric void; accessible: spheres centred in percolating probe-centre components, from the probe diameter up.

Type:

total

normalisation: Literal['cell_fraction', 'region_fraction']

fraction of the cell volume per bin; region_fraction: fraction of the region’s volume (bins sum to 1).

Type:

cell_fraction

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketcher.document.porosity.PorosityPlan(*, structure, engine='reference', probe, radii=<factory>, surface='accessible', sampling=<factory>, window_delta_angstrom=0.1, psd=<factory>, slab_policy='refuse')[source]

Bases: _Model

Everything a geometric pore analysis depends on, stated.

Parameters:
structure: str
engine: str
probe: Probe
radii: RadiusTable
surface: Literal['accessible', 'connolly', 'none']
sampling: Sampling
window_delta_angstrom: float

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.

psd: PsdSettings
slab_policy: Literal['refuse', 'cell_box']

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).

Type:

For a structure that is not 3D periodic

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

vibesketcher.document.porosity.parse_plan(data)[source]

A validated plan (raises pydantic.ValidationError).

Parameters:

data (dict[str, Any])

Return type:

PorosityPlan

vibesketcher.document.porosity.plan_porosity(structure, plan)[source]

The planning record: the stated plan, radius table, grid ladder, work and refusals.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.porosity.plan_document(document, data)[source]
Parameters:
Return type:

dict[str, Any]

vibesketcher.document.porosity.analyse(structure, plan)[source]

Run the reference estimate over the ladder; refuses with codes, never guesses.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.porosity.analyse_document(document, data)[source]
Parameters:
Return type:

dict[str, Any]

vibesketcher.document.porosity.psd_csv(result)[source]

PSD and cumulative data as CSV with the structure digest and definitions.

Parameters:

result (dict[str, Any])

Return type:

str

vibesketcher.document.porosity.viewer_fingerprint(structure)[source]

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).

Parameters:

structure (PeriodicStructure)

Return type:

str

vibesketcher.document.porosity.handoff_record(structure, result, files=None)[source]

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.

Parameters:
Return type:

dict[str, Any]