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 |
|---|---|---|---|
|
neutral finite torus (Γ-CCM) |
real-Γ supercell |
none: neutral fitted lattice sums |
|
neutral finite torus (Γ-CCM) |
Bloch, on the Γ-centred torus mesh |
none: neutral fitted lattice sums |
|
bare 1/r on the torus |
real-space supercell |
Wigner–Seitz supercell integral weights |
|
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) |
|---|---|---|---|---|---|
|
3D |
3D |
3D |
refused |
mp2, ccsd, dlpno-mp2, dlpno-ccsd |
|
3D |
3D |
3D |
refused |
RHF: all four; UHF: mp2, dlpno-mp2, dlpno-ccsd |
|
3D |
3D |
3D |
refused |
RHF: mp2, ccsd; UHF: mp2 |
|
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 explicitchi_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.correlationneeds a Hartree–Fock reference.backendis 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_extensionorwigner_seitz_shells(N = 2s + 1 per periodic axis);the primitive-site mapping: site
Li1@n1,n2,n3sits 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 akpointsmesh 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/capabilitiesreturns the table.POST /api/documents/{id}/periodic/{structure}/aiccm/seriestakesspecandextensionsorshells. It returns the plan and the files, or 422 with the reasons. The document is not changed.POST /api/periodic/aiccm/comparetakesplanandresults. It returns the table, or 422 naming every mismatch.POST /api/documents/{id}/periodic/{structure}/inputwithmodel: aiccmand anaiccmobject 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.