BIPOLE Implementation Status

Last updated: 2026-06-20

Summary

BIPOLE is vibe-qc’s own Ewald-J-split periodic SCF path. All four methods support Gamma and multi-k SCF, the exact finite-difference force path, FD strain-gradient cell relaxation, and structure optimization (atoms + cell). Full workflow via run_periodic_job(optimize=True).

⚠ Absolute energies on ionic crystals, FIXED at Γ (all four drivers); multi-k corrected gauge available opt-in (2026-06-11). The root-caused defects (spheropole gauge double-count; Γ-locality projection dropping real cross-cell 1e/J terms; a formally divergent full-Coulomb direct-K series with the Bloch density) are fixed by the Ewald exchange split (option (b) redesign): K = K_SR(erfc ω) + K_LR(reciprocal, K≠0) + (ξ_M − π/(Vω²))·S·D·S, full-Bloch density, no spheropole term. Validated out-of-process vs PySCF GDF: exchange element-wise to 8e-4 / E_K to 0.3 mHa at the converged MgO density (ω-invariant); H₂ 12-bohr box converges to PySCF to ~1 µHa (RHF), ~0.05 mHa (RKS/SVWN + PBE, the projection removal also fixes the XC grid density), ~0.08 mHa (PBE0, the α_HF-scaled hybrid split path), +0.07 mHa (UHF triplet) and ~1 mHa (UKS). All four drivers default to the corrected gauge at BOTH Γ and multi-k (Phase-5 flip, 2026-06-13). The multi-k q = k−k′ ≠ 0 LR-exchange channels (option (b) Phase 3, 2026-06-11/12), per-(k,k′) momentum-transfer channels on q-shifted reciprocal meshes + the BvK-supercell Madelung correction (α_HF-scaled for hybrids, per spin for UHF/UKS), are validated on the H₂ box [2,1,1] vs out-of-process PySCF (RHF +0.12 mHa at cutoff 7, −0.002 at 12; RKS SVWN/PBE0 +0.04/+0.06; UHF +0.03; UKS k-shift 0.013) and to +0.0001 mHa/cell against the explicitly-doubled supercell at Γ (the supercell-unfolding identity, the rigorous internal proof). The multi-k corrected gauge needs a Monkhorst-Pack mesh; an ad-hoc k-list (band path / explicit list) at multi-k falls back to the legacy gauge under the auto default. Pass use_exchange_ewald_split=False for the legacy gauge. Outstanding heavy confirmation: the MgO [2,2,2] c12 RHF+RKS parity run (examples/regression/bipole_parity/mgo_multik_parity.py) is staged for the queue, belt-and-suspenders on top of the supercell identity, fleet-blocked at the 2026-06-13 flip. Two practical caveats for ionic Γ work: (1) the corrected gauge contracts full Bloch folds, diffuse AO tails (e.g. STO-3G Mg 3sp) need fold-converged cutoffs (MgO/STO-3G: ≥12-16 bohr; the driver measures the S(Γ)-fold drift and warns); (2) minimal-basis ionic Γ SCF has multiple genuine solutions (PySCF itself lands on different totals from different starts on MgO/STO-3G Γ), check the basin against a reference density for absolute claims. Forensics + tables: handovers/HANDOVER_BIPOLE_PRODUCTION.md §0a; examples/regression/bipole_parity/mgo_exchange_split_probe.py.

Production forces are finite-difference (exact), in BOTH gauges. compute_bipole_gradient_fd differentiates the actual driver energy, so it follows whichever exchange gauge the SCF used (corrected or legacy) and is correct by construction; bipole_optimize, run_periodic_job(optimize=True), and periodic NEB default to it. The analytic BIPOLE gradient implements the LEGACY Γ-local gauge only and REFUSES corrected-gauge SCF results (ValueError when result.exchange_ewald_split is True; landed v0.12.0 6af56d91). Corrected-gauge analytic gradients landed 2026-06-17 for all four methods (RHF/UHF/RKS/UKS) at both Γ and multi-k (G3 row below; FD-validated, un-refused). The legacy-gauge analytic preview remains available and covers:

• RHF/UHF Gamma, complete for general crystals, ~1e-7 Ha/bohr vs FD.

• RHF/UHF multi-k, maintained [2,1,1] regressions with diagonal-Z (RHF) and coupled-spin-Z (UHF) responses.

