AICCM — the `aiccm2026dev-a` line (experimental)¶

Warning

Experimental, and one of two parallel ab-initio CCM development lines. This page documents the aiccm2026dev-a four-center weighting and its method stack, developed and validated independently for a head-to-head comparison against a second line. It is separate, on purpose, from the side-by-side catalog in experimental features and the CCM reference. The post-HF / padded-ERI builders are small / 1-D / 2-D validation paths (kept out of __all__); the accurate 3-D route is the periodic GDF (below). Numbers here are research-grade.

What `aiccm2026dev-a` is¶

The ab-initio Cyclic Cluster Model (AICCM) computes a crystal’s electronic structure on a finite Born-von-Karman torus (the cluster with cyclic boundary conditions), feeding vibe-qc’s ordinary molecular method kernels a Wigner-Seitz-supercell (WSSC) weighted set of integrals. The hard part is the two-electron four-center term.

aiccm2026dev-a is the symmetric four-center (derived in AICCM_ALGORITHM.md §13). It replaces the historical union12 product weight ω_μν · ½(ω_μρ+ω_νρ) · ω_ρσ — which singles out the ket anchor ρ and so breaks the 8-fold permutational symmetry an SCF energy functional requires — with a symmetric bridge and an independent minimum-image fold:

ω^sym_{μνρσ} = ω_μν · ω_ρσ · ¼(ω_μρ + ω_νρ + ω_μσ + ω_νσ)

with ρ and σ each folded to their own minimum image of the home bra (the ket-pair weight ω_ρσ taken at the relative cell). The result is exactly 8-fold permutationally symmetric for any lattice — a genuine variational ERI set — verified to machine precision (≤3e-18) on 1-D chains and on 2-D hexagonal and oblique lattices, where union12 is 1.6e-3 (1-D) to 2.1e-2 (2-D) asymmetric. The weighting rests only on the WSC minimum image, so it is lattice-general (the reference cell is the WSC).

In 1-D and orthorhombic lattices the two weightings give the same energy (the WSC symmetry hides the asymmetry); in non-orthorhombic ≥2-D they diverge — e.g. a 2-D hex H lattice gives aiccm2026dev-a -0.400456 vs union12 -0.399044 Ha/atom, and a 3-D BCC lattice diverges by ~5 mHa/atom.

Sizing the cluster: interaction radius (the real-space dual of a k-mesh)¶

The cluster can be sized two ways. The explicit mesh nrep=(N1,N2,N3) is the advanced override; the recommended knob is a real-space interaction range R_c — how far the WSSC interactions reach around every atom — from which the minimal nrep is derived automatically:

from vibeqc.periodic.ccm import CCMSystem, ccm_interaction_range_scan

# size by a real-space radius (bohr); nrep is derived (Å convenience too)
ccm = CCMSystem.from_interaction_range(unit, 12.0, "sto-3g")        # R_c = 12 bohr
ccm = CCMSystem(unit, basis="sto-3g", interaction_range_ang=6.5)    # R_c = 6.5 Å
print(ccm.nrep, ccm.wsc_inscribed_radius, ccm.kspacing_equiv)

This is the real-space dual of k-point sampling, grounded in CCM ≡ SCM-Γ: a cyclic cluster of size (N1,N2,N3) is a Born–von-Kármán torus sampling a Γ-centred (N1,N2,N3) Monkhorst–Pack mesh, and a radius R_c corresponds to a uniform k-spacing Δk = π/R_c — a larger radius ⇔ a denser k-mesh.

The derivation is rigorous (docs/aiccm2026dev_a_followon.md § A): the minimal cluster is the one whose supercell Wigner–Seitz cell encloses a sphere of radius R_c around every atom. The WS inscribed-sphere radius is r_in = λ₁/2 (half the shortest lattice vector); the per-direction rule N_i = ⌈2 R_c / d_i⌉ (d_i = unit-cell interplanar spacing) provably guarantees r_in ≥ R_c because λ₁ ≥ min_i N_i d_i. It is tight for orthogonal cells and conservative (never under-shoots) for oblique ones; dim caps non-periodic directions.

A radius convergence scan — the CCM analogue of a k-point convergence study — comes for free:

scan = ccm_interaction_range_scan(unit, "sto-3g",
                                  radii_bohr=[6, 9, 12, 15, 18, 24, 30])
print(scan.converged_radius(1e-4))     # smallest R_c converged to 0.1 mHa/atom

