AICCM troubleshooting and diagnostics

This page catalogues the common failure modes and diagnostic signals you will encounter with Γ-CCM and χ-CCM[1]. Γ-CCM is the direct-torus representation; χ-CCM is the finite-character (Γ-centred character-mesh) representation of the same declared finite-BvK-torus Hamiltonian. For each: what it looks like, which JSON field or log line to check, and the fix.

1. S^CCM non-positive-definite - ill-conditioned cluster

Symptom. The SCF diverges immediately, or the energy is unphysically low/high, or the run fails with a linear-dependence error.

Cause. The cyclic-cluster overlap matrix S^CCM has a negative or near-zero eigenvalue. This happens when the cluster is too small for the basis (atoms are too close across cell boundaries) or when the geometry is compressed. The LiH chain at the CRYSTAL .d12 spacing of a=2.0 Å is the canonical example - the overlap collapses to non-PD.

Diagnose. Run the pre-flight check:

cd aiccm-2026
python testset.py --check

Or inspect programmatically:

import numpy as np
from vibeqc.periodic.ccm import CCMSystem, ccm_overlap

ccm = CCMSystem(system, nrep, basis)
S = ccm_overlap(ccm)
eig_min = float(np.linalg.eigvalsh(S)[0])
print(f"min eig S^CCM = {eig_min:.2e}")
assert eig_min > 1e-3, "Cluster is ill-conditioned - increase nrep or spacing"

Fix. Increase the cluster size (nrep), increase the cell spacing, or switch to a more compact basis. For 1-D chains, ensure the vacuum padding in non-periodic directions is at least 20-40 bohr.

2. Madelung over-binding on ionic systems (bare four-center)

Symptom. The bare-1/r four-center energy is significantly lower (more negative) than the GDF reference on an ionic crystal. E.g. LiH rocksalt RKS-PBE/atom: 4-center −4.540 vs GDF −4.203 Ha - a 337 mHa/atom gap.

Cause. The bare 1/r sum is not charge-neutral; it carries a Madelung-scale self-interaction. The correct periodic interaction on a torus is the neutral (Ewald) Green’s function v_E.

Diagnose. Compare bare-4c vs GDF on the same system:

cd aiccm-2026
python run_case.py lih-rocksalt aiccm-hf --out /tmp/
python run_case.py lih-rocksalt aiccm-ri   --out /tmp/
# The aiccm-hf (bare 4c) energy will be ~hundreds of mHa/atom lower

Or in Python:

from vibeqc.periodic.ccm.scf import run_ccm_rhf
from vibeqc.periodic.ccm.ri import run_ccm_rhf_gdf
from vibeqc.periodic.ccm import ccm_eri_neutral

e_bare = run_ccm_rhf(ccm, method="aiccm2026dev-a").energy_per_atom
e_ri   = run_ccm_rhf_gdf(ccm).energy_per_atom
e_neutral = run_ccm_rhf(ccm, eri=ccm_eri_neutral(ccm)).energy_per_atom
print(f"bare − GDF = {(e_bare - e_ri) * 1000:.1f} mHa/atom")

Fix. For absolute HF/KS energies of ionic systems, use the GDF route (run_ccm_rhf_gdf / aiccm-ri). The bare four-center remains valid for covalent / molecular / 1-D systems and for energy differences where the Madelung shift cancels. For ionic correlation, run the post-HF stack on the neutral four-center (ccm_eri_neutral) - the neutral reference is required because the Madelung background shifts the occupied-virtual denominators.

The test set flags this explicitly: systems with four_center_quantitative=False have a Madelung gap and need the RI/GDF route.

3. Low-dimensional RI exxdiv over-binding

Symptom. On 1-D and 2-D systems, the aiccm-ri and aiccm-ks-ri (and gdf) routes produce an energy that is consistently ~192 mHa/atom (1-D h-chain) or similar below the four-center / bipole reference, roughly independent of cluster size.

Cause. The multi-k GDF RI routes carry a 3D-Ewald exxdiv='ewald' correction that over-binds vacuum-padded low-dimensional cells. This is a periodic-GDF low-D/vacuum limitation shared by the multi-k gdf reference family, not a CCM-weighting issue.

Diagnose. Compare RI vs four-center on the same 1-D/2-D system:

python run_case.py h-chain aiccm-hf   # four-center (correct)
python run_case.py h-chain aiccm-ri   # GDF RI (over-binds ~192 mHa/atom)
python run_case.py h-chain bipole     # BIPOLE reference (correct)

Fix. For 1-D and 2-D, use the four-center (aiccm-hf/aiccm-ks) or the real-space bipole reference. The RI routes are reliable for 3-D bulk. Energy differences (where the shift cancels) and correlation are unaffected.

The run_case.py docstring and the runner both print this caveat.

4. χ-CCM four-center blocked in 1-D and 2-D

Symptom. run_periodic_job(..., aiccm_backend="four_center") fails on a 1-D or 2-D system with a clear error.

Cause. χ-CCM’s direct four-center backend uses the neutral 3-D Ewald J-split, which is not defined for 1-D/2-D cells. A neutral wire/slab Green function is required but not yet implemented.