• RKS/UKS Gamma-local, maintained LDA asymmetric cells with XC Pulay, moving-grid correction, and KS Bloch-CPHF.

• RKS/UKS multi-k, diagonal-Z + corrected-W (the v_bg/spheropole W convention) + J^LR + XC Pulay; warns. KS CPHF gated to Gamma.

• Finite-temperature/fractional-occupation analytic gradients are now landed in the corrected gauge (Mermin free-energy form; FD-validated RKS Γ ~2e-8 / multi-k ~4e-9). The legacy gauge above still rejects them.

• Meta-GGA tau-Pulay is landed (un-gated 2026-06-20; validated to 1e-9 against an independent reimplementation; see G3). The sole remaining gated analytic case is the legacy multi-k KS-CPHF: a ratified deferral (2026-06-20), legacy-gauge-only, since the corrected-gauge multi-k KS path is variational and needs no CPHF; see handovers/HANDOVER_BIPOLE_GRADIENT.md Case 3.

• Space-group symmetry: attached symmetry auto-enables the bit-exact symmetry-reduced one-electron S/T integrals (SYM2c atom-pair orbits) in all four drivers, energy-invariant on MgO to <1e-9 (test_symmetry_fock_mgo_energy_invariance). Fock symmetry enforcement is opt-in (use_fock_symmetry=True) and not part of the production path: the 2026-06-09 auto-on version used a whole-matrix transformation (wrong for multi-atom cells, ~0.5 Ha on MgO), and even the corrected atom-pair-resolved enforcement reshuffles the truncated J/K builder’s orbit-asymmetric truncation error (~4e-2 Ha on MgO at cutoff 6). All production force paths default to the exact FD gradient compute_bipole_gradient_fd.

Completed

Milestone	Description
M1-M12	Foundation, spheropole diagnosis, multipole infrastructure
M13	Multi-k via kpoints kwarg
M14	RKS/UKS/UHF promoted to user API
M15	Multipole near/far split fix
G2	C++ spheropole kernel (all cases through d-d)
G3	FD gradient (all 4 methods, exact) + analytic research preview
M16	2D/1D gradient support documented
M17	optimize=True in run_periodic_job
M18	Stress tensor + gradient-based cell optimization

User API

from vibeqc.periodic_runner import run_periodic_job

# SCF + atomic relaxation
result = run_periodic_job(system, basis, method="RHF", jk_method="bipole",
                          optimize=True, optimize_max_iter=30)

# SCF + full cell+atom (FD strain-gradient cell step)
result = run_periodic_job(system, basis, method="RHF", jk_method="bipole",
                          optimize=True, optimize_cell=True)

# Standalone force virial diagnostic (not the periodic stress)
from vibeqc.bipole_gradient import compute_stress_tensor
virial = compute_stress_tensor(system, gradient)

# Gradient-based cell optimization
from vibeqc.bipole_optimize import relax_cell_gradient
result = relax_cell_gradient(system, "sto-3g", kmesh, method="RHF")

Remaining Gaps