On the 1-D H₂ chain (6-bohr cell, STO-3G, aiccm2026dev-a) E/atom converges to 0.1 mHa/atom by R_c ≈ 9 bohr ((3,1,1)) and to 10 µHa/atom by R_c ≈ 18 bohr ((6,1,1)). The demonstration across all 28 test-set crystals (every Bravais lattice) is aiccm-2026/demo_interaction_range.py.

The method stack¶

Every driver takes method="aiccm2026dev-a" (default is "union12"). The four-center Coulomb/exchange carries the cyclic boundary conditions; correlation and XC are the molecular algebra fed the CCM integrals.

import numpy as np
from vibeqc import Atom, PeriodicSystem
from vibeqc.periodic.ccm import CCMSystem
from vibeqc.periodic.ccm.scf import run_ccm_rhf, run_ccm_rhf_scalable
from vibeqc.periodic.ccm.uhf import run_ccm_uhf
from vibeqc.periodic.ccm.dft import run_ccm_rks, run_ccm_uks
from vibeqc.periodic.ccm.mp2 import run_ccm_mp2
from vibeqc.periodic.ccm.ump2 import run_ccm_ump2
from vibeqc.periodic.ccm.ccsd import run_ccm_ccsd
from vibeqc.periodic.ccm.ri import (
    run_ccm_rhf_gdf, run_ccm_rks_gdf, run_ccm_rhf_rij, run_ccm_rhf_rijcosx)

BOHR = 1.0 / 0.529177210903
pos = [[x * BOHR, 0, 0] for x in (0.0, 0.8, 2.0, 2.8)]     # H4 alternating chain
unit = PeriodicSystem(3, np.diag([4.0 * BOHR, 40.0, 40.0]),
                      [Atom(1, p) for p in pos], charge=0, multiplicity=1)
ccm = CCMSystem(unit, (4, 1, 1), "sto-3g")

# --- Hartree-Fock and Kohn-Sham, with the four-center Coulomb ---------------
rhf = run_ccm_rhf(ccm, method="aiccm2026dev-a")          # closed-shell HF
sca = run_ccm_rhf_scalable(ccm, method="aiccm2026dev-a") # same, scalable C++ (reaches 3-D)
rks = run_ccm_rks(ccm, "pbe", method="aiccm2026dev-a")   # KS-DFT (any libxc functional)

# --- correlation: MP2 / UMP2 / CCSD(T), on the CCM MO integrals -------------
mp2 = run_ccm_mp2(ccm, method="aiccm2026dev-a")
cc  = run_ccm_ccsd(ccm, method="aiccm2026dev-a")         # CCSD + (T)
print(rhf.energy_per_atom, mp2.e_correlation, cc.e_correlation, cc.e_t)

# --- the 4-center -> RI -> RIJCOSX approximation hierarchy ------------------
ri  = run_ccm_rhf_gdf(ccm)                          # RI Coulomb (accurate, via GDF)
rik = run_ccm_rks_gdf(ccm, "pbe")                   # RI + KS
cox = run_ccm_rhf_rijcosx(ccm)                      # RI-J + chain-of-spheres K

level	HF	KS	open-shell	correlation
4-center	`run_ccm_rhf` / `run_ccm_rhf_scalable`	`run_ccm_rks`	`run_ccm_uhf`, `run_ccm_uks`	`run_ccm_mp2`, `run_ccm_ump2`, `run_ccm_ccsd` (+(T)), `run_ccm_uccsd` (+(T))
RI (3c)	`run_ccm_rhf_gdf`	`run_ccm_rks_gdf`	(GDF Γ)	via the RI MOs
RIJCOSX (3c)	`run_ccm_rhf_rijcosx`	—	—	—
local correlation	—	—	—	`ccm_dlpno_mp2`, `ccm_dlpno_ccsd` (DLPNO, on the neutral reference)

Properties (any converged CCM SCF): ccm_homo_lumo_gap, ccm_mulliken_charges, ccm_lowdin_charges, ccm_dipole, ccm_numerical_gradient (see Properties below).

The 4-center → RI → RIJCOSX hierarchy¶

