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
|
Version of this construction, recorded in provenance. |
Recorded on every built structure and in every report. |
|
|
Repeats of the generating cell along one axis. |
|
Vacancies one build may place. |
|
Stone-Wales rotations one build may place. |
|
The largest smallest-ring the ring search looks for. |
|
Carbon atoms in one generating (period-2) cell of the truncated mucube. |
|
Default perception factor for the geometry cross-check, d <= f (r_a + r_b). |
Constructions in the model plan; only |
Functions
|
Coordination, bond lengths and angles under PBC, vertex symbols and a ring census. |
|
Build the model; refuse ( |
The model plan: constructions (built or planned), parameters, bounds and status. |
|
|
A probe-defined porosity plan for a built model, validated but not run. |
|
Build without storing: the model record, contacts and the structure, or the refusal. |
|
The graph checks of a stored carbon structure, with its model record when it has one. |
Classes
|
A net-derived carbon model: net, construction, parameters, termination and seed. |
Exceptions
|
A model the builder will not produce; |
- 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
builtones 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:
BaseModelA 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)])]])
stone_wales_bond (Literal['edge', 'ring'])
min_distance (Annotated[float, Gt(gt=0), Le(le=3), AllowInfNan(allow_inf_nan=False)])
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¶
- edge_bond_length: float | None¶
Bond along each mucube edge (joins two hexagons); default
bond_length.
- stone_wales_bond: Literal['edge', 'ring']¶
edge(between two octagons) orring(hexagon-octagon).- Type:
Which bonds rotate
- exception vibesketcher.chem.porous_carbon.PorousCarbonRefused(code, message)[source]¶
Bases:
BuildRefusedA model the builder will not produce;
codeis stable.
- 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.
targetsgives each chemical bond’s target length in stored order (default 1.42 angstrom).
- 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:
- vibesketcher.chem.porous_carbon.model_catalog()[source]¶
The model plan: constructions (built or planned), parameters, bounds and status.
- 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.porosityunchanged; this states the assumptions a net-derived sheet adds. Nothing is estimated here.
- 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:
- 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.