χ-CCM / aiccm2026dev-b: 3D backends and dimensional guards

This tutorial exercises only χ-CCM[1], the finite-translation-group character CCM implemented under the aiccm2026dev-b selector. Γ-CCM, the union-and-weight/Wigner–Seitz integral-weighting sibling selected as aiccm2026dev-a, has its own page and example. The inputs stay explicit so a future construction-level comparison will not share either implementation’s core; the current reportable route map is empty.

Build a small neutral 3D cell

import numpy as np
import vibeqc as vq

def h2_cell():
    lattice = np.diag([8.0, 12.0, 12.0])
    system = vq.PeriodicSystem(
        3,
        lattice,
        [vq.Atom(1, [0, 0, 0]), vq.Atom(1, [1.4, 0, 0])],
    )
    basis = vq.BasisSet(system.unit_cell_molecule(), "sto-3g")
    return system, basis

Lengths are in bohr. Current χ-CCM-B SCF is enabled only for 3D periodicity. True 1D wire and 2D slab absolute energies fail closed until one shared mixed-boundary Coulomb gauge is implemented. A chain-like visualization test can still be built as a 3D vacuum-padded torus; that is not a 1D Coulomb model.

Run 3D RHF and Kohn–Sham DFT

system, basis = h2_cell()
for backend in ("four_center", "ri", "rijcosx"):
    rhf = vq.run_aiccm2026dev_b_rhf(
        system, basis, lattice_extension=(2, 1, 1),
        backend=backend, progress=False
    )
    rks = vq.run_aiccm2026dev_b_rks(
        system, basis, "pbe0", lattice_extension=(2, 1, 1),
        backend=backend, progress=False
    )
    print(backend, rhf.energy, rks.energy)

rijcosx means RI-J plus COSX-K. It therefore exercises COSX in RHF and in a hybrid such as PBE0. For a pure functional such as PBE, RI and RIJCOSX have the same exchange content because there is no exact-exchange K term.

Inspect the invariants

d = rhf.aiccm2026dev_b
assert d.wigner_seitz_partition_error < 1e-12
assert d.density_idempotency_error < 1e-7
assert d.electron_count_error < 1e-7
print(d.mesh, d.backend, d.inverse_bloch_imaginary_residual)
print(d.coulomb_kernel, d.exchange_q0, d.boundary_model)

d.mesh is retained for compatibility; d.lattice_extension is the primary name. To ask for interactions through two primitive translations on both sides of each atom, use wigner_seitz_shells=2. This selects the odd extension (5, 5, 5) in 3D and derives the equivalent reciprocal character net automatically. Do not set a separate k mesh.

Do not validate the method by convergence alone. Repeat with increasing cyclic meshes and a matched reciprocal-space reference. No 1D/2D χ-CCM-B absolute energy is currently defined: every backend fails closed until one shared wire/slab Coulomb Hamiltonian is derived.

Confirm the lower-dimensional fail-close

Lower-dimensional inputs are guard coverage, not energy calculations. This check must print six expected failures and no energy:

for dim, lattice in (
    (1, np.diag([8.0, 20.0, 20.0])),
    (2, np.diag([8.0, 8.0, 20.0])),
):
    lowd_system = vq.PeriodicSystem(
        dim,
        lattice,
        [vq.Atom(1, [0, 0, 0]), vq.Atom(1, [1.4, 0, 0])],
    )
    lowd_basis = vq.BasisSet(lowd_system.unit_cell_molecule(), "sto-3g")
    for backend in ("four_center", "ri", "rijcosx"):
        try:
            vq.run_aiccm2026dev_b_rhf(
                lowd_system,
                lowd_basis,
                lattice_extension=(2, 1, 1),
                backend=backend,
                progress=False,
            )
        except NotImplementedError as exc:
            print(f"{dim}D {backend} expected fail-close: {exc}")
        else:
            raise AssertionError(
                f"{dim}D χ-CCM-B {backend} unexpectedly returned an energy"
            )

The convention fields are part of the numerical result, not prose decoration. For the current production route they read coulomb_kernel="3d-periodic-g0" and exchange_q0="bvk-ewald". A strict-zero-mode exchange reference changes the finite-N HF eigenvalues and therefore the MP2 or CC denominators, even though both choices target the same infinite-crystal limit.

Open the validated QVF fixtures

