BIPOLE Implementation Status

Last updated: 2026-05-21

Summary

BIPOLE is the CRYSTAL-gauge periodic boundary conditions path in vibe-qc. All four methods support multi-k, multipole acceleration, analytic gradients, force-based stress tensor, and structure optimization (atoms + cell). Full workflow via run_periodic_job(optimize=True).

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++ CJAT33 spheropole kernel (all cases through d-d)
G3	Gradients (all 4 methods) + FD fallback
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 (gradient-based stress)
result = run_periodic_job(system, basis, method="RHF", jk_method="bipole",
                          optimize=True, optimize_cell=True)

# Standalone stress tensor
from vibeqc.bipole_gradient import compute_stress_tensor
stress = 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	Other chat
G2	Spheropole higher-l terms	HIGH	LANDED — +4.112 Ha vs CRYSTAL +4.119 Ha
G3	J^LR reciprocal gradient derivatives	MEDIUM	Other chat