vibe-sketcherDocumentation

Porosity plans

The sketcher can plan a geometric pore analysis of a periodic structure and run a small reference estimate of it. A plan states every choice the result depends on. The estimate is a geometric planning estimate on a sampled grid. Geometric void is not adsorption capacity, and neither the accessible nor the Connolly surface area is a BET surface area. An estimate can be stored on its structure and written as a publication table. Calculation engines own production porosity, and the 3D inspection of pores and surfaces belongs in vibe-viewer.

Plans

A plan is a JSON object:

Field

Meaning

structure

The periodic structure ID in the document.

probe

species (a label kept as given), radius_angstrom (required, 0 to 10) and an optional radius_source.

radii

name: vdw (RDKit’s van der Waals radii, the default) or covalent (RDKit’s covalent radii), and per-element overrides in angstrom. These are the tables guest loading uses.

surface

accessible (the default), connolly or none.

sampling

spacings_angstrom: a grid-spacing ladder from coarse to fine (default [0.4, 0.2]), tolerance_diameter_angstrom (0.1), tolerance_fraction (0.01), tolerance_area_relative (0.03, for the Connolly area), surface_samples_per_atom (400) and seed (0).

window_delta_angstrom

The window-sensitivity delta (0.1). It is raised to the grid resolution when smaller.

psd

bin_width_angstrom (0.2), region (total or accessible) and normalisation (cell_fraction or region_fraction).

engine

reference (the default). Any other engine is refused here.

slab_policy

refuse (the default) or cell_box for a structure that is not 3D periodic.

The planning record repeats the plan and adds the radius table with its name, source, RDKit version and the radius used for each element. It also gives the definitions, the grid shape of each ladder level, the work against the bounds, the structure digest and any refusals. Nothing in the document changes.

Refusals

Code

Reason

porosity.periodicity_unsupported

The structure is not 3D periodic and no slab policy was stated.

porosity.engine_unavailable

The plan names an engine other than reference. Zeo++, PoreBlazer and the RASPA geometric tools are candidates only, pending dependency, executable and licence review.

porosity.definition_unsupported

A Connolly plan whose probe radius is below twice the smoothing width at some ladder level, which is four grid steps. Refine the ladder or plan the accessible surface.

porosity.partial_occupancy

Partially occupied or disordered sites have no single geometry.

porosity.unknown_override

A radius override names no element of the structure.

porosity.too_large

A ladder level exceeds 262144 grid points, the distance work exceeds 150 million evaluations, the surface exceeds 200000 samples or the PSD exceeds 200 bins.

With slab_policy set to cell_box, the stated cell bounds each nonperiodic direction. No images, grid connections or windings cross its faces, and any vacuum inside the cell counts as void. The result then carries a notice that its fractions describe the cell, not the material.

Definitions

The distance field d(x) is the distance from a point to the nearest atom surface, the minimum of distance(x, atom) - r_atom over every atom and lattice image. The volume definitions follow Ongari et al.:

Quantity

Definition

Geometric void fraction

Fraction of the cell with d >= 0: a zero-radius probe. This is the total pore volume.

Probe-centre fraction

Fraction where a probe centre fits, d >= r_probe.

Probe-occupiable fraction

Fraction covered by probe spheres centred where they fit.

Accessible fraction

Probe-occupiable fraction of the components that percolate. This is the accessible pore volume.

Non-accessible fraction

Probe-occupiable fraction of isolated pockets.

The largest included sphere Di is 2 max d, and the largest free sphere Df is 2 t, where t is the largest threshold at which d >= t percolates. Both follow Willems et al. (the Zeo++ terms). Df is also given along each lattice axis.

Channel dimensionality comes from the periodic connectivity of the grid points where the probe centre fits. Grid points are joined to their six face neighbours with a union-find on the torus, and each union carries an integer lattice offset. A closed loop whose offsets do not cancel is a winding. The rank of the windings of a component is its dimensionality: 0 for a pocket and 1 to 3 for a channel system. Points are added in order of decreasing d, so one pass gives the threshold t_k at which a k-dimensional channel first appears.

