Periodic paper workflows¶
This page describes the prospective qualification of periodic paper workflows (#196). Six workflows that a solid-state paper typically needs are driven through the Python SDK, the CLI, the REST API, the MCP server and, for one workflow, the browser. The results must be the same document, with the same cells, sites and images. The corpus qualifies drawing, exchange and input writing. It does not qualify any calculated number; see scientific limits.
The corpus¶
The corpus is in tests/data/paper_workflows/. manifest.json names corpus
version 1, its status prospective-synthetic and a provenance statement. It
lists every workflow file with its SHA-256 and its budgets. Each workflow file
holds build recipes, the structures and balances they must give, figures, a
reaction scheme, energy plans and vibe-qc inputs, as plain JSON.
Every input is synthetic and written for this repository under MPL-2.0. None
is a historical result, experimental data or taken from a publication. The
triclinic Li/H cell is not a real material. The rocksalt and fcc cells use the
library’s prototype lattice constants, whose source is recorded in each
structure’s provenance["builder"]. The test refuses a manifest whose hash
does not match, whose path leaves the directory, whose status or provenance
claims historical evidence, or whose workflow file is not marked synthetic.
To change a workflow, write a new corpus version and record why; do not edit
version 1 in place.
Workflow |
Builds |
Checks |
|---|---|---|
|
an |
supercell volume ×4, four images of each parent site, isometric figure with the Wigner–Seitz cell and the first Brillouin zone, a Γ-centred 2×2×2 PBC input |
|
CO upright on a top site of a three-layer Cu(111) 2×2 slab |
the complex is the slab plus one C and one O, slab site IDs unchanged, side figure with layers, a 2-D input on the automatic J/K route |
|
an MgO(100) slab and the same slab with a surface O vacancy |
MgO(100) + H₂(g) → V_O/MgO(100) + H₂O(g) balances in atoms, charge and sites; the step without water is refused; the scheme figure |
|
a 2×2×2 MgO supercell with a neutral and a +2 O vacancy |
the removed site is |
|
a periodic (6,6) carbon nanotube cell |
24 carbons, periodic along c only, a 1-D input written with the axes relabelled, BIPOLE refused |
|
rocksalt LiH |
a real-gamma AICCM input with its torus record (2×2×2, 8 cells, 16 sites), a refusal without a torus, a four-center torus series |
What the test checks¶
tests/test_paper_workflows.py runs each workflow and checks the following:
The structures, the reaction scheme and every written file are identical through the SDK, the CLI, REST and MCP. Figures are compared byte for byte.
Atom balances: an adsorbate complex is its slab plus the molecule, and a defective cell is its parent minus the removed atoms. Site, charge and atom balances of the reaction steps come from the structures, not from labels.
Identities: every site keeps its ID, element, parent site and image through
.vsksave and load, and through the QVF structure and vendor sections.Each vibe-qc input parses as Python, lists every site once by its ID and carries the structure’s charge. AICCM inputs also carry their torus record.
Malformed and unbounded requests are refused by every interface and leave the document unchanged. These include unknown fields and kinds, bad identifiers, more than 200 slab layers, oversized tubes, supercells over 25 000 sites, singular matrices, missing sources or sites, more than 1000 defects, non-finite numbers, figure repeats over 20, k-meshes over 64 and injected method or basis text.
Budgets: each workflow must finish within its time budget, and its
.vsk, largest SVG, largest QVF and largest input must stay within their size budgets. The budgets were set before any optimisation. They are about ten times the sizes measured when the corpus was frozen, and 30 s where about 1 s was measured. They are safety limits, not performance targets.
tests/test_browser_paper_workflows.py opens the triclinic workflow in the
Solid-state builder. It checks that the panel shows each structure’s
composition, site count and cell. It then downloads the Wigner–Seitz and
Brillouin-zone figure and compares it byte for byte with the SDK figure drawn
with the options the browser sent.
python -m pytest tests/test_paper_workflows.py -q
python -m pytest tests/test_browser_paper_workflows.py -q # needs Playwright Chromium
The QVF checks need qvf-writer. Without it the parity test is skipped, and a skip is not a pass.
Scientific limits¶
The corpus proves that a model and its input are what the recipes say. It does not prove that a calculation on them is right. Keep two questions apart.
Numerical convergence asks whether the number stops changing as the numerical parameters grow, for a fixed method. These parameters are the k-mesh, the basis set, the cyclic cluster or AICCM torus, the slab thickness, the vacuum gap, the in-plane cell, the supercell size and the SCF thresholds. Experimental accuracy asks whether the converged number agrees with a measurement. That depends on the method (HF, the functional, the correlation treatment), on the model (an ideal surface at 0 K, without disorder or temperature) and on what is compared (an electronic energy is not an enthalpy). A fully converged number can still be far from experiment. This corpus checks neither.
Workflow by workflow:
The inputs use STO-3G and Γ or 2×2×2 meshes so that they stay small. They show that an input is valid. They are far from basis-set or k-point convergence.
A slab is a model with a finite thickness, vacuum and lateral cell, and fixed bottom layers. Converge each of them. The adsorbate height is a starting geometry, not an optimised one. Site preferences of CO on transition-metal surfaces depend on the functional (P. J. Feibelman et al., J. Phys. Chem. B 105, 4018 (2001)).
A balanced reaction step is bookkeeping only. It says nothing about the reaction energy, the barrier or the rate. A reaction energy needs total energies of consistent models, stated chemical potentials, and zero-point and thermal terms where they matter.
A neutral vacancy formation energy depends on the oxygen chemical potential. The −4.9 eV in the corpus is a synthetic stated value, not a reference. It also depends on supercell size, and 64 atoms is small.
A charged defect needs a Fermi level, potential alignment and a finite-size correction (C. Freysoldt, J. Neugebauer and C. G. Van de Walle, Phys. Rev. Lett. 102, 016402 (2009)). The energy plan therefore refuses one. The charged structure and its input are admitted explicitly, with the charge stated on the structure and in the script. The total energy of a charged periodic cell depends on the engine’s compensating-background convention.
vibe-qc reads the first lattice vectors as the periodic ones. The nanotube, periodic along c, is written with its axes relabelled (a, b, c) → (c, a, b), and its k-mesh is given in that order as
n,1,1. A (6,6) tube is metallic, so a Γ-only calculation is not converged along the axis.An AICCM torus series measures convergence with the torus for one fixed Hamiltonian. Its comparison table is a convergence table, not an accuracy claim, and AICCM is experimental in vibe-qc.
A recorded live run¶
The triclinic workflow’s input fits the shared calculation gateway (1 CPU, 512 MB, 120 s). The run is planned and will be recorded on #196, together with the vibe-qc release that ran it. A run shows that the written input runs on that release. It is not a convergence or accuracy result.
What remains open¶
This slice does not finish #196. Still open:
the manual review by a paper author of the workflows, figures and wording;
package tests on the declared platforms, which belong to the release candidate;
queue replay of periodic jobs through vibe-scheduler, since the in-app queue submits molecular jobs only;
reviewed reference figures stored as images, and browser parity for the workflows beyond the triclinic one.