χ-CCM / aiccm2026dev-b (experimental)¶
aiccm2026dev-b is the code selector for χ-CCM[1], the
finite-translation-group character approach to the variational finite-BvK-torus
CCM. The name is prose only: use
jk_method="aiccm2026dev-b" in inputs. Its sibling is
aiccm2026dev-a, Γ-CCM, which uses the
union-and-weight/Wigner–Seitz integral-weighting construction. The selectors,
core mathematics, tests, examples, and handovers remain separate so comparison
of the two approaches stays auditable.
D89 records the B identity explicitly:
ccm_approach="chi-ccm",
ccm_construction="finite-translation-group-character", and
evaluation_representation="gamma-centred-character-mesh". These immutable
fields appear on B diagnostics/results and in fleet, QVF vendor, and .system
metadata. QVF schema version 1 keeps the older human-readable
representation field for compatibility, but evaluation_representation is
normative. The exact real-Gamma Fourier form of the same χ-defined Hamiltonian
is an evaluation control, not a Γ-CCM identity. Pre-D89 records are not
numerically retracted solely for lacking the new fields, but they cannot be
used as construction-comparison evidence.
Warning
The 3D SCF routes remain active experimental diagnostics, but their numerical
two-electron supports are not all absolute-energy converged. BIPOLE-routed
four-center values are revision-bound unless they record a converged opt-in
M4a sr_image_extent_bohr, or until efficient M4b becomes the production
default. The χ-CCM-B selector and fleet runner do not yet expose or attest
M4a. Restricted semilocal four-center RKS instead needs a reciprocal-tail
policy, and dense-core RSGDF-200 RI/RIJCOSX values are convergence or
route-plumbing evidence rather than quantitative absolute energies. Do not
curate those rows for publication without an explicit truncation-convergence
contract.
Warning
D88 corrects a lattice-convention defect in pre-D88 χ-CCM-B records.
PeriodicSystem.lattice stores lattice vectors as columns, so Cartesian
translations are system.lattice @ n and the BvK lattice is
system.lattice @ diag(mesh). New convention records serialize
lattice_vector_convention="columns", and successful fleet payloads record
primitive_lattice_bohr. The fleet audit binds the exact BvK matrix to those
fields; the Γ/χ comparator reports no comparison when the binding is absent or
inconsistent. Because the Madelung, probe-charge, and
fleet helpers are shared, all affected pre-D88 Γ-CCM and χ-CCM records require
rerun under the fingerprint rule; no missing convention field is inferred. A
symmetric lattice that commutes with diag(mesh) is numerically outside this
defect class, but its old record is not newly attested. The shared builders for
graphene, mgo-slab, ice-ih, co2-dryice, and sio2-quartz require fresh
Γ and χ fingerprints. Ordinary pre-D88 periodic GDF exact-exchange and BIPOLE
J/K records for affected lattice/mesh combinations also require audit and
rerun.
For the skew audit matrix [[7,.4,.2],[.3,8,.5],[.1,.6,9]] bohr and mesh
(2,3,1), the corrected positive Madelung convention gives
xi_M=0.138352993811598. The pre-D88 fitted helper gave
0.143621616230995, an RHF two-electron seam overbinding of 5.268622
mHa/cell, while the pre-D88 four-center probe gave 0.138913224426180.
The theory article already uses the column convention correctly. D88 is a
code and fingerprint repair, not a kernel, sign, or theory change. The 1D/2D
absolute-energy guard and analytic-total-gradient guard remain fail closed.
D89 records that Γ-CCM and χ-CCM are distinct approaches, not representation
aliases. This warning holds the declared exchange-q=0 convention fixed and
does not assign different Coulomb kernels to the approach names.
χ-CCM defines a finite Born–von Karman translation group from a real-space lattice extension. Its full Γ-centred character net is then derived exactly. It minimizes RHF/RKS or UHF/UKS energy over translation-commuting idempotent spin densities. Wigner–Seitz weights select only tied representatives of one translation class. They are not multiplied into an otherwise non-periodized three- or four-center tensor.
Run it¶
result = vq.run_periodic_job(
system,
basis,
method="RKS",
functional="pbe0",
jk_method="aiccm2026dev-b",
aiccm_lattice_extension=(2, 1, 1),
aiccm_backend="ri", # "four_center", "ri", or "rijcosx"
rsgdf_ke_cutoff=200.0,
)
check = result.aiccm2026dev_b
print(result.energy)
print(check.density_idempotency_error, check.electron_count_error)
print(check.coulomb_kernel, check.exchange_q0, check.boundary_model)
For vibe-view-ready periodic archives, leave output_qvf=True (the default).
χ-CCM-B writes torus-periodic density grids over the full BvK cell and, for
restricted records, torus-periodic orbital grids instead of molecular
wavefunction.gto payloads. Add qvf_wannier_centers=True to also localize
the occupied finite-torus space and embed an x_ccm.wannier_centers overlay
in Angstrom / Angstrom-squared units; unrestricted records currently emit the
spin-summed density plus alpha/beta Wannier centres, not spin-resolved orbital
grids.
aiccm_wigner_seitz_shells=2 is the radius-style alternative. It produces
five primitive translations in every active direction, from (-2) through
(+2), and hence an odd cyclic extension of five. The legacy kpoints= tuple
is retained as an exact alias, but it is not a second convergence parameter.
Creating inputs¶
There are three ways to create a χ-CCM input, from fastest to most customisable.
1. The test-set runner (fastest)¶
The aiccm-2026/ runner covers every implemented closed-shell route and
lists unsupported theory gaps explicitly.
cd aiccm-2026
# Quick start - 3-D MgO RHF/RI route smoke; default KE is not quantitative
python run_case_b.py mgo rhf-ri
# Four-center diagnostic only; absolute values are revision-bound
python run_case_b.py c-diamond rhf-4c
# RKS/PBE with RI backend on diamond
python run_case_b.py c-diamond rks-pbe-ri
# Hybrid functional with RIJCOSX
python run_case_b.py bn-zb rks-pbe0-rijcosx
# Post-HF: canonical RI-MP2 on 3-D LiH rocksalt (3-D only)
python run_case_b.py lih-rocksalt ri-mp2
# DLPNO local correlation (exact limit = canonical oracle)
python run_case_b.py lih-rocksalt dlpno-mp2 --local-mode exact
# Override cluster size and basis
python run_case_b.py mgo rhf-ri --mesh 2 2 2 --basis pob-tzvp-rev2
Every run writes <system>__b-<route>.json with energy, orbital properties,
SCF diagnostics (idempotency, electron count, commutator norm, DIIS subspace,
accelerator settings), and for post-HF routes: correlation components, pair
counts, T1 norm, PNO correction, and finite-torus factor residuals.
scf_options.fock_mixing is the requested input, whereas
convergence_diagnostics.fock_mixing is the executed effective previous-Fock
weight after backend defaults are resolved. The values can differ for a
DIIS-off four-center KS run, where a request of 0.0 can execute as 0.30.
This is provenance only; it does not change the SCF algorithm or energy.
Pre-D86 records in that case are not convergence-fingerprint-complete.
For direct Python SCF calls, a non-None fock_mixing= keyword overrides
options.fock_mixing; otherwise the options field supplies the request. The
selected request must lie in [0, 1), and resolving it does not rewrite the
caller’s options field. All four four_center routes and multi-cell fitted
RHF/RKS can execute a nonzero request. Three-dimensional Gamma-only RI RHF
accepts resolved zero but rejects nonzero because mixing would switch to the
legacy molecular-limit GDF operator; the other one-cell fitted restrictions
are unchanged. Fitted RI/RIJCOSX UHF/UKS do not implement a previous-Fock
mixing loop and therefore
reject a nonzero request explicitly.
An explicit keyword zero overrides a nonzero options value, although that
requested zero can still resolve to executed 0.30 on a DIIS-off four-center
KS route under the documented automatic rule. D87 changes convergence-control
selection and validation on supported execution routes, not their finite
Hamiltonian or backend mixing formula. The Gamma explicit-zero correction
deliberately restores the declared operator instead of preserving the old
route-selection bug. Successful pre-D87 direct calls with differing
keyword/options values, plus fitted RI/RIJCOSX UHF/UKS calls with a nonzero
options-only request, have
incomplete request fingerprints. Pre-D87 Gamma-only RI RHF calls where either
input source was nonzero, including an explicit-zero keyword over nonzero
options, followed the legacy operator and are not χ-CCM-B results. The 1D/2D
absolute-energy and analytic total-gradient fail-closed policies remain in
force. D72 now runs before every backend-specific Gamma and mixing guard,
closing a former 1D one-cell RI-RHF escape. Any value from that route is
invalid and must not be reported.
2. Fleet batch generation¶
Generate the full benchmark matrix and submit to the vibe-queue scheduler:
cd aiccm-2026
# Coverage: all currently runnable SCF implementations + post-HF on 3D LiH
python make_jobs_b.py --profile coverage
python make_jobs_b.py --profile coverage | sh
# First AICCM-paper χ-CCM route matrix
python make_jobs_b.py --profile paper1
python make_jobs_b.py --profile paper1 | sh
# Same route/mesh matrix at the CRYSTAL-matched orbital basis
python make_jobs_b.py --profile paper1 --basis pob-tzvp-rev2 | sh
# All closed-shell systems through all nine SCF paths
python make_jobs_b.py --profile scf | sh
# All valid post-HF inputs
python make_jobs_b.py --profile posthf | sh
# Diamond-family RKS/PBE/RI convergence investigation
python make_jobs_b.py --profile investigate | sh
# Focused submissions
python make_jobs_b.py --profile scf --system mgo --host twin-big | sh
python make_jobs_b.py --profile posthf --system lih-rocksalt --host twin-big | sh
Each emitted job claims 4 CPU slots / 8 GB memory and targets the appropriate
fleet host by tier. The paper1 profile defaults to twin-big; lower-dimensional
anchors are retained as explicit fail-closed coverage until O1 supplies a shared
wire/slab Coulomb kernel. In the larger profiles, tier A targets mars, tier
B/C targets twin-big, and post-HF targets twin-big. Override with --host.
3. Building a system from scratch - worked examples¶
Every example is a complete, runnable script. Copy-paste, adjust the geometry and basis, and run.
Example 1 - 3-D H₂: all three backends side by side¶
import numpy as np
import vibeqc as vq
system = vq.PeriodicSystem(
3, np.diag([8.0, 12.0, 12.0]),
[vq.Atom(1, [0, 0, 0]), vq.Atom(1, [1.4, 0, 0])],
)
basis = vq.BasisSet(system.unit_cell_molecule(), "sto-3g")
common = dict(
jk_method="aiccm2026dev-b",
aiccm_lattice_extension=(2, 1, 1),
max_iter=40, progress=False,
citations=False, write_xyz_file=False, output_qvf=False,
)
for backend in ("four_center", "ri", "rijcosx"):
r = vq.run_periodic_job(system, basis, method="RHF",
aiccm_backend=backend, **common)
d = r.aiccm2026dev_b
print(f"{'RHF/' + backend:>14s} E/cell = {r.energy:.12f} Ha "
f"idem = {d.density_idempotency_error:.1e}")
This example checks dispatch and internal consistency. It is not a license to interpret the three printed finite-cutoff values as independently converged absolute energies.
Example 2 - 1-D polymer chain: RI backend with vacuum padding¶
import numpy as np
import vibeqc as vq
# Polyethylene-like 1-D chain: 2 CH₂ units along x, 20 bohr vacuum in y,z
system = vq.PeriodicSystem(
1, np.diag([5.0, 20.0, 20.0]),
[vq.Atom(6, [0, 0, 0]), vq.Atom(1, [0.9, 0, 0]),
vq.Atom(1, [-0.9, 0, 0]),
vq.Atom(6, [2.5, 0, 0]), vq.Atom(1, [3.4, 0, 0]),
vq.Atom(1, [1.6, 0, 0])],
)
basis = vq.BasisSet(system.unit_cell_molecule(), "sto-3g")
# 1-D: all current χ-CCM-B SCF backends fail closed until O1 lands.
for backend in ("ri", "rijcosx"):
try:
vq.run_periodic_job(
system, basis, method="RKS", functional="pbe",
jk_method="aiccm2026dev-b",
aiccm_lattice_extension=(4, 1, 1),
aiccm_backend=backend,
max_iter=60, progress=False,
)
except NotImplementedError as exc:
print(f"{backend} is intentionally blocked: {exc}")
Example 3 - 2-D slab: MgO(001) surface¶
import numpy as np
import vibeqc as vq
a = 4.21 # Angstrom
# 2-D slab: periodic in xy, 50 bohr vacuum in z
lat = np.array([[a/2, a/2, 0], [-a/2, a/2, 0], [0, 0, 50.0]])
system = vq.PeriodicSystem(
2, lat,
[vq.Atom(12, [0, 0, 0]), vq.Atom(8, [0, a/2, 0])],
)
basis = vq.BasisSet(system.unit_cell_molecule(), "sto-3g")
try:
vq.run_periodic_job(
system, basis, method="RHF",
jk_method="aiccm2026dev-b",
aiccm_lattice_extension=(2, 2, 1),
aiccm_backend="ri",
max_iter=60, progress=False,
)
except NotImplementedError as exc:
print(f"2-D χ-CCM-B RI is intentionally blocked: {exc}")
Example 4 - Diamond: hybrid functional comparison (PBE vs PBE0)¶
import numpy as np
import vibeqc as vq
a = 3.5670
lat = np.array([[0, a/2, a/2], [a/2, 0, a/2], [a/2, a/2, 0]])
system = vq.PeriodicSystem(
3, lat,
[vq.Atom(6, [0, 0, 0]), vq.Atom(6, [a/4, a/4, a/4])],
)
basis = vq.BasisSet(system.unit_cell_molecule(), "sto-3g")
for func, backend in [("pbe", "ri"), ("pbe0", "ri"),
("pbe", "rijcosx"), ("pbe0", "rijcosx")]:
r = vq.run_periodic_job(
system, basis, method="RKS", functional=func,
jk_method="aiccm2026dev-b",
aiccm_lattice_extension=(2, 2, 2),
aiccm_backend=backend,
max_iter=80, progress=False,
)
gap = r.aiccm2026dev_b.fundamental_gap
print(f"{'RKS/' + func + '/' + backend:>20s} E/atom = {r.energy / 2:.8f} Ha",
f"gap = {gap:.4f}" if gap else "")
Example 5 - LiH rocksalt: full post-HF stack¶
import numpy as np
import vibeqc as vq
from vibeqc.periodic_aiccm2026dev_b_posthf import (
run_aiccm2026dev_b_mp2,
run_aiccm2026dev_b_dlpno_mp2,
run_aiccm2026dev_b_dlpno_ccsd_t,
)
a = 4.0840
lat = np.array([[0, a/2, a/2], [a/2, 0, a/2], [a/2, a/2, 0]])
system = vq.PeriodicSystem(
3, lat,
[vq.Atom(3, [0, 0, 0]),
vq.Atom(1, (lat @ np.array([0.5, 0.5, 0.5])).tolist())],
)
basis = vq.BasisSet(system.unit_cell_molecule(), "sto-3g")
ext = (2, 2, 2)
# Canonical RI-MP2 (exact finite-torus oracle)
mp2 = run_aiccm2026dev_b_mp2(system, basis, lattice_extension=ext)
print(f"Canonical RI-MP2 Ecorr = {mp2.e_correlation:.8f} Ha")
# DLPNO-MP2 at the exact (no-truncation) limit == canonical
for mode in ("exact", "pno"):
d_mp2 = run_aiccm2026dev_b_dlpno_mp2(
system, basis, lattice_extension=ext, local_mode=mode,
)
print(f"DLPNO-MP2 ({mode:>5s}) Ecorr = {d_mp2.e_corr:.8f} Ha "
f"npairs = {d_mp2.n_pairs}")
# DLPNO-CCSD(T) -- exact limit and truncated
for mode in ("exact", "pno"):
d_cc = run_aiccm2026dev_b_dlpno_ccsd_t(
system, basis, lattice_extension=ext, local_mode=mode,
)
print(f"DLPNO-CCSD(T) ({mode:>5s}) Ecorr = {d_cc.e_correlation:.8f} Ha "
f"(T) = {d_cc.e_t:.2e}")
Example 6 - Local correlation: localization modes and PNO truncation¶
import numpy as np
import vibeqc as vq
from vibeqc.periodic_aiccm2026dev_b_posthf import run_aiccm2026dev_b_dlpno_mp2
a = 4.0840
lat = np.array([[0, a/2, a/2], [a/2, 0, a/2], [a/2, a/2, 0]])
system = vq.PeriodicSystem(
3, lat,
[vq.Atom(3, [0, 0, 0]),
vq.Atom(1, (lat @ np.array([0.5, 0.5, 0.5])).tolist())],
)
basis = vq.BasisSet(system.unit_cell_molecule(), "sto-3g")
# Compare localization methods at the exact limit
for localise in ("pm", "wannier", "iao", "none"):
r = run_aiccm2026dev_b_dlpno_mp2(
system, basis, lattice_extension=(2, 1, 1),
localise=localise, local_mode="exact",
)
print(f"DLPNO-MP2 l={localise:>7s} Ecorr = {r.e_corr:.8f} Ha")
# PNO truncation sweep
print("\nPNO truncation sweep (Pipek--Mezey):")
for tcut in (0.0, 1e-8, 1e-7, 1e-6, 1e-5):
r = run_aiccm2026dev_b_dlpno_mp2(
system, basis, lattice_extension=(2, 1, 1),
localise="pm", local_mode="pno", tcut_pno=tcut,
)
print(f" tcut_pno={tcut:.0e} Ecorr = {r.e_corr:.8f} "
f"npairs = {r.n_pairs}")
Example 7 - Properties: band structure, Mayer bond orders, charges¶
import numpy as np
import vibeqc as vq
from vibeqc.periodic_aiccm2026dev_b_properties import (
derive_aiccm2026dev_b_scf_properties,
aiccm2026dev_b_band_structure,
aiccm2026dev_b_mayer_bond_orders,
)
a = 3.5670
lat = np.array([[0, a/2, a/2], [a/2, 0, a/2], [a/2, a/2, 0]])
system = vq.PeriodicSystem(
3, lat,
[vq.Atom(6, [0, 0, 0]), vq.Atom(6, [a/4, a/4, a/4])],
)
basis = vq.BasisSet(system.unit_cell_molecule(), "sto-3g")
# SCF first
result = vq.run_periodic_job(
system, basis, method="RHF",
jk_method="aiccm2026dev-b",
aiccm_lattice_extension=(2, 2, 2),
aiccm_backend="ri",
max_iter=80, progress=False,
)
# One-particle properties
props = derive_aiccm2026dev_b_scf_properties(result, system, basis)
print(f"HOMO = {props.homo:.4f} Ha, LUMO = {props.lumo:.4f} Ha")
print(f"Gap = {props.gap:.4f} Ha = {props.gap * 27.2114:.2f} eV")
print("Mulliken charges:", props.mulliken_charges)
print(f"Density idempotency: {props.density_idempotency:.2e}")
# Band structure (folded-Γ spectrum on the torus)
bands = aiccm2026dev_b_band_structure(
system, basis, result,
k_path_labels=["Γ", "X", "W", "K", "Γ", "L", "U"],
)
print(f"Band path: {len(bands.k_points)} k-points, "
f"{bands.n_bands} bands")
# Mayer bond orders (primitive cell)
bonds = aiccm2026dev_b_mayer_bond_orders(result, system, basis)
for (i, j), bo in bonds.bond_orders.items():
print(f" Bond ({i},{j}): BO = {bo:.4f}")
Example 8 - SCF convergence tuning¶
import numpy as np
import vibeqc as vq
a = 4.0840
lat = np.array([[0, a/2, a/2], [a/2, 0, a/2], [a/2, a/2, 0]])
system = vq.PeriodicSystem(
3, lat,
[vq.Atom(3, [0, 0, 0]),
vq.Atom(1, (lat @ np.array([0.5, 0.5, 0.5])).tolist())],
)
basis = vq.BasisSet(system.unit_cell_molecule(), "sto-3g")
base = dict(
method="RHF", jk_method="aiccm2026dev-b",
aiccm_backend="ri", aiccm_lattice_extension=(2, 2, 2),
max_iter=100, progress=False,
)
# Default (DIIS from iter 2, subspace 6)
r_def = vq.run_periodic_job(system, basis, **base)
print(f"Default DIIS: {r_def.energy:.8f} Ha "
f"{r_def.n_iter} iters")
# Larger DIIS subspace
r_diis = vq.run_periodic_job(system, basis, diis_subspace=12, **base)
print(f"DIIS n=12: {r_diis.energy:.8f} Ha "
f"{r_diis.n_iter} iters")
# EDIIS+DIIS accelerator
r_ediis = vq.run_periodic_job(
system, basis, scf_accelerator="EDIIS_DIIS", **base,
)
print(f"EDIIS+DIIS: {r_ediis.energy:.8f} Ha "
f"{r_ediis.n_iter} iters")
# Level shift + dynamic damping (ionic convergence aid)
r_ls = vq.run_periodic_job(
system, basis,
level_shift=0.3, level_shift_warmup=5,
dynamic_damping=True, damping=0.5,
**base,
)
print(f"LS+damp: {r_ls.energy:.8f} Ha "
f"{r_ls.n_iter} iters")
# Damping only, no DIIS
r_damp = vq.run_periodic_job(
system, basis, damping=0.3, use_diis=False, **base,
)
print(f"Damp 0.3: {r_damp.energy:.8f} Ha "
f"{r_damp.n_iter} iters")
Example 9 - Wigner-Seitz shell sizing (radius-style)¶
import numpy as np
import vibeqc as vq
a = 3.5670
lat = np.array([[0, a/2, a/2], [a/2, 0, a/2], [a/2, a/2, 0]])
system = vq.PeriodicSystem(
3, lat,
[vq.Atom(6, [0, 0, 0]), vq.Atom(6, [a/4, a/4, a/4])],
)
basis = vq.BasisSet(system.unit_cell_molecule(), "sto-3g")
# Wigner-Seitz shell sizing: shells=1 -> 3 translations (-1,0,+1)
# shells=2 -> 5 translations (-2,-1,0,+1,+2) per active direction
for shells in (1, 2, 3):
r = vq.run_periodic_job(
system, basis, method="RHF",
jk_method="aiccm2026dev-b",
aiccm_wigner_seitz_shells=shells,
aiccm_backend="ri",
max_iter=40, progress=False,
)
d = r.aiccm2026dev_b
print(f"shells={shells} mesh={d.character_mesh_shape} "
f"E/atom = {r.energy / 2:.8f} Ha")
Example 10 - Direct SCF API vs run_periodic_job¶
import numpy as np
import vibeqc as vq
from vibeqc.periodic_aiccm2026dev_b import run_aiccm2026dev_b_rks
system = vq.PeriodicSystem(
3, np.diag([8.0, 12.0, 12.0]),
[vq.Atom(1, [0, 0, 0]), vq.Atom(1, [1.4, 0, 0])],
)
basis = vq.BasisSet(system.unit_cell_molecule(), "sto-3g")
# Via run_periodic_job (high-level, I/O, output plan, citations)
r1 = vq.run_periodic_job(
system, basis, method="RKS", functional="pbe",
jk_method="aiccm2026dev-b",
aiccm_lattice_extension=(2, 1, 1),
aiccm_backend="ri",
)
# Via the direct SCF API (low-level, returns SCF result + diagnostics,
# emits AICCM2026DevBExperimentalWarning)
r2 = run_aiccm2026dev_b_rks(
system, basis, aiccm_lattice_extension=(2, 1, 1),
functional="pbe", aiccm_backend="ri",
)
print(f"run_periodic_job: E = {r1.energy:.12f} Ha")
print(f"Direct SCF API: E = {r2.energy:.12f} Ha")
print(f"Convention: {r2.finite_torus_convention.coulomb_kernel}")
All available routes¶
Every route is a single python run_case_b.py <system> <route> invocation.
The complete closed-shell χ-CCM method matrix:
route |
method |
ERI backend |
example |
|---|---|---|---|
|
RHF |
four-center (3-D only) |
|
|
RHF |
pair-resolved 3-center RI-J/RI-K (3-D only) |
|
|
RHF |
RI-J + COSX exchange (3-D only) |
|
|
RKS/PBE |
four-center (3-D only) |
|
|
RKS/PBE |
RI (3-D only) |
|
|
RKS/PBE |
RIJCOSX (3-D only) |
|
|
RKS/PBE0 |
four-center (3-D only) |
|
|
RKS/PBE0 |
RI (3-D only) |
|
|
RKS/PBE0 |
RIJCOSX (3-D only) |
|
|
canonical RI-MP2 (3-D only) |
pair-resolved finite-torus RI |
|
|
DLPNO-MP2 (3-D only) |
exact real representation of RI torus |
|
|
DLPNO-CCSD (3-D only) |
exact real representation of RI torus |
|
|
DLPNO-CCSD(T) (3-D only) |
exact real representation of RI torus |
|
Post-HF --local-mode controls:
--local-mode exact(default) - disables PNO and pair truncations; the accuracy oracle that reproduces the canonical finite-torus limit.--local-mode pno- exercises the current PNO approximation.
Localization options (post-HF): localise="pm" (PBC-safe Pipek-Mezey,
default), localise="wannier", localise="iao", localise="none" (canonical
occupieds - use with --local-mode exact for the validation limit).
Audit B, inspect approach status, and compare controls or CRYSTAL¶
# Audit B records first. Reportable-status 1-D/2-D records fail this gate.
python aiccm-2026/audit_b.py results-b/
# A true Γ-CCM/χ-CCM approach delta is currently not defined.
python aiccm-2026/compare_b.py results-b/
# Optionally add the separately attested neutral-torus real-Gamma control.
python aiccm-2026/compare_b.py results-b/ \
--real-gamma-control-results results-control/
# With a CRYSTAL23 reference column
python aiccm-2026/compare_b.py results-b/ \
--real-gamma-control-results results-control/ \
--crystal-refs aiccm-2026/crystal_refs_b.json --csv comparison.csv
Only compare calculations with the same geometry, orbital basis, functional,
and reciprocal mesh. The cheap default cross-stream pass uses each registry
basis, usually STO-3G; the article/CRYSTAL pass should be emitted explicitly
with --basis pob-tzvp-rev2 so its JSON records advertise the matched basis.
compare_b.py refuses old lower-dimensional B records with status="ok" or
status="not_converged"; these pre-guard absolute energies remain failure
evidence and are not table data.
The reportable Γ/χ approach map is empty. B rhf-ri versus A
aiccm-hf-direct is a neutral-torus representation control, not evidence for
the union-and-weight Γ-CCM approach. The A RI and RIJCOSX harness routes call
the same multi-k GDF SCF drivers as B, so their agreement is a common-path
regression check. The direct route assembles and minimizes the real
Γ-supercell neutral-torus SCF problem but intentionally reuses the common per-q
RSGDF fit and one-electron primitives; it does not independently validate that
shared RI machinery. Equality of the Γ-CCM and χ-CCM approaches for any
specified operator and route remains evidence to establish under the common
exchange-q=0 convention.
Even this control remains fail-closed. Comparator contract v2 is an
incomplete validation scaffold and must not be emitted unchanged. It
requires both producer JSON records to embed the same canonical
comparison_input, with its hash in comparison_contract.input_sha256, and
validates that payload against the result and contract. It records
ao_linear_dependence_threshold separately from
auxiliary_metric_linear_dependence_threshold, and it requires requested and
reported smearing_temperature=0.0 Ha so a finite-temperature SCF energy cannot
be labelled as a comparison delta. Comparator v2 does not bind Fock mixing,
and D86 leaves it unchanged and incomplete. A superseding comparison contract
must bind requested and executed accelerator controls. It also requires matching clean source,
native-core, host, package-version, and successful composite producer-process
attestation. The cached aiccm-host-probe/v2 result is only a preflight. Each
runner binds it to the copied benchmark payload and to the identity of the
process producing the energy, records linked native-library versions, and
always runs a cheap shifted-mesh native-versus-Python Fourier-transform canary
in that process. If the native-core path SHA256 differs from preflight, the
producer reruns the full v2 API, reciprocal-cutoff, and LiH direct-versus-GDF
checks in process; the cheap canary alone cannot approve a changed core. It
then re-reads the identity, libraries, and payload immediately before writing
the result and accepts only an exactly stable result identity.
The core SHA256 identifies bytes currently at the imported module’s filesystem path, not the native image already mapped into memory. The same-process numerical checks cover loaded behavior without claiming a cryptographic mapped image identity. The comparator independently validates every nested schema, digest, check version, and tolerance and compares the B and real-Gamma control records by current producer identity, not by preflight history or their intentionally different payload digests.
The legacy --a-results option is accepted only as an alias for
--real-gamma-control-results. It does not identify the supplied records as
Γ-CCM and should not appear in new commands.
Neither runner emits aiccm2026-gamma-chi/v2, and that schema is not
sufficient for producer emission. A neutral-torus character/real-Gamma factor
audit found and fixed one prerequisite in the shared RSGDF builder. The builder
now enumerates the
physical shifted support 0 < |G+q| <= sqrt(2 E_cut) instead of shifting an
already truncated |G| ball. This makes reciprocal-equivalent transfer labels
share one support while preserving time reversal at even-mesh Nyquist
channels. Canonical χ-CCM post-HF factor transforms now match the neutral-torus
folded fitted-Gram control to the numerical floor on both (2,1,1) and
(3,1,1) meshes; separate gates cover compact fitted-Gram and canonical-factor
relabelling. This is a same-Hamiltonian Fourier control, not Γ-CCM construction
evidence.
The q=0 RSGDF path is byte-preserved, but the finite nonzero-q support changed. Treat pre-D78 records that built nonzero-q factors as revision-bound: RHF/UHF and hybrid RI with exact GDF exchange, neutral-torus folds, and RI post-HF/full-pair caches. Semilocal RI and RIJCOSX SCF use only q=0 RSGDF factors for J and are numerically unaffected by this support change.
The acceptance schema still has open work. It must separate the common Bloch
pair-density phase from the producer-specific factor pipeline. Γ uses
canonical auxiliary-AO builder blocks, then an unfolded-k fold, real q/-q
stack, and null-row prune; χ SCF self-contracts compact metric eigenmodes.
The schema must establish q-resolved retained auxiliary-projector agreement
together with gauge-invariant fitted-Gram agreement, not only matching ranks,
thresholds, or projectors. For the current A route it must also require
full/no-drop at every B character and verify the
finite-Fourier overlap relation, so each character retains all primitive-cell
AO directions. If projected spaces are supported later, it must compare
Fourier-related retained-space projectors rather than rank counts alone. A
later RUN.meta or other curation sidecar cannot retroactively attest the
numerical input, build, probe, payload, or producer process that produced an
existing energy. Existing rows are not upgraded to this contract.
From the qc-input-library¶
The qc-input-library has independent input generation for both streams:
cd ~/gitlab/qc-input-library/aiccm2026testset
# Generate χ-CCM inputs for all 3-D systems
python generate_inputs.py --stream b
# Tier A only with SCF convergence variants
python generate_inputs.py --stream b --tier A --scf-sweep
Electron-repulsion backends¶
The direct SCF APIs are run_aiccm2026dev_b_rhf,
run_aiccm2026dev_b_rks, run_aiccm2026dev_b_uhf, and
run_aiccm2026dev_b_uks. Every invocation emits
AICCM2026DevBExperimentalWarning.
For RI and RIJCOSX, the high-level run_periodic_job surface forwards the
same fitting controls as the direct APIs: gdf_method, rsgdf_ke_cutoff, and
mdf_ke_cutoff. The .out file prints all three values so queued finite-N
numbers can be reproduced without guessing which reciprocal auxiliary mesh was
used.
Global hybrids such as PBE0 remain available through all three 3D backends.
HSE06 is currently available only through 3D four_center, where its exchange
is the screened 0.25 K_erfc(omega=0.11) operator and the full-range BvK seam
is inactive. RI and RIJCOSX fail closed for HSE06 and every other
range-separated functional because their fitted/COSX exchange route is
full-range only. They do not silently replace HSE06 by PBE0. The four-center
HSE route is algebraically wired but not yet truncation-certified for diffuse
AO-pair charges. M4a can pad the base corrected-gauge traversal but does not
pad HSE’s dedicated screened \(K_{\mathrm{erfc}}\) build, so quantitative HSE
values require a separate screened-exchange domain fix. The B selector does
not currently expose or attest M4a in any case.
Every χ-CCM result carries an explicit finite-torus convention descriptor. Current
production records coulomb_kernel="3d-periodic-g0",
exchange_q0="bvk-ewald", the boundary model, the character mesh, and the BvK
Madelung supercell. Finite-N HF, MP2, CCSD(T), and DLPNO numbers are comparable
only at the same declared convention. A strict-zero-mode exchange reference is a
different finite-N Hamiltonian with the same thermodynamic target, not a harmless
label change. If a finite solid leaves a non-rank-1 Madelung remainder after the
leading molecular-limit term is identified, treat it as finite-size physics of
the same periodic kernel, not as an RI error or an adjustable gauge.
Canonical RI-MP2 is available in 3D through
run_aiccm2026dev_b_mp2(system, basis, lattice_extension). It uses B’s own RI-RHF
orbitals and pair-resolved three-center tensors. It does not route through the
older Gamma-supercell post-HF helper because that helper has a different
finite HF energy and exchange q=0 convention. MP2 fails closed in 1D/2D until
their long-range gauges are matched.
The canonical MP2 implementation streams each pair-resolved AO-space Lpq
block directly into the occupied-virtual Lov factors, so it does not hold the
full AO-space pair cache at the same time as the MO-space factors.
The same declared 3D χ-CCM convention is available through
run_aiccm2026dev_b_dlpno_mp2, run_aiccm2026dev_b_dlpno_ccsd, and
run_aiccm2026dev_b_dlpno_ccsd_t. These routes inverse-transform the
pair-resolved RI factors to the complete real finite torus; they do not run a
different Gamma-supercell SCF. The total finite-torus correlation energy is
divided by the number of cyclic cells exactly once.
The finite-torus setup uses χ-CCM native OpenMP kernels for the one-body
matrix inverse transform, the pair-resolved RI-factor inverse transform, and
the three-index AO-to-MO contractions consumed by the local-correlation
drivers. The RI-factor kernel writes the final real tensor directly, avoiding
the former six-dimensional complex temporary. Density and property residue
blocks use a native finite-character inverse Bloch transform. The
finite-translation occupied-index permutation table and occupied-pair orbit
partition used by local-correlation diagnostics also run in native
finite-group kernels, with the Python closures kept as regression oracles.
This accelerates setup and reduces peak memory, but it is not yet
translation-representative local-correlation scaling.
For complete-domain local-PNO exact-limit corrections, the real-torus MP2
audit also streams the L[P,i,a] contraction in native OpenMP code rather
than storing the full ijab tensor.
run_aiccm2026dev_b_ccsd and run_aiccm2026dev_b_ccsd_t select the
canonical-occupied, complete-domain, zero-threshold limit explicitly. They
use the same finite-torus contractions and convention descriptor as the local
route and are validation oracles, not a second Hamiltonian.
The default occupied localization is PBC-safe Pipek–Mezey. Molecular Boys
localization is rejected. The B-only localise="wannier" and
localise="iao" options feed the finite-torus localized occupieds into the
same PAO/PNO pipeline. The Wannier spread is currently a projected circular
AO-centre approximation; the IAO cross overlap is not yet periodized across
the supercell boundary. PNO truncation is available, but pair-distance
screening, finite occupied-coupling radii, and local auxiliary fitting fail
closed until their domains use minimum-image periodic distances. Use
localise="none", zero PNO/domain thresholds, all pairs, and complete
occupied coupling to reach the canonical finite-torus validation limit.
At that MP2 limit, the result exposes raw_local_e_corr_per_cell and the
independent complete_space_correction_per_cell audit.
The unrestricted 3D counterparts are run_aiccm2026dev_b_ump2,
run_aiccm2026dev_b_uccsd_t, run_aiccm2026dev_b_dlpno_ump2, and
run_aiccm2026dev_b_dlpno_uccsd_t. Alpha and beta occupied projectors are
localized independently. The full-domain UCCSD(T) implementation is the
explicitly cost-capped O(N^6) correctness oracle from the DLPNO stack, not a
claim of production reduced scaling. The truncated route uses PNO subspaces,
but representative-only pair propagation remains disabled.
derive_aiccm2026dev_b_scf_properties reports electron and spin counts,
Mulliken charge/spin populations, finite-net band gaps, idempotency, and
spin contamination. The returned object carries the same finite-torus
convention descriptor as the parent SCF result. aiccm2026dev_b_band_structure
stores the descriptor in bands.metadata["finite_torus_convention"], and
aiccm2026dev_b_mayer_bond_orders does the same for the primitive-cell Mayer
table, so direct Python analyses and the B-owned JSON summaries cannot be
mistaken for a strict-zero-mode or isolated-wire/slab Hamiltonian.
Periodic QVF output from
run_periodic_job(..., jk_method="aiccm2026dev-b", output_qvf=True) emits the
visual structure.pbc, structure.lattice_vectors, volume.density, and
restricted volume.orbital sections over the full BvK torus cell. For mesh
sizes larger than (1, 1, 1), the writer builds the visual supercell, folds
the finite-character density into the matching AO density matrix, and emits
Gamma-character HOMO/LUMO orbital grids in that same cell for restricted
records. Unrestricted records emit the spin-summed density grid and, with
qvf_wannier_centers=True, alpha/beta Wannier-centre overlays; spin-resolved
orbital grids remain open. The writer deliberately omits wavefunction.gto,
because molecular GTO evaluation would clip a periodic torus orbital instead
of applying cyclic boundary conditions. The grid sampler applies AO image sums
on the declared periodic axes and leaves vacuum axes unwrapped. The archive
also carries the first-party x_vibeqc.aiccm2026dev_b_convention vendor JSON
section, advertised by the root x_vibeqc extension marker, with the method
selector, mesh, backend, and finite-torus convention descriptor used for the SCF
result.
Periodic cell dipoles, Berry-phase polarization, analytic response, and
correlated properties without a relaxed correlated one-particle density fail
closed.
QVF visualization fixtures¶
run_periodic_job(..., jk_method="aiccm2026dev-b", output_qvf=True) writes
vibe-view-ready periodic QVF archives. For finite-torus visualization the
archive stores the full BvK display cell in structure.lattice_vectors and
ships precomputed torus-aligned volume.density / volume.orbital grids.
The chi-CCM-B writer may also include x_ccm.wannier_centers, which vibe-view
draws as an optional overlay.
Two sanitized visualization fixtures are bundled with the docs:
The files were generated at pre-D89 source d746d238 (shown as d746d23 in
their archived output). They validate only the visualization pipeline. Because
they lack the normative D89 approach identity fields, they are not
construction-comparison or numerical-validation evidence.
Case |
Input |
Output |
QVF |
vibe-view capture |
|---|---|---|---|---|
3D vacuum-padded H-chain, RI, |
||||
3D H2-pair, RI, |
The full capture set and sanitized .system manifests are summarized in the
chi-CCM-B fixture README.
Gradients and forces¶
χ-CCM-B now exposes an explicit gradient-status surface:
aiccm2026dev_b_gradient_status(result) reports the finite-torus convention,
backend, lattice extension, and the still-open derivative terms for the result.
The first independently checkable component helpers return only fixed pieces
of the 3-D Ewald one-electron electrostatics for results that declare the
3d-periodic-g0 / bvk-ewald convention:
compute_aiccm2026dev_b_ewald_nuclear_gradient(system, result) differentiates
the nuclear-repulsion term, while
compute_aiccm2026dev_b_ewald_electron_nuclear_gradient(...) differentiates
sum_g Tr[D(g) V_ne(g)] at a caller-supplied fixed real-torus density and
lattice cutoff. The convenience bundle
compute_aiccm2026dev_b_ewald_electrostatic_gradient_components(...) returns
those two arrays plus their fixed-density sum, with the Ewald alpha and cutoffs
recorded in the returned component object.
compute_aiccm2026dev_b_ewald_electrostatic_energy_components(...) returns
the matching fixed-density scalar energy pieces for central-difference audits
of that component bundle. For the explicit fixed-density electron-nuclear and
electrostatic bundle helpers, the supplied density LatticeMatrixSet.cells
must exactly match the lattice-cell list implied by lattice_options, its AO
dimension must match the operator template, and it must carry one correctly
shaped AO block per cell; mismatches fail closed rather than mixing cutoffs
or AO spaces in the audit pair.
The kinetic part is available as a second explicit fixed-density audit pair.
compute_aiccm2026dev_b_fixed_density_kinetic_energy(...) evaluates
sum_g Tr[D(g) T(g)], while
compute_aiccm2026dev_b_fixed_density_kinetic_gradient(...) returns its
analytic AO-centre derivative with the supplied real-torus density blocks held
fixed. The same exact cell-index, Cartesian-translation, AO-dimension, and
block-shape guards apply.
The derivative is tested against central differences of the matching scalar on
displaced bases, so this is an independently checkable component rather than
an inferred total force.
The overlap constraint is available as a third explicit audit pair.
compute_aiccm2026dev_b_fixed_energy_weighted_overlap_lagrangian(...)
evaluates
-sum_g,mu,nu W_mu,nu(g) S_mu,nu(g) for a caller-supplied real-torus
energy-weighted density, while
compute_aiccm2026dev_b_fixed_energy_weighted_overlap_gradient(...)
returns its analytic AO-centre derivative with the numerical W(g) blocks
and lattice held fixed. The scalar is a Lagrangian companion, not a separately
additive electronic energy. The same exact support guards apply, and the test
uses real but individually nonsymmetric residue blocks to pin the Frobenius
orientation and sign against central differences.
There is deliberately no SCF-density kinetic or overlap/Pulay wrapper yet.
Current SCF results do not retain the resolved one-electron lattice cutoff
needed to prove that a reconstructed kinetic operator has the same cell
support as the SCF operator. Constructing the stationary energy-weighted
density also requires the D85 binding: a rebuilt final physical variational
Fock, occupied coefficients and integer occupations, retained-space
projectors, and structure, basis, torus, backend, gauge, and numerical-support
digests. It is formed from Lambda = C_occ^H F_var C_occ, not accepted from
unattested stored orbital energies. The BvK exchange seam or screened-exchange
kernel contributes to that physical Fock but has a separate explicit
fixed-density derivative; it must not be hidden inside or double-counted with
the overlap term. The public overlap helpers therefore prove only the
fixed-W skeleton.
Callers doing a derivation audit must therefore pass the fixed density or
energy-weighted density and the known matching lattice_options explicitly
instead of relying on a default cutoff.
All component helpers now also bind the result to the active finite torus:
the result mesh, character mesh, and BvK repetitions must agree, and the
recorded column-vector BvK lattice must equal
system.lattice @ diag(mesh) within 1e-12 bohr. SCF-density folding accepts
only the complete unreduced, unshifted Γ-centred character net with uniform
weights. This guard does not attest atoms, basis identity, operator cutoffs,
or the origin of caller-supplied density blocks.
compute_aiccm2026dev_b_scf_density_lattice(...) inverse-Bloch folds the
stored SCF k-density onto the same lattice-cell list as
compute_overlap_lattice, so a converged B result can feed those
fixed-density component helpers without hand-written density reconstruction.
For restricted records, the fold first checks for singlet multiplicity and a
non-negative even effective electron count. For unrestricted records, it checks
that the effective electron count and multiplicity imply non-negative integer
alpha/beta occupations. The stored k-density blocks must also match the active
AO basis dimension before they are inverse-Bloch folded.
compute_aiccm2026dev_b_scf_ewald_electrostatic_energy_components(...)
performs that fold and returns the same fixed-density electrostatic energy
pieces at the stored SCF density.
compute_aiccm2026dev_b_scf_ewald_electrostatic_gradient_components(...)
performs that fold and returns the nuclear, electron-nuclear, and
fixed-density electrostatic sum at the stored SCF density.
These helpers are useful for derivation tests, but they are not total forces.
compute_aiccm2026dev_b_gradient(result, ...) and
run_aiccm2026dev_b_gradient(result, ...) fail closed with a
NotImplementedError until the derivative of the declared χ-CCM Hamiltonian is
derived and validated.
Γ-CCM and χ-CCM remain distinct approaches compared at a declared common
exchange-q=0 convention; their names do not select different Coulomb kernels.
This guard is intentional. The sibling Γ-CCM analytic-gradient route
differentiates a direct-torus WSSC molecular-kernel energy. Production χ-CCM-B
numbers declare coulomb_kernel="3d-periodic-g0" and
exchange_q0="bvk-ewald", so a χ-CCM-B force must include the derivative of
that finite-character Hamiltonian, including the BvK exchange seam and the
RI/RIJCOSX metric and three-center response when those backends are selected.
RKS and UKS additionally require the exchange-correlation quadrature and grid
derivative.
For HSE06 four-center records, the corresponding missing exchange term is the
screened erfc-kernel derivative rather than a full-range seam contribution.
Substituting Γ-CCM gradients would silently change the Hamiltonian behind the
forces. Geometry optimizers should therefore treat χ-CCM-B analytic forces as
not implemented rather than falling back to another CCM representation. The
high-level run_periodic_job(..., jk_method="aiccm2026dev-b") surface now
rejects optimize=True and hessian=True for the same reason.
Space-group analysis is opt in with symmetry_mode="diagnostic" on the
direct APIs or aiccm_symmetry="diagnostic" on run_periodic_job. It
attaches the spglib group, exact cluster-compatible subgroup, atom/cell maps,
and irreducible k orbits without changing the SCF build. The integrals mode
fails closed until general-k sewing matrices and shell-quartet scatter pass
energy and Fock parity.
Electron-repulsion backends¶
Backend |
Coulomb |
Exact exchange |
Current purpose |
|---|---|---|---|
|
direct periodic four-center build, 3D only |
direct periodic four-center build, 3D only |
diagnostic direct route; absolute values held pending domain convergence |
|
pair-resolved periodic three-center fit, 3D only |
pair-resolved fitted exchange, 3D only |
scalable RI reference |
|
same RI-J, 3D only |
chain-of-spheres exchange, 3D only |
faster HF and hybrid KS trial route |
For 3D four_center jobs, the neutral Ewald J split resolves the nuclear
real-space cutoff no larger than the electronic J/K cutoff. With library
defaults, both therefore resolve to 15 bohr rather than the raw 15/25 bohr
option pair. Benchmark JSON records expose the actual values in
direct_lattice_cutoffs; RI and RIJCOSX records set that field to null.
That pair describes coherent physical density/nuclear support, not the larger
internal ket-image traversal required for smeared AO-pair charges.
M4a now provides an opt-in sr_image_extent_bohr correctness oracle, but the
B selector and fleet harness do not expose or record it and the unpadded
default is byte-identical. BIPOLE-routed four-center benchmark numbers without
a converged M4a extent, including the earlier pre-6fed8620 H2 RHF/PBE0 smoke
rows, remain revision-bound until such an extent is attested or efficient M4b
lands. Pure restricted semilocal RKS instead uses a finite-KE analytic-FT
Hartree partial sum and needs separate reciprocal-tail convergence.
RI, RIJCOSX, and four-center currently run only for 3D cells. Lower-dimensional χ-CCM-B SCF fails closed until the neutral wire/slab Green function and the matching RI/GDF support are implemented and anchor-tested. The derived character net is Γ-centred. RIJCOSX currently requires at least two cyclic cells. Post-HF remains 3D-only until the lower-dimensional long-range gauges are matched.
Dimensional Coulomb conventions¶
The finite translation-group identity is dimension independent. The Coulomb
kernel is not. The current 3D four-center route uses the neutral Ewald J split
and the Ewald exact-exchange finite-size correction. The 1D and 2D direct
four-center fallback is a direct-truncated active-lattice kernel, not the
neutral wire/slab finite-torus Green function. The lower-dimensional neutral-RI
mesh is also not a Coulomb kernel because it pins every transverse reciprocal
component at (G_\perp=0). aiccm2026dev-b therefore blocks all
lower-dimensional SCF backends before returning an absolute energy.
Consequently, lower-dimensional χ-CCM-B is not an absolute-energy parity backend today. Matched 1D wire and 2D slab Green functions remain an acceptance item. The code does not disguise this mismatch with damping or a fitted offset.
Future isolated low-dimensional support needs a shared mixed-boundary kernel:
a 2D slab Green function with isolated transverse boundary, a 1D wire Green
function with isolated transverse boundary, and matching exchange q=0 and
self-potential conventions derived from that same kernel. The 3D
exchange_q0="bvk-ewald" seam must not be imported into those routes as if it
were universal.
What is checked on every result¶
Wigner–Seitz representative weights sum to one for every translation class.
A restricted density obeys \(DSD=2D\); unrestricted spin densities obey \(D^\sigma S D^\sigma=D^\sigma\) independently.
The weighted total and spin-resolved electron counts match the cell.
The inverse Bloch transform has a negligible imaginary residual for the Γ-centred character mesh.
These checks establish internal consistency, not thermodynamic-limit accuracy. Converge the cyclic lattice extension and compare against a matched reciprocal-space calculation before using a number quantitatively.
Separate examples and theory¶
Complete χ-CCM fleet inputs
The comparative manuscript is the detailed theory record. It includes the historical ab-initio weighting, the Janetzko–Köster–Salahub deMon2k KS-ADFT construction, both 2026 development streams, and the reciprocal-space reference formulation.