The accessible surface is the probe-centre surface of Lee and Richards. Each atom carries a sphere of radius r_atom + r_probe, sampled at uniformly random points from the stated seed, as in Shrake and Rupley. A point counts when no other expanded sphere contains it and the probe centre there lies in a percolating component, as Duren et al. apply it to frameworks. Areas are given per cell in square angstrom, in m²/cm³ and in m²/g, using RDKit’s standard atomic weights. Surface points in pockets are reported as non-accessible area. The Connolly surface can be planned but is not computed by the reference engine.

The pore-size distribution is the geometric one of Gelb and Gubbins. Each void point gets the diameter of the largest void sphere that contains it. The covered fraction for each bin edge comes from opening the void with a ball, a periodic FFT convolution on the grid. Each bin holds the fraction in pores between its edges, its density per angstrom of diameter, its volume in cm³ per gram, and the cumulative fraction and volume in pores of at least the lower edge. With region set to accessible, spheres are centred in percolating components only and the bins start at the probe diameter. The normalisation is the fraction of the cell volume or of the region’s volume.

Connolly surface

With surface set to connolly, the reference engine computes the solvent-excluded surface of Connolly, Richards’ molecular surface. It is the boundary of the region that probe spheres can occupy. It has contact patches on the atoms and re-entrant patches on the probe where the probe touches two or more atoms. The result gives:

Field

Meaning

connolly_area_angstrom2, _m2_per_cm3, _m2_per_g

The total Connolly surface, over every probe-centre component.

accessible_connolly_area_angstrom2, _m2_per_cm3, _m2_per_g

The Connolly surface of the percolating components alone.

excluded_volume_angstrom3, excluded_volume_fraction

The volume inside the Connolly surface: the atoms and the crevices no probe reaches.

occupiable_fraction, occupiable_cm3_per_g

The probe-occupiable (Connolly) pore volume.

accessible_occupiable_fraction, accessible_occupiable_cm3_per_g

The same over the percolating components.

method

The smoothing width, the smoothed values before the bias correction, the band points and the stencil size.

The probe-occupiable region is the set of points within r_probe of the probe-centre region C. Its boundary is the level set D = r_probe of the distance D to C. The clearance of a probe-centre point c is exact, m(c) = d(c) - r_probe, because the distance to a union of spheres from outside is the smallest distance to one of them. So the ball of radius m(c) about c lies in C, and D(x) is the minimum of distance(x, c) - m(c) over the grid points c of C. That minimum is constant along the inward normal, so the grid gives D without staircase error, accurate to second order in the grid spacing. The minimum runs over a stencil of grid offsets in a narrow band around the surface.

The area and the volume come from regularised delta and Heaviside functions of D - r_probe with a cosine kernel of half-width eps, two grid steps (Engquist, Tornberg and Tsai). Smoothing biases the area by sigma2 / 2 A''(s) and the volume by sigma2 / 2 A'(s), where A(s) is the area of the parallel surface D = s and sigma2 the kernel’s second moment. Both are removed with central differences of the smoothed area at r_probe +/- eps, the Steiner expansion of a parallel-surface family. The correction is exact for a sphere, whose area is quadratic in s. Because the kernel needs r_probe - 2 eps >= 0, a probe smaller than four grid steps is refused.

Every ladder level gives the Connolly area and the excluded volume fraction. The two finest levels are compared, the area against tolerance_area_relative and the excluded fraction against tolerance_fraction. The estimate is checked against closed forms. For one sphere in a box, the Connolly surface is the atom’s sphere and the excluded volume its ball, both within 1.5 % at a 0.2 Å grid. For two touching spheres, two contact caps are joined by a re-entrant torus patch. Pappus’ theorem gives its area, and the volume is the integral of the same profile. The estimate is within 2 % and 3 % of these at a 0.2 Å grid, and the area lies between the caps alone and two whole spheres.

Window sensitivity and outcomes

A pore window close to the probe radius is not called open or closed. The dimensionality is evaluated again at r_probe - delta and r_probe + delta, and the outcome is:

