[PR1] feat: add Boys function for 2 electron and validation tests

[San1357]

Summary

• Implemented Boys function using hyp1f1 (Kummer confluent hypergeometric function)
• Added boys_function_standard for single-order evaluation
• Added boys_function_all_orders for computing F_m(T) for m = 0 to m_max
• Added get_boys_function factory for selecting potential type
• Part of Issue WoC: 2-electron integrals: better performance and more flexibility #221 (Week 1)

What Changed

File	Lines	What
gbasis/integrals/boys_functions.py	+132	Boys function implementations
tests/test_boys_functions.py	+157	15 unit tests
.gitignore	+1	Added virtual env directory

Mathematical Reference

The Boys function is defined as:

$$F_m(T) = \int_0^1 t^{2m} \exp(-Tt^2) , dt$$

Computed using the relation with Kummer's confluent hypergeometric function (Helgaker eq. 9.8.39):

$$F_m(T) = \frac{_1F_1(m + \frac{1}{2};, m + \frac{3}{2};, -T)}{2m + 1}$$

How To Test

# Run Boys function tests
pytest tests/test_boys_functions.py -v

# Check coverage
pytest tests/test_boys_functions.py --cov=gbasis.integrals.boys_functions --cov-report=term-missing

# Check formatting & linting
black --check --line-length 100 gbasis/integrals/boys_functions.py
ruff check gbasis/integrals/boys_functions.py

# Verify existing tests not broken
pytest tests/ --timeout=120

Proof That It Works

Tests (15 passed)

Black: Clean

Ruff: Clean

Existing tests: Not broken

306 passed, 279 skipped, 1 xfailed, 4 warnings in 66.88s

Checklist

• Tests added for each new function
• All 15 tests pass
• Coverage 100%
• Black formatted (line-length 100)
• Ruff linting clean
• Existing tests not broken (306 passed)
• Docstrings in numpydoc format
• No new dependencies added (uses existing scipy, numpy)
• Pure Python only (no C/Fortran)

Scope of this PR

• This PR ONLY adds Boys function implementations
• Does NOT modify any existing code
• Does NOT change any existing tests

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

[msricher]

This looks good to me so far, clean code and good tests. In .gitignore, qc-dev-env/ is just your local Python virtualenv? If so, then don't include it here; ignores specific to you or your machine go in .git/info/exclude.

[San1357]

@msricher Thanks for the Positive feedback & review. Yes, qc-dev-env is my local Python virtualenv. I've moved it from .gitignore to .git/info/exclude in the latest commit.

[San1357]

@msricher I've also tried to optimized boys_function_all_orders:

• Replaced the Python for-loop with NumPy broadcasting (single vectorized hyp1f1 call for all orders)
• Used np.asarray instead of np.atleast_1d to preserve multidimensional T shapes
• Added 4 new tests (small-T, multidim broadcasting, recurrence, random spot-checks)
• Total: 19 tests, all passing

[msricher]

@marco-2023 can you also review it? I think it's ready for merge.

[San1357]

Hi @msricher , @marco-2023 @PaulWAyers

What's new in this update

The initial PR set up the core Boys function (boys_function_standard,
boys_function_all_orders) for the standard Coulomb potential. This update
extends the module with three additions:

1.Downward Recursion — boys_function_recursion seeds from F_{m_max} using
hyp1f1, then recurses down via F_m = (2T·F_{m+1} + e^{-T}) / (2m+1).
Avoids calling hyp1f1 for every order separately, which matters when all
orders 0…m_max are needed at once. Tested up to m=20 and T=500.

2. Range-Separated Potentials — boys_function_erf and boys_function_erfc
add support for the attenuated Coulomb potentials used in range-separated DFT
(HSE, CAM-B3LYP, etc.). erf(ωr)/r covers the long-range part, erfc(ωr)/r
covers the short-range complement. get_boys_function is extended to accept
"erf" and "erfc" as potential types, requiring omega to be passed.

3. High-Precision Reference — boys_function_mpmath computes the Boys function
using arbitrary-precision arithmetic via mpmath (default 50 dps). It's slow by
design — useful only for validating the other implementations or probing edge
cases at very high orders where scipy.hyp1f1 may drift.

Tests

Added TestBoysRecursion (7 tests) and TestBoysMpmath (4 tests, auto-skipped
if mpmath isn't installed). All existing tests continue to pass.