vibe-sketcher/Documentation

Solid-state structures and inputs

Build crystals, choose their cell and turn them into periodic models. The models are stored as periodic structures. The solid-state input builder plan (#227) lists the steps that follow. The tutorial builds MgO, an Al₂O₃ slab and benzene on it.

Every builder records its recipe in the structure’s provenance["builder"], so you can see how a model was made and rebuild it. Lengths are in angstrom, angles in degrees, and cells are right-handed row vectors.

Lattices

All 20 lattice types are available by their Pearson-style symbol:

Dimension	Symbols
3D	aP triclinic, mP and mS monoclinic (unique axis b, C-centred), oP, oS (C), oI and oF orthorhombic, tP and tI tetragonal, hR rhombohedral (hexagonal axes, obverse), hP hexagonal, cP, cI and cF cubic
2D	mp oblique, op rectangular, oc centred rectangular, tp square, hp hexagonal
1D	l line

Each type takes only the parameters it leaves free. For example tP takes a and c, mP takes a, b, c and beta, and cF refuses a b. Conventional cells use the standard setting of the International Tables. The primitive cell follows Setyawan and Curtarolo (2010), and its transform is recorded. A plane or line lattice also needs a full three-dimensional cell, so each of its nonperiodic vectors has the length vacuum (20 Å by default). The layer sits in the middle of that vector, and the pbc mask marks the periodic directions.

A motif is given as sites in fractional coordinates of the conventional cell. Symmetry operations are optional and use ITA notation such as -x+y,-x,z+1/2. The builder adds the centring translations itself and merges coincident sites. Two different elements on one site are refused.

Space groups

A crystal can also be given by its space group and asymmetric unit. Every one of the 230 groups is available in all 564 tabulated settings. Name a setting by number (225), by Hermann–Mauguin symbol (Fm-3m, F m -3 m, P2_1/c), by Hall symbol, or with an extension: :H or :R for hexagonal or rhombohedral axes, :1 or :2 for the origin choice. Without an extension, hexagonal axes and origin choice 2 are used, as the Bilbao Crystallographic Server does.

vibe-sketcher solid space-groups Fd-3m
vibe-sketcher solid space-groups --operations "P 21/c"
vibe-sketcher solid crystal al2o3.vsk --id al2o3 --space-group "R -3 c" --a 4.7602 \
  --c 12.9933 --site Al:0,0,0.35216 --site O:0.30624,0,0.25 --cell conventional

The operations are generated from the Hall symbol (Hall 1981), with centring, inversion, screw and glide translations and origin shifts, and the group is closed by multiplication. They are checked against Gemmi’s tables for every setting (scripts/generate_space_group_table.py). The cell must satisfy the crystal system, for example a = b for tetragonal groups, or only β differing from 90° for monoclinic groups with unique axis b. Missing lengths and angles are filled in from those rules.

Each generated site records its orbit, meaning the asymmetric site it comes from, and each orbit records its multiplicity and site-symmetry order, under provenance["builder"]["asymmetric_unit"]. A site within 0.1 Å of a special position that does not lie on it is reported. It is never moved: symmetry is applied exactly as given. Two asymmetric sites that generate the same position are refused. --cell primitive reduces centred cells, including R groups on hexagonal axes, to their primitive cell.

Finding the space group

With the optional symmetry extra (pip install "vibe-sketcher[symmetry]", spglib), the sketcher finds the space group of any 3D periodic structure:

vibe-sketcher solid symmetry al2o3.vsk --structure al2o3
vibe-sketcher solid symmetry al2o3.vsk --structure al2o3 --symprec 0.01 --json

The report gives the number, Hermann–Mauguin and Hall symbols, the setting, point group and crystal system, the number of operations, and for each site its Wyckoff letter, site symmetry and the independent site it is equivalent to. --symprec is the distance tolerance in angstrom (default 0.001). A larger tolerance can find a higher group in measured or relaxed coordinates. Detection never changes the structure. Slabs, wires and partially occupied sites are refused, because a layer or rod group is not a space group.

The same extra adds four cell choices:

Choice	What it builds
standard_conventional	the standardised conventional cell of the detected group
standard_primitive	the primitive cell of that standardised cell
niggli	the Niggli-reduced cell
delaunay	the Delaunay-reduced cell

A standardised cell keeps the measured positions. They are carried through the change of basis and origin shift, not replaced by symmetric ones. The largest displacement that idealisation would cause is recorded under provenance["builder"]["idealization_displacement_angstrom"], for atoms and for the cell vectors. --idealize applies it. Niggli and Delaunay reductions are unimodular changes of basis, so the atoms and the volume are unchanged. Building a crystal from a space group does not need spglib.

Experimental CIF files

solid import-cif reads a CIF from an experiment or a database and expands its asymmetric unit to the full conventional cell. The reader is pure Python, so it needs no extra and works on Python 3.15 (Hall et al. 1991 describe the syntax). Opening a .cif file in the browser or the desktop app uses it whenever the lossless P1 reader cannot, with the default options.

vibe-sketcher solid import-cif al2o3.vsk corundum.cif --id al2o3
vibe-sketcher solid import-cif si.vsk si.cif --id si --setting Fd-3m:1
vibe-sketcher solid import-cif bto.vsk disordered.cif --id bto --disorder majority
vibe-sketcher solid import-cif bto.vsk disordered.cif --id bto2 --disorder group --disorder-group 1

The symmetry comes from the symmetry-operation loop (_space_group_symop_operation_xyz or _symmetry_equiv_pos_as_xyz). If there is no loop, it comes from the Hall symbol, then from the Hermann–Mauguin symbol or the number. Listed operations must form a group. They are matched to one of the 564 tabulated settings, and a file whose symbol names another group is refused. Operations of a nonstandard setting are used as given, with a warning. A symbol without operations that has two settings, such as F d -3 m with two origin choices, is refused until --setting names one.

Numbers keep their standard uncertainties. 4.7602(3) is read as 4.7602 with an uncertainty of 0.0003, and the uncertainties of the cell and the sites are recorded. Symmetry images closer than --merge-tolerance (0.01 Å) are merged. Atoms of different sites closer than 0.5 Å are refused unless they are disorder resolved by the chosen policy:

--disorder	What it does
refuse (default)	Refuses any partially occupied site or disorder group, and names them.
group	Keeps --disorder-group and drops the other groups. Partial sites outside groups are still refused.
majority	Keeps the most occupied group of each disorder assembly, and the most occupied species on a mixed or partly vacant site.

Kept sites are written fully occupied. Every dropped site, merge and filled site is listed under provenance["builder"]["disorder"] and ["merges"]. The record also holds the data block and the text’s SHA-256, the space-group setting, the asymmetric unit with multiplicities, and, where the file gives them, the DOI, journal, database codes and measurement temperature. A cell whose composition does not match _chemical_formula_sum with Z is reported as a warning. Cartesian-only sites and magnetic CIFs are refused.

Bilbao Crystallographic Server files

The Bilbao Crystallographic Server (Aroyo et al. 2006) reads and writes structures in its plain BCS format: the space-group ITA number, the lattice parameters, the number of independent atoms, and one line per atom of the asymmetric unit. This is the example from its input pages:

# Space Group ITA number
221
# Lattice parameters (lengths in angstroems and angles in degrees)
5.0 5.0 5.0 90 90 90
# Number of independent atoms in the asymmetric unit
3
# [atom type] [number] [WP] [x] [y] [z]
Ba 1 1a 0.0 0.0 0
Ti 2 1b 0.5 0.5 0.5
O 3 3c 0.5 0.0 0.5

vibe-sketcher solid import-bcs bto.vsk batio3.txt --id bto
vibe-sketcher solid export-bcs al2o3.vsk --structure al2o3 -o al2o3-bcs.txt
vibe-sketcher solid transform-setting bto.vsk --source bto --id bto-2x -t "2a,b,c"
vibe-sketcher solid transform-setting mgo.vsk --source mgo --id mgo-p -t "b/2+c/2,a/2+c/2,a/2+b/2"

The server works in the default setting of each group, which is also the sketcher’s choice for a bare number: origin choice 2 and hexagonal axes. Lines starting with # are labels. The second atom column is kept as a label. A Wyckoff field such as 3c must match the multiplicity of the generated orbit, and - leaves it unchecked; the letter itself is not checked yet (#229). Export writes a structure built from a space group in its default setting (a template, the space-group builder or a BCS file) from its recorded asymmetric unit, with Wyckoff letters from the BCS input or from spglib. Any other 3D structure is first standardised and idealised with the symmetry extra. If spglib’s setting differs from the default only by an origin shift, as with origin choice 1 of I4₁/amd, the origin is moved.

transform-setting describes the same crystal in another basis and origin. It uses the convention of International Tables for Crystallography Vol. A, Section 1.5: the new basis is (a′, b′, c′) = (a, b, c)P, the origin shift p is given in the old coordinates, and x′ = P⁻¹(x − p). It is written a-b,a+b,c;0,0,1/4. det P must be positive. A smaller cell is admitted only when its vectors are translations of the crystal, for example the primitive cell of a face-centred lattice. Bilbao’s own (P,p) syntax was not checked against its help pages, which could not be read when this was written.

Nothing is fetched from the server. Its pages show a Creative Commons BY-NC-SA 4.0 licence for their content, so paste or open files you saved yourself and cite the server as its pages ask.

Prototypes

vibe-sketcher solid prototypes lists the library:

Name	Lattice	Example and default parameters
rocksalt	cF	MgO, a = 4.212
corundum	hR	α-Al₂O₃, a = 4.7602, c = 12.9933, Al 12c z = 0.35216, O 18e x = 0.30624 (Lewis et al. 1982)
fcc, bcc, hcp	cF, cI, hP	Cu, Fe, Mg
diamond, zincblende, wurtzite	cF, cF, hP	Si, GaAs, ZnO
cscl, fluorite, rutile, perovskite	cP, cF, tP, cP	CsCl, CaF₂, TiO₂, SrTiO₃
graphene, hbn	hp	C and BN sheets
chain	l	the H-chain model

The a, c and vacuum values can be overridden. Elements can be renamed: --species Mg=Ca turns rocksalt MgO into CaO. The default lattice constants are room-temperature experimental values. Choose the values your method needs.

Crystal templates

The template library holds standard crystals with literature parameters: elements (fcc, bcc, hcp and diamond structures), rocksalt, CsCl and fluorite halides and oxides, zincblende and wurtzite semiconductors, rutile and anatase, corundum-type sesquioxides, cubic perovskites, spinels, α-quartz, calcite, and layered crystals (graphite, h-BN, MoS₂, WS₂, LiCoO₂). The template list gives every entry with its space group, cell, Z, common surfaces and reference.

vibe-sketcher solid templates
vibe-sketcher solid templates spinel
vibe-sketcher solid templates --category oxides --json
vibe-sketcher solid crystal mgo.vsk --id mgo --template mgo
vibe-sketcher solid crystal al2o3.vsk --id al2o3 --template corundum --cell conventional
vibe-sketcher solid crystal cao.vsk --id cao --template mgo --a 4.811 --species Mg=Ca

A template is found by name, alias (periclase, hematite, quartz) or formula when only one template has it. TiO2 is refused because it names both rutile and anatase. Each template is a space group and an asymmetric unit, expanded as in Space groups. The structure records the template, its reference and any --a, --c or --species override under provenance["builder"]["template"]. The library test builds every template and checks its composition, Z, shortest distance, space group and, where recorded, density. The prototypes above remain for swapping elements into a structure type.

Cell choices

Choice	What it builds
primitive	the primitive cell of the recorded (or given) Bravais type
conventional	the conventional cell; for a centred lattice, a cell with several lattice points
supercell	an integer row-matrix repeat with parent-site and image maps
wigner_seitz	the same lattice with every site moved to its image nearest the origin lattice point
wigner_seitz_supercell	a supercell followed by the Wigner–Seitz placement
standard_conventional, standard_primitive, niggli, delaunay	standardised and reduced cells; these need the symmetry extra (see Finding the space group)

A Wigner–Seitz cell changes where the atoms are drawn, not the lattice or the composition. A periodic calculation therefore sees the same model. A cyclic cluster takes its shape from this placement. Sites that lie exactly on a Wigner–Seitz face are listed in provenance["builder"]["boundary_sites"]. vibe-sketcher solid wigner-seitz prints the Wigner–Seitz polyhedron of a lattice, its vertices and faces in angstrom, for figures.

Slabs

A slab is cut from a three-dimensional bulk structure. The Miller index refers to the rows of that structure’s cell. For example, (0, 0, 1) of the hexagonal conventional corundum cell is the basal (0001) plane. The surface cell is an integer transform of the bulk cell whose first two rows span the plane (Sun and Ceder 2013). For a conventional cell of a centred lattice, the builder first reduces the cell to the primitive one and converts the Miller index with it, so the in-plane cell is the smallest surface cell of the crystal. MgO(100), for example, gets a 2.98 Å square cell rather than the 4.21 Å cubic face. Pass surface_cell="given" (--surface-cell given) to keep the cell you supplied.

Option	Meaning
layers and layer_unit	stoichiometric (default) counts the smallest runs of atomic planes whose composition is a multiple of the bulk formula, such as one Al–O₃–Al unit of α-Al₂O₃(0001). plane counts atomic planes, and cell counts repeats of the oriented bulk cell.
termination	Which atomic plane of one bulk repeat forms the bottom face.
vacuum	The gap in angstrom between the slab and its periodic image along the normal.
repeat	The in-plane repeat, n1,n2 or a 2×2 integer matrix.
fixed_layers	The bottom layers whose sites are listed in provenance["builder"]["fixed_sites"], for optimisers.
periodicity	2d gives a true two-dimensional model (PBC T, T, F); 3d gives a vacuum-padded three-dimensional cell. These are different models.

The builder reports the compositions of the top and bottom planes. It warns when the slab is not stoichiometric or its two faces differ, because such a slab may carry a dipole. It never passivates or neutralises a surface on its own.

Slabs from templates in one step

A slab can be cut straight from a crystal template. The Miller index then refers to the template’s conventional cell: hexagonal axes for rhombohedral groups, so 0001 (or 0,0,1) is the basal plane of corundum. Miller–Bravais indices hkil are accepted with i = −(h + k).

vibe-sketcher solid terminations --template rutile --miller 110
vibe-sketcher solid slab al2o3.vsk --template al2o3 --id al2o3-0001 --miller 0001 \
  --layers 4 --vacuum 15 --repeat 2,2 --fixed-layers 1
vibe-sketcher solid slab tio2.vsk --template rutile --id tio2-110 --miller 110 --layers 3

solid terminations lists every bottom plane of the cut. For each it shows the bottom and top planes, the atom count and thickness, whether the slab is stoichiometric, which terminations give the same slab, and the polarity. It works on a document bulk structure too (DOCUMENT --source ID).

In the browser, Preview terminations applies to the current bulk source or template, Miller index, layer count and layer unit. Changing one of these, or building a new structure, clears the previous list and asks you to preview again. Only the latest request can update the open panel; a late result or error cannot replace the current preview.

Polarity is decided with formal ionic charges, which are defined here only for binary ionic crystals: the anion takes its standard charge (O²⁻, F⁻, S²⁻, N³⁻, …) and the cation balances it. A slab is polar when it has a net formal charge or a dipole along the normal (Tasker 1979). Rutile (110) ending on bridging oxygen and CaF₂(111) ending on fluorine are nonpolar. ZnO(0001) and GaAs(100) are polar. Elements, ternary crystals such as SrTiO₃ and covalent crystals get no verdict.

Without --termination, a template slab takes the first nonpolar termination. Where none is known, it takes the first termination that builds. A polar template slab is refused unless --allow-polar (allow_polar) is given. A slab cut from a document structure keeps termination 0 and is never refused for polarity. The verdict is recorded under provenance["builder"]["polarity"], and the template under provenance["builder"]["template"]. solid add-layers rebuilds the template bulk when it adds layers to such a slab.

Adsorbates

An adsorbate comes from SMILES (embedded with ETKDG and MMFF94), from a drawn document species (its first conformer, or its SMILES), or from explicit atoms. It is placed above the top face:

• site: top of an anchor surface site, the default being the top-layer site nearest the cell centre. Also bridge (midway to the nearest top-layer neighbour), hollow (the centroid with the two nearest neighbours), or position (an in-plane fractional position).

• height: the vertical distance from the site to the adsorbate’s lowest atom, or to the atom numbered attach.

• orientation: flat puts the molecular plane parallel to the surface, upright puts the long axis along the normal, and as-is keeps the given frame. rotate turns the molecule about the normal.

A placement closer than min_distance (1.2 Å) to the slab is refused, and so is one closer than 1.6 Å to the adsorbate’s own periodic image. Use a larger repeat for the second case. Each placement is recorded under provenance["builder"]["adsorbates"].

Defects

Defects are applied to named sites of a pristine structure: vacancy (remove a site), substitution (replace its element) and interstitial (add an element at a fractional position at least 0.7 Å from every atom). The pristine structure’s ID, the defect list and the stoichiometry change are recorded. The charge and spin are only what you state. They are never inferred from the defect.

Periodic nanotubes

kind: "nanotube" builds a periodic carbon nanotube cell: one or more translation periods of a single- or multi-walled tube along z, with the same chiral-vector construction as the finite nanotubes. The x and y vectors are not periodic. They hold the outer diameter plus vacuum (default 10 Å) and the tube axis sits in their middle.

Field	Meaning
type	armchair (n,n), zigzag (n,0) or chiral (n,m)
n, m	Chiral indices; m only for chiral, with 0 ≤ m ≤ n
outer_walls	Further walls {n, m}, each 0.30–0.40 nm outside the last
periods	Translation periods of the innermost wall in the cell (default 1)

A (5,5) cell has 20 carbons and c = 2.4595 Å; a (10,0) cell has 40 carbons and c = 4.260 Å. Every carbon has three bonds, and bonds across the cell boundary along z record their lattice image. A multi-walled cell needs walls whose periods are in a whole-number ratio, which means all armchair or all zigzag walls. Other combinations are incommensurate and are refused rather than strained. The cell is neutral with the lowest multiplicity the electron count allows, which is not a ground-state prediction. The finite nanotube’s descriptive periodic record remains separate from these physical cells.

Nanotubes rolled from a layer

kind: "rolled_nanotube" rolls any two-dimensional structure of the document into a periodic tube. The source can be a sheet such as the graphene or hbn prototype, a custom plane lattice with a multi-plane motif (an MX2 layer, for example) or a slab cut with periodicity: "2d". This follows the construction CRYSTAL uses for inorganic nanotubes (Noël et al., J. Comput. Chem. 31, 855, 2010).

Field	Meaning
source	A 2D structure: periodic along a1 and a2, not a3
n, m	The rolling vector R = n a1 + m a2, which becomes the circumference
indices	lattice (default): n and m count the source’s own a1 and a2, as CRYSTAL’s input does. nanotube: the carbon convention for a hexagonal layer, with a1 and a2 60° apart, so (n,n) is armchair and (n,0) zigzag in either hexagonal setting
periods	Tube periods in the cell (default 1)
vacuum	Gap between tube images, default 10 Å
inward_normal	Roll with the layer’s +normal side facing the axis

The tube period is the shortest layer vector perpendicular to R. An oblique layer whose metric has no such vector is refused, because the tube would not be periodic. The radius is |R|/2π for the layer’s middle surface. An atom at height h above that surface sits at radius |R|/2π + h, so outer planes are stretched and inner planes compressed along the circumference. Relax before reading geometry from the tube. Rolled graphene reproduces the carbon tubes above: the same atom count, radius and period for every (n,m). Each site records its layer site as parent_site. Bonds are not carried over from the layer, and tubes thinner than 0.4 nm are refused.

Metal-organic frameworks

kind: "framework" assembles a metal-organic framework (MOF) from a node, a ditopic dicarboxylate linker and the net they imply (Yaghi et al. 2003). Each carboxylate’s O-C-O plane is shared by the node and the linker it binds. The lattice constant follows from the construction. The edge is twice the distance from the node centre to the carboxylate carbon, plus the linker’s carboxylate C…C distance.

Node	Net	Metals	Cell
zn4o: Zn4O(CO2)6 (MOF-5, IRMOF series)	pcu	Zn	conventional (cubic, 8 clusters) or primitive (2 clusters)
paddlewheel: M2(CO2)4	sql layer with vacuum (default 15 Å); pcu with a pillar	Cu (default) or Zn	one paddlewheel

Linkers are bdc (terephthalate), bpdc (biphenyl-4,4′-dicarboxylate), tpdc (p-terphenyl-4,4″-dicarboxylate), or any linear dicarboxylic acid given as linker_smiles. A SMILES linker is embedded with RDKit (ETKDG v3, then MMFF94) under a fixed seed. Both carboxylate bonds must lie within 15° of the axis through the carboxylate carbons, so isophthalate is refused. The acid groups become the node’s carboxylates. The dabco and bipyridine pillars bind the paddlewheel’s axial sites and make a three-dimensional framework.

Neighbouring Zn4O clusters are related by inversion, so both ends of a linker see the same carboxylate plane. That is why the conventional MOF-5 cell is the doubled Fm-3m cube. Rings of the preset linkers are coplanar. When a SMILES linker’s two carboxylate planes disagree, the build records a note. Bonds, including the metal–oxygen and metal–nitrogen bonds, come from the construction. The built cells are close to the measured ones:

Framework	Built a (Å)	Measured a (Å)
MOF-5 (zn4o, bdc)	25.93	25.832 (Li et al., Nature 402, 276, 1999)
IRMOF-8 (zn4o, 2,6-naphthalenedicarboxylic acid as SMILES)	30.33	30.0915 (Eddaoudi et al., Science 295, 469, 2002)
DMOF-1 (paddlewheel, Zn, bdc, dabco)	10.95, c = 9.72	10.93, c = 9.61 (Dybtsev, Chun and Kim, Angew. Chem. Int. Ed. 43, 5033, 2004)

These are unrelaxed starting geometries. Frameworks are neutral by construction. Zn(II) nodes are closed-shell (multiplicity 1). The spin of coupled Cu(II) paddlewheels is left unspecified, because the builder does not predict it. Open paddlewheel layers have empty axial sites, where real layers carry ligands or solvent. Other nets and nodes, net-edge records and interpenetration are not built yet. solid frameworks lists the nodes, linkers and pillars.

Editing a structure

Every edit replaces the structure under its ID, unless you pass a new identifier (--id). Each edit is appended to provenance["builder"]["edits"]. An edit that puts two atoms, or an atom and its periodic image, closer than 0.5 Å is refused.

• Cell parameters (edit_cell, solid edit-cell): set a, b, c (Å) and alpha, beta, gamma (degrees, α = ∠(b, c), β = ∠(a, c), γ = ∠(a, b)), or scale every periodic length. The cell keeps its orientation. With keep="fractional" the atoms move with the cell, which strains the structure. With "cartesian" they stay where they are. Along a nonperiodic direction an atom always keeps its distance from the middle of that vector, so a slab is never stretched. vacuum sets the gap above a 2D slab. If you change an angle of a cell built from a Bravais type, the edit records that the cell may no longer have that symmetry.

• Select and move (move_sites, solid move): select sites by ID, by element, by slab layer (0 is the bottom), by adsorbate (index or label) or by a height window. Translate the selection in Å or in cell fractions, and/or rotate it by an angle about an axis through its centroid. The default axis is the slab normal, z.

• Set sites (set_sites, solid set-site): give named sites a new fractional or Cartesian position, or a new element.

• Add slab layers (add_layers, solid add-layers): add layers on top of a slab made by the slab builder. The slab is cut again from its recorded bulk source with the same Miller index, layer unit, termination and repeat. The existing sites stay where they are, including any you moved or edited. The new layers go above the old top layer, adsorbates rise with the surface, and the normal vector grows by the added thickness. If the in-plane cell was edited since the cut, the request is refused: rebuild the slab instead.

Showing a structure in vibe-viewer

solid view (REST POST /api/documents/{id}/periodic/{structure}/view, MCP view_periodic, and Show in vibe-viewer (3D) in the panel) sends the structure to vibe-viewer as a QVF of its own. The file holds the sites in angstrom, the lattice row vectors, the PBC mask and the dimensionality, plus the full typed record. vibe-viewer draws it in 3D with its unit cell; for a slab or a wire it draws only the periodic edges. Delivery follows the same two routes as for molecules. If vibe-viewer started this sketcher, the structure goes to the open viewer. Otherwise vibe-view open starts one. Without vibe-viewer the request is refused with an installation hint.

Dragging into vibe-viewer

You can drag Drag to vibe-viewer in the panel, or Drag to 3D on a species card with a 3D structure, onto a vibe-viewer window or tab. The structure opens there in 3D, with the same file Show in vibe-viewer sends.

• Desktop app: the drag is a native file drag, so a drop on the viewer’s window or dock icon, or into a folder, works.

• Browser: the drag carries a link (application/x-vibe-structure, schema vibe-structure-drag/1). A vibe-viewer build with drop support fetches it from this server. In Chromium, a drop on the desktop saves the file.

Hovering over the handle prepares the drag: the server writes the QVF under ~/.cache/vibe-sketch/views/drag/ and issues a ten-minute link, POST /api/documents/{id}/drag with structure or species. That link serves the bytes only to pages on this machine. The desktop app drags only files from that folder.

Publication figures

solid figure (REST POST /api/documents/{id}/periodic/{structure}/figure, MCP periodic_figure, and Publication figure in the panel) draws a periodic structure as SVG, or as PDF or PNG with the publication extra. The structure stays a full 3D model with its lattice vectors, periodicity and cells. A figure is a 2D projection or schematic drawn from that model for paper, and it never changes the structure or the inputs. For the full 3D view, hand the same model to vibe-viewer.

Option	Meaning
view	top (along −z), side (along +y), front (along −x), isometric, uvw (along the real-space direction direction) or hkl (along the normal of the plane direction)
repeat	Display repeats along the periodic directions. These are drawing only and never change the model, and the figure says so.
complete_boundary	Draw atoms on a cell face on the opposite face too (default on), as crystallographic figures do
cell, vectors	The edges of the periodic cell, and a, b, c with their lengths. A slab or wire has only its periodic edges.
bonds	Bonds from covalent radii (Cordero et al. 2008) within 1.15 × the sum, across cell boundaries
plane	A Miller plane (hkl), drawn where it cuts the unit cell (3D cells)
wigner_seitz	The real-space Wigner–Seitz cell of the lattice point at the origin, dashed
brillouin	A second panel with the first Brillouin zone, the Wigner–Seitz cell of the reciprocal lattice, with b₁, b₂, b₃ in 1/Å and the convention b_i · a_j = 2π δ_ij
labels, legend, scale_bar, width	Element or site labels, the element key, an ångström scale bar, and the width
heights	The height of each atom along the view, written beside it as in crystallographic projections: a fraction of the lattice period along the view (0, ½, ¼) or, where the view is not a lattice direction (across a slab’s vacuum), ångström above the lowest atom. Atoms that coincide in projection share one label.
depth_cue	Atoms further from the viewer drawn smaller and paler
polyhedra	Elements whose coordination polyhedra are shaded, e.g. ["Ti"]. The polyhedron is the convex hull of the bonded atoms of other elements (the bond rule above), across cell boundaries.
layers	Slab side views: layers numbered from the bottom, fixed layers marked “(fixed)” and fixed atoms with dashed outlines, and the vacuum stated below
stacking	Slab side views: stacking letters A, B, C, … of the atomic planes. Planes get the same letter when their in-plane positions coincide modulo the surface lattice; planes closer than a line of text share one label, such as C/A.
symmetry_elements	The symmetry elements of the space group in a view along a, b or c of a 3D crystal, in the style of the International Tables diagrams. Axes parallel to the view are drawn as filled lens, triangle, square or hexagon glyphs, with the screw number beside a screw axis. Rotoinversions are open rings with a dot, labelled with their height. Mirrors are solid lines and glide planes dashed (glide in the plane of the drawing), dotted (glide along the view) or dash-dotted (n, d and g glides). Inversion centres are small open circles. Planes perpendicular to the view are listed at the top-left corner with their heights. The group comes from the structure’s record (a template, the space-group builder, a CIF or BCS file in its conventional cell) or is detected with spglib. Elements oblique to the view, such as the cubic threefold axes, are not drawn, and the figure counts them.
inplane_axes	With symmetry_elements: the twofold axes lying in the plane of the drawing, as thin lines with arrows (one arrow for a 2₁)
labels="wyckoff"	Each atom labelled with its multiplicity and Wyckoff letter in the standard setting, such as 4f (spglib)
symprec	The spglib length tolerance in Å (default 0.001)

The camera is right-handed: screen right × screen up points towards you. Atoms use the Jmol colours. Text and strokes scale with the drawing, so a 2.5 Å cell and a 20 Å slab read alike.

vibe-sketcher solid figure cu.vsk --structure cu --view isometric --wigner-seitz --brillouin -o fcc.svg: the fcc Wigner–Seitz cell (a rhombic dodecahedron) and the first Brillouin zone (a truncated octahedron).

--view side --repeat 2,1,1 on the benzene/Al₂O₃(0001) slab.

vibe-sketcher solid figure tio2.vsk --structure tio2 --view top --repeat 2,2,1 --heights --polyhedra Ti -o rutile.svg: edge-sharing TiO₆ octahedra, with heights in units of c = 2.959 Å.

--view side --layers --stacking on a six-layer Cu(111) slab with two fixed layers: the ABC stacking of a face-centred cubic metal.

vibe-sketcher solid figure tio2.vsk --structure tio2 --view top --symmetry-elements --labels wyckoff --no-bonds -o p42mnm.svg: the symmetry elements of P4₂/mnm projected along c, with Ti on 2a and O on 4f.

Adsorption, surface and defect energies

solid energy plan (REST POST /api/documents/{id}/periodic/energy/plan, MCP plan_solid_energy) fixes the members of an energy difference. It writes one vibe-qc input per member with the same Hamiltonian, plus the plan (KIND-plan.json), which records the formula, the normalisation and every assumption. solid energy evaluate (REST POST /api/periodic/energy/evaluate, MCP evaluate_solid_energy) reads each member’s result QVF. It checks that the run converged, that its composition is the planned structure’s and that its method is the planned one, then returns the energy. A gas-phase molecule is computed as a molecule with the same method and basis; SECCM members pair with molecular MSINDO.

Kind	Formula	Members	Refused when
adsorption	E_ads = [E(slab + n X) − E(slab) − n E(X)] / n, in eV and kJ/mol	--complex, --slab, --gas species	the complex was not built on that slab, the cells differ, or the composition difference is not a whole number of X
surface	γ = [E(slab) − N E(bulk cell)] / (2A), in J/m² and eV/Ų	--slab, --bulk (and --bulk-kmesh)	the slab is not stoichiometric with identical faces, or not a whole multiple of the bulk cell
defect	E_f = E(defective) − E(pristine) − Σ Δn_i μ_i, in eV	--defective, --pristine, --reservoir per changed element	a reservoir is missing, or the defect is charged

A reservoir is a stated value with its source (--reservoir O=-4.9@source) or a gas species and its atom count (--reservoir O=o2/2, so μ_O = E(O₂)/2). Charged defects are refused. They need a Fermi level, potential alignment and a finite-size correction (Freysoldt, Neugebauer and Van de Walle 2009), and the plan does not supply those rather than report an uncorrected number. The plan records k-mesh, slab thickness, vacuum and cluster size but does not converge them, and it uses geometries as built: relax them first.

vibe-sketcher solid energy plan ads.vsk --kind adsorption --complex benzene --slab slab \
  --gas m1 --model seccm --max-iter 1000 -o energy
vibe-sketcher solid energy evaluate energy/adsorption-plan.json \
  --result complex=complex-benzene-seccm.qvf --result slab=slab-slab-seccm.qvf \
  --result gas=gas-m1.qvf

For flat benzene drawn 3.0 Å above the three-layer α-Al₂O₃(0001) 2×2 slab, unrelaxed, the three SECCM/MSINDO runs (vibe-qc 0.18.12) give E_ads = +0.90 eV. That is repulsive at this fixed geometry, which is why the plan says to relax first.

vibe-qc inputs

vibe-sketcher solid input writes a Python script for one periodic structure. Run it with vibeqc run NAME.py. The script lists the lattice rows and atoms in angstrom and converts them to bohr with CODATA 2018. It builds a vq.PeriodicSystem from lattice_vectors=[a1, a2, a3], which avoids any row/column ambiguity. Four models are available:

Model	What it runs	Dimensions
pbc	run_periodic_job with HF (--method hf) or a functional (--method pbe), a basis set and a J/K route. BIPOLE is the default for 3D cells. vibe-qc’s automatic route, a true 2D or 1D Coulomb treatment, is the default otherwise.	1D, 2D, 3D
seccm	the semiempirical cyclic cluster model (MSINDO), closed-shell single points. The cell’s atoms are the cluster, and its periodic vectors are the translations: CCM1D, CCM2D or CCM3D.	1D, 2D, 3D
aiccm	the ab initio cyclic cluster model, with an explicit --variant (real-gamma, neutral-bloch, four-center, chi) and a Born–von Kármán torus --extension n1,n2,n3	3D (vibe-qc#1089 tracks 1D/2D)
mace	a periodic MACE single point, or with --task opt a positions (or --mace cell) optimisation	1D, 2D, 3D

k-points are a PBC concept. --kmesh n1,n2,n3 gives a Γ-centred mesh by default. --kmesh-kind monkhorst-pack gives the Monkhorst–Pack mesh, which skips Γ for even meshes. Without --kmesh, the job is Γ-only. Nonperiodic directions must stay at 1. A cyclic cluster samples the Brillouin zone through the size of the cluster, so seccm and aiccm take no mesh. Use a wigner_seitz_supercell for the cluster.

--mace positions adds a periodic MACE pre-optimisation before any model. It keeps fixed the sites the slab builder marked (fixed_layers) and any fixed_sites of the spec. --mace cell relaxes a 3D cell without fixed atoms instead. The relaxed system goes straight into the main job. A cluster model then uses the relaxed cell as its cluster. The model is named explicitly (--mace-model, default medium-mpa-0). --accept-mace-license records that you accept the academic licence of the weights; it is never set for you. Without MACE installed, the script stops with vibe-qc’s installation hint.

The writer refuses what vibe-qc cannot run, with a reason. Today that covers:

• BIPOLE on a true 2D or 1D model;

• AICCM below three dimensions;

• open-shell or optimisation SECCM;

• k-points on a cluster model;

• an odd electron count for the stated multiplicity;

• partial occupancies;

• MACE cell relaxation with fixed atoms or below three dimensions.

--max-iter raises the SCF iteration budget; some SECCM slabs need about 1000 iterations. --spec spec.json takes a whole PeriodicJobSpec instead of the options.

SECCM and AICCM are experimental in vibe-qc, and the scripts say so. A script that runs shows that the input is valid. It does not show convergence. Converge the k-mesh, cluster size, slab thickness and vacuum yourself.

In the browser

Choose Solid-state builder… from the command palette (Ctrl/Cmd+K). The panel has one form per step: crystal, framework (MOF), periodic nanotube, rolled nanotube, cell choice, slab, adsorbate, defects and vibe-qc input. Import ▸ MOF or nanotube cell… opens the same panel at the framework form. Each form adds a new periodic structure to the document through the same REST recipes. After a build, every source list moves to the new structure, so the steps chain without re-selecting. Adsorbates can come from a species drawn on the canvas or from SMILES. The preview shows a schematic top or side projection of the chosen structure, with its formula, its dimensionality and any warnings the builder recorded. It is an aid to orientation, not a 3D viewer; detailed 3D work stays in vibe-viewer. Download input saves the vibe-qc script. A request the writer refuses shows its reasons in the panel.

Below the preview, Edit the previewed structure fills in the current cell parameters for editing. Click atoms in the preview to select them; shift-click adds atoms. You can also select by element or slab layer, or choose the last adsorbate. Drag a selected atom to move the whole selection in the plane of the view (x, y from the top, x, z from the side), or type a translation and a rotation about the normal. Add layers grows a builder slab, and Show in vibe-viewer (3D) hands the structure over.

Command line

vibe-sketcher solid crystal mgo.vsk --id mgo --prototype rocksalt
vibe-sketcher solid cell mgo.vsk --source mgo --id mgo-conv --choice conventional
vibe-sketcher solid cell mgo.vsk --source mgo --id mgo-ws --choice wigner_seitz_supercell \
  --matrix 2,2,2
vibe-sketcher solid crystal tio2.vsk --id tio2 --bravais tP --a 4.594 --c 2.959 \
  --site Ti:0,0,0 --site O:0.3048,0.3048,0 \
  --op x,y,z --op -x,-y,z --op -y+1/2,x+1/2,z+1/2 --op y+1/2,-x+1/2,z+1/2 \
  --op -x+1/2,y+1/2,-z+1/2 --op x+1/2,-y+1/2,-z+1/2 --op y,x,-z --op -y,-x,-z \
  --cell conventional
vibe-sketcher solid wigner-seitz mgo.vsk --structure mgo
vibe-sketcher solid crystal al2o3.vsk --id al2o3 --prototype corundum --cell conventional
vibe-sketcher solid slab al2o3.vsk --source al2o3 --id slab --miller 0,0,1 --layers 3 \
  --repeat 2,2 --fixed-layers 1
vibe-sketcher solid adsorb al2o3.vsk --source slab --id benzene --smiles c1ccccc1 --height 3.0
vibe-sketcher solid defect al2o3.vsk --source slab --id vac --vacancy O1 --charge 0
vibe-sketcher solid edit-cell al2o3.vsk --structure slab --vacuum 20
vibe-sketcher solid move al2o3.vsk --structure benzene --adsorbate 0 --by 0,0,0.2 --rotate 30
vibe-sketcher solid add-layers al2o3.vsk --structure benzene --count 2
vibe-sketcher solid view al2o3.vsk --structure benzene
vibe-sketcher solid input mgo.vsk --structure mgo --method pbe --basis pob-tzvp --kmesh 4,4,4
vibe-sketcher solid input mgo.vsk --structure mgo-ws --model seccm --method msindo
vibe-sketcher solid input mgo.vsk --structure mgo --model aiccm --variant four-center \
  --extension 2,2,2
vibe-sketcher solid input al2o3.vsk --structure benzene --method pbe --mace positions
vibe-sketcher solid nanotube cnt.vsk --id cnt --armchair 10 --periods 4
vibe-sketcher solid nanotube cnt.vsk --id dwnt --armchair 5 --outer-wall 10,10
vibe-sketcher solid nanotube cnt.vsk --id chiral --chirality 6,3
vibe-sketcher solid crystal bn.vsk --id bn --prototype hbn
vibe-sketcher solid roll bn.vsk --source bn --id bnnt --chirality 10,10 --indices nanotube
vibe-sketcher solid framework mof.vsk --id mof5 --node zn4o --linker bdc
vibe-sketcher solid framework mof.vsk --id irmof8 --node zn4o \
  --linker-smiles 'OC(=O)c1ccc2cc(C(=O)O)ccc2c1'
vibe-sketcher solid framework mof.vsk --id dmof --node paddlewheel --metal Zn \
  --linker bdc --pillar dabco

The solid crystal, solid nanotube and solid framework commands create the document when it does not exist yet. solid build DOCUMENT --recipe recipe.json applies any recipe written as JSON.

Python

from vibesketcher.document import new_document
from vibesketcher.document.solid_build import CellRecipe, CrystalRecipe, build

doc = build(new_document(), CrystalRecipe(identifier="al2o3", prototype="corundum"))
doc = build(doc, CellRecipe(identifier="al2o3-hex", source="al2o3", choice="conventional"))

The lower-level functions live in vibesketcher.document.crystal: prototype, build_crystal, primitive_cell, wigner_seitz_cell and wigner_seitz_polyhedron. NanotubeRecipe, RolledNanotubeRecipe and FrameworkRecipe build periodic nanotubes and frameworks the same way. Their builders are vibesketcher.chem.nanotube_cells.build_nanotube_cell, vibesketcher.chem.rolled_tubes.roll_layer and vibesketcher.chem.frameworks.build_framework.

REST and MCP

• POST /api/documents/{id}/periodic/build takes revision and recipe.

• GET /api/documents/{id}/periodic/{structure}/wigner-seitz returns the polyhedron.

• GET /api/periodic/prototypes lists the library.

• POST /api/documents/{id}/periodic/import-cif takes revision, text, identifier and the import options; the MCP tool is import_cif.

• POST /api/documents/{id}/periodic/import-bcs (text, identifier), GET /api/documents/{id}/periodic/{structure}/bcs and POST /api/documents/{id}/periodic/transform-setting (source, identifier, transformation); the MCP tools are import_bcs, export_bcs and transform_setting.

• GET /api/periodic/templates?query=&category= searches the crystal templates; a crystal recipe takes template with optional a and c.

• A slab recipe takes template (with template_a, template_c) instead of source, and allow_polar. GET /api/periodic/templates/{name}/terminations?miller=1,1,0&layers=1 and GET /api/documents/{id}/periodic/{structure}/terminations?miller= preview the terminations; the MCP tool is slab_terminations.

• POST /api/documents/{id}/periodic/edit takes revision and edit (kinds edit_cell, move_sites, set_sites, add_layers), and GET /api/documents/{id}/periodic/{structure}/cell returns the cell parameters.

• GET /api/periodic/frameworks lists the framework nodes, linkers and pillars.

• GET /api/documents/{id}/periodic/{structure}/symmetry?symprec=0.001 returns the space-group report, or 503 without the symmetry extra.

• POST /api/documents/{id}/periodic/{structure}/input takes spec and returns the files, or 422 with the refusal reasons.

The MCP tools build_periodic, wigner_seitz, periodic_prototypes, periodic_frameworks, periodic_templates, periodic_symmetry, write_periodic_input, edit_periodic and view_periodic call these routes. In Python, use vibesketcher.inputs.vibeqc_periodic.write_periodic_input(structure, spec), and vibesketcher.document.solid_edit for the edits.