Status

Code

Meaning

uncertain

porosity.window_uncertain

The dimensionality changes inside the window, so a threshold lies within delta of the probe radius.

zero

porosity.zero_accessible

The probe fits nowhere in the cell.

blocked

porosity.blocked

The probe fits only in isolated pockets.

open

porosity.open

The probe percolates throughout the window.

The window record lists which thresholds lie inside it, the delta used and whether it was raised to the grid resolution.

Grid and convergence

The grid samples each axis at points i/n, with n the length over the spacing rounded up to an even number, so the cell’s half points are always included. The resolution h is the grid’s covering radius. d changes by at most the distance moved, so a sampled maximum is within h of the continuum value. Every ladder level is reported, and the two finest levels are compared for Di, Df, the void fraction, the accessible fraction and the dimensionality. A difference beyond the tolerances adds the notice porosity.not_converged. The surface and the PSD come from the finest level.

The reference estimate is checked against closed forms. A single sphere in a cubic box gives its void fraction, Di, Df and surface area. A simple cubic lattice gives Di = a sqrt(3) - 2r and Df = a sqrt(2) - 2r. Rods along one axis give a 1D channel, and closed walls give a cage. A probe radius equal to the simple cubic window radius a / sqrt(2) - r gives the uncertain outcome.

Files and the Viewer handoff

The PSD CSV starts with comment lines that name the structure and its SHA-256 digest, the probe, the radius table and its version, the grid, the outcome and the PSD definition, region, normalisation and units. The figure draws the PSD as bars with the cumulative curve on the right axis and the same provenance in its footer. A distribution with no volume is refused (porosity.empty_distribution), never drawn empty. Figures are SVG, or PDF and PNG through the publication extra.

The Viewer handoff is a sidecar JSON record. It carries the structure ID and digest, the lattice, the fingerprint that vibe-viewer computes for the same Cartesian positions, the grid shape, spacing and resolution, the plan, the outcome, the window, the finest-level result, the convergence and the surface. A viewer_request holds the probe radius, spacing and radius table that vibe-viewer’s own pore grid estimate takes, so the Viewer can recompute the field for 3D inspection. The written files are listed with their SHA-256 digests. A handoff for a structure that has changed since the estimate is refused.

Stored estimates

An estimate can be stored on its structure as one edit, checked against the document revision. It goes into the structure’s provenance under porosity, schema vibesketcher.porosity-store/1. Each record has an id (porosity-N unless stated), the structure digest, the revision it was based on, the probe, the surface definition, the outcome and the full estimate. The digest leaves provenance out, so storing changes no digest. Up to 16 estimates can be stored on one structure.

When the structure changes after an estimate was stored, the estimate is stale. The list of stored estimates marks each record stale or current and gives the current digest. Undo removes the last stored estimate, and it is refused once the structure has changed. A stale estimate is never written as a table.

Code

Reason

porosity.revision_conflict

The edit is based on another document revision.

porosity.stale_estimate

The estimate belongs to another version of the structure.

porosity.nothing_to_undo

Undo found no stored estimate.

porosity.no_estimate

A table or a lookup found no stored estimate.

Stored estimates travel with the document, in the .vsk file and in the QVF document section. QVF has no porosity contract, so the QVF writers also add a non-critical vendor section x_vibesketch.porosity. It holds every stored estimate with its structure digest, for a reader that does not know the sketch format. Overwriting a native sketch QVF that holds the section is allowed, since the section is rebuilt from the sketch.

Publication tables

The publication table of a current stored estimate lists Di, Df, the channel dimensionality, the outcome, the void, probe-occupiable and accessible fractions, the accessible pore volume, the accessible or Connolly surface area per cell, per volume and per mass, the excluded volume fraction, the Connolly pore volume, the framework density and whether the ladder converged. Each row has the quantity, symbol, value and unit. Every table carries the label “geometric planning estimate, not BET/adsorption capacity”, the structure digest, the probe, the radius table with its version, the engine, the grid and the seed. Tables are CSV (full precision), SVG and LaTeX (a plain table float with tabular).

