vibe-sketcherDocumentation

Solid-state input builder plan

Maintainer request, 2026-11-10, tracker hub #227. This page plans how a user builds periodic models and cyclic clusters and writes vibe-qc inputs that run. It extends the periodic authoring plan (#187) and reuses the typed periodic structures (#188). The solid-state structures and inputs guide documents what has landed.

What the user must be able to build

Model

Dimensions

Variants

Periodic calculation input

1D, 2D, 3D

primitive cell, conventional cell, integer supercell, Wigner–Seitz cell, Wigner–Seitz supercell

2D periodic input with surface chemistry

2D

the variants above plus adsorbates and defects

Cyclic cluster, SECCM or AICCM

1D, 2D, 3D

a (Wigner–Seitz) supercell whose periodic vectors are the cluster translations

2D cyclic cluster with surface chemistry

2D

the cluster above plus adsorbates and defects

Every crystal lattice is supported: the 14 three-dimensional Bravais lattices, the 5 plane lattices and the line lattice. Periodic jobs sample the Brillouin zone on Gamma-centred or Monkhorst–Pack meshes, including BIPOLE. Periodic MACE can pre-optimise any of these structures before the electronic-structure job.

Design decisions

  • The builders live in vibe-sketcher. vibe-qc builds metal slabs only and has no bulk prototypes, general supercells or Wigner–Seitz placement. The builders use numpy only, so there is no new hard dependency (no ASE, pymatgen or spglib). Each builder cites its published construction.

  • The document schema does not change. Builders return PeriodicStructure records and write their recipe into provenance["builder"]. A periodic job specification is passed to the writer and is not stored in the document yet.

  • The writer emits a Python script for vibeqc run. It builds a vq.PeriodicSystem in bohr with lattice_vectors=[a1, a2, a3], so no row/column ambiguity arises. Pending-QVF output follows once periodic job specs exist in the document.

  • A Wigner–Seitz cell is an atom placement, not a new lattice. Each site is translated to the image nearest the cell centre. For a PBC job this is the same model. For a cyclic cluster it defines the shape of the cluster.

  • The writers fail closed. A combination the engine cannot run is refused at write time with a reason and is never mapped to a nearby keyword. Today this covers AICCM with dim < 3 (vibe-qc#1089), SECCM open shells and gradients, cell relaxation with fixed atoms, and MACE cell relaxation with dim < 3.

  • Status labels. SECCM and AICCM are experimental in vibe-qc and the generated inputs say so.

Work packages

Step

Issue

Deliverable

1

#222

Bravais lattices, prototype crystals (MgO rocksalt, α-Al₂O₃ corundum, metals, diamond, zincblende, wurtzite, CsCl, fluorite, rutile, perovskite, graphene/hBN, chain), and primitive, conventional, supercell and Wigner–Seitz cell choices

2

#190

Slabs from a bulk cell and Miller index: stoichiometric layer count, termination, vacuum, in-plane repeat, frozen bottom layers; adsorbates from drawn or named molecules on top, bridge, hollow or explicit sites, with flat or upright orientation and collision checks

3

#191

Vacancies, substitutions and interstitials with parent-site maps and an explicit charge and spin

4

#193

Periodic vibe-qc writer: HF/DFT on BIPOLE, GDF or automatic J/K, Gamma-centred or Monkhorst–Pack k-meshes, dim 1–3

5

#224

Periodic MACE pre-optimisation of positions (fixed atoms allowed) or of the cell

6

#223

SECCM and AICCM cyclic-cluster inputs in 1D, 2D and 3D (AICCM detail in #194)

7

#225

Tutorials: bulk MgO, an n-layer α-Al₂O₃(0001) slab, and benzene adsorbed on it

8

#226

Browser panel as a client of the same API

9

#189

Publication views of cells, Wigner–Seitz cells and Brillouin zones (consumes step 1)

Each step ships an SDK function, a CLI command, a REST route and an MCP tool, followed by documentation and a changelog fragment. The browser comes last.

Acceptance

Generated inputs for MgO (BIPOLE multi-k, SECCM CCM3D) and for the Al₂O₃(0001) slab with and without benzene (periodic DFT, SECCM CCM2D) are run with a current vibe-qc build at a small basis. Each tutorial records the runtime identity it was checked with. These runs show that the inputs work, not that the chemistry is converged. k-mesh, slab thickness, vacuum and cluster size must still be converged independently.

References

  • W. Setyawan and S. Curtarolo, Comput. Mater. Sci. 49, 299 (2010), doi:10.1016/j.commatsci.2010.05.010: standard primitive and conventional cells for the 14 Bravais lattices.

  • International Tables for Crystallography, Vol. A (2016): space-group operations and Wyckoff positions for the prototypes.

  • T. Bredow, G. Geudtner and K. Jug, J. Comput. Chem. 22, 861 (2001), doi:10.1002/jcc.1051: the cyclic cluster model and its Wigner–Seitz weighting.

  • H. J. Monkhorst and J. D. Pack, Phys. Rev. B 13, 5188 (1976), doi:10.1103/PhysRevB.13.5188: k-point meshes.

  • W. Sun and G. Ceder, Surf. Sci. 617, 53 (2013), doi:10.1016/j.susc.2013.05.016: efficient slab construction for arbitrary Miller indices.