BIPOLE Implementation Status

Last updated: 2026-06-10

Summary

BIPOLE is the CRYSTAL-gauge periodic boundary conditions path in vibe-qc. 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: 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). Since the corrected gauge is now the BIPOLE default (Γ since 2026-06-10/11; multi-k since the Phase-5 flip 2026-06-13), the analytic path is reached only via an explicit use_exchange_ewald_split=False SCF. Decision (Phase 5, 2026-06-13): FD is ratified as the permanent production force/stress path; the corrected-gauge analytic-kernel migration (re-derive W/Pulay on the split-exchange functional) is a deferred future milestone, parallel to the periodic-SCF chat’s EWALD-route gradient migration — NOT a v0.13.0 deliverable. On legacy-gauge results the maintained analytic preview still 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 and meta-GGA tau-Pulay remain gated.

  • 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)

HIGH

Scoped 2026-06-10 — L≤3 machinery correct (absolute octupole pin vs exact Coulomb; (16,16) tensor; H₂ e2e <0.1 mHa). Stays off-by-default: for centrosymmetric cubic targets (MgO/NaCl) the cell-level L≤3 moments vanish by symmetry, so the branch only pays off on low-symmetry cells; the conservative auto-enable (cutoff ≥ 14 bohr, ≥20% far pairs, R ≥ L·max_lat margin) governs opt-in. Default-on needs a demonstrated production benchmark win, not more correctness work.

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) Γ RHF/UHF/RKS/UKS analytic gradients are now un-refused and pinned against FD; corrected-gauge multi-k analytic gradients still raise until the per-k q-channel K_LR + supercell-Madelung gradient lands.

MEDIUM

Updated 2026-06-16: FD stays the production recommendation for v0.13.0. The corrected-gauge Γ analytic migration has landed as preview coverage; multi-k corrected-gauge analytic migration, meta-GGA tau, multi-k KS-CPHF, and fractional-occupation analytic gradients remain gated.

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)