vibe-sketcherDocumentation

Porous and negative-curvature carbon models

kind: "porous_carbon" builds a carbon sheet from a named generating net and the periodic surface around it. The result is a geometric model, unrelaxed, not a stable material. Every built structure and every report carries that status. Relaxing the model, or validating it with an ML potential, is a separate periodic job, and neither run is proof that the material can be made or is stable.

The model plan

A model plan states everything the model depends on: the generating net, the surface between its two labyrinths, the cell, the sheet construction and its parameters, the termination and the seed of any stochastic step. solid porous-carbon-models (CLI), GET /api/periodic/porous-carbon-models (REST) and porous_carbon_models (MCP) list the constructions.

Construction

State

Net

Surface

Sheet

truncated_mucube

built

pcu

Schwarz P, as the skew polyhedron {4,6|4}

6.8.8: a hexagon per polyhedron vertex, an octagon per square

d_surface_on_dia

planned

dia

Schwarz D, {6,6|3}

needs a reviewed 6/7/8-ring decoration

tpms_remeshing

planned

any

a nodal minimal surface

needs a cited, bounded remeshing algorithm

zeolite_templated

planned

a zeolite framework

pore walls

needs licensed framework data

A planned construction, a net outside the catalogue of Reticular frameworks, a layer net and any termination other than none are refused with stable codes.

The truncated mucube

The unit cubes of a cubic grid with period 2 are split in two. A cube is on the net when at most one of its indices is odd: a node cube on each pcu vertex and an arm cube on each pcu edge. The squares between the two sets form the regular skew polyhedron {4,6|4}, the mucube (Coxeter, Proc. London Math. Soc. s2-43, 33, 1937). Six squares meet at every grid point, and the polyhedron is a discrete form of Schwarz’s P surface around the net.

Truncating every six-valent vertex to a hexagon turns each square into an octagon. Each carbon then lies on one 6-ring and two 8-rings, the vertex symbol 6.8.8. Carbon sheets of negative Gaussian curvature on periodic minimal surfaces (schwarzites) were proposed by Mackay and Terrones (Nature 352, 762, 1991) and Lenosky, Gonze, Teter and Elser (Nature 355, 333, 1992). The builder does not claim to reproduce the coordinates of any published structure.

The carbon for grid point v and edge direction e sits at a v + rho u. Here u is e projected onto the tangent plane of the P nodal surface at v (von Schnering and Nesper, Z. Phys. B 83, 407, 1991). The six projections are 60 degrees apart, so each hexagon is planar and regular with bond rho. The grid edge is a = edge + 4 rho / sqrt(6), so the bond along every polyhedron edge has the length edge.

Field

Default

Meaning

net

pcu

generating net

construction

truncated_mucube

construction from the model plan

bond_length

1.42 Å

hexagon bond and hexagon radius, 1.2 to 1.7 Å

edge_bond_length

bond_length

bond joining two hexagons

bond_tolerance

0.15 Å

largest bond misfit before a refusal

repeat

[1, 1, 1]

generating cells along each axis, 1 to 3

vacancies

0

carbons removed, at most a quarter of the cell less one, and 32

stone_wales

0

Stone–Wales bond rotations, at most 16 and no two sharing an atom or ring

stone_wales_bond

edge

which bonds rotate: edge (between two octagons) or ring (hexagon–octagon)

seed

0

seed of the vacancy choice (NumPy default_rng(seed)) and of the rotated bonds (default_rng([seed, 1]))

min_distance

1.8 Å

closest allowed contact between carbons that are not bonded

max_ring_size

12

bound of the ring search

termination

none

the only value: no hydrogen or other cap is ever added

One generating cell holds 48 carbons in a cubic cell of edge 2a, 7.48 Å at the default bond. The largest model has 1296 carbons.

Checks

The builder computes the topology and does not assume it.

  • Closed sheet. The construction faces, a hexagon per polyhedron vertex and an octagon per square, must be cycles of the bond graph. Every bond must lie on exactly two faces, and the faces must be consistently oriented.

  • Euler characteristic and genus. chi = V - E + F per cell and genus = 1 - chi/2. One generating cell has V 48, E 72, F 20 (8 hexagons, 12 octagons), so chi is -4 and the genus 3. The genus must equal the cycle rank of the generating net’s quotient graph, E - V + 1 (3 for pcu, and 2 R + 1 for R repeated cells).

  • Curvature count. For a 3-connected sheet, 3V = 2E turns Euler’s relation into “the sum over faces of 6 - n is 6 chi”, the count Mackay and Terrones and Lenosky et al. use for schwarzites.

  • Rings. Independently of the construction, the smallest ring at every bond angle (the vertex symbol of O’Keeffe and Hyde, Zeolites 19, 370, 1997) is searched in the periodic lift up to max_ring_size atoms. The distinct rings are counted once per cell; * marks an angle with no ring within the bound.

  • Coordination. Every carbon that is not 3-coordinate is flagged (coordination.not_three). Hybridisation is not assigned. The report gives the range of bond-angle sums (360 degrees would be planar), and sp2 character is not implied.

  • Bonds under periodic boundary conditions. Each bond length is checked against its target. Pairs that are not bonded but lie within the perception range (1.15 times the summed covalent radii) are counted, and a contact closer than min_distance is refused.

