vibe-sketcherDocumentation

Periodic bond graphs and crystal preparation

A periodic structure can carry a bond graph: edges from a site in the home cell to a site in the cell displaced by an integer image, a labelled quotient graph in the sense of Chung, Hahn and Klee (Acta Cryst. A40, 42, 1984). Each edge says what it means, so a reviewer can tell a chemical bond from a candidate or a crystallographic distance. Nothing perceives or repairs bonds behind your back. Preparation steps such as removing guests or completing hydrogen are previewed as derived models with their deltas before anything is stored.

A prepared model is a reviewed starting model. It is not a validated electronic state or an equilibrium structure.

Edge kinds

Every entry of bonds has these fields (all additive to schema 1):

Field

Meaning

a, b, image

Site a in the home cell, site b in cell image.

order

Bond order; 1.5 marks an aromatic bond.

kind

authored (default), perceived, distance, topology or suppressed.

order_source

builder, manual, imported, perceived or prepared.

rule

The rule or source that proposed the edge.

distance_angstrom

A tabulated distance, for distance edges.

Only authored edges are the chemical graph. Builders write authored edges, and so do accepted perceptions and manual edits. A perceived edge is a candidate a distance rule proposed; it waits for review. A distance edge is a crystallographic distance-table entry, such as a row of a CIF _geom_bond loop. It is never promoted to a bond. A topology edge belongs to a net description. A suppressed edge records a pair someone ruled out, so a later perception does not propose it again. Bonds stored before this change read as authored.

Editing the graph

A graph edit is a list of operations, applied in order and recorded as one undoable step in the structure’s provenance (provenance.graph):

Operation

Effect

add_bond (a, b, image, order)

An authored bond with a manual order; image defaults to the nearest image.

set_order (a, b, image, order)

Sets the order by hand, and accepts a perceived edge.

remove_bond (a, b, image, kind)

Removes one edge.

suppress (a, b, image, reason)

Rules the pair out and removes any bond between them.

perceive (scale, metals, metal_metal)

Proposes candidates with d <= scale (r_a + r_b).

accept_perceived (edges)

Makes the listed perceived edges, or all of them, authored.

clear_perceived

Removes every perceived edge and the perception record.

import_cif_distances (cif, block, tolerance)

Stores the CIF _geom_bond loop as distance edges.

Perception uses RDKit’s covalent radii (Cordero et al., Dalton Trans. 2008, 2832) with a default scale of 1.15. It skips pairs that are already stored, and metal-metal pairs unless metal_metal is true. Two metal radii reach the next coordination shell of most ionic solids. The rule, its parameters and a fingerprint of the geometry are recorded.

Geometry edits (cell, move, rotate, set sites) keep the stored edges exactly as they were. When the geometry changes after a perception, the report says graph.perception_stale; when an authored bond becomes much longer than a covalent bond, it says graph.bond_stretched. Manual bond orders keep their order_source through save and load, geometry edits and supercells.

The CIF importer reads no connectivity. To keep a CIF’s distance table, pass the same text to import_cif_distances. Each tabulated label pair is matched to the expanded site pairs whose minimum-image distance agrees within the tolerance. A row that matches no pair is refused.

The last graph edit can be undone. Undo refuses when the edges that edit added have changed since.

The graph report

The report gives edge counts by kind, the perception record, each site’s coordination number, the fragments and coded diagnostics. Fragments are the connected components of the authored and perceived edges. Each has a dimensionality, the rank of the lattice translations its cycles carry: molecule, chain, layer or framework. A molecule drawn across a cell face is reported as one molecule with crosses_boundary.

Each diagnostic has a stable code, a severity, a message, a remedy and the sites and edges concerned. The report lists every code with its meaning under codes.

Code

Meaning

geometry.clash

Two atoms are far closer than a bond; a warning for disorder alternatives.

geometry.duplicate_site

Two sites of one element coincide.

site.partial_occupancy

A partially occupied or disordered site.

graph.none, graph.distance_table_only

No chemical graph is stored.

graph.unreviewed_perceived

Perceived candidates await review.

graph.perception_stale, graph.perception_unrecorded

The perception predates the geometry or has no record.

graph.bond_stretched, graph.bond_not_minimum_image

An authored bond is too long or joins a far image.

graph.missing_contact

A close pair has no edge of any kind.

graph.duplicate_edge, graph.self_edge

Malformed edges.

coordination.isolated_site, coordination.overcoordinated

Odd coordination of light atoms.

coordination.valence_sum

A light atom’s bond-order sum exceeds its valence.

coordination.metal_ambiguous

Metal coordination and valence stay a reviewer’s call.

coordination.aromatic_ambiguous

Aromatic orders leave the Kekule structure open.

fragment.crosses_boundary, fragment.extended, fragment.several

Fragment notes.

