vibe-sketcherDocumentation

vibesketcher.chem.porous_carbon

Net-derived porous and negative-curvature carbon models: a plan and one builder (#204).

A model plan names everything a net-derived carbon model depends on: the generating net, the surface that separates its two labyrinths, the cell, the sheet construction and its parameters, the termination and the seed of any stochastic step. model_catalog() lists the constructions; one is built here, the others are planned and refused by name.

The built construction, truncated_mucube, starts from the primitive cubic net pcu (the net of vibesketcher.chem.reticular, written out in code; no RCSR data). The unit cubes of a period-2 cubic grid are split into the cubes on the net (a node cube on each net vertex and an arm cube on each net edge, at most one odd index) and the rest. The squares between the two sets form the regular skew polyhedron {4,6|4} (the “mucube”; H. S. M. Coxeter, Proc. London Math. Soc. s2-43, 33 (1937), doi:10.1112/plms/s2-43.1.33): every grid point is a vertex where six squares meet, and the polyhedron is a discrete form of Schwarz’s P surface around the net. Truncating it (each six-valent vertex cut to a hexagon, each square becoming an octagon) gives a 3-connected graph whose every vertex lies on one 6-ring and two 8-rings, the vertex symbol 6.8.8 (vertex symbols: M. O’Keeffe and S. T. Hyde, Zeolites 19, 370 (1997), doi:10.1016/S0144-2449(97)00133-4). Carbon schwarzites of this kind, sp2-like sheets of negative Gaussian curvature on periodic minimal surfaces, were proposed by A. L. Mackay and H. Terrones, Nature 352, 762 (1991), doi:10.1038/352762a0, and T. Lenosky, X. Gonze, M. Teter and V. Elser, Nature 355, 333 (1992), doi:10.1038/355333a0. This builder does not claim to reproduce the coordinates of any published structure.

Atom placement is explicit and deterministic. The carbon for vertex v and edge direction e sits at a v + rho u, where u is e projected onto the tangent plane of the P nodal surface cos X + cos Y + cos Z = 0 at v (H. G. von Schnering and R. Nesper, Z. Phys. B 83, 407 (1991), doi:10.1007/BF01313411; with X = pi (x - 1/2) every grid point lies on it and its normal there is ((-1)^x, (-1)^y, (-1)^z)). The six projections are 60 degrees apart, so each hexagon is planar and regular with bond rho (bond_length); the grid edge a is chosen so the bond along each mucube edge is edge_bond_length: a = edge + 4 rho / sqrt(6).

Topology is computed, not assumed. The construction faces (one hexagon per mucube vertex, one octagon per square) are checked to be closed cycles of the bond graph with every bond on exactly two faces and a consistent orientation; then chi = V - E + F per cell and genus = 1 - chi / 2. For a 3-connected graph 3V = 2E turns Euler’s relation into sum over faces of (6 - n) = 6 chi, the curvature count used for schwarzites (Mackay and Terrones 1991; Lenosky et al. 1992): with only hexagons and octagons, 12 (g - 1) / 2 octagons per cell. The same genus is the cycle rank E - V + 1 of the generating net’s quotient graph, since the sheet bounds a tubular neighbourhood of the net. Ring statistics come independently from the bond graph: the smallest ring at each bond angle (O’Keeffe and Hyde 1997), searched breadth-first in the periodic lift.

A Stone-Wales defect (A. J. Stone and D. J. Wales, Chem. Phys. Lett. 128, 501 (1986), doi:10.1016/0009-2614(86)80661-3) turns one bond by 90 degrees about its midpoint, in the sheet’s local tangent plane. Atom i of bond i-j gives up neighbour a and takes d; j gives up d and takes a. The two rings that shared the bond lose an atom, and the two rings at its ends gain one. Graphene’s 6,6,6,6 becomes the 5-7-7-5 defect. On this sheet a mucube-edge bond lies between two octagons, so its rings go from 8,8,6,6 to 7,7,7,7. A hexagon bond lies between a hexagon and an octagon, so its rings go from 6,8,8,8 to 5,7,9,9. The rotation is applied to the construction faces as well as to the bonds. The faces are then checked again as a closed, orientable surface: the Euler characteristic and genus must be unchanged, because the transformation preserves V, E and F. The ring census is recomputed independently from the bond graph. The two atoms move to the midpoint plus or minus half the bond, along the in-plane direction that takes each one towards its new neighbours. Nothing else moves, and nothing is relaxed. The bond-misfit and contact checks apply to the result unchanged. The bonds to rotate are chosen with numpy.random.default_rng([seed, 1]) among the bonds of the requested kind. No atom or face is shared between two rotations.

Nothing is relaxed, capped or hybridised: no hydrogen is added, a carbon with fewer than three neighbours is reported, bond orders are a connectivity placeholder (1, not a Kekule structure) and sp2 character is not assumed. The result is a geometric model, unrelaxed, not a stable material; a relaxation or ML validation is a separately admitted periodic job and not proof of synthesis or stability. The generating net and the mucube are kept in the construction record; no site sits on a net vertex, so net edges are never written as chemical bonds.

None of the papers cited here are in the project’s literature library yet.

Module Attributes

CONSTRUCTION_VERSION

Version of this construction, recorded in provenance.

STATUS

Recorded on every built structure and in every report.

MAX_REPEAT

Repeats of the generating cell along one axis.

MAX_VACANCIES

Vacancies one build may place.

MAX_STONE_WALES

Stone-Wales rotations one build may place.

MAX_RING

The largest smallest-ring the ring search looks for.

ATOMS_PER_CELL

Carbon atoms in one generating (period-2) cell of the truncated mucube.

PERCEPTION_SCALE

Default perception factor for the geometry cross-check, d <= f (r_a + r_b).

CONSTRUCTIONS

Constructions in the model plan; only built ones run.

Functions

analyse_carbon_graph(structure, *[, ...])

Coordination, bond lengths and angles under PBC, vertex symbols and a ring census.

build_porous_carbon(recipe)

Build the model; refuse (PorousCarbonRefused) what the plan does not support.

model_catalog()

The model plan: constructions (built or planned), parameters, bounds and status.

porosity_handoff_plan(structure, *[, ...])

A probe-defined porosity plan for a built model, validated but not run.

preview(recipe)

Build without storing: the model record, contacts and the structure, or the refusal.

structure_report(structure, *[, ...])

The graph checks of a stored carbon structure, with its model record when it has one.

Classes

PorousCarbonRecipe(*[, kind, net, ...])

A net-derived carbon model: net, construction, parameters, termination and seed.

Exceptions

PorousCarbonRefused(code, message)

A model the builder will not produce; code is stable.

vibesketcher.chem.porous_carbon.CONSTRUCTIONS: dict[str, dict[str, Any]] = {'d_surface_on_dia': {'net': 'dia', 'reason': 'the truncation of {6,6|3} gives 12-rings; a 6/7/8-ring D-type sheet needs a reviewed decoration', 'state': 'planned', 'surface': 'Schwarz D (discrete: regular skew polyhedron {6,6|3})'}, 'tpms_remeshing': {'reason': 'triangulation/remeshing to a 3-connected carbon graph needs a cited, bounded remeshing algorithm', 'state': 'planned', 'surface': 'a triply periodic minimal surface (nodal approximation)'}, 'truncated_mucube': {'cell': 'the period-2 cubic grid cell of pcu, cubic, edge 2a', 'defects': {'stone_wales': '90-degree bond rotation (Stone and Wales 1986): an edge bond turns rings 8,8,6,6 into 7,7,7,7, a ring bond 6,8,8,8 into 5,7,9,9; unrelaxed', 'vacancies': 'seeded removal; never capped'}, 'net': 'pcu', 'parameters': ['bond_length', 'edge_bond_length', 'repeat', 'vacancies', 'stone_wales', 'stone_wales_bond', 'seed'], 'sheet': 'truncation of the mucube: a hexagon per six-valent vertex, an octagon per square; vertex symbol 6.8.8', 'state': 'built', 'stochastic': 'vacancy placement (numpy default_rng(seed)) and the Stone-Wales bonds (numpy default_rng([seed, 1]))', 'surface': 'Schwarz P (discrete: regular skew polyhedron {4,6|4}, the mucube)', 'termination': 'none: no hydrogen is added; undercoordinated carbons are reported'}, 'zeolite_templated': {'net': 'a zeolite framework', 'reason': 'needs licensed framework coordinates (IZA database terms not reviewed) and a cited pore-wall carbon construction', 'state': 'planned'}}

Constructions in the model plan; only built ones run.

vibesketcher.chem.porous_carbon.STATUS = 'geometric model, unrelaxed, not a stable material'

Recorded on every built structure and in every report.

class vibesketcher.chem.porous_carbon.PorousCarbonRecipe(*, kind='porous_carbon', identifier, net='pcu', construction='truncated_mucube', bond_length=1.42, edge_bond_length=None, bond_tolerance=0.15, repeat=(1, 1, 1), vacancies=0, stone_wales=0, stone_wales_bond='edge', seed=0, min_distance=1.8, max_ring_size=12, termination='none')[source]

Bases: BaseModel

A net-derived carbon model: net, construction, parameters, termination and seed.

Parameters:
  • kind (Literal['porous_carbon'])

  • identifier (Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9_-]{0,63}$')])

  • net (Annotated[str, MinLen(min_length=1), MaxLen(max_length=32)])

  • construction (Annotated[str, MinLen(min_length=1), MaxLen(max_length=64)])

  • bond_length (Annotated[float, Ge(ge=1.2), Le(le=1.7), AllowInfNan(allow_inf_nan=False)])

  • edge_bond_length (Annotated[float | None, Ge(ge=1.2), Le(le=1.7), AllowInfNan(allow_inf_nan=False)])

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

  • repeat (tuple[Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1), Le(le=3)])], Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1), Le(le=3)])], Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1), Le(le=3)])]])

  • vacancies (Annotated[int, Ge(ge=0), Le(le=32)])

  • stone_wales (Annotated[int, Ge(ge=0), Le(le=16)])

  • stone_wales_bond (Literal['edge', 'ring'])

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

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

  • max_ring_size (Annotated[int, Ge(ge=6), Le(le=16)])

  • termination (Annotated[str, MinLen(min_length=1), MaxLen(max_length=32)])