Four-center — the exact WSSC-weighted Coulomb/exchange. HF (run_ccm_rhf, and the scalable C++ run_ccm_rhf_scalable that reaches genuine 3-D) and KS (run_ccm_rks/run_ccm_uks, pure and hybrid) reproduce the molecular kernels exactly in the isolated limit.
RI — density-fitted (3-center) Coulomb. The accurate route is run_ccm_rhf_gdf / run_ccm_rks_gdf: because CCM ≡ SCM-Γ, vibe-qc’s native GDF Γ driver on the cluster supercell is the CCM with an RI Coulomb, and it reproduces the four-center to the RI fitting error (≲0.1 mHa/atom in 1-D and 3-D). The RI-consistent three-center is the neutral cderi ccm_neutral_cderi (ccm_ri_tensors_neutral / ccm_ri_j_neutral / ccm_ri_k_neutral): its RI-J/K reproduce the neutral four-center to machine ε. The research route run_ccm_rhf_rij keeps the explicit eq-13 union three-center weighting on the bare-1/r integrals; it is exact in the isolated limit but ~few-% periodically — the bare-1/r four-center is non-separable, so no weighting of its 3-center is RI-consistent (§13.7). Use the neutral cderi (or run_ccm_rhf_gdf) for the RI-consistent route.
RIJCOSX — run_ccm_rhf_rijcosx: the WSSC RI-J Coulomb plus chain-of-spheres (COSX) seminumerical exchange (Neese 2009) on a supercell grid. Exchange is short-ranged (decays within the WSC), so the seminumerical K is a natural fit; the isolated limit reproduces molecular RIJCOSX to ~5 µHa.

Local correlation: DLPNO-MP2 / DLPNO-CCSD(T)¶

Domain-based local pair natural orbitals (DLPNO) on the cyclic cluster, reusing vibe-qc’s validated molecular DLPNO machinery with the cyclic overlap S^CCM and the neutral four-center reference:

from vibeqc.periodic.ccm import CCMSystem, ccm_dlpno_mp2, ccm_dlpno_ccsd
from vibeqc.periodic.ccm.scf import run_ccm_rhf
from vibeqc.periodic.ccm.neutral import ccm_eri_neutral, ccm_neutral_cderi

g = ccm_eri_neutral(ccm)              # neutral four-center g_eff = Σ_P L⊗L
L = ccm_neutral_cderi(ccm)            # its RI cderi
scf = run_ccm_rhf(ccm, eri=g)         # neutral SCF reference

mp2 = ccm_dlpno_mp2(ccm, scf, cderi=L, localize="pm", tcut_pno=1e-7)
cc  = ccm_dlpno_ccsd(ccm, scf, cderi=L, g_neutral=g, localize="pm", tcut_pno=1e-7)
print(mp2.e_corr, cc.e_correlation, cc.e_t)

ccm_dlpno_mp2 — pair domains (Mulliken tcut_mkn) → semicanonical PAOs → PNOs (occupation threshold tcut_pno) → coupled LMP2; canonical or localized (Pipek–Mezey / Boys) occupieds.
ccm_dlpno_ccsd — subspace-projected DLPNO-CCSD(T): the per-pair PNOs are merged into a union virtual space and vibe-qc’s CCM CCSD engine runs in {occ, V_trunc}.

The reference is neutral, by necessity. The bare-1/r Madelung background is block-diagonal in occ/virt and shifts the orbital-energy denominators, so independent bare-vs-neutral SCF→correlation do not agree (it is a fixed-reference diagnostic, not a Madelung-invariance theorem). CCM correlation therefore runs on the neutral four-center / GDF reference. The hard gate: at no truncation (tcut_pno = tcut_mkn = 0) DLPNO-MP2 and DLPNO-CCSD(T) reproduce the canonical CCM MP2 / CCSD(T) on the same neutral four-center to machine ε (tests/test_ccm_dlpno_{mp2,ccsd}.py).

Open-shell correlation (UHF reference)¶

run_ccm_ump2 (UMP2) and run_ccm_uccsd (UCCSD(T)) run on the spin-resolved UHF-CCM reference. run_ccm_uccsd drives vibe-qc’s spin-orbital UCCSD(T) engine with the neutral cderi transformed into the α/β MO bases; on a closed-shell cluster it reproduces run_ccm_ccsd to ≤1e-8 (the αα = ββ collapse), and a doublet cluster converges with negative correlation (tests/test_ccm_uccsd.py).

Properties¶

One-particle properties on a converged CCM SCF (vibeqc.periodic.ccm.properties):

from vibeqc.periodic.ccm import (ccm_homo_lumo_gap, ccm_mulliken_charges,
                                 ccm_lowdin_charges, ccm_dipole, ccm_numerical_gradient)
