vibe-sketcherDocumentation

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

smiles

* atoms, also [*:1] or [1*] (labels *1), or CXSMILES labels such as _R1

generic

a drawn R-group core or attachment structure in the document (labels _R1, _AP1)

atoms

[{symbol, xyz}] with X for a marker; the anchor is the nearest real atom; optional bonds [[i, j, order]]

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

pcu

3

1

6-c octahedron

dia

3

2 (primitive fcc cell)

4-c tetrahedron

sql

2

1

4-c square

hcb

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.

  1. 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.

  2. Linker placement. A linker has exactly two connection points, each within angle_tolerance of 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_rotation turns the linker about its edge, in degrees.

  3. 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_spread warning.

  4. Closure. A join more than closure_tolerance (0.3 Å) off its bond length is refused. One more than 0.05 Å off gives an assembly.bond_strain warning.

  5. 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

net, assignment

The net and which block sits on each vertex and edge

blocks

Each block’s source, formula, atoms, connection points and markers removed

placements

Each placed block’s rotation, translation, and port or edge orientation

joins

Each join’s sites, distance, target bond length and deviation

counts

Expected and actual connections and atoms, markers removed, markers in the structure (0), unmapped connection points (0), topology edges, chemical bonds

stoichiometry

The cell formula and each vertex block’s formula

edge_angstrom, edge_needs_angstrom

The edge length used and each edge’s need

diagnostics

Warnings with stable codes

The build is refused when expected and actual counts differ.

Refusals

Code

Meaning

net.unknown

The net is not in the catalogue

site.coordination_mismatch

A node’s connection points do not match its vertex

site.direction_mismatch

A node’s directions miss the vertex figure

linker.not_ditopic, linker.not_linear

The linker has not two points, or they are bent

assembly.closure, assembly.collision

A join does not close, or atoms overlap

block.*

An unreadable block, missing or malformed markers, or a missing generic

gated.*

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/nets lists the nets.

  • POST /api/documents/{id}/periodic/reticular/preview takes recipe and changes nothing. Pass structure: true to include the built structure.

  • POST /api/documents/{id}/periodic/build with a kind: "reticular" recipe builds it, revision-checked and recorded as an edit.

The MCP tools are periodic_nets, preview_reticular and build_periodic.