model_config = {'extra': 'forbid'}

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

kind: Literal['porous_carbon']
identifier: _ID
net: str
construction: str
bond_length: float

Hexagon (ring) bond, angstrom; also the hexagon circumradius.

edge_bond_length: float | None

Bond along each mucube edge (joins two hexagons); default bond_length.

bond_tolerance: float

Largest allowed difference between any bond and its target, angstrom.

repeat: tuple[_Repeat, _Repeat, _Repeat]
vacancies: int
stone_wales: int

Stone-Wales bond rotations, placed with seed.

stone_wales_bond: Literal['edge', 'ring']

edge (between two octagons) or ring (hexagon-octagon).

Type:

Which bonds rotate

seed: int
min_distance: float

Closest allowed contact between carbons that are not bonded, angstrom.

max_ring_size: int
termination: str

the builder never adds hydrogen or other caps.

Type:

Only none

exception vibesketcher.chem.porous_carbon.PorousCarbonRefused(code, message)[source]

Bases: BuildRefused

A model the builder will not produce; code is stable.

Parameters:
Return type:

None

vibesketcher.chem.porous_carbon.analyse_carbon_graph(structure, *, targets=None, kinds=None, max_ring_size=12)[source]

Coordination, bond lengths and angles under PBC, vertex symbols and a ring census.