Diagnose. The error is explicit - no guesswork needed.

Fix. Use aiccm_backend="ri" or aiccm_backend="rijcosx" for 1-D and 2-D χ-CCM runs. The four-center backend is currently 3-D only.

5. SCF oscillation on metals or near-metallic systems

Symptom. The SCF energy oscillates between iterations without converging, or converges to a state with unphysical properties.

Cause. Metals (gapless systems) are outside the CCM’s design envelope. The CCM targets gapped insulators and semiconductors; a vanishing gap makes the SCF ill-conditioned. The na-bcc system in the test set is a metal and is flagged as tier-C / convergence-risky.

Diagnose. Inspect the SCF trace in the output JSON. In the χ-CCM runner the scf_trace_tail field shows the last 8 iterations’ energy step and gradient norm.

Fix. If you must run a metal:

  • Enable smearing (--smearing-temperature 0.01)

  • Use a level shift (--level-shift 0.3 --level-shift-warmup 5)

  • Try the EDIIS+DIIS accelerator (--scf-accelerator EDIIS_DIIS)

  • Increase the cluster size (a Γ-only calculation on a small cluster of a metal may have no gap at all)

The test-set backup for na-bcc is sc2o3-bixbyite (a cI insulator, same Bravais lattice).

6. DIIS subspace too small or too large

Symptom. The SCF converges slowly (many iterations) or diverges after a few DIIS cycles.

Diagnose. The DIIS subspace size (diis_subspace, default 6) and start iteration (diis_start, default 2) are printed in the JSON output. A subspace that is too small discards useful history; one that is too large admits near-linear-dependent error vectors.

Fix. For difficult systems, try a larger subspace:

python run_case.py mgo aiccm-hf --diis-dim 12    # Γ-CCM
python run_case_b.py mgo rhf-ri --diis-subspace 12  # χ-CCM

Or delay DIIS to build a better initial density:

python run_case_b.py mgo rhf-ri --diis-start 5

If DIIS consistently destabilises, try damping without DIIS:

python run_case_b.py mgo rhf-ri --damping 0.5 --no-diis

7. χ-CCM COSX requires at least two cyclic cells

Symptom. run_case_b.py ... rhf-rijcosx fails when the mesh is (1,1,1).

Cause. The native finite-torus chain-of-spheres exchange bridge needs at least two cyclic cells per active direction to construct the neighbour list.

Diagnose. The error is explicit.

Fix. Use a mesh of at least (2,1,1) or (2,2,1) for active directions, or switch to rhf-ri for single-cell runs.

8. Post-HF OOM on dense 3-D four-center

Symptom. run_ccm_mp2 or run_ccm_ccsd runs out of memory on a 3-D ionic crystal with more than ~16 atoms.

Cause. The padded four-center and neutral cderi builds are small-cluster validation paths - they build the full N⁴ ERI tensor. Dense 3-D four-centers OOM beyond small clusters.

Diagnose. Monitor memory. The C++ scalable HF kernel handles the SCF; the post-HF ERI builder does not yet have a scalable 3-D path.

Fix. For 3-D energies, use the GDF route (run_ccm_rhf_gdf). For 3-D correlation, use DLPNO-CCSD(T) (which works through the neutral cderi and is subspace-projected) or the χ-CCM post-HF routes (which use pair-resolved RI tensors). Canonical CCSD(T) on the four-center is currently feasible only for 1-D chains and very small 2-D/3-D clusters.

9. χ-CCM post-HF is 3-D only

Symptom. run_case_b.py h-chain ri-mp2 or any post-HF route on a 1-D or 2-D system fails closed.

Cause. χ-CCM’s post-HF Coulomb derivation is validated only in 3-D. Lower-dimensional long-range gauges are not yet matched.

Diagnose. The b_routes.py unsupported_reason function reports this explicitly for each (system, route) combination.

Fix. Run post-HF on 3-D systems only. The coverage profile in make_jobs_b.py intentionally restricts post-HF to the 3-D LiH anchor.

10. Γ-CCM DLPNO requires the neutral reference

Symptom. ccm_dlpno_mp2 or ccm_dlpno_ccsd produce correlation energies that disagree with the canonical CCM MP2/CCSD(T) by more than machine epsilon at zero PNO truncation.

Cause. The DLPNO machinery expects the neutral cderi (from ccm_neutral_cderi) and the neutral g_neutral (from ccm_eri_neutral). Passing the bare-1/r four-center or its cderi shifts the denominators.

Diagnose. Check the no-truncation gate: ccm_dlpno_mp2(..., tcut_pno=0.0).e_corr must equal run_ccm_mp2(..., eri=g_neutral).e_correlation to machine ε.

Fix. Always construct the neutral reference:

from vibeqc.periodic.ccm.neutral import ccm_eri_neutral, ccm_neutral_cderi

g = ccm_eri_neutral(ccm, ke_cutoff=120.0)
L = ccm_neutral_cderi(ccm, ke_cutoff=120.0)
scf = run_ccm_rhf(ccm, eri=g)
dlpno = ccm_dlpno_mp2(ccm, scf, cderi=L, localize="pm")

See also