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 |
|---|---|
|
The periodic structure ID in the document. |
|
|
|
|
|
|
|
|
|
The window-sensitivity delta (0.1). It is raised to the grid resolution when smaller. |
|
|
|
|
|
|
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 |
|---|---|
|
The structure is not 3D periodic and no slab policy was stated. |
|
The plan names an engine other than |
|
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. |
|
Partially occupied or disordered sites have no single geometry. |
|
A radius override names no element of the structure. |
|
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 |
Probe-centre fraction |
Fraction where a probe centre fits, |
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 |
|---|---|
|
The total Connolly surface, over every probe-centre component. |
|
The Connolly surface of the percolating components alone. |
|
The volume inside the Connolly surface: the atoms and the crevices no probe reaches. |
|
The probe-occupiable (Connolly) pore volume. |
|
The same over the percolating components. |
|
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 |
|---|---|---|
|
|
The dimensionality changes inside the window, so a threshold lies within delta of the probe radius. |
|
|
The probe fits nowhere in the cell. |
|
|
The probe fits only in isolated pockets. |
|
|
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 |
|---|---|
|
The edit is based on another document revision. |
|
The estimate belongs to another version of the structure. |
|
Undo found no stored 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/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¶
T. F. Willems, C. H. Rycroft, M. Kazi, J. C. Meza and M. Haranczyk, Microporous Mesoporous Mater. 149, 134 (2012), doi:10.1016/j.micromeso.2011.08.020. The largest included and free sphere.
D. Ongari, P. G. Boyd, S. Barthel, M. Witman, M. Haranczyk and B. Smit, Langmuir 33, 14529 (2017), doi:10.1021/acs.langmuir.7b01682. The volume definitions.
J. Hoshen and R. Kopelman, Phys. Rev. B 14, 3438 (1976), doi:10.1103/PhysRevB.14.3438. Cluster labelling.
L. D. Gelb and K. E. Gubbins, Langmuir 15, 305 (1999), doi:10.1021/la9808418. The geometric pore-size distribution.
B. Lee and F. M. Richards, J. Mol. Biol. 55, 379 (1971), doi:10.1016/0022-2836(71)90324-X. The accessible surface.
A. Shrake and J. A. Rupley, J. Mol. Biol. 79, 351 (1973), doi:10.1016/0022-2836(73)90011-9. Surface sampling.
T. Duren, F. Millange, G. Ferey, K. S. Walton and R. Q. Snurr, J. Phys. Chem. C 111, 15350 (2007), doi:10.1021/jp074723h. Accessible surface areas of frameworks.
M. L. Connolly, J. Appl. Cryst. 16, 548 (1983), doi:10.1107/S0021889883010985. The molecular surface.
F. M. Richards, Annu. Rev. Biophys. Bioeng. 6, 151 (1977), doi:10.1146/annurev.bb.06.060177.001055. The molecular (solvent-excluded) surface and its contact and re-entrant parts.
B. Engquist, A.-K. Tornberg and R. Tsai, J. Comput. Phys. 207, 28 (2005), doi:10.1016/j.jcp.2004.09.018. Regularised delta functions on grids.