vibe-sketcherDocumentation

Solid-state and surface reaction authoring plan

Planning audit, 2026-11-08, tracker parent #187. The maintainer requested this paper-workflow scope. It is not an implemented capability or a release assignment. Phase 5 remains after 1.0 with scheduling and dependency decisions pending.

Current support and gaps

Requirement

Current state

Surface/electrode/stack/particle figures and grafted molecules

Implemented schematic metadata and anchors (#140); no physical lattice, vacuum or coverage.

Formula solids and electrochemical half reactions

Implemented (#141/#142); not crystal structures or periodic electronic states.

Finite carbon nanostructures and carbon defects

Generated nanotubes/graphene/ribbons/fullerenes, vacancy/Stone–Wales metadata; limited 1D repeat metadata records intent but no periodic writer.

Atomistic unit cells, physical slabs with adsorbates, general defects

Missing in Sketcher. Existing schematic anchors do not supply these models.

General periodic QVF input

Typed periodic structures and lossless CIF/QVF interchange (#188); see periodic structures. Publication projections and periodic jobs remain planned.

Multi-k PBC/AICCM planning from a sketch

No periodic JobSpec/writer. Molecular MACE admission is unrelated to periodic model admission.

The existing surface tools can already illustrate grafting and surface reactions. They cannot support a calculation of a slab, defect or bulk phase merely by supplying a material/facet label.

Model and product boundaries

Keep three linked records: reaction/drawing intent, physical periodic structures, and calculation specifications/results. A figure refers to model/site IDs but its projection, scale and repeated display copies do not change the model. Physical units, cell conventions and atom/image identities remain explicit. Reuse the Sketcher/Viewer scope: Sketcher prepares editable schemes, paper figures and calculation plans; Viewer handles detailed 3D editing and result inspection. A basic preview/form in Sketcher is required; using Viewer is optional. Reuse compatible public builder/interchange APIs after contract checks, without importing Viewer’s rendering stack as a hard dependency.

Additive document records should carry lattice vectors in stated units, fractional/Cartesian conventions, dimensionality/PBC, persistent sites, periodic image bonds, occupancy/disorder, charge/spin and source provenance. Preserve primitive/conventional-cell transformations and physical supercell matrices. CIF disorder must be retained or explicitly refused, never silently ordered. Existing molecular species, formula solids and schematic surface objects remain valid; conversion to a calculable periodic model is explicit.

Do not conflate:

  • the crystallographic unit cell and an integer physical supercell;

  • image repetitions for figure composition and actual atoms in the job;

  • real-space Wigner–Seitz cells and reciprocal-space first Brillouin zones;

  • k-point integration meshes, band paths and finite-group character meshes;

  • AICCM torus repetitions, interaction shells/weighting and ordinary PBC limits.

For reciprocal vectors state the convention, e.g. a_i · b_j = 2π δ_ij. A geometric WS overlay is not an integral-weighting prescription. A finite torus calculation is not automatically a converged infinite crystal result.

Crystal Builder feature audit

The feature comparison, tracker #198, extends this plan without duplicating the periodic pilot. #188 is delivered as bounded physical-cell and P1 CIF/QVF interchange; general symmetry remains #199. New work: #199 symmetry/cell standardization; #200 periodic graph/preparation; #201 periodic CNT/BN and commensurate carbon stacks; #202 reticular frameworks; #203 guests/packing; #204 porous carbon; #205 amorphous polymers; #206 porosity report planning; #207 diffraction; #208 response/thermochemistry recipes; #209 further periodic interchange adapters. All lack release placement. Prioritize the existing slab/CNT pilot, then symmetry/graph safety and #201; framework, porous-material and broader analysis extensions follow dependencies. Figures, slabs, defects, jobs and qualification stay with #189–#197.

Dependency-ordered implementation

Issue numbers below belong to this repository; each issue includes scope, refusals, sources and acceptance criteria. None is assigned a release milestone.

Step

Issue

Depends on

Deliverable

1

#188

Parent design review

Typed cells/sites, integer transforms, CIF and lossless periodic QVF.

2

#189

#188

Regenerated vector figures: projections, vectors, unit/supercells, WS/BZ, boundary bonds and labels.

3

#190

#188

Faceted slabs, terminations, vacuum/layers, fixed atoms, adsorbates from drawn molecules and physical coverage.

4

#191

#188

Vacancies, substitutions, interstitials and complexes with pristine-parent and site/image maps.

5

#192

#188–#190

Surface/bulk reaction states, gas/solution reservoirs, empty sites and atom/charge/site balancing.

6

#193

#188/#190

Periodic vibe-qc jobs, explicit multi-k meshes and version/runtime capability gates.

7

#194

#193/#189

Experimental AICCM variants, torus/interaction controls, normalization and convergence provenance.

8

#195

#191–#194

Adsorption, surface, reaction and defect energy recipes with explicit reference/correction choices.

9

#196

#195

End-to-end paper figures, queue replay, Viewer exchange and numerical-limit qualification.

Extension

#197

#188/#191, slab support #190

Interfaces, epitaxial strain, grain boundaries, stacking faults and dislocation model assumptions.

SDK, CLI, REST and MCP come first for every capability; the browser edits the same typed records and supports review/undo. Each implementation needs schema regeneration where applicable, docs/changelog and its consumers’ tests. Writers must refuse unsupported combinations rather than omit periodic data or guess engine keywords. Detailed work can proceed in parallel only after the model and interchange contracts are agreed.

Paper workflows and scientific controls

Start with a skew bulk unit cell and supercell; Au(111) with CO on an explicitly selected site; an oxide slab reaction; a neutral vacancy; and a periodic carbon tube. Add charged defects and electrochemical surfaces only with supported boundary conditions and reference data. These examples demonstrate workflows, not validated catalytic chemistry or material-specific accuracy.

Slabs need explicit Miller indices, termination, thickness/layer count, vacuum axis/length, in-plane repeat and frozen layers. State true 2D periodicity versus a 3D vacuum-box approximation; they are different models. Adsorbates need stable attachment atom/site IDs, height and orientation, multiplicity and collision checks. Surface-area-normalized coverage is distinct from an anchor repeat label. Polar surfaces, passivation and compensation require explicit choices.

Reaction graphics should express adsorption/desorption, dissociation, diffusion, surface vacancies and solid-state synthesis with actual phase/site identities. * denotes a recorded empty surface site, not an electron or molecular wildcard. Diffusion endpoints retain lattice image displacements, preventing interpolation across an unintended cell boundary. Reaction arrows never imply an admitted periodic NEB engine route.

Periodic job discovery must include dimension, method/reference/backend, spin, k-mesh, task, gradients/stress and electrostatic restrictions. Compare a pinned engine public contract and a healthy selected worker. Mesh shifts, weights and coordinates cannot disappear on write/replay. Basis/ECP, smearing/occupation and fixed cell/atom controls require explicit support. No fallback to Gamma, a finite cluster or a different electrostatic model is allowed without user selection.

The current engine AICCM manual distinguishes real-gamma, neutral-bloch, four-center and chi, selected explicitly by method="aiccm", variant=..., with aiccm_lattice_extension for torus repeats. All remain experimental. Treat these names as an audit snapshot, not frozen Sketcher keywords or a claim that every reference/task/dimension is supported. Capture Hamiltonian, representation, repeats, shells, energy normalization and engine identity; compare variants only when their definitions warrant it.

Energy recipes require compatible methods/cells, reference chemical potentials, per-face areas and stoichiometric normalization. Charged defects additionally need charge/Fermi-level conventions, alignment and a justified finite-size correction; unavailable inputs block a corrected formation-energy claim. Surface electrochemical recipes must distinguish the computational hydrogen electrode approximation from explicit charged or constant-potential interface simulation. Converge k-mesh, bulk/defect supercell, slab thickness, vacuum and AICCM torus/ interaction settings independently. Numerical convergence does not prove accuracy.

Literature and implementation references

These motivate the requirements; they do not select new dependencies or grant data redistribution rights. Library reuse needs version/licence review and maintainer approval for a new hard dependency. Keep any crystallographic source licence, original CIF, transformation history and citation with the structure.

Implementation readiness starts with #188’s model/API design and a QVF contract review. Implementation scheduling, new dependency selection and scientific acceptance are separate decisions; this plan does not authorize another repository’s changes or a new publication.