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
Diand largest free sphereDffollow Willems, Rycroft, Kazi, Meza and Haranczyk, Microporous Mesoporous Mater. 149, 134-141 (2012), doi:10.1016/j.micromeso.2011.08.020 (the Zeo++ definitions). HereDfis 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_probeof the distanceDto the probe-centre regionC(Cdilated 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
Grid points one ladder level may sample. |
|
Point-image distance evaluations one analysis may make (all levels). |
|
Surface samples one analysis may draw. |
|
Band-point x stencil-offset distance evaluations one Connolly region may make. |
|
Smoothing half-width of the Connolly delta/Heaviside functions, in grid steps. |
|
Engines named in plans. |
|
Stable refusal and outcome codes. |
Functions
|
Run the reference estimate over the ladder; refuses with codes, never guesses. |
|
|
|
The Viewer handoff sidecar: grid parameters, results and digests as provenance. |
|
A validated plan (raises pydantic.ValidationError). |
|
|
|
The planning record: the stated plan, radius table, grid ladder, work and refusals. |
|
PSD and cumulative data as CSV with the structure digest and definitions. |
|
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
|
Everything a geometric pore analysis depends on, stated. |
|
The probe: a species label as given and its hard-sphere radius. |
|
Pore-size distribution binning, region and normalisation. |
|
The atom radii: RDKit's van der Waals or covalent table, as in guest loading (#203). |
|
The grid as a convergence ladder of spacings (coarse to fine) and the tolerances. |
Exceptions
|
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
referenceruns 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:
ValueErrorA plan, analysis or writer refused with stable codes.
- class vibesketcher.document.porosity.Probe(*, species, radius_angstrom, radius_source=None)[source]¶
Bases:
_ModelThe probe: a species label as given and its hard-sphere radius.
- Parameters:
- 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:
_ModelThe atom radii: RDKit’s van der Waals or covalent table, as in guest loading (#203).
- Parameters:
- name: Literal['vdw', 'covalent']¶
- 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:
_ModelThe 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)])
- tolerance_area_relative: float¶
Relative tolerance of the Connolly surface area between the two finest levels.
- 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:
_ModelPore-size distribution binning, region and normalisation.
- Parameters:
- 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:
_ModelEverything a geometric pore analysis depends on, stated.
- Parameters:
structure (Annotated[str, MinLen(min_length=1), MaxLen(max_length=64)])
engine (Annotated[str, MinLen(min_length=1), MaxLen(max_length=40)])
probe (Probe)
radii (RadiusTable)
surface (Literal['accessible', 'connolly', 'none'])
sampling (Sampling)
window_delta_angstrom (Annotated[float, Ge(ge=0), Le(le=2), AllowInfNan(allow_inf_nan=False)])
psd (PsdSettings)
slab_policy (Literal['refuse', 'cell_box'])
- radii: RadiusTable¶
- surface: Literal['accessible', 'connolly', 'none']¶
- 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), orcell_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:
- Return type:
- vibesketcher.document.porosity.plan_porosity(structure, plan)[source]¶
The planning record: the stated plan, radius table, grid ladder, work and refusals.
- Parameters:
structure (PeriodicStructure)
plan (PorosityPlan)
- Return type:
- vibesketcher.document.porosity.analyse(structure, plan)[source]¶
Run the reference estimate over the ladder; refuses with codes, never guesses.
- Parameters:
structure (PeriodicStructure)
plan (PorosityPlan)
- Return type:
- vibesketcher.document.porosity.psd_csv(result)[source]¶
PSD and cumulative data as CSV with the structure digest and definitions.
- 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:
- vibesketcher.document.porosity.handoff_record(structure, result, files=None)[source]¶
The Viewer handoff sidecar: grid parameters, results and digests as provenance.
filesmaps written file names (CSV, SVG) to their SHA-256. Theviewer_requestnames 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.