Bond orders are 1, a connectivity placeholder, not a Kekulé structure. Every bond records its rule and order_source: builder.

The generating net and the polyhedron stay in the construction record. No carbon sits on a net vertex, so net edges are never written as chemical bonds.

Pristine and defect maps

Vacancies are chosen with seed from the construction order, so the same recipe always removes the same carbons. The defect map lists each vacancy with its grid point and direction, the construction rings it breaks, every site that is not 3-coordinate or whose vertex symbol is not 6.8.8, and the count of pristine sites. The pristine topology record is kept apart from the graph of the defective model. Undercoordinated carbons are flagged and never capped.

Stone–Wales rotations

A Stone–Wales defect (Stone and Wales, 1986) turns one C–C bond by 90° about its midpoint. The two rings that shared the bond each lose an atom, and the two rings at its ends each gain one. In graphene, four hexagons become the 5–7–7–5 pair. On the 6.8.8 sheet:

stone_wales_bond

Bond

Rings before

Rings after

edge

joins two hexagons; lies between two octagons

8, 8, 6, 6

7, 7, 7, 7

ring

hexagon bond; lies between a hexagon and an octagon

6, 8, 8, 8

5, 7, 9, 9

The rotation is applied to the bond graph and to the construction faces. The faces are checked again as a closed, orientable sheet, under the defect_topology record. V, E and F are unchanged, and so are the Euler characteristic, the genus and the curvature count Σ(6 − n) = 6χ. A model whose topology would change is refused. The ring census comes independently from the bond graph, so it confirms the new rings.

The two rotated carbons move to the bond midpoint ± half the bond, in the sheet’s local plane, towards their new neighbours. The local plane is the best-fit plane of the bond and its four neighbours. Nothing else moves and nothing is relaxed. The formed bonds are typed stone_wales. The usual bond-misfit and contact checks apply. At the default bond, an edge rotation makes 1.45 Å bonds. A ring rotation stays within the default 0.15 Å tolerance and 1.8 Å contact limit.

The bonds to rotate are drawn with seed from the bonds of the chosen kind. A request that cannot be placed without two rotations sharing an atom or a ring is refused (porous_carbon.stone_wales_crowded). Rotations are applied before vacancies, and the vacancy choice does not depend on them. The defect map’s stone_wales list gives each rotated bond with its rings before and after, and the bonds broken and formed.

Reports and porosity handoff

solid porous-carbon-report DOCUMENT --structure ID (CLI), POST /api/documents/{id}/periodic/porous-carbon/report (REST) and porous_carbon_report (MCP) rerun the graph checks on a stored structure. A structure edited after its build has a stale model record, and the live checks win.

With --probe-radius (REST probe_radius) the report adds a porosity plan for Porosity. The plan is validated, not run. It states the assumptions a sheet model adds: the sheet is one atom thick and divides the cell into two congruent labyrinths, both void for a geometric analysis; atoms are hard spheres; the model is unrelaxed; and geometric void is not adsorption capacity.

Building

$ vibe-sketcher solid porous-carbon-models
$ vibe-sketcher solid porous-carbon carbon.vsk --id p688 --preview
$ vibe-sketcher solid porous-carbon carbon.vsk --id p688 --repeat 1,1,2 --vacancies 2 --seed 7
$ vibe-sketcher solid porous-carbon carbon.vsk --id sw --stone-wales 2 --stone-wales-bond edge --seed 5
$ vibe-sketcher solid porous-carbon-report carbon.vsk --structure p688 --probe-radius 1.3

The SDK uses vibesketcher.chem.porous_carbon: model_catalog, preview, build_porous_carbon, structure_report and porosity_handoff_plan. REST and MCP build through POST /api/documents/{id}/periodic/build and build_periodic with a kind: "porous_carbon" recipe, which is revision checked and undone like any build. POST /api/documents/{id}/periodic/porous-carbon/preview and preview_porous_carbon preview a build without storing it. A built model round-trips through VSK and QVF and exports to the periodic formats like any structure, with its record in the provenance.

The cited papers are not yet in the project’s literature library.