#	Task	Priority	Status
G1	Production multipole far-pair (default-on)	RETIRED 2026-06-20	Closed as a production / default-on candidate (maintainer-ratified 2026-06-20). The branch is now a gated research artifact: it never auto-enables (only an explicit use_multipole_far_field=True activates it) and is correct only on dipole-free cells. The earlier “L≥1 interaction-tensor normalization” diagnosis was wrong; the bare tensor is unit-test-correct vs exact Coulomb (tests/test_bipole_multipole.py: dipole-dipole, quad-monopole, octupole-monopole all <1e-4; absolute (16,16) octupole pin). The Ha-scale, dipole-tracking failure (−2.78 Ha on LiH/STO-3G; does not converge with multipole order) is in the periodic far-field composition under the Ewald-J split (layer-by-layer diagnosis in the gitignored references/g1_diag*.py): (A) cell moments are built from the P0-localized Γ density, so the contraction Σ_g P(g)·M(g) collapses to Tr[P(0)·M(0)] ≠ N_e instead of the Γ-fold Tr[P(0)·Σ_g M(g)]; a spurious ≈ −0.63 e per-cell net charge; (B) build_j_far_field_multipole returns the far-field potential (an additive term) but apply_multipole_far_field replaces every cell’s J_SR block with it (all cells, incl. the home cell, are flagged “far”) and drops the reciprocal J_LR; a bare-Coulomb real-space lattice sum that is only conditionally convergent for a dipolar 3D cell (Madelung/Ewald; §7); (C) the driver aliases f2e_real = F_J_SR_lat and overwrites its blocks with j_sr − ½K + F_LR before passing them as J_SR_blocks to apply_multipole_far_field, whose “near” branch then double-counts F_LR and K; so even a neutral, dipole-free cell with no far pairs is wrong (H₂ is ~0.5 Ha off on current main, regardless of geometry; the old “dipole-free cells are accurate” claim reflected an older code state and no longer holds). Fixing (A) alone makes it worse (−4.08 Ha: the now-correct large dipole sums conditionally); fixing (A)+screening+keeping J_LR still leaves −2.29 Ha (home-cell J_SR clobbered). No speed win is available either: the exact Ewald-J split already handles the far field optimally in reciprocal space (J_LR), so there is no real-space far cost to accelerate; the probe runs ~1.0-1.14× the exact cost. Off-by-default + the (corrected) enable-time warning + regression tests (tests/test_bipole_multipole_far_field_retired.py; smoke-only tests/test_bipole_fock_multipole.py) pin this. Re-opening would require a from-scratch redesign (Γ-correct neutral moments + an additive, Ewald-consistent far-field), which has no production case.
G2	Spheropole higher-l terms	HIGH	LANDED, +4.112 Ha vs CRYSTAL +4.119 Ha
G3	FD is the production force/stress path (exact, both gauges). The analytic gradient remains a maintained preview. Legacy-gauge results cover RHF/UHF Γ (general crystals), RHF/UHF multi-k (maintained regressions), RKS/UKS Γ-local (maintained LDA cells), and RKS/UKS multi-k (diagonal-Z + W + J^LR + XC Pulay, warns). Corrected-gauge (exchange_ewald_split) Γ and multi-k RHF/UHF/RKS/UKS analytic gradients are un-refused and pinned against FD (multi-k landed 2026-06-17, 2f2da9ec/5d0b6e05/0fe4ecac). Fractional-occupation (finite-T smeared, Mermin free-energy) analytic gradients are landed in the corrected gauge, fractional D + W = Σ_i f_i ε_i C_iC_i† with no occupation-response term (A = E − T·S is stationary w.r.t. the occupations); FD-validated RKS Γ ~2e-8 / multi-k ~4e-9; the legacy gauge still rejects them. Meta-GGA τ-Pulay is landed (validated to 1e-9 against an independent reimplementation; SCAN/r2SCAN produce physically-reasonable gradients; TPSS/M06-L carry known residual blowup from pre-existing SCF MO-eigenvalue garbage; FD remains the production force path). Sole remaining gated analytic case: multi-k KS-CPHF, DEFERRED (ratified 2026-06-20). Legacy-gauge-only: the corrected-gauge multi-k KS path is variational and needs no CPHF, and is FD-validated (RKS ~5e-8, re-confirmed 2026-06-20). The legacy multi-k KS path runs a diagonal-Z preview that warns; RHF/UHF legacy multi-k FD pins are active after the 2026-07-04 full-K exchange-gradient fix. A full multi-k KS-CPHF is a complex k-space coupled-perturbed solver; building it for the deprecated legacy gauge has no production need (FD is exact, corrected gauge covers multi-k KS analytically) and is not a v0.14 blocker. See handovers/HANDOVER_BIPOLE_GRADIENT.md Case 3.	MEDIUM	Updated 2026-07-04: FD stays the production recommendation. Corrected-gauge Γ and multi-k analytic migration landed (all four methods); fractional-occupation analytic gradients landed in the corrected gauge (FD-validated); meta-GGA τ-Pulay landed (un-gated); legacy-gauge RHF/UHF multi-k strict xfails retired after the BIPOLE full-K exchange-gradient convention fix. Multi-k KS-CPHF deferral ratified (§11), legacy-gauge-only, see handover.
G4	Space-group symmetry for one-electron integrals	MEDIUM	LANDED, bit-exact SYM2c-reduced S/T auto-enabled in all four drivers (MgO invariance <1e-9); Fock symmetry enforcement demoted to opt-in (truncation-asymmetry, 2026-06-10)