gap = ccm_homo_lumo_gap(scf, ccm)              # band/fundamental gap (RHF or UHF)
q   = ccm_mulliken_charges(scf, ccm)           # per-cell charges + transl. spread
mu  = ccm_dipole(scf, ccm)                     # finite-cluster dipole (see caveat)
grad = ccm_numerical_gradient(ccm)             # central-difference dE/dR; force = −grad

gap — ε_LUMO − ε_HOMO over the supercell-Γ spectrum (= the gap at the k-points the cluster folds to Γ; spin-resolved for UHF/UKS). Well defined.
populations — Mulliken / Löwdin with S^CCM; per-cell image-averaged charges, with translational_spread as a cyclic-symmetry diagnostic. Well defined.
dipole — the finite-cluster electric dipole. ⚠ not the bulk polarization: the position operator is ill-defined on a torus (Resta 1998) and plain ⟨μ|r|ν⟩ wraps for boundary-crossing orbitals; faithful only for non-wrapping (dilute) clusters, and a symmetry indicator (≈ 0 for centrosymmetric) otherwise.
forces — central-difference dE/dR per unit-cell atom (the displacement propagates to every image). It satisfies translational invariance (Σ forces ≈ 0) and reproduces vibe-qc’s molecular analytic RHF gradient in the isolated limit to ~1e-7. The analytic WSSC-weighted gradient + the Resta/Berry-phase bulk polarization are roadmap items.

See docs/aiccm2026dev_a_followon.md §§ 2, C, D for the derivations and gates.

The four-center Madelung gap (resolved)¶

The bare-1/r WSSC four-center is quantitative for covalent / molecular / 1-D systems (it matches the periodic gdf energy to sub-mHa/atom there) but over-binds ionic 3-D crystals by a Madelung-scale shift. §13.2 traces this to the kernel: the honest finite Born–von-Kármán torus interaction is the charge-neutral (Ewald) torus Green’s function v_E, not a truncated bare 1/r sum. The neutral four-center g_eff = (μν|v_E|ρσ) is ccm_eri_neutral — the RI density-fit of v_E (§13.7), built from the periodic-Γ GDF cderi on the cluster supercell, and exactly 8-fold symmetric.

The gap turns out to be a pure mean-field (Hartree) background. In the molecular limit the neutral and bare four-centers differ by a rank-1 term,

g_eff[μν,ρσ] = (μν|ρσ)_bare − ξ · S_μν · S_ρσ ,   ξ = madelung_constant_for_cell(cluster)

because the AO-pair “charge” is q_μν = ∫φ_μφ_ν = S_μν. Two consequences settle the question:

HF / KS energy — ξ·S⊗S is ∝ S in the Fock (a uniform shift). For absolute ionic energies use the neutral route, which is exactly run_ccm_rhf_gdf / run_ccm_rks_gdf (CCM ≡ SCM-Γ: multi-k GDF on the unit cell is the density fit of v_E). The bare four-center remains correct for covalent / molecular / 1-D and for energy differences where the shift cancels.
Correlation (fixed reference only) — the background is block-diagonal in the occ/virt split (J: −ξN_e S, K: −ξ SDS): it leaves the HF orbitals invariant but shifts the occ–virt gap by O(ξ). In the MO basis ξ·(CᵀSC)⊗(CᵀSC) = ξ·I⊗I has no occupied–virtual element, so at a fixed reference it does not enter the MP2/CCSD numerator. It does shift every denominator, so independent bare-vs-neutral SCF→correlation runs do NOT agree — the neutral reference is required for ionic correlation. (This corrects an earlier overclaim that the bare four-center is Madelung-robust for correlation; the rank-1 result is a fixed-reference diagnostic, not an all-post-HF theorem — see the aiccm2026dev-a paper §7.)

So the practical recipe for ionic systems is: take both the absolute HF/KS energy and the correlation from the neutral route (GDF reference) — the bare four-center is a covalent / molecular / 1-D and small-cluster tool. ccm_eri_neutral is the small-cluster analysis tool that makes the decomposition explicit (it OOMs on dense ionic 3-D, like the bare padded four-center; the GDF route is the production energy path).

Tutorial: H4 chain, full hierarchy¶

The runnable demo is examples/periodic/aiccm2026dev_a_demo.py:

