vibe-sketcherDocumentation

Interfaces, stacking faults and extended defects

vibe-sketcher builds two kinds of extended-defect model from structures you already have. kind: "interface" joins two slabs into a heterointerface on a commensurate in-plane cell. kind: "stacking_fault" displaces part of a close-packed stack. Grain boundaries and dislocations are planned only: you can record a complete plan for one, but no atoms are placed.

Every model is an unrelaxed starting geometry. Building one is not relaxation, and it says nothing about thermodynamic stability, adhesion, interface or fault energy, or band alignment. Each record lists these under not_claimed. It also lists the strain and size convergence that a calculation on the model still owes, under convergence_requirements.

Browser workflow

Choose Import → Interface or stacking fault…, or search the command palette for Interface. The solid-state panel opens at the heterointerface form. All controls are native labelled inputs, selectors and buttons; the menu, cell choices, preview and build actions are reachable by keyboard.

For a heterointerface:

  1. Build or import the two parent slabs/layers first, then choose Bottom phase and Top phase. Enter a new structure ID.

  2. Set the maximum cell area, mismatch percentage, twist and twist tolerance. Leave twist empty to search all rotations. Flip the top phase chooses which face meets the substrate.

  3. Choose Find coincidence cells and select a result. The choices show mismatch, atom count, area, rotation and both integer matrices. Alternatively, enter the two matrices directly, for example 1,0;0,1 for each.

  4. Choose Strain allocation explicitly. The default None refuses a mismatched cell. Keep bottom lattice; strain top is suitable when you deliberately hold the substrate fixed; it is not selected automatically. Weighted sharing enables a top-lattice weight.

  5. Set the translation, gap, minimum allowed contact and atom limit. A 2-D model uses vacuum; a 3-D repeated stack enables the second interface gap and contains two interfaces per cell.

  6. Choose Preview interface. Inspect the schematic side projection, site count, periodicity, per-phase strain and closest contact. Expand the convergence requirements before planning calculations. Build reviewed interface adds the reviewed structure and selects it in the panel.

For a stacking fault, use the Stacking fault form in the same panel. Choose either a crystal template (Cu by default) or a document bulk structure, then the Miller index, number of atomic planes, fault type, boundary condition and separation bounds. Explicit shift enables a fractional displacement; Slab with free surfaces enables vacuum. Preview fault reports the stacking sequence when defined and distances to the periodic image or free surfaces. Build reviewed fault inserts that model.

A preview does not change the document. Changing any form input discards the review and disables its build button. Changing search inputs also clears old coincidence-cell choices. Responses arriving after a form change or panel close are ignored. A build checks the captured document, drawing and revision again; a remote edit or document switch refuses it instead of redirecting it. Correct a refused input and preview again; after a document switch, close the panel and reopen it on the intended document. Existing parent structures are preserved. The server records the same recipe and provenance used by SDK, CLI and MCP.

After building, the panel’s existing structure controls provide publication views, input writing and QVF/viewer handoff. These are starting models: browser access does not add a relaxation, energy, stability or interface-overlay claim.

Heterointerfaces

An interface needs two parent slabs in the document, a bottom one (the substrate) and a top one (the overlayer). A parent is any slab-like cell: its a and b lie in the surface plane and c points along the normal. Slabs cut with kind: "slab" qualify (see Slabs), and so do 2-D layers such as a honeycomb_stack monolayer. Bulk cells with less than 3 Å of vacuum along the normal are refused.

Strain allocation

On a mismatched cell one or both phases must be strained, and you decide which. strain_allocation is required whenever the mismatch is not zero.

strain_allocation

Lattice kept

Phase strained

none (default)

refuses any mismatch

none

bottom

the bottom phase’s

the top phase

top

the top phase’s

the bottom phase

mean

halfway between

both, about equally

weighted

top_weight of the way to the top lattice

both

The record stores each phase’s strain tensor in the interface frame. This is the left stretch tensor minus the identity (the Biot strain). The record also stores the principal strains, the largest absolute strain and the area change. Only the in-plane lattice is strained. The normal direction is left as it was, so no Poisson response is applied.

Registry, gap and stacking

  • translation: shifts the top phase in-plane, in fractions of the interface cell. Default [0, 0].

  • gap: required. The normal distance from the highest bottom atom to the lowest top atom, in ångström.

  • top_flip: turns the top slab over, so that its recorded top termination faces the interface. The bottom slab’s top termination always faces it. The record names the termination composition facing the interface for both phases.

  • periodicity: "2d" (PBC T, T, F) adds vacuum above the stack. "3d" repeats the stack along the normal with periodic_gap between the top phase and the next bottom image. A 3-D cell holds two interfaces, and the record says so.

  • min_distance: the closest interphase contact allowed. A build with a closer contact is refused.

Each site of the interface records its phase, its parent structure and parent site, and the lattice image it came from. The table is in site_map, and each site’s parent_site and image fields carry the same information. The charge is the sum of the parents’ stated charges, or none when either is unstated. No compensating charge is chosen and the spin is left unset. Bonds of the parents are not carried over. Perceive them with the periodic graph tools.

vibe-sketcher solid slab ag-mgo.vsk --template mgo --id mgo --miller 0,0,1 --layers 2
vibe-sketcher solid slab ag-mgo.vsk --template ag --id ag --miller 0,0,1 --layers 3
vibe-sketcher solid interface ag-mgo.vsk --id ag-on-mgo --bottom mgo --top ag \
  --gap 2.5 --strain-allocation bottom --preview
vibe-sketcher solid interface ag-mgo.vsk --id ag-on-mgo --bottom mgo --top ag \
  --gap 2.5 --strain-allocation bottom

Cube-on-cube Ag(001) on MgO(001) is a 1 × 1 cell with seven atoms. Ag is strained by 3.08 % to the MgO lattice.

Stacking faults

A stacking fault is built in a bulk crystal: a structure in the document (source) or a crystal template (template, for example cu). The bulk is oriented on the fault plane miller (default (111)) with the slab surface transform, and planes atomic planes are stacked along the normal. The planes from fault_plane upwards (the middle plane by default) are then displaced rigidly in-plane. This is the generalised stacking-fault construction of Vitek (Philos. Mag. 18, 773, 1968).

fault

Displacement

intrinsic

one stacking offset above the fault: ABC|BCA, one plane missing

extrinsic

one offset above the fault and a second above the next plane: one plane inserted

shift

the explicit displacement, in fractions of the surface cell

The stacking offset is measured from the stack itself. For intrinsic and extrinsic the stack must be ABC close-packed: equal planes, each the one below moved by one offset, with three offsets making a lattice vector. In fcc (111) the offset is the Shockley partial a/6 ⟨112⟩, of length a/√6 (Hirth and Lothe, Theory of Dislocations, 2nd ed., 1982). Other stacks are refused for the named faults and need shift.

model: "periodic" (the default) tilts c by the total displacement, so each cell holds exactly one fault. The fault must be at least min_image_separation (10 Å by default) from its periodic image. model: "slab" adds vacuum, and the fault must be at least half that distance from each free surface. repeat replicates the cell in-plane. The record gives the ABC sequence and Frank’s h/c notation. An intrinsic fault shows two adjacent h planes, and an extrinsic fault shows hch.

vibe-sketcher solid stacking-fault cu.vsk --id cu-isf --template cu --fault intrinsic
vibe-sketcher solid stacking-fault cu.vsk --id cu-esf --template cu --fault extrinsic \
  --planes 15
vibe-sketcher solid stacking-fault cu.vsk --id cu-usf --template cu --fault shift \
  --displacement 0.1667,0.1667

The Cu intrinsic fault has 12 planes, a displacement of 1.476 Å and 25.0 Å between the fault and its image. Every atom keeps twelve nearest neighbours at a/√2, as a stacking fault should. The displacement is rigid. Relax the positions, at least along the normal, before reading a fault energy.

Grain boundaries and dislocations

plan_extended_defect (CLI solid plan-defect SPEC.json) records a plan and builds nothing. A missing assumption is refused with a stable code, never filled in with a default.

  • A grain boundary (kind: "grain_boundary") needs rotation_axis, misorientation_deg or sigma, boundary_plane, boundary_type (tilt, twist or mixed), boundary_conditions (periodic_bicrystal or vacuum_bicrystal) and translation (or "sampled").

  • A dislocation (kind: "dislocation") needs burgers_vector (fractions of the bulk cell rows) and line_direction. It also needs boundary_conditions (dipole_periodic, quadrupole_periodic, cylinder_fixed_boundary or slab_free_surfaces) and elastic_model: isotropic with poisson_ratio, anisotropic with the 6 × 6 elastic_constants_gpa, or none. Finally it needs core_model. An optional glide_plane must contain both the line and the Burgers vector.

Both need the bulk as source or template. A complete dislocation plan records the Burgers vector in ångström, its length, its screw and edge components and the character. For example, b = a/2 [1 -1 0] along [1 1 -2] in copper is an edge dislocation with a Burgers vector of 2.556 Å.

{"kind": "dislocation", "template": "cu", "burgers_vector": [0.5, -0.5, 0],
 "line_direction": [1, 1, -2], "glide_plane": [1, 1, 1],
 "boundary_conditions": "quadrupole_periodic", "elastic_model": "isotropic",
 "poisson_ratio": 0.34, "core_model": "unspecified"}

Building coincidence-site-lattice bicrystals and elastic dislocation fields is planned and not available yet.

Viewer, QVF and writers

Interfaces and stacking faults are ordinary periodic structures. The .vsk and QVF documents round-trip them exactly, including the full record. periodic_qvf sends one to vibe-viewer with one QVF atom per site in site order, the site ID as the atom name, and the lattice, PBC and charge. The vibe-qc periodic writer and the CIF, POSCAR, extended XYZ and GEN exports apply their usual refusals.

Python, REST and MCP

from vibesketcher.document import new_document
from vibesketcher.document.interfaces import interface_matches
from vibesketcher.document.solid_build import build, parse_recipe

doc = new_document()
for recipe in (
    {"kind": "honeycomb_stack", "identifier": "hbn", "layers": [{"material": "hbn"}]},
    {"kind": "honeycomb_stack", "identifier": "gr"},
):
    doc = build(doc, parse_recipe(recipe))
print(interface_matches(doc, "hbn", "gr", max_area=60)["candidates"][0])
doc = build(
    doc,
    parse_recipe(
        {
            "kind": "interface",
            "identifier": "gr-hbn",
            "bottom": "hbn",
            "top": "gr",
            "gap": 3.35,
            "strain_allocation": "bottom",
        }
    ),
)
  • POST /api/documents/{id}/periodic/build builds interface and stacking_fault recipes, with the revision checked and the build recorded as an edit. The MCP tool is build_periodic.

  • POST /api/documents/{id}/periodic/interface/matches (bottom, top, max_area, max_strain, twist_deg, angle_tolerance_deg, top_flip, max_candidates) ranks coincidence cells. The MCP tool is interface_matches.

  • POST /api/documents/{id}/periodic/extended/preview (recipe, structure) previews a build without storing it. The MCP tool is preview_extended_defect.

  • POST /api/periodic/extended-defects/plan (plan, optional document) plans a grain boundary or dislocation. The MCP tool is plan_extended_defect.