vibe-qc/Documentation

BIPOLE multi-k local correlation: scientific programme

Planning baseline 8 November 2026. Development prompts are indexed on programme issue #593. This is the BIPOLE correlation part of #593/#508. The milestones below have numerical exits, not promised release dates. QC0.18/#557 is complete. References to source paths below are relative to the vibe-qc repository. Issue numbers identify the project tracker records.

What actually executes

Method	Molecular or Gamma control	Full mesh and BIPOLE status
RHF	Molecular and periodic Gamma Fock builds exist. A Gamma match checks only self-inverse phases.	Public BIPOLE RHF/UHF and KS build short-range real-space J/K and reciprocal J/K. See python/vibeqc/pbc_bipole_fock.py (restricted/unrestricted builders), cpp/src/periodic_fock.cpp, docs/bipole_domain_contract.md. #606 binds the terminal state to #472. RHF on a gapped full mesh is the first correlation reference. KS, hybrids and UHF have independent SCF uses.
Integrals	Native diagnostics evaluate finite ordered AO quartets.	#221/#272 supply a bounded private all-k J/K action. _bipole_physical_source.py:PhysicalSource has no certified Hamiltonian or symmetry and enumerates under its own support declaration. Public physical J/K has different selections for direct and crossed contractions. The resolved-domain settings hash omits basis, geometry and executed kernel. #947 owns whether to wire or retire private code. The source refusal in dlpno/source.py:refuse_unsupported_periodic_reference is correct today.
Canonical and local MP2	Independent molecular canonical and finite Gamma comparisons exist. Replicating a molecule or using only Gamma supplies a limiting test.	Standalone MANTA RI-RHF full-mesh finite-torus MP2 passed signed non-self-inverse q, same factors and projectors (#591 note 63005). Translated occupied seeds, spatial domains, PNOs and coupled local residuals execute on that source. Domain+PNO passed (846a68a5); screening alone passed (7a299834); GitLab main f50255a1 still rejects screening plus truncation in driver and solver. #1001 tracks multiband oracle coverage. Classic χ has its own finite-torus passes and an externally unqualified LiH row (#572); #1007 owns χ evidence. BIPOLE has one opt-in full-space MP2 fixture (#1004); other sources remain unqualified.
CCSD	Molecular compiled CCSD/PNO equations and Gamma retained-GDF comparisons exist.	periodic_runner.py → periodic_dlpno.py:correlate_periodic_reference can fold an admitted full GDF mesh to a real BvK representation and call the molecular engine. This evaluates the admitted multi-k finite operator and incurs folded storage. dlpno/translation_ccsd.py:evaluate_translation_ccsd evaluates restricted complete-strong-pair residuals/energy; #586 owns iterations, mixed pair treatment and dispatch. Separate experimental χ canonical CC has its own source and restart. No converged BIPOLE local CCSD row.
Triples	Molecular canonical and local approximations differ. #884/#887/#888 qualify components of the molecular TNO/coupled route; #889 tracks repeated-label occupation disagreement. A folded GDF calculation can exercise its selected molecular algorithm on its torus.	#587 requires accepted periodic amplitudes, triple orbit counting, transported spaces and a nonzero triples benchmark. Neither a molecular ORCA comparison nor a public method selector establishes a translation-native BIPOLE triples result.
Front door, artifacts and restart	QVF encodes method options including triples (#558); output/formats/qvf.py writes correlated energy components. χ canonical CC has a source-bound amplitude/DIIS restart.	#932 owns consolidation of periodic drivers. Standalone MANTA’s library call is not BIPOLE runner dispatch. No demonstrated BIPOLE correlated output, amplitude restart, public dispatch, capacity or speed pass. Require negative cases for zero iterations and failed upstream convergence, including omission versus computed numerical zero.

The label BIPOLE here identifies the project’s periodic Gaussian/Ewald split SCF implementation. Short range uses supported translated product pairs and midpoint-limited quartets; the reciprocal part uses Fourier transforms of AO products. An optional bipolar far-field approximation to a screened quartet is an additional algorithm (#764). Do not infer that the executed production short-range integral is a point multipole from the route name. For isotropic Gaussian products the screened interaction depends on both widths even for monopoles (Izmaylov 2006 Eqs 40-43). MANTA is an optional integral provider with its own native RI and Fock receipts (#617/#581); its primitive substitution into BIPOLE has a separate proof (#629). χ-AICCM uses finite translation-group characters and its own physical-pair producer. The AICCM article’s ROUTES_AND_VALIDATION.md documents historical naming differences. Use producer identities for every row and no cross-provider claims by association.

Relevant negative and positive evidence: #703 records a 512-point H₂ HF offset of 1.8538 microhartree against a 1 microhartree CRYSTAL criterion despite a matched Ewald/PySCF control. #767 records symmetry-on/off LiH mean-field energies within 8.5e−14 Ha. #762 records MgO 5³ SCF median 631.705 → 311.104 s with increased memory. These constrain the reference and illustrate a resource tradeoff; they give no correlated accuracy or cost verdict.

Finite operator before locality

The finite H₂ operator experiment found a rounded-transfer counterexample on the full three-point mesh (#1003). After repair, the complete exact-transfer replay passes (#1009). Stage 2 (#1004) now matches raw MP2 on this fixture against independent Bloch and finite-supercell sums. Other BIPOLE correlation routes retain the default refusal.

Initial research domain: neutral 3D, fixed cell, all-electron Gaussian basis, insulating restricted closed shell, integer band filling, no frozen orbitals, full unshifted uniform mesh, confirmed physical RHF F/S/D and positive retained overlap. Record direct and reciprocal lattices, fractional/Cartesian k and weights, basis contractions/ordering, gap, support sets, precision, kernel and exchange zero mode. First use a small orthorhombic cell. Later qualify multi-band/frozen complete occupied bands, then skew cells. Shifted meshes, IBZ-only sources, broken time reversal, independent spins, ECP, slabs/wires, metallic or near-degenerate references each require distinct derivations and rows. Refuse them by default. Preserve any existing qualified method on other producers. This programme requires no DFT expansion.

Convention to verify against executed arrays. Adopt normalized Bloch sums on N primitive cells, e.g. ψₚₖ=N^(−1/2)Σ_R exp(+ik·R)φₚR, with inverse conjugate phase. Map to the code’s signed axes explicitly. For transition density ψᵢψₐ the transfer is q=kₐ−kᵢ modulo the reciprocal lattice; the partner has −q. The ordered integral J=(ia|jb) is zero unless kᵢ+kⱼ−kₐ−k_b=G. Swapping electron labels leaves the bilinear Coulomb value invariant; reversing both transition densities conjugates it. In a general complex gauge carry conjugation, including orbital rotations and pair-space bras. For normalized finite-torus orbitals use E₂/cell=(1/N)Σ Re[J (2J−K)]/Δ with K=(ib|ja), Δ=εᵢ+εⱼ−εₐ−ε_b. This uses finite-torus integrals, which already contain their 1/N; a primitive Bloch-integral implementation must derive its own weights. Enforce the relation by a second, independently normalized Fourier construction. Validate conjugations with phases, degenerate-subspace rotations, relabelled cells, self-inverse and opposite transfers, and an intentional wrong conjugation or lost orbit. Real folding is conditional on a sewn time-reversal pair and a commensurate torus. IBZ needs certified star/sewing, stabilizers, spin and source closure (#589/#577); extra weights alone cannot reconstruct an amplitude.

Potential obstruction and decision. Split Coulomb into erfc(ωr)/r plus erf(ωr)/r. The finite direct and crossed supports may violate pair permutations even when J[D] and K[D] look physical. The dropped short-range G=0 cell-average term involves π/(Ωω²) times pair overlaps; the long-range exchange probe-charge term in the Fock is a separate convention. Preserve it in ε. Derive its action (including vanishing overlap where applicable) for each transition type before the correlation contraction. A single common positive DF metric is a hypothesis, not a requirement. Permit bounded direct four-index actions if they have correct symmetries. Compare the complete ordered tensor and actions on a spanning Hermitian probe set at fixed D. A failure under matched support blocks same-source admission. Diagnose first by component, index and support tuple; propose a revised finite operator or a clearly labelled separate fit, with its own scientific decision, rather than loosening thresholds.

Local MP2. Begin from all pairs and the full virtual projector Q=I−C_occ C_occ†S (including frozen occupieds once enabled). Derive localized occupied home-cell orbitals and their translations; existing normalized-AO seeds are controls. An optimized translation-covariant Wannier gauge needs #848/#582, gap and spread convergence and an equivalent reconstructed occupied projector. Project selected atom AOs with Q, diagonalize the overlap in the domain at the stated linear-dependence threshold and orthonormalize. Build the spin-adapted MP2 pair density from direct/exchange amplitudes with their adjoints, recording the norm, metric and eigenvalue cut. Compare projectors at degeneracies. The first projected solver treats every retained pair as strong. For each projected pair include Fock virtual actions and both occupied-index couplings, transporting amplitudes with overlaps between unequal pair spaces. Count ordered translations once per cell; i=j, reversed and self-inverse representatives have different multiplicities. Classify by unweighted declared pair energy with stable ties, preserve diagonal and full translation/reversal orbits. A dropped row/source has zero raw contribution. Treat weak/distant MP2 estimates and discarded-PNO corrections as named increments with disjoint pair lists and documented prefactors. Test omitted-source versus dropped-after-solve explicitly. Restore the canonical raw result with full domains, zero PNO/pair thresholds. Vary real-space range and k mesh independently; an exact finite-torus limit does not imply bulk convergence.

CCSD then triples. For restricted local CCSD define T=T₁+T₂, Rμ=⟨Φμ|exp(−T)H exp(T)|Φ⟩ and connected correlation energy from the reference projection. Use the shared spin-adapted compiled equation families and compare each singles, linear doubles, ladder/ring, exchange, disconnected T₁ and cross-pair Fock term at arbitrary amplitudes with dense identical-source CCSD. Store translation-labelled singles and unique-pair matrices; transform both virtual legs with the proper pair overlaps, conjugates and reciprocal occurrence. Precompute momentum/index maps for each contraction. Only after all-strong convergence qualify weak MP2 amplitudes, distant terms and their feedback, one model at a time. Define global residual, absolute energy step and DIIS with metric/source identity. Reject nonconvergence and invalid denominators before energy promotion or triples.

The existing molecular closed-shell options distinguish diagonal-local-Fock T0, the rotated-occupied compatibility option named t1, and an exact-oracle option. The separate molecular coupled implementation supplies evidence about its own equations.

First triples model proposed for this programme: restricted semicanonical local (T0). Use converged CC singles/doubles, TNOs from the three pair densities in the joint projected PAO domain, a semicanonical physical virtual Fock, six simultaneous occupied/virtual permutations, and diagonal occupied-minus-virtual denominators. Define W/V (or code W/U) normalization, repeated indices, connected/disconnected terms and 1/N by mapping to the chosen spatial-orbital reference. Termwise agreement precedes contraction. In localized occupieds this model omits off-diagonal occupied Fock coupling; full TNO rank alone does not make it canonical. Demonstrate a canonicalized complete-space control and a localized fixture with measured omission. The subsequent model is iterative occupied-Fock-coupled triples following Guo Eq 2 with explicit cross-triple overlaps, compared with diagonal Eq 3. Bind iteration residual and convergence to that named model. No bare ‘(T)’ label until the selected algorithm and limitations appear in output. Require nonzero triples, six permutations, repeated-label orbits with stabilizers and noninteracting replicas with nonzero correlation. Molecular and LNO triples supply related checks under matched equations, not interchangeable reference energies.

Milestones and decisions

Increment and tracker	Deliverable and exit	Risk and response
1 · finite source #1003, #531/#606/#947	Tiny Gamma component ledger then a true non-TRIM transfer fixture; independent SR/LR/q=0 quartet and full J/K probes at declared tolerances.	No common operator: retain D93, publish reproducible counterexample, return to #531/#947 for the specific decision.
2 · correlation bridge #1004, #572/#592	Bounded owned panel or selected integral action, immutable source and backpressure; canonical/full-space multi-k MP2 in vq with independent Bloch and finite-supercell references.	Full tensor or independent gauges needed: prove transport or reduce the supported domain; no hidden O(N⁴) production fallback.
3 · physical and local MP2 #1005, #582/#848/#591	Separate operator and locality ladders, strong/weak/distant partitions, additivity, optimized occupied gauge, H₂ mechanisms then multiband LiH and diamond; frozen bands separately.	Near a threshold, support errors switch pair lists/PNO ranks; compare at both fixed and recomputed masks.
4 · coupled CCSD #586	Fixed-amplitude residual oracle, then converged all-strong calculation, canonical recovery and additivity on a BIPOLE mesh; mixed pairs and corrections after these pass.	Surviving residual or gauge error: isolate contraction, keep public CCSD unavailable.
5 · named triples #587	Nonzero (T0) oracle, then separately qualified iterative variant. Validate canonical and localized limits on the same CC solution.	Small denominators, band crossing, repeated-label defect: refuse affected orbit/variant. Molecular TNO failures (#889) require independent resolution wherever reused.
6 · operational support #932/#558/#589/#592/#793/#818	Public opt-in runner/QVF, only supported tuples; immutable restart and bounded disk/host memory. Full mesh first, qualified reconstruction and nonuniform block ownership later.	Changed basis, complex gauge, finite support, mesh, mask, ranks or binaries: refuse incompatible restart or explicitly recompute from a valid earlier stage.
7 · efficiency and claims #591/#574/#821/#822, #1006	Same-accuracy total cost and external data on held-out materials; formal claim decisions and reproducible archive.	If CRYSCOR decks or comparable hardware are missing, publish limited absolute results. A speed ranking needs comparable complete runs.

Engineering acceptance is a reviewed-by-author bounded design, focused source check and tested commit on main. Scientific acceptance additionally needs a containing-runtime vq job and independent matched evidence. Cost and paper acceptance have separate exits. Later release selection is a maintainer decision.

Measurement and evidence for claims

Claim	Required evidence and failure controls
Executed multi-k BIPOLE operator and canonical MP2	#1003/#1004. Store S, F, D, orbitals/energies, transition blocks, support receipts and native IDs. Match primitive to independently constructed commensurate supercell. Rotate phases and exactly degenerate equal-occupation subspaces, permute orbitals, shift cell origin. Deliberately drop −q and swap an interband exchange leg. One-band H₂ cannot catch every error; multiband control is essential (#1001 oracle, separate material/source).
Local MP2 and local CCSD accuracy	#582/#586/#1005. Matched atomic/cell inputs, all-electron or explicit ECP and core, spin, k/weights, singularity, convergence and per-cell convention. Record raw energies, separated pair corrections, R₁/R₂ and dE, retained ranks/counts and cap failures. Test size consistency by two noninteracting correlated fragments, size extensivity by commensurate repetition, translation/gauge at fixed physical projectors. A localized result can depend on the gauge: measure spread and sensitivity rather than assume arbitrary occupied rotation invariance.
Bulk and application fidelity	#1005/#721. Independently refine physical supports, reciprocal resolution, mesh, orbital/aux bases if used and each locality threshold. Use both common orbitals and self-consistent solutions. Record cross terms E(H,L)−E(H,full)−E(H_ref,L)+E(H_ref,full). Test LiH, diamond and a near-gap rejection; add a surface only after a boundary-condition and coverage study. CRYSTAL23 HF can check the reference; independently established CRYSCOR version/input can check local MP2. PySCF KMP2 or coupled-cluster on identical operands isolates equations; ORCA can check a corresponding molecular limit. #721 CO/MgO original criterion stands; published ±0.2 versus ±2.0 kJ/mol differs, and binding/relaxation, counterpoise and basis/PNO extrapolations matter.
Named triples	#587/#1005. Compare selected individual moments, denominators, retained TNO projectors, stabilizer counts, signed energy and connected size scaling. Separate CCSD, local space, T0 versus iterative and finite-mesh errors; report model dependence when off-diagonal occupied Fock is nonzero. Full-space comparisons to canonical CCSD(T) require an equation-matched limit.
Operational and speed envelope	#591/#592/#793/#818. Map each (q,k) owner and unique pair to bounded auxiliary/AO or quartet blocks. Preflight simultaneous reservations including replicated intermediates, native workspaces, spill files and communication buffers; test one-byte-short refusal, read failure and restart from last complete generation. Distribute full k/q blocks first with deterministic reductions; retain symmetry only after covariance and equivalence. Store cold and warm setup, Fock, transforms, localization, selection, iterations, triples, checkpoint/output separately; report end-to-end medians and variation, wall time, aggregate and per-rank peak RSS, I/O and transferred bytes, actual ranks/threads/builds, utilization and nonconvergence. Fixed hardware strong scaling and size-per-rank weak scaling at the same accuracy; at least three repeated cost observations per compared configuration.
Publication claim	#1006. Archive inputs, complete outputs, compiler/build/host, immutable source and native hashes, tolerances frozen before evaluation, scripts and held-out failures. Compare exact small-cell direct, BIPOLE, χ and MANTA only where matched; distinguish operator/metric/boundary differences. Ablate source, locality, orbit reduction and parallel implementation individually. A new derivation with a falsifiable error bound, or replicated time-to-accuracy advantage beyond known combinations, is a hypothesis. Reproduction of established periodic local methods is independently useful. Journal choice confers no evidentiary status.

Gates. Preserve #591 raw full-space 2e−9 Ha/cell, residual 1e−11, ΔE 1e−13 Ha, and stricter H₂ 1e−10/1e−12/1e−13 where applicable. The tiny #1003 proposed operator gates are 1e−10 Ha absolute for normalized selected integrals/actions and 1e−12 Ha for forbidden momentum. Before each new periodic CC comparison register per-cell gates, suggested initial full-space 1e−8 Ha/cell CCSD and 1e−9 Ha/cell triples, residual 1e−11 and ΔE 1e−13 Ha/cell; molecular targets do not establish these periodic results. Pre-register material-specific local/physical accuracy and resource budgets under #1005, guided by tighter independent reference plateaus and target observables. Report an unresolved tolerance floor rather than retrofitting the tolerance. #591 LiH’s 1e−6 external gate is conditional on matched Hamiltonians.

Research record and sources. The canonical library’s collections/pbc-programme-2026-11-03/{evidence.md,gaps.md,acquisitions.json} records versioned papers, SI and uncertain reference inputs (library commit 6755ee4e). Primary anchors: Sun 2023, Eqs 18-22; Izmaylov et al., Eqs 40-43; McClain et al., §4; Pisani et al., §§II-V; Nejad et al., §§II, IV-VI, Eqs 7-14, 37-44; Riplinger et al., Eqs 1-15; Guo et al., Eqs 1-3; Ye and Berkelbach, Eqs 10-26 and SI S1-S3. Nejad’s finite BvK model and Zhu’s megacell boundary differ. CRYSCOR local MP2, LNO-CCSD(T), DLPNO-(T0) and iterative local triples each have specific equations. For missing main papers use the library intake; SI beside its parent and missing licensed decks belong in the existing gap record. No CIS/F12 or metallic CC claim follows from these sources.