The docs include two small aiccm2026dev-b QVF archives that were rendered with vibe-view as periodic visualization checks:

They were generated at pre-D89 source d746d238 (shown as d746d23 in the archived output). They are visualization-only fixtures and lack the normative D89 approach identity fields. Do not use them as construction-comparison or numerical-validation evidence.

vibe-view open docs/_static/examples/chi-ccm-b-qvf/output-chi-ccm-b-hchain-ri-n4-wannier.qvf
vibe-view open docs/_static/examples/chi-ccm-b-qvf/output-chi-ccm-b-h2pair-3d-ri-n2-wannier.qvf

The first is a 3D vacuum-padded H-chain with aiccm_lattice_extension=(4,1,1); the second is a 3D H2-pair with aiccm_lattice_extension=(2,1,1). Each archive contains the full BvK display cell, the density grid, HOMO/LUMO volume sections, DOS/PDOS, the finite-torus convention vendor section, and an x_ccm.wannier_centers overlay. The published inputs, verbose .out logs, sanitized .system manifests, QVFs, and PNG captures are summarized in the chi-CCM-B fixture README.

Add canonical RI-MP2 in 3D

system, basis = h2_cell()
mp2 = vq.run_aiccm2026dev_b_mp2(
    system,
    basis,
    (2, 1, 1),
    progress=False,
)
print(mp2.e_hf_per_cell)
print(mp2.e_corr_ss_per_cell, mp2.e_corr_os_per_cell)
print(mp2.e_total_per_cell)
assert mp2.momentum_conservation_error < 1e-12
assert mp2.max_energy_imaginary_residual < 1e-12

The three-center factors are expressed in the original auxiliary basis before opposite momentum transfers are contracted. This removes arbitrary eigenvector phases between the (q) and (-q) metric factorizations. MP2 is not variational; its correctness gates are the finite-group momentum rule, real energy, size normalization, and reciprocal-space KMP2 parity. Check mp2.finite_torus_convention == mp2.hf_result.aiccm2026dev_b.finite_torus_convention before comparing against an external KMP2 or CC calculation.

Add local-PNO MP2 and CCSD(T)

from vibeqc.dlpno.ccsd_local_solver import LocalCCSDOptions
from vibeqc.dlpno.mp2 import DLPNOMP2Options

local_mp2 = vq.run_aiccm2026dev_b_dlpno_mp2(
    system,
    basis,
    (2, 1, 1),
    dlpno_options=DLPNOMP2Options(
        localise="wannier",
        tcut_pno=0.0,
        tcut_pno_weak=0.0,
        tcut_mkn=0.0,
        tcut_pairs=0.0,
        tcut_pairs_weak=0.0,
    ),
    progress=False,
)

local_cc = vq.run_aiccm2026dev_b_dlpno_ccsd_t(
    system,
    basis,
    (2, 1, 1),
    cc_options=LocalCCSDOptions(
        localise="pipek-mezey",
        tcut_pairs=0.0,
        coupling_radius=0.0,
        compute_triples=True,
        triples_mode="t1",
    ),
    progress=False,
)
canonical_cc = vq.run_aiccm2026dev_b_ccsd_t(
    system,
    basis,
    lattice_extension=(2, 1, 1),
    progress=False,
)
print(local_mp2.e_corr_per_cell)
print(local_mp2.raw_local_e_corr_per_cell)
print(local_mp2.complete_space_correction_per_cell)
print(local_mp2.local_correlation_space)
print(local_cc.e_corr_per_cell, local_cc.e_t_per_cell)
print(canonical_cc.e_corr_per_cell, canonical_cc.e_t_per_cell)

The real-torus transform is exact. localise="wannier" uses the B-only finite-torus occupied gauge described in the localization tutorial. The returned local space reports the exact-limit PAO rank and candidate translation pair orbits. It does not skip equivalent pairs yet. IAO pair propagation is gated because its explicit-supercell cross overlap is not exactly translation covariant.

At complete domains and zero PNO thresholds, the MP2 wrapper independently evaluates a full-space, rotation-invariant DF-MP2 contraction. The raw local solver value and complete_space_correction_per_cell remain visible; the reported total recovers the canonical finite-torus limit. Truncated PNO calculations receive no correction. Pipek–Mezey remains available, while molecular Boys localization is rejected.

