DF-CCSD / CCSD(T) — Implementation Handover¶

Last updated: 2026-05-22 (M13 — release-ready audit) Branch: main
Status: GATED EXPERIMENTAL — VIBEQC_EXPERIMENTAL_CCSD=1 required; Scuseria 1988 spatial-orbital DF-CCSD converges with DIIS

Milestone Log¶

#	What	Status
M1-M5	Initial implementation, 5 critical bugs	Done
M6-M9	F-001/F-002 fixes, DIIS convergence, W_oooo fix	Done
M10	T1-dressed Fock builder (wired, negligible effect)	Done
M11	Python verification framework (`cc_verify.py`)	Done
M12	MO phase mismatch diagnosis (4 of 7 MOs flipped vs PySCF)	Done
M13	Release-ready audit: gate verified, tests pass, no doc over-claims	Done

Release-Ready Audit (M13)¶

Check	Result
Experimental gate (`VIBEQC_EXPERIMENTAL_CCSD=1`)	PASS — RuntimeError without it
Build (no errors, no CCSD warnings)	PASS
Adjacent tests (89 passed, 7 xfail, 1 skipped)	PASS
CCSD not claimed in user docs	PASS
CHANGELOG only claims citation routes (accurate)	PASS
No papered-over bugs	PASS — MO phase mismatch documented, not hidden

Current Behavior¶

Metric	Value
E_corr (H2O/STO-3G, cc-pvdz-ri)	-0.021 Ha
DIIS convergence	Energy stable to machine precision
R1 residual at fixed point	~0.04
R2 residual at fixed point	~0.19
T1 norm	~0.035
T2 norm	~0.276

Known Limitations¶

Numerics unvalidated against reference — MO phase mismatch with PySCF (4/7 MOs flipped) prevents direct comparison. Scuseria 1988 equations are self-consistent with vibe-qc’s MO convention.
RHF-only, closed-shell only — no UHF-CCSD, no EOM-CC
No analytic gradients — energy only
No (T) validation — triples formula present but untested
Performance — several O(N^6) loops use explicit indexing

Files¶

File	Purpose
`cpp/include/vibeqc/ccsd.hpp`	Data structures + entry point
`cpp/src/ccsd.cpp`	CCSD solver, DIIS, (T) triples
`cpp/src/bindings.cpp`	pybind11 bindings (lines 2852-2950)
`cpp/CMakeLists.txt`	Build (+1 line)
`python/vibeqc/cc.py`	Python wrapper + aux autodetect
`python/vibeqc/runner.py`	`method="ccsd"`/`"ccsd(t)"` + gate
`tests/test_ccsd.py`	xfail tests (numerics TBD)
`python/vibeqc/cc_verify.py`	R2 verification against PySCF
`python/vibeqc/output/citations/database.toml`	CCSD/CCSD(T) citation routes
`docs/handover_ccsd.md`	This file

M14: 2-Electron Validation Failure (2026-05-22)¶

He/3-21G test: CCSD gives R2=0.217 at iter 1 for a 1-occupied, 1-virtual system. For 2 electrons, CCSD must equal FCI (exact). The Scuseria 1988 equations in DF form fail to reduce to the correct CID equation because the W_oooo and W_vvvv DF terms contribute nonzero even for single-element T2.

Root cause confirmed: DF approximation breaks the exact integral relationship that Scuseria 1988 equations rely on. PySCF DF-CCSD port is required for correct numerics. This port needs MO phase alignment with PySCF as a prerequisite.