Preparation

A preparation names a source structure, an optional identifier for the derived model (default SOURCE-dedup, SOURCE-nofrag or SOURCE-h) and one step. The preview returns the derived model, its deltas, refusals and notices with stable codes, and provenance: the operation, its parameters and the source digest. Deltas cover the removed and added sites, the stoichiometry before and after, the charge and multiplicity, and the edges. Applying adds the derived model next to its source; the source is unchanged. An apply is refused while the preview has refusals. A preparation can be undone while the derived model is unchanged.

remove_duplicates

Drops sites of one element closer than tolerance (0.1 A by default) to an earlier site. Coincident sites that are partially occupied, in a disorder group or of different elements are refused rather than merged. Edges of the removed sites are dropped and counted.

remove_fragments

Drops the chosen molecules by fragment index (fragments) or by any of their sites. It needs a stored chemical graph. A chain, layer or framework is refused, and a charged structure needs removed_charge. A stated multiplicity becomes unspecified.

complete_hydrogens

Adds hydrogen to carbon whose authored graph fixes the geometry: CH on two or three neighbours, CH2 on two neighbours and CH on a triple bond. It reads the bond-order sum and the neighbour directions; C-H lengths are 1.09, 1.08 and 1.06 A. Protonation of N, O and other heteroatoms is never guessed; they are listed as notices. Methyl and terminal =CH2 rotors, metal neighbours, non-integer order sums, disordered sites, perceived bonds nobody accepted and hydrogen that would clash are refused. Narrow the request with sites to the unambiguous carbons, or place the others by hand.

Choosing a disorder alternative is part of the CIF import (disorder, disorder_group); see Experimental CIF files.

In the browser

Open Solid-state builder… from the command palette and use the Diagnose and prepare form. It calls the same report and preparation routes as below.

  1. Choose the Source structure and Diagnose bond graph. The panel lists the edge counts by kind, every diagnostic as its severity, code, message, sites and remedy, and every fragment with its index, formula, dimensionality and whether it crosses a cell face. The diagnosis reads the document and changes nothing; it is cleared when the structures change.

  2. Choose a Preparation step. Removing duplicates takes a tolerance; removing fragments takes the fragment indices from the diagnosis or any of their sites, and the charge removed with them for a charged structure; completing hydrogen takes an optional list of carbon sites. Only the controls of the chosen step are shown.

  3. Preview preparation shows the derived model’s formula, site count and schematic with its deltas: the sites removed and added, the stoichiometry, charge and multiplicity before and after, and the edges removed and added. Refusals and notices are listed with their codes and messages exactly as the server returns them, and a refused or empty preview cannot be added.

  4. Add reviewed preparation adds the derived model next to its source, checked against the previewed revision and source digest. Changing any input first discards the preview. Undo preparation removes the model again while it is unchanged.

Graph edits (perceive, accept, set orders, suppress) are not in the panel yet; use the CLI, REST or MCP routes below.

Python, command line, REST and MCP

from vibesketcher.document import periodic_graph as pg, periodic_prepare as pp

edit = pg.parse_graph_edit({"structure": "mof", "operations": [{"op": "perceive"}]})
structure = pg.apply_graph_edit(structure, edit)
report = pg.report(structure)
plan = pp.parse_preparation(
    {"source": "mof", "step": {"operation": "remove_fragments", "fragments": [1]}}
)
preview = pp.preview(structure, plan)
document = pp.apply(document, plan, source_sha256=preview["source_sha256"])
vibe-sketcher solid graph mof.vsk --structure mof
vibe-sketcher solid graph-edit mof.vsk --structure mof --perceive --accept
vibe-sketcher solid graph-edit mof.vsk --structure mof --set-order C1,C2,0,0,0,2
vibe-sketcher solid graph-undo mof.vsk --structure mof
vibe-sketcher solid prepare mof.vsk --source mof --operation remove_fragments --fragment 1
vibe-sketcher solid prepare mof.vsk --source mof --operation remove_fragments --fragment 1 --apply
vibe-sketcher solid prepare-undo mof.vsk --structure mof-nofrag

solid prepare without --apply prints the preview as JSON and exits with status 3 when it is refused.

  • GET /api/documents/{id}/periodic/{structure}/graph returns the report.

  • POST /api/documents/{id}/periodic/{structure}/graph takes revision and operations; POST .../graph/undo takes revision.

  • POST /api/documents/{id}/periodic/preparation/preview takes preparation and changes nothing.

  • POST /api/documents/{id}/periodic/preparation takes revision, preparation and optionally the preview’s source_sha256; POST .../preparation/undo takes revision and structure.

Guests and solvent are added to a host by guest loading.

A stale revision is answered with 409. The MCP tools are periodic_graph, edit_periodic_graph (with undo), preview_preparation and apply_preparation (with undo).