$ python examples/periodic/aiccm2026dev_a_demo.py
=== 8-fold ERI symmetry (max permutation violation) ===
  1D H4 chain (4,1,1) : union12 1.63e-03   aiccm2026dev-a 0.00e+00
  2D hex      (2,2,1) : union12 2.12e-02   aiccm2026dev-a 3.10e-18
  2D oblique  (2,2,1) : union12 1.94e-02   aiccm2026dev-a 3.10e-18
=== Full stack on the 1D H4 chain (4,1,1), aiccm2026dev-a ===
  RHF     E/atom = -0.542676   (gold -0.542875)
  MP2     Ecorr  = -0.129514   /cell
  CCSD    Ecorr  = -0.190443   /cell
  CCSD(T) Ecorr  = -0.191100   /cell  [(T)=-6.57e-04]
=== 2D hexagonal lattice (2,2,1): aiccm2026dev-a vs union12 ===
  RHF E/atom : union12 -0.399044   aiccm2026dev-a -0.400456   (Δ=-1.413 mHa/atom)

Steps the demo walks through: (1) build the symmetric four-center and confirm it is exactly 8-fold symmetric on three lattices while union12 is not; (2) run the HF → MP2 → CCSD(T) stack on the H4 chain (HF converges to the gold -0.542875 Ha/atom with cluster size); (3) show the non-orthorhombic ≥2-D divergence from union12. For the 3-center hierarchy, swap run_ccm_rhf → run_ccm_rhf_gdf (RI) → run_ccm_rhf_rijcosx (RIJCOSX) and compare.

Validation status¶

piece	status
symmetric four-center	exact 8-fold symmetry (≤3e-18), 1-D / 2-D-hex / 2-D-oblique / 3-D
HF (4c), C++ scalable	== padded to µHa; 1-D → gold -0.542875; reaches 3-D
KS (4c), RKS/UKS	== molecular `run_rks`/`run_uks` (PBE/PBE0/B3LYP) to <1e-6
MP2 / UMP2	== molecular `run_mp2` / `run_ump2` (isolated)
CCSD(T)	== molecular DF-CCSD to the DF gap; (T) to ~1e-8
RI (GDF)	== four-center to the RI fitting error (≲0.1 mHa/atom, 1-D + 3-D)
RIJCOSX	== molecular RIJCOSX (isolated) to ~5 µHa
neutral four-center (`ccm_eri_neutral`)	8-fold symmetric; `= bare − ξ·S⊗S`, ξ = cell Madelung const
Madelung background (fixed ref)	block-diagonal in occ/virt → no correlation numerator term; shifts denominators, so independent bare-vs-neutral SCF differ (neutral ref required)
RI-consistent 3-center (`ccm_neutral_cderi`)	neutral RI-J/K == four-center to machine ε; bare union RI-J ~1e-3 (non-separable)

Tests: tests/test_ccm_aiccm2026dev_a.py, tests/test_ccm_dft.py, tests/test_ccm_ri.py, tests/test_ccm_neutral.py.

Madelung gap — characterized (see The four-center Madelung gap above): the ionic over-binding is, to leading order, a mean-field background ξ·S⊗S. Both the absolute HF/KS energy and the correlation come from the neutral route (GDF reference): the background shifts the occ–virt gap, so it leaves the correlation numerator unchanged only at a fixed reference and the bare four-center is not a substitute for the neutral reference in post-HF (corrects an earlier “rigorously Madelung-robust correlation” claim). The neutral four-center ccm_eri_neutral (the §13.7 density-fit of v_E) makes the leading-order decomposition explicit; the non-rank-1 remainder is an open quantification.

RI consistency — resolved (§13.7): the RI-consistent three-center is the neutral cderi ccm_neutral_cderi (its RI-J/K reproduce the four-center to machine ε). The bare-1/r union RI-J (run_ccm_rhf_rij) is ~few-% because the bare-1/r four-center is non-separable; the GDF route is the RI-consistent energy.

Open items (research): a scalable dense-3-D neutral four-center (both ccm_eri_neutral/ccm_neutral_cderi and the bare padded four-center are small-cluster — the GDF route is the production energy path for dense ionic 3-D).

Theory: AICCM_ALGORITHM.md §13. Reference: Peintinger & Bredow, J. Comput. Chem. 35, 839 (2014), doi:10.1002/jcc.23550.

AICCM — the aiccm2026dev-a line (experimental)¶

What aiccm2026dev-a is¶