SDK

from vibesketcher.document.porosity import analyse, handoff_record, parse_plan, psd_csv
from vibesketcher.render.porosity import psd_figure

plan = parse_plan(
    {
        "structure": "mof",
        "probe": {"species": "N2", "radius_angstrom": 1.82},
        "sampling": {"spacings_angstrom": [0.4, 0.2], "seed": 1},
    }
)
result = analyse(structure, plan)
text = psd_csv(result)
svg = psd_figure(result)
record = handoff_record(structure, result, {"mof-psd.csv": "<sha256>"})

plan_porosity(structure, plan) returns the planning record without running, and plan_document and analyse_document take a document and the plan as JSON.

from vibesketcher.document import porosity_store
from vibesketcher.render.porosity_table import table

document, record = porosity_store.store(document, result, revision=document.revision)
structure = document.periodic_structures[0]
porosity_store.stored(structure)  # every record, marked stale or current
tex = table(porosity_store.fresh(structure), "tex")
document = porosity_store.undo(document, "mof")

porosity_store.from_qvf(data) reads the x_vibesketch.porosity section of a QVF archive.

CLI

vibe-sketcher solid porosity-plan mof.vsk --structure mof \
    --probe-radius 1.82 --probe-species N2 --spacing 0.4,0.2
vibe-sketcher solid porosity mof.vsk --structure mof --probe-radius 1.82 \
    --probe-species N2 --csv psd.csv --figure psd.svg --handoff mof-pores.json

--plan reads the whole plan from a JSON file, and the options override it. solid porosity-plan prints the planning record as JSON. solid porosity prints the main results, --json the full estimate and -o writes it to a file. The handoff lists the files written with it. A refusal exits with status 3.

vibe-sketcher solid porosity-store mof.vsk --structure mof --probe-radius 1.82 \
    --probe-species N2 --surface connolly --spacing 0.4,0.2 --estimate-id n2
vibe-sketcher solid porosity-stored mof.vsk --structure mof
vibe-sketcher solid porosity-table mof.vsk --structure mof -o mof-pores.tex
vibe-sketcher solid porosity-undo mof.vsk --structure mof

solid porosity-store takes the plan options of solid porosity and saves the document (or -o) with the estimate stored. solid porosity-table writes .csv, .svg or .tex, or CSV to standard output.

REST and MCP

Route

Purpose

POST /api/documents/{id}/porosity/plan

{plan}: the planning record.

POST /api/documents/{id}/porosity/estimate

{plan}: the reference estimate.

POST /api/documents/{id}/porosity/psd-csv

{plan}: the PSD CSV.

POST /api/documents/{id}/porosity/psd-figure

{plan, options, format, dpi}: the PSD figure.

POST /api/documents/{id}/porosity/handoff

{plan, files}: the Viewer handoff record.

| POST /api/documents/{id}/porosity/store | {revision, plan, estimate_id}: run the estimate and store it. | | POST /api/documents/{id}/porosity/undo | {revision, structure}: remove the last stored estimate. | | GET /api/documents/{id}/porosity/stored/{structure} | The stored estimates without payloads, marked stale or current. | | GET /api/documents/{id}/porosity/stored/{structure}/{estimate} | One stored estimate with its payload. | | GET /api/documents/{id}/porosity/table/{structure}?estimate=&format= | The publication table, csv, svg or tex. |

Only store and undo change the document, as one recorded edit each. Refusals return 422 with errors and their codes. A revision conflict or a stale estimate returns 409, and a structure without stored estimates 404. The MCP tools plan_porosity, estimate_porosity, porosity_psd_figure, porosity_handoff, store_porosity_estimate (with undo), list_porosity_estimates and porosity_table call them.

Not covered yet

Running Zeo++ or another engine, Voronoi networks, a QVF exchange contract for porosity results beyond the vendor section, Connolly surfaces for probes smaller than four grid steps and placing the tables and figures in a publication report are open. vibe-qc and QVF define no porosity contract yet. The Viewer does not read the handoff record or the vendor section yet.

References