vibe-sketcherDocumentation

AICCM planning (experimental)

The ab initio cyclic cluster model (AICCM) replaces Bloch sampling by a finite Born–von Kármán torus of Nc = N1·N2·N3 copies of the input cell. vibe-qc runs it as run_periodic_job(method="aiccm", variant=...). The four variants are four constructions, not four spellings of one method:

Variant

Hamiltonian

Representation

Interaction weighting

real-gamma

neutral finite torus (Γ-CCM)

real-Γ supercell

none: neutral fitted lattice sums

neutral-bloch

neutral finite torus (Γ-CCM)

Bloch, on the Γ-centred torus mesh

none: neutral fitted lattice sums

four-center

bare 1/r on the torus

real-space supercell

Wigner–Seitz supercell integral weights

chi

neutral torus defined by finite translation-group characters

character mesh

characters; tied boundary images for even N

The four-center weights follow Peintinger and Bredow, J. Comput. Chem. 35, 839 (2014). An interaction on the border of the Wigner–Seitz supercell that occurs n times gets the two-centre weight 1/n. The three- and four-centre weights are built from the two-centre ones over unions of supercells. vibe-qc runs the symmetric torus form of these weights.

The interaction weighting belongs to the Hamiltonian. The Wigner–Seitz cell that solid wigner-seitz and the figure option wigner_seitz draw is a geometric drawing aid. vibe-sketcher never reads integral weights from a drawing, and a finite torus is never labelled converged bulk. AICCM is experimental in vibe-qc, and nothing here asserts scientific validity.

The capability table

The writer obeys a capability table pinned to the vibe-qc releases it was read from: 0.18.11 and 0.18.12, whose AICCM front doors are identical. The table crosses the variant, the SCF reference and the periodic dimension, and lists the admitted correlation treatments and chi backends. Every row the table does not admit is refused with its reason.

vibe-sketcher solid aiccm capabilities          # admitted rows
vibe-sketcher solid aiccm capabilities --all    # with the refused rows and reasons
vibe-sketcher solid aiccm capabilities --json   # the whole table

Variant

RHF

UHF

RKS, UKS

ROHF, ROKS

Correlation (HF references)

real-gamma

3D

3D

3D

refused

mp2, ccsd, dlpno-mp2, dlpno-ccsd

neutral-bloch

3D

3D

3D

refused

RHF: all four; UHF: mp2, dlpno-mp2, dlpno-ccsd

four-center

3D

3D

3D

refused

RHF: mp2, ccsd; UHF: mp2

chi

3D

3D

3D

refused

none from this writer

Further rules:

  • AICCM is three-dimensional in the pinned releases. The neutral-bloch RHF/RKS slab route is on vibe-qc main after 0.18.12 (vibe-qc#1089). It stays refused until a pinned release carries it.

  • chi ROHF needs aiccm_backend="ri", fit_source="classic" and explicit chi_coulomb_controls. This writer does not express those controls, so it refuses the row. The chi correlation routes need their own explicit-source controls and are refused too.

  • correlation needs a Hartree–Fock reference. backend is a chi control.

  • The SCF reference is inferred as vibe-qc infers it. Without a functional the job is Hartree–Fock; with one it is Kohn–Sham. A singlet with an even electron count is restricted and anything else unrestricted. scf_reference (rhf, uhf, rohf, roks) asks for one explicitly.

  • engine_version (default 0.18.11) names the release the input is written for. The script stops with a message on any other vibe-qc version. Write the input again after the table has been updated.

The convention record

Every AICCM input comes as two files: the script and NAME.aiccm.json. The record holds:

  • the torus repeats, Nc, and the control that set them: lattice_extension or wigner_seitz_shells (N = 2s + 1 per periodic axis);

  • the primitive-site mapping: site Li1@n1,n2,n3 sits at fractional (f + n)/N of the supercell, and image (0, 0, 0) is the input cell;

  • the physical supercell in angstrom;

  • the electronic mesh. vibe-qc derives it from the torus, so the record says independent: false, and a kpoints mesh beside the torus is refused;

  • the interaction weighting of the variant, and a separate note that the geometric Wigner–Seitz figure is not a weighting;

  • the energy normalisation: hartree per input cell, the torus total divided by Nc. That is per primitive cell only when the structure is primitive; the record names the cell setting and the formula units;

  • the Hamiltonian identity and its SHA-256 digest: engine version, variant, reference, functional, basis, correlation, backend, electrons, multiplicity, the iteration budget and the cell, everything except the torus.

vibe-sketcher solid topology --record NAME.aiccm.json draws the torus the record describes; see cyclic figures.

The script also writes NAME.aiccm-result.json after the run: the digest, the torus, the executed vibe-qc version, the energy per cell and whether the SCF converged.

Torus convergence series

A series is one Hamiltonian on two to twelve tori. Each member is written by the same fail-closed writer, and the series plan records the shared digest.

vibe-sketcher solid aiccm series lih.vsk --structure lih --variant four-center \
  --extension 1,1,1 --extension 2,2,2 --extension 3,3,3 -o series
# run each script with vibe-qc, then:
vibe-sketcher solid aiccm compare series/lih-aiccm-series.json series/*.aiccm-result.json

--shells 0,0,0 --shells 1,1,1 builds the ladder from Wigner–Seitz shells instead. --spec spec.json takes a whole PeriodicJobSpec with model: aiccm.

compare lists the energy per cell of each torus, the change from the previous torus and the difference to the largest one. It refuses the comparison when any result:

  • carries another Hamiltonian digest;

  • ran another variant or normalisation;

  • ran on another vibe-qc version than planned, or the results mix versions;

  • belongs to a torus that is not planned or is repeated;

  • did not converge, or has no finite energy.

The differences describe finite tori. They are not a converged-bulk claim.

REST, MCP and Python

  • GET /api/periodic/aiccm/capabilities returns the table.

  • POST /api/documents/{id}/periodic/{structure}/aiccm/series takes spec and extensions or shells. It returns the plan and the files, or 422 with the reasons. The document is not changed.

  • POST /api/periodic/aiccm/compare takes plan and results. It returns the table, or 422 naming every mismatch.

  • POST /api/documents/{id}/periodic/{structure}/input with model: aiccm and an aiccm object writes one input, as before.

The MCP tools are aiccm_capabilities, plan_aiccm_series and compare_aiccm_series; write_periodic_input writes single inputs.

from vibesketcher.document import crystal as cr
from vibesketcher.inputs import aiccm
from vibesketcher.inputs.vibeqc_periodic import PeriodicJobSpec

lih = cr.prototype("rocksalt", identifier="lih", a=4.084, species_map={"Mg": "Li", "O": "H"})
spec = PeriodicJobSpec(model="aiccm", variant="four-center", basis="sto-3g")
plan, bundle = aiccm.plan_series(lih, spec, extensions=[(1, 1, 1), (2, 2, 2)])
table = aiccm.capability_table()

aiccm.compare_series(plan, results) tabulates the finished members.