For the exact-limit diagnostic, use localise="none", set tcut_pno and tcut_mkn to zero, keep tcut_pairs=0 and coupling_radius=0, and select triples_mode="exact". This is a validation calculation, not a scalable production setting. The LiH example has a nonzero triples term and is pinned against a separately contracted canonical finite-torus DF-CCSD(T) oracle. The localized-gauge CC exact-limit audit is still open, so the CC example continues to use Pipek–Mezey rather than claiming Wannier-gauge parity.

Open-shell HF, KS, and correlation

li = vq.PeriodicSystem(
    3,
    np.eye(3) * 15.0,
    [vq.Atom(3, [0.0, 0.0, 0.0])],
    multiplicity=2,
)
li_basis = vq.BasisSet(li.unit_cell_molecule(), "sto-3g")

uhf = vq.run_aiccm2026dev_b_uhf(
    li, li_basis, lattice_extension=(1, 1, 1),
    backend="ri", progress=False,
)
uks = vq.run_aiccm2026dev_b_uks(
    li, li_basis, "lda", lattice_extension=(1, 1, 1),
    backend="ri", progress=False,
)
ump2 = vq.run_aiccm2026dev_b_ump2(
    li, li_basis, lattice_extension=(1, 1, 1), progress=False,
)
uccsdt = vq.run_aiccm2026dev_b_uccsd_t(
    li, li_basis, lattice_extension=(1, 1, 1), progress=False,
)
local_uccsdt = vq.run_aiccm2026dev_b_dlpno_uccsd_t(
    li, li_basis, lattice_extension=(1, 1, 1), progress=False,
)

properties = vq.derive_aiccm2026dev_b_scf_properties(uhf, li, li_basis)
print(properties.n_alpha, properties.n_beta, properties.s_squared)
print(properties.mulliken_spin_populations)
print(ump2.energy, uccsdt.energy, local_uccsdt.energy)

The one-cell Li example is a code-path check, not a converged crystal. Increase the real-space extension and inspect the localization aliasing flags before using local domains. Canonical UMP2 uses zero PNO truncation. Canonical UCCSD and UCCSD(T) use the full-domain O(N^6) pilot and are deliberately capped by max_nbf; the current local sibling is the PNO projection oracle, not yet the representative-pair reduced-scaling production algorithm.

Run the maintained example

python examples/periodic/aiccm2026dev_b_demo.py --dim 3 --backend four_center
python examples/periodic/aiccm2026dev_b_demo.py --dim 3 --backend ri
python examples/periodic/aiccm2026dev_b_demo.py --dim 3 --backend rijcosx
python examples/periodic/aiccm2026dev_b_mp2.py
python examples/periodic/aiccm2026dev_b_local_correlation.py

# Expected fail-closed guard checks; these print no energy.
python examples/periodic/aiccm2026dev_b_demo.py --dim 1 --backend ri
python examples/periodic/aiccm2026dev_b_demo.py --dim 2 --backend rijcosx

All 1D/2D B SCF backends intentionally raise before SCF. Do not use a lower-dimensional demo invocation as an energy calculation until one shared wire/slab Coulomb convention is derived.

For a historical H4 side-by-side route diagnostic, run examples/regression/benchmark_aiccm2026dev_b.py. It explicitly reports the Γ-CCM/χ-CCM approach comparison as not-defined and emits no approach delta.

For the B/CRYSTAL fleet and future cross-approach study, generate the χ-CCM-owned inputs from the shared system registry. The current Γ-CCM/χ-CCM approach-comparison status remains not-defined:

python aiccm-2026/make_jobs_b.py --profile coverage
python aiccm-2026/make_jobs_b.py --profile coverage | sh

The coverage profile records the 1D/2D rows as expected fail-closed coverage, runs all nine RHF/RKS integral combinations in 3D, and then runs all four implemented 3D post-HF routes. The larger scf, posthf, paper, and full profiles are documented in aiccm-2026/README_B.md.

---

[1]

Γ-CCM and χ-CCM are distinct CCM approaches. Γ-CCM uses the union-and-weight/Wigner–Seitz integral-weighting construction; χ-CCM uses the finite-translation-group character construction. They are compared at a declared common exchange-q=0 convention. Their distinction is not a choice of Coulomb kernels, and equality for a specified operator/route is evidence to establish, not a naming premise.