vibe-sketcherDocumentation

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-gamma and neutral-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 occurs n times gets the two-centre weight 1/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 order N the boundary images at +/- N/2 are tied and share exact weights (vibe-qc periodic.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 and run_periodic_job front 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() and compare_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

CONTRACT

Where the table was read and which engine releases it is pinned to.

NORMALISATION

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

aiccm_refusals(structure, spec)

Everything in an AICCM request the pinned table does not admit.

capability(variant, reference, dim)

The table row, or None for a variant/reference the table does not know.

capability_table()

The pinned table as plain data (SDK, CLI, REST and MCP).

compare_series(plan, results)

Tabulate a finished series, or raise ValueError naming every mismatch.

hamiltonian_identity(structure, spec)

Everything that defines the Hamiltonian of one torus member except the torus.

identity_digest(identity)

plan_series(structure, spec, *[, ...])

A repeat/shell convergence series: one Hamiltonian, two or more tori.

resolve_reference(structure, spec)

The SCF reference vibe-qc will run, and a refusal reason ('' when fine).

resolve_torus(structure, spec)

The torus repeats (N1, N2, N3), or None with a refusal reason.

torus_record(structure, spec)

The convention record of one admitted AICCM input (call after the refusals).

Classes

Capability(variant, reference, dim, ...)

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: _Spec

AICCM controls beyond the variant and the torus (all optional).

Parameters:
  • scf_reference (Literal['rhf', 'uhf', 'rohf', 'roks'] | None)

  • correlation (Literal['mp2', 'ccsd', 'dlpno-mp2', 'dlpno-ccsd'] | None)

  • wigner_seitz_shells (tuple[int, int, int] | None)

  • backend (Literal['four_center', 'ri', 'rijcosx'] | None)

  • engine_version (str)

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).

correlation: Literal['mp2', 'ccsd', 'dlpno-mp2', 'dlpno-ccsd'] | None
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.

backend: Literal['four_center', 'ri', 'rijcosx'] | None

the J/K backend.

Type:

chi only

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: object

One row of the pinned table: may the writer ask for this combination?

Parameters:
variant: str
reference: str
dim: int
admitted: bool
correlation: tuple[str, ...]
backends: tuple[str, ...]
hamiltonian: str
representation: str
interaction_weighting: str
mesh: str
reason: str
vibesketcher.inputs.aiccm.aiccm_refusals(structure, spec)[source]

Everything in an AICCM request the pinned table does not admit.

Parameters:
Return type:

list[str]

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).

Return type:

dict[str, Any]

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.

Parameters:
Return type:

dict[str, Any]

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:
Return type:

dict[str, Any]

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 spec with 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:
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=None is Hartree-Fock, a functional Kohn-Sham; a singlet with an even electron count is restricted, anything else unrestricted. Explicit rhf/uhf/rohf reject a functional and roks requires one.

Parameters:
Return type:

tuple[str, str]

vibesketcher.inputs.aiccm.resolve_torus(structure, spec)[source]

The torus repeats (N1, N2, N3), or None with a refusal reason.

Parameters:
Return type:

tuple[tuple[int, int, int] | None, str]

vibesketcher.inputs.aiccm.torus_record(structure, spec)[source]

The convention record of one admitted AICCM input (call after the refusals).

Parameters:
Return type:

dict[str, Any]