AICCM: the ab initio cyclic cluster model (experimental)¶

Warning

Experimental. Every AICCM variant is a research method: the drivers emit vibeqc.AICCM2026DevAExperimentalWarning (Gamma-CCM producers) or vibeqc.AICCM2026DevBExperimentalWarning (chi-CCM), the .system manifest records [run].method_status = "experimental" for every AICCM job, the test files stay in the manual research lanes, and the experimental catalog rows stay. “Standard” means the method is reached, configured, recorded and cited like every other vibe-qc method, not that it stops being experimental.

Selecting it¶

One front door selects every formulation; variant names the formulation and is mandatory:

import vibeqc as vq

res = vq.run_periodic_job(
    system, basis,
    method="aiccm",
    variant="real-gamma",                # real-gamma | chi | neutral-bloch | four-center
    functional=None,                     # None -> Hartree-Fock, a functional name -> Kohn-Sham
    scf_reference=None,                  # None -> inferred; "rohf" | "roks" explicit
    aiccm_lattice_extension=(2, 2, 2),   # the Born-von Karman torus, every variant
    output="lih-aiccm",
)

Omitting variant with method="aiccm" fails closed listing the four values. jk_method stays "auto" (the default) or equals the variant’s own underlying route; anything else raises ValueError naming both. Passing variant= or scf_reference= with any other method is also refused rather than ignored.

The variants¶

`variant=`	what it runs	Hamiltonian	code path	status today
`"real-gamma"`	the neutral Gamma-CCM construction in its k-free real-Gamma supercell representation	neutral finite torus	`vibeqc.periodic.ccm.direct` through the per-unit-cell adapter `periodic/ccm/real_gamma_runner.py`	RHF, RKS, UHF, UKS; dim 3 only; `optimize=True` with a fixed cell works
`"chi"`	chi-CCM, the finite-translation-group character construction on a Gamma-centred character mesh	neutral, chi-defined	`vibeqc.periodic.chi`	RHF, RKS, UHF, UKS; dim 3 only; `aiccm_backend="four_center" \| "ri" \| "rijcosx"` plus the `aiccm_symmetry*` and `aiccm_wigner_seitz_shells` keywords
`"neutral-bloch"`	the same neutral construction as `real-gamma`, in the Bloch representation: the library producer `run_ccm_*_gdf` on the torus mesh	neutral finite torus	`vibeqc.periodic.ccm.ri`	fails closed from the runner until its arm lands (milestone M1b of the front-door plan); `run_ccm_scf(ccm, route="neutral-bloch")` runs it today
`"four-center"`	the union-and-weight / Wigner-Seitz four-centre lineage (2014 AICCM, symmetrised)	bare 1/r on the torus	`vibeqc.periodic.ccm.scf`, `dft`, `uhf`	fails closed from the runner until its arm is wired (milestone M3); use `run_ccm_scf(ccm, route="four-center")`

real-gamma and neutral-bloch are one Hamiltonian in two representations (Theorem 1 of the Gamma-CCM paper; the tree pins their agreement at 1e-8 Ha per cell). four-center and chi are distinct constructions from it and from each other: a difference between variants is a construction difference, never a convergence or representation artefact (D74, D89, D90 in the decisions log). There is no variant="gamma": the bare spellings gamma, gamma-ccm, gamma_ccm fail closed on the runner exactly as on the library (ruling R1, 2026-08-21, D124), because one word cannot choose between the two neutral producers and must never silently select the four-centre lineage.

The SCF reference is inferred¶

method="aiccm" takes the place of the SCF string, so the reference is derived the way the library’s run_ccm_scf already derives it:

functional=None runs Hartree-Fock; a functional name runs Kohn-Sham.
The system decides restricted versus unrestricted: a multiplicity of 1 with an even electron count is restricted (RHF or RKS); any other multiplicity, or an odd electron count, is unrestricted (UHF or UKS).
scf_reference="rohf" or "roks" asks for the restricted open-shell references explicitly ("rohf" rejects a functional, "roks" requires one). No variant implements them today, so the request fails closed with the runner’s ROHF/ROKS refusal rather than being downgraded.

The keyword is not called reference: on the library correlation drivers that name already means the correlation reference ("neutral" versus "direct"). A broken-symmetry UHF on a closed-shell singlet cannot be expressed through the front door; the deprecated jk_method spellings with an explicit method="UHF" still reach it.

The torus¶

