Reticular frameworks from drawn building blocks¶
kind: "reticular" assembles a framework from building blocks you draw and a
net you name. A node block sits on every vertex of the net. A ditopic linker
block sits on every edge, or the nodes bond to each other directly when no
linker is given. This is the reticular construction of Yaghi, O’Keeffe and
co-workers (Nature 423, 705, 2003). The preset metal-organic frameworks
(kind: "framework", see
Metal-organic frameworks)
stay available. The reticular builder is for blocks the presets do not cover.
The result is an unrelaxed starting geometry. Nothing is relaxed, and no connectivity is guessed. When the blocks do not fit the net, the build is refused with a stable code.
Connection points¶
A block marks each connection point with a dummy atom bonded to exactly one anchor atom. The direction from the anchor to the marker is the attachment direction.
Block source |
Connection points |
|---|---|
|
|
|
a drawn R-group core or attachment structure in the document (labels |
|
|
Markers are never physical atoms. They are removed before assembly, and the anchors are bonded across each net edge with a single bond. The vibe-qc input writer, the QVF writers and the CIF, POSCAR, extended XYZ and GEN exports refuse a reticular structure whose assembly record has a connection point left unjoined, or that has lost its record.
A block drawn without coordinates is embedded with RDKit (ETKDG v3, then MMFF94 or UFF) under a fixed seed. During embedding the markers are hydrogen atoms, so an attachment direction is a normal bond direction. Implicit hydrogen on the other atoms becomes explicit.
Nets¶
The nets are defined in vibe-sketcher from the geometry of their lattices, with unit edge length. They use the RCSR three-letter names (O’Keeffe et al., Acc. Chem. Res. 41, 1782, 2008), but no RCSR or PORMAKE data is bundled or read.
Net |
Dimension |
Vertices |
Vertex figure |
|---|---|---|---|
|
3 |
1 |
6-c octahedron |
|
3 |
2 (primitive fcc cell) |
4-c tetrahedron |
|
2 |
1 |
4-c square |
|
2 |
2 |
3-c triangle |
solid nets (CLI), GET /api/periodic/nets (REST) and periodic_nets (MCP)
list the vertices, the edges with their images, the coordination and the
unit-edge cell. Layer nets get vacuum (default 15 Å) over the thickest atom.
Assembly¶
Every vertex gets node. The second vertex of dia or hcb can get
second_node instead. Every edge gets linker. The assignment is recorded.
Site matching. A node needs as many connection points as its vertex has edges. It is turned by the proper rotation that best maps its centre-to-marker directions onto the vertex’s edge directions, over every assignment of points to edges (Kabsch, Acta Cryst. A32, 922, 1976). Ties keep the first assignment. A direction further off than
angle_tolerance(20° by default) is refused.Linker placement. A linker has exactly two connection points, each within
angle_toleranceof its anchor-to-anchor axis. The axis lies along the edge, and the point whose label sorts first faces the edge’s tail vertex. The linker’s widest direction lies along a fixed reference. For layer nets that reference is in the plane.linker_rotationturns the linker about its edge, in degrees.Edge length. Each edge needs the length that makes every join a bond of the covalent-radius sum (Cordero et al., Dalton Trans. 2008, 2832). The longest of those lengths sets the cell. When the lengths differ, the report gives an
assembly.edge_spreadwarning.Closure. A join more than
closure_tolerance(0.3 Å) off its bond length is refused. One more than 0.05 Å off gives anassembly.bond_strainwarning.Collisions. Non-bonded atoms closer than
min_distance(1.0 Å), or closer than 0.75 of their covalent-radius sum, are refused. Turning the linker often clears a clash between neighbouring linkers.
The net’s edges are stored as topology edges, separate from the chemical
bonds (see Periodic bond graphs). Each joins the sites
nearest the two vertices, in the right cell image. Their rule names the net
and the edge.
The assembly record¶
provenance.builder.assembly holds the record, and a preview returns it
without storing anything.
Field |
Content |
|---|---|
|
The net and which block sits on each vertex and edge |
|
Each block’s source, formula, atoms, connection points and markers removed |
|
Each placed block’s rotation, translation, and port or edge orientation |
|
Each join’s sites, distance, target bond length and deviation |
|
Expected and actual connections and atoms, markers removed, markers in the structure (0), unmapped connection points (0), topology edges, chemical bonds |
|
The cell formula and each vertex block’s formula |
|
The edge length used and each edge’s need |
|
Warnings with stable codes |
The build is refused when expected and actual counts differ.
Refusals¶
Code |
Meaning |
|---|---|
|
The net is not in the catalogue |
|
A node’s connection points do not match its vertex |
|
A node’s directions miss the vertex figure |
|
The linker has not two points, or they are bent |
|
A join does not close, or atoms overlap |
|
An unreadable block, missing or malformed markers, or a missing generic |
|
A gated extension was requested |
Interpenetration, rod nodes, merged nets, partitioned pores and
supertetrahedral units are gated extensions. A topology name does not imply
them, and they are refused by name (interpenetration above 1, or
extensions).
Python, command line, REST and MCP¶
from vibesketcher.chem.reticular import ReticularRecipe, build_reticular, preview
recipe = ReticularRecipe(
identifier="dia-ph",
net="dia",
node={"smiles": "[*]C([*])([*])[*]"},
linker={"smiles": "[*]c1ccc([*])cc1"},
linker_rotation=45,
)
report = preview(recipe)["assembly"]["counts"]
structure = build_reticular(recipe)
vibe-sketcher solid nets
vibe-sketcher solid reticular frame.vsk --id dia-ph --net dia \
--node '[*]C([*])([*])[*]' --linker '[*]c1ccc([*])cc1' --linker-rotation 45 --preview
vibe-sketcher solid reticular frame.vsk --id dia-ph --net dia \
--node '[*]C([*])([*])[*]' --linker '[*]c1ccc([*])cc1' --linker-rotation 45
vibe-sketcher solid reticular frame.vsk --id layer --net hcb --node-generic g1
--preview prints the assembly record as JSON and exits with status 3 when
the assembly is refused. --node-atoms FILE reads a JSON atom list, or an
object with atoms and bonds.
GET /api/periodic/netslists the nets.POST /api/documents/{id}/periodic/reticular/previewtakesrecipeand changes nothing. Passstructure: trueto include the built structure.POST /api/documents/{id}/periodic/buildwith akind: "reticular"recipe builds it, revision-checked and recorded as an edit.
The MCP tools are periodic_nets, preview_reticular and build_periodic.