Reads the chemical edges (authored and perceived); topology, distance and suppressed edges are ignored. targets gives each chemical bond’s target length in stored order (default 1.42 angstrom).

Parameters:
Return type:

dict[str, Any]

vibesketcher.chem.porous_carbon.build_porous_carbon(recipe)[source]

Build the model; refuse (PorousCarbonRefused) what the plan does not support.

Parameters:

recipe (PorousCarbonRecipe)

Return type:

PeriodicStructure

vibesketcher.chem.porous_carbon.model_catalog()[source]

The model plan: constructions (built or planned), parameters, bounds and status.

Return type:

dict[str, Any]

vibesketcher.chem.porous_carbon.porosity_handoff_plan(structure, *, probe_species='He', probe_radius=1.3, radius_source='user-stated hard-sphere radius')[source]

A probe-defined porosity plan for a built model, validated but not run.

The plan goes to vibesketcher.document.porosity unchanged; this states the assumptions a net-derived sheet adds. Nothing is estimated here.

Parameters:
Return type:

dict[str, Any]

vibesketcher.chem.porous_carbon.preview(recipe)[source]

Build without storing: the model record, contacts and the structure, or the refusal.

Parameters:

recipe (PorousCarbonRecipe)

Return type:

dict[str, Any]

vibesketcher.chem.porous_carbon.structure_report(structure, *, max_ring_size=12, probe_radius=None, probe_species='He')[source]

The graph checks of a stored carbon structure, with its model record when it has one.

A porous_carbon build’s record is compared with the current graph: an edit after the build makes the record stale, and the live checks win.

Parameters:
Return type:

dict[str, Any]