Every variant reads aiccm_lattice_extension=(N1, N2, N3) (or an integer for a cubic extension) as the Born-von Karman torus, and aiccm_wigner_seitz_shells=s as the odd-extension shorthand 2s+1. The k-mesh argument kpoints= stays an accepted alias for the torus mesh (inputs written before the front door keep running), for every variant the rule is “the real-space control or the legacy k-mesh alias, not both”, and a shifted mesh is rejected because the mesh defines the torus, not a Bloch sampling.

Convergence keywords¶

Both lines gate the SCF on an energy change and on a gradient norm (the DIIS commutator residual). Energy-converged is not density-converged, so a tight conv_tol_energy alone does not give a converged density. The run_periodic_job keywords map onto the drivers as follows:

`run_periodic_job` keyword	`chi` (`PeriodicRHFOptions` / `PeriodicKSOptions`)	`real-gamma` (`run_ccm_*_direct` keywords)
`max_iter` (default 80)	`options.max_iter`	`max_iter`
`conv_tol_energy` (default 1e-7)	`options.conv_tol_energy`	`conv_tol`
gradient criterion	`options.conv_tol_grad`, fixed at 1e-6	`conv_tol_grad`, fixed at 1e-6

A convergence control that is set explicitly but that the selected variant cannot execute fails closed before SCF instead of being dropped. The real-gamma loop implements no damping, Fock mixing, density mixing or level shift (its executed values are structural zeros, recorded per D86), so an explicit damping=, fock_mixing=, fmixing_percent=, density_mixer= or level_shift= on that variant raises; dynamic_damping= is chi-only, as before. The real-gamma adapter forwards neither the DIIS controls (use_diis, diis_start_iter, diis_subspace_size) nor initial_guess / solver; those keep their defaults on that variant. convergence="auto" is wired for the GDF and BIPOLE routes only and is reported as “plain defaults” on every AICCM variant.

Legacy selector spellings¶

spelling	before the front door	since the front door
`jk_method="real-gamma"`, `"real_gamma"`	the real-Gamma control	resolves to `variant="real-gamma"` with a `DeprecationWarning` naming the `method="aiccm", variant=...` form
`jk_method="aiccm2026dev-b"`, `"chi"`, `"chi-ccm"`	chi-CCM	resolves to `variant="chi"` with the same warning
`jk_method="aiccm2026dev-a"`	fails closed (unwired)	resolves to `variant="four-center"` with the warning, then fails closed until the arm lands
`jk_method="gamma"`, `"gamma-ccm"`, `"gamma_ccm"`	the four-centre selector	retired: fails closed with the ruling-R1 message
`jk_method="neutral-bloch"`, `"bloch-control"`, `"gdf-control"`, `"aiccm-ri"`	plain unit-cell GDF	retired: fails closed with a pointer at `variant="neutral-bloch"` and the library entry (the same words name the neutral producer there; a word must not mean two Hamiltonians)
`jk_method="aiccm2026dev-a-real-gamma"`, `"aiccm2026dev-a-direct"`	rejected	rejected, unchanged (the A prefix names the four-centre construction)
`jk_method=PeriodicJKMethod.AICCM2026DEV_B` (or the other two legacy members)	dispatched silently	dispatched with the same `DeprecationWarning`; `PeriodicJKMethod.NEUTRAL_BLOCH` as a `jk_method` is refused

The warning is attributed to your own call site, not to a vibe-qc frame, which is what makes it visible: Python’s default filters show a DeprecationWarning only when it is blamed on __main__. The .out carries the same pointer for logs and for callers that filter warnings away: the line under “J/K method” reads (user-requested: 'real-gamma'; deprecated spelling of method='aiccm', variant='real-gamma').

What the outputs record¶

The .out “J/K method” line reads aiccm (<variant>) ...; experimental, followed by (selected by method='aiccm', variant='...'; SCF reference RHF inferred). The .system manifest carries [run].method_status = "experimental", aiccm_variant, aiccm_selector ("front-door" or "legacy-jk_method"), the variant’s route under jk_method_requested / _resolved / _executed (a front-door job records the route value in all three), the inferred SCF reference under [plan].method, and the variant’s convention record (exchange_q0, torus size, representation; see output files). The references block cites the variant’s own route (real-gamma, aiccm2026dev-b) rather than a plain periodic SCF.

Limitations of this milestone¶

neutral-bloch and four-center fail closed from the runner; both run from the library today (run_ccm_scf(ccm, route=...)).
Post-HF (MP2, CCSD(T), DLPNO) is library-only on every line; the runner correlation arm is a later milestone.
chi-CCM has no analytic gradient by design; real-gamma relaxes atoms on a fixed cell only; the four-centre gradients are library-only.
Every variant is 3-D only; double hybrids are reachable on no variant from the runner.