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:
Build or import the two parent slabs/layers first, then choose Bottom phase and Top phase. Enter a new structure ID.
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.
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,1for each.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.
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.
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.
Coincidence search¶
The two in-plane lattices rarely match. The search follows Zur and McGill
(J. Appl. Phys. 55, 378, 1984, doi:10.1063/1.333084). It enumerates every
superlattice of each phase up to max_area (square ångström) as an integer
Hermite normal form matrix. Pairs of equal area are compared, and the pairs
whose principal mismatch is at most max_strain are kept. The mismatch is the
largest principal strain the top phase needs to fit the bottom lattice.
twist_deg fixes the rotation of the top phase about the normal (0 by
default, so the parents’ a axes are aligned). Set it to null (--twist any) to admit every rotation. Rotations that differ by a point rotation of
either lattice count as the same orientation. Candidates are ranked by
mismatch, then by area. Every candidate records both integer supercell
matrices, the area, the rotation, the principal strains and the atom count.
vibe-sketcher solid stack iface.vsk --id hbn --layer hbn
vibe-sketcher solid stack iface.vsk --id gr
vibe-sketcher solid interface-matches iface.vsk --bottom hbn --top gr --max-area 60
vibe-sketcher solid interface-matches iface.vsk --bottom hbn --top gr --max-area 300 \
--max-strain 0.02 --twist any
The first search returns the aligned 1 × 1 cell, which needs 1.79 % strain.
The second returns rotated moiré cells of 110 atoms or more with less than
0.05 % strain. To use a cell you already know, pass bottom_matrix and
top_matrix (--bottom-matrix "2 0; 0 2") instead of searching. They are
checked against max_strain and the twist like any candidate.
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.
|
Lattice kept |
Phase strained |
|---|---|---|
|
refuses any mismatch |
none |
|
the bottom phase’s |
the top phase |
|
the top phase’s |
the bottom phase |
|
halfway between |
both, about equally |
|
|
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) addsvacuumabove the stack."3d"repeats the stack along the normal withperiodic_gapbetween 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).
|
Displacement |
|---|---|
|
one stacking offset above the fault: ABC|BCA, one plane missing |
|
one offset above the fault and a second above the next plane: one plane inserted |
|
the explicit |
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") needsrotation_axis,misorientation_degorsigma,boundary_plane,boundary_type(tilt,twistormixed),boundary_conditions(periodic_bicrystalorvacuum_bicrystal) andtranslation(or"sampled").A dislocation (
kind: "dislocation") needsburgers_vector(fractions of the bulk cell rows) andline_direction. It also needsboundary_conditions(dipole_periodic,quadrupole_periodic,cylinder_fixed_boundaryorslab_free_surfaces) andelastic_model:isotropicwithpoisson_ratio,anisotropicwith the 6 × 6elastic_constants_gpa, ornone. Finally it needscore_model. An optionalglide_planemust 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/buildbuildsinterfaceandstacking_faultrecipes, with the revision checked and the build recorded as an edit. The MCP tool isbuild_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 isinterface_matches.POST /api/documents/{id}/periodic/extended/preview(recipe,structure) previews a build without storing it. The MCP tool ispreview_extended_defect.POST /api/periodic/extended-defects/plan(plan, optionaldocument) plans a grain boundary or dislocation. The MCP tool isplan_extended_defect.