vibesketcher.inputs.aiccm¶
Explicit AICCM planning for vibe-qc: capabilities, torus record and convergence series (#194).
The ab initio cyclic cluster model (AICCM) replaces Bloch sampling by a finite
Born-von Karman torus of N_c = N1 N2 N3 copies of the input cell. vibe-qc
runs it as run_periodic_job(method="aiccm", variant=...), and the four
variants are four distinct constructions, not four spellings of one:
real-gammaandneutral-bloch: the neutral Gamma-CCM torus in its real-Gamma supercell and in its Bloch representation (one Hamiltonian, two representations per the engine’s Theorem 1, but recorded as two variants here and never compared across);four-center: bare 1/r on the torus with Wigner-Seitz supercell integral weights, the lineage of M. F. Peintinger and T. Bredow, J. Comput. Chem. 35, 839 (2014), doi:10.1002/jcc.23550: an interaction on the border of the Wigner-Seitz supercell (WSSC) that occursntimes gets the two-centre weight1/n; three- and four-centre weights are built from the two-centre ones over unions of WSSCs (that paper, “Two-center interactions” and Table 1). vibe-qc executes the symmetric torus form of those weights;chi: finite translation-group characters on the torus’ character mesh; for an even orderNthe boundary images at+/- N/2are tied and share exact weights (vibe-qcperiodic.chi.scf).
What this module owns:
CAPABILITIES, the engine-version-pinned table of what the writer may ask for (variant x SCF reference x periodic dimension, plus correlation), read from vibe-qc’s AICCM manual andrun_periodic_jobfront door. The writer consults it and refuses every row it does not admit; nothing is inferred from a nearby row.torus_record(), the convention record written beside every AICCM input: torus repeats, the primitive-site to torus-image mapping, the physical supercell, the electronic mesh (derived from the torus by the engine), the shell control, the energy normalisation and the interaction weighting of the variant. The weighting is a property of the Hamiltonian; the Wigner-Seitz cell the figure renderer draws is a geometric drawing aid and is never read as integral weights.plan_series()andcompare_series(), the repeat/shell convergence study: one Hamiltonian, a ladder of tori, and a comparison that refuses runs whose conventions or engine versions differ. A finite torus is a finite torus: no member is ever labelled converged bulk.
AICCM is experimental in vibe-qc; nothing here asserts scientific validity.
Module Attributes
Where the table was read and which engine releases it is pinned to. |
|
|
the torus total divided by the number of cells, i.e. per input cell (which is the primitive cell only when the structure is primitive). |
Functions
|
Everything in an AICCM request the pinned table does not admit. |
|
The table row, or None for a variant/reference the table does not know. |
The pinned table as plain data (SDK, CLI, REST and MCP). |
|
|
Tabulate a finished series, or raise ValueError naming every mismatch. |
|
Everything that defines the Hamiltonian of one torus member except the torus. |
|
|
|
A repeat/shell convergence series: one Hamiltonian, two or more tori. |
|
The SCF reference vibe-qc will run, and a refusal reason ('' when fine). |
|
The torus repeats (N1, N2, N3), or None with a refusal reason. |
|
The convention record of one admitted AICCM input (call after the refusals). |
Classes
|
One row of the pinned table: may the writer ask for this combination? |
- class vibesketcher.inputs.aiccm.AICCMOptions(*, scf_reference=None, correlation=None, wigner_seitz_shells=None, backend=None, engine_version='0.18.11')¶
Bases:
_SpecAICCM controls beyond the variant and the torus (all optional).
- Parameters:
- scf_reference: Literal['rhf', 'uhf', 'rohf', 'roks'] | None¶
None infers the reference as vibe-qc does (functional -> KS, else HF; singlet with an even electron count -> restricted, else unrestricted).
- wigner_seitz_shells: tuple[int, int, int] | None¶
The odd-torus shorthand N = 2s + 1 per periodic axis; nonperiodic axes stay 0. Exclusive with
lattice_extension.
- engine_version: str¶
The vibe-qc release the input is written for; the script refuses to run on another one.
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- vibesketcher.inputs.aiccm.CONTRACT: dict[str, Any] = {'default_version': '0.18.11', 'engine': 'vibe-qc', 'pending_upstream': ['neutral-bloch RHF/RKS on dim = 2 slabs is on vibe-qc main after 0.18.12 (vibe-qc#1089) and in no release yet; this table refuses it until a pinned release carries it'], 'read_from': ["vibe-qc user guide 'AICCM: the ab initio cyclic cluster model' (user_guide/aiccm.md)", 'vibe-qc run_periodic_job AICCM front door (periodic_runner.py)', 'vibe-qc periodic.chi.scf cyclic_lattice_extension (torus and shell resolution)'], 'read_on': '2026-11-11', 'status': 'experimental', 'versions': ['0.18.11', '0.18.12']}¶
Where the table was read and which engine releases it is pinned to. The AICCM front door of 0.18.11 (the release the fleet runs) and 0.18.12 are identical; 0.18.12 only adds the executed exchange_q0 to the manifest.
- class vibesketcher.inputs.aiccm.Capability(variant, reference, dim, admitted, correlation, backends, hamiltonian, representation, interaction_weighting, mesh, reason)[source]¶
Bases:
objectOne row of the pinned table: may the writer ask for this combination?
- Parameters:
- vibesketcher.inputs.aiccm.aiccm_refusals(structure, spec)[source]¶
Everything in an AICCM request the pinned table does not admit.
- Parameters:
structure (PeriodicStructure)
spec (PeriodicJobSpec)
- Return type:
- vibesketcher.inputs.aiccm.capability(variant, reference, dim)[source]¶
The table row, or None for a variant/reference the table does not know.
- Parameters:
- Return type:
Capability | None
- vibesketcher.inputs.aiccm.capability_table()[source]¶
The pinned table as plain data (SDK, CLI, REST and MCP).
- vibesketcher.inputs.aiccm.compare_series(plan, results)[source]¶
Tabulate a finished series, or raise ValueError naming every mismatch.
A comparison is refused when any result was computed under another Hamiltonian identity, another engine version, another normalisation or another variant than the plan, when a torus is missing, foreign or repeated, or when a run did not converge.
- vibesketcher.inputs.aiccm.hamiltonian_identity(structure, spec)[source]¶
Everything that defines the Hamiltonian of one torus member except the torus.
Two inputs belong in one convergence series exactly when their identities (and hence
identity_digest()) agree.- Parameters:
structure (PeriodicStructure)
spec (PeriodicJobSpec)
- Return type:
- vibesketcher.inputs.aiccm.plan_series(structure, spec, *, extensions=None, shells=None)[source]¶
A repeat/shell convergence series: one Hamiltonian, two or more tori.
Every member is the same
specwith only the torus changed, written by the fail-closed periodic writer. The plan records the shared Hamiltonian identity;compare_series()refuses results that do not carry it.- Parameters:
structure (PeriodicStructure)
spec (PeriodicJobSpec)
- Return type:
tuple[dict[str, Any], InputBundle]
- vibesketcher.inputs.aiccm.resolve_reference(structure, spec)[source]¶
The SCF reference vibe-qc will run, and a refusal reason (’’ when fine).
Mirrors the engine’s inference:
functional=Noneis Hartree-Fock, a functional Kohn-Sham; a singlet with an even electron count is restricted, anything else unrestricted. Explicitrhf/uhf/rohfreject a functional androksrequires one.- Parameters:
structure (PeriodicStructure)
spec (PeriodicJobSpec)
- Return type:
- vibesketcher.inputs.aiccm.resolve_torus(structure, spec)[source]¶
The torus repeats (N1, N2, N3), or None with a refusal reason.
- Parameters:
structure (PeriodicStructure)
spec (PeriodicJobSpec)
- Return type:
- vibesketcher.inputs.aiccm.torus_record(structure, spec)[source]¶
The convention record of one admitted AICCM input (call after the refusals).
- Parameters:
structure (PeriodicStructure)
spec (PeriodicJobSpec)
- Return type: