vibe-sketcher/Documentation

Periodic structures and interchange

Periodic structures are physical models, separate from molecular Species, formula solids and schematic surface pictures. Release placement remains unassigned. Publication projections, slab construction, defects, periodic reaction schemes and calculation inputs follow the periodic authoring plan.

Install pip install 'vibesketcher[periodic]' for CIF parsing with Gemmi 0.7.5. Gemmi provides wheels for Python 3.14; a Python 3.15 source build is not yet qualified. The model and QVF paths do not require Gemmi. QVF uses the existing optional QVF toolkit installation.

Physical conventions

Document.periodic_structures is an additive schema-1 list, omitted when empty. Each PeriodicStructure has three independent right-handed lattice row vectors in angstrom, a three-axis pbc mask, and persistent site IDs. Dimensionality is the number of true PBC flags. A slab still requires a full rank cell, including its explicitly supplied nonperiodic vector; vacuum is never invented. site.fractional @ lattice_angstrom gives Cartesian angstrom coordinates (structure.cartesian(site)). Fractional positions are not wrapped on import. Site occupancy, disorder group, lattice-image bonds, optional total charge/multiplicity, provenance and cell setting (primitive, conventional or unspecified) are retained. A bond’s image is the integer translation applied to its second site. Missing charge or spin stays unspecified. Cell volume, vector lengths and Cartesian positions must remain finite and numerically expressible; finite vector components alone are insufficient. Invalid mutable SDK edits are revalidated before CIF/VSK/QVF serialization.

supercell applies an integer row-cell matrix, expands sites and bonds and records the parent cell, parent-site IDs and integer images. It scales a stated total charge; total spin stays unspecified because it is not additive. Transforms may not mix periodic and nonperiodic axes. Matrix entries have absolute value at most 1,000,000 and positive determinant at most 25,000, checked with exact integer arithmetic before conversion. Stored parent transforms use the same limits. Image arithmetic during supercell construction also refuses bond translations or transformed fractional coordinates outside ±1,000,000, before integer conversion can overflow or lose the image mapping. Ordinary unwrapped coordinates are retained on import; an out-of-range operation refuses without changing that source model. These are physical repeats, not display repetitions. No primitive/conventional conversion or symmetry search is implied by the cell-setting label. The existing nanotube PeriodicCell remains valid 1D descriptive metadata; it is not automatically promoted to this model because it lacks two lattice vectors and a vacuum choice. Construct a physical cell explicitly from independently justified data.

SDK, CLI, REST and MCP

from vibesketcher.document import PeriodicSite, PeriodicStructure, new_document
from vibesketcher.document.periodic import supercell, with_periodic
from vibesketcher.document.formats import export, import_into

cell = PeriodicStructure(
    id="carbon",
    lattice_angstrom=((3, 0, 0), (1, 4, 0), (0, 0, 15)),
    pbc=(True, True, False),
    sites=[PeriodicSite(id="C1", symbol="C", fractional=(0, 0, 0.5))],
)
document = with_periodic(new_document(), cell)
repeated = supercell(cell, [[2, 0, 0], [0, 2, 0], [0, 0, 1]], identifier="repeat")
archive = export(document, "qvf").content
restored = import_into(None, archive, "qvf").document

vibe-sketcher convert carbon.cif -o carbon.qvf
vibe-sketcher convert carbon.qvf -o carbon.vsk
vibe-sketcher periodic carbon.vsk --structure crystal1 --identifier repeat \
  --matrix '[[2,0,0],[0,2,0],[0,0,1]]' -o repeated.qvf
vibe-sketcher periodic carbon.vsk --record periodic-record.json -o updated.qvf

POST /api/documents accepts format: "cif" with text data, or a validated whole document. GET /api/documents/{id}/export/{format} (CIF, QVF or VSK) exports it. POST /api/documents/{id}/periodic takes revision and structure to upsert; POST /api/documents/{id}/periodic/supercell takes revision, source, identifier and matrix. Stale revisions return 409. MCP exposes the same operations as new_document, open_document, show_document, set_periodic, periodic_supercell, export and save_document; show_document includes validated periodic records.

Lossless boundary and refusals

The lossless CIF import accepts one explicit P1 data block with stated cell parameters and fractional coordinates. Missing or unknown coordinates or occupancy, magnetic CIF and unsupported elements are refused. Files with nontrivial symmetry go through the experimental CIF import, which expands the symmetry and records its decisions. It does not keep the raw text for lossless export. Disordered P1 sites retain occupancy/group without silently ordering them. The original text, comments, uncertainties and extra tags are retained verbatim. Export verifies both the model receipt and a fresh parse of that text; editing its physical model makes raw export refuse. To author a normalized CIF after an edit, explicitly clear both source_cif and source_model_sha256, thereby choosing to discard the original syntax and uninterpreted tags.

New structures export standard P1 lengths/angles and sites, plus a validated _vibesketcher_periodic_json record. This extension preserves lattice orientation, PBC masks, image bonds and parent mappings that standard coreCIF cannot fully express. Import checks its standard-site and cell-metric projection for conflicts. Normalized coordinates use round-trip decimal precision. CIF output is read back and compared to its typed model before it is returned. Other CIF readers see the standard 3D cell; use QVF/VSK when a recipient must understand the complete model. CIF export requires a single structure without molecular, reaction, job or other drawing content.

QVF native structure sections expose Cartesian coordinates, row lattice vectors, PBC and occupancy through the existing public writer. The full typed document section preserves all additional fields. External periodic QVF opens as periodic records rather than molecular species; original native payloads, bond payloads and section metadata remain in provenance. Unknown native fields are retained, not promoted to validated physical semantics. Periodic reaction schemes are refused pending their dedicated model. No QVF specification or toolkit changes are required. Archive byte identity is not promised; scientific model readback is.

Molecular file exports, drawing exports and calculation writers refuse documents containing periodic models. Limits are 100 structures per document, 25,000 sites and 100,000 bonds per structure, existing input/archive byte/depth limits, and one million candidate images per supercell enumeration. These limits are checked before allocating expanded structures.