[PR-5] feat: integrate OS+HGP algorithm into electron_repulsion module

[San1357]

Summary

• Implemented ElectronRepulsionIntegralImproved class — uses compute_two_electron_integrals_os_hgp (OS+HGP algorithm) instead of old _compute_two_elec_integrals
• Implemented electron_repulsion_integral_improved() — drop-in replacement for electron_repulsion_integral() with same interface
• Full integration: gbasis framework → OS+HGP pipeline (Boys → VRR → ETR → Contract → HRR)
• Part of Issue WoC: 2-electron integrals: better performance and more flexibility #221 (Week 6),
• builds on PR [PR-2] feat: implement VRR for OS+HGP two-electron integral pipeline #234 (VRR),
• PR [PR-3] feat: implement ETR (Eq. 66) and primitive contraction for OS+HGP pipeline #237 (ETR),
• and PR [PR-4] feat: implement HRR (Eq. 67) and complete OS+HGP two-electron integral pipeline #238 (HRR)

What Changed

File	Lines	What
gbasis/integrals/_two_elec_int_improved.py	+732	Core OS+HGP pipeline: Boys → VRR → ETR → Contract → HRR, with _optimized_contraction, _get_factorial2_norm, and compute_two_electron_integrals_os_hgp
gbasis/integrals/electron_repulsion.py	+248	Added ElectronRepulsionIntegralImproved class and electron_repulsion_integral_improved() public API integrating the pipeline into gbasis framework
tests/test_electron_repulsion.py	+574	17 integration tests: matches old implementation, Horton reference values, symmetry checks, bra-ket reordering
tests/test_two_elec_int_improved.py	+699	Unit tests for all pipeline stages: Boys, VRR, ETR, HRR, contraction, norm, and reordering

Mathematical Reference

The two-electron repulsion integral:

$$(\mu\nu|\lambda\sigma) = \int\int \phi_\mu(\mathbf{r}_1)\phi_\nu(\mathbf{r}_1) \frac{1}{r_{12}} \phi_\lambda(\mathbf{r}_2)\phi_\sigma(\mathbf{r}_2) , d\mathbf{r}_1 d\mathbf{r}_2$$

Pipeline steps:

1. Boys function $F_m(T)$ — auxiliary integral
2. VRR (Obara-Saika vertical recurrence) — builds primitive integrals
3. ETR (Electron Transfer Recurrence) — reduces angular momentum
4. Contraction — combines primitives with coefficients + norms
5. HRR (Head-Gordon-Pople horizontal recurrence) — shifts angular momentum to bra/ket

How To Test

# Unit tests (pipeline stages)
python -m pytest tests/test_two_elec_int_improved.py -v

# Integration tests
python -m pytest tests/test_electron_repulsion.py -v -k "improved"

# Coverage
python -m pytest tests/test_two_elec_int_improved.py tests/test_electron_repulsion.py --cov=gbasis/integrals --cov-report=term-missing

Proof That It Works

Unit tests (pipeline stages)

Integration tests (full ERIs via gbasis framework)

All tests

Coverage

black & ruff test

First Checklist

• Tests added for each new function
• All 35 tests pass
• Black formatted
• Ruff linting clean
• Existing tests not broken
• Docstrings in numpydoc format
• No new dependencies added (uses existing numpy)
• Pure Python only (no C/Fortran)

Scope Of this PR

• Implements full OS+HGP algorithm for two-electron repulsion integrals
• Adds ElectronRepulsionIntegralImproved class following gbasis conventions
• Adds electron_repulsion_integral_improved() public API
• Does not replace existing electron_repulsion_integral() — both coexist
• Week 6 deliverable integrating ETR (PR [PR-3] feat: implement ETR (Eq. 66) and primitive contraction for OS+HGP pipeline #237) +
• HRR (PR [PR-4] feat: implement HRR (Eq. 67) and complete OS+HGP two-electron integral pipeline #238) into the gbasis module

Second Checklist

• Write a good description of what the PR does.
• Add tests for each unit of code added (e.g. function, class)
• Update documentation
• Squash commits that can be grouped together
• Rebase onto master

Type of Changes

	Type
	🐛 Bug fix
✓	✨ New feature
	🔨 Refactoring
	📜 Docs