WoC: 2-electron integrals: better performance and more flexibility

[PaulWAyers]

Description

Add functionality to the GBasis library for evaluating 2-electron integrals, including non-Coulomb repulsions. The current Python implementation is very slow, but it also uses a very inefficient algorithm. A more efficient algorithm, combining the Obara-Saika and Head-Gordon-Pople recursions, would fix this issue. One advantage of having this coded in (pure) Python is that it makes it easy to explore new screening methods, exploit sparsity, and include unconventional integrals (e.g., screened Coulomb interactions). Here is a good introduction to Gaussian integral evaluation, which can help you get your bearings without overwhelming you with (important!) details.

📚 Package Description and Impact

GBasis is a pure-Python package for evaluating and analytically integrating Gaussian-type orbitals and their related quantities. The goal is to build a set of tools to the quantum chemistry community that are easily accessible and easy to use as to facilitate future scientific works.

👷 What will you do?

Your main focus will be to (re)implement the 2-electron integrals in GBasis. This is important partly because it seems we may have a bug in the integrals for high angular momentum (cf. #216) and because the current implementation is painfully slow. It is very helpful for many people to have a pure Python implementation of the 2-electron integrals because, while it will always be (relatively) slow, it allows more flexibility for development of new algorithms and facilitates cross-platform code interoperability. In addition, in many cases integral evaluation is not the performance bottleneck.

The key steps will be to

1. Understand the recursive evaluation of Gaussian integrals.
2. Implement the key recursions. (vertical, horizontal, electron-transfer)
3. Apply these recursions in sequence to evaluate the 2-electron integrals.
4. Write functions for different "initializations" of the Boys function to support different types of 2-electron integrals.

2-electron integrals from PySCF can be used for testing, as can a recursion check against existing integrals (which are surely reliable for low angular momentum). For more general integral types, one will have to test by manual verification (e.g., numerical integration using Grid.

🏁 Expected Outcomes

1. Implement the recursive evaluation of 2-electron integrals into GBasis using the algorithm in the notes. This requires implementing several different recursions, which are the "building blocks" for the algorithm as a whole.
2. Implement several different "generalized Boys functions" so that multiple types of 2-electron integrals are supported.
3. Write comprehensive tests and documentation for all new functionality.
4. Write tutorial Jupyter notebooks that show how to use the new functionality.

Required skills	Python, OOP
Preferred skills	Be comfortable with calculus and numerical algorithms (especially recursion). Experience with scientific programming and quantum chemistry can help
Project size	350 hours, Large
Difficulty	Medium to Hard 🥵

🙋 Mentors

Paul Ayers	ayers_at_mcmaster_dot_ca	@PaulWAyers
Marco Martínez-González	mmg870630_at_gmail_dot_com	@marco-2023
Fanwang Meng	fanwang_dot_meng_at_queensu_dot_ca	@FanwangM

📝 Notes

1. An algorithm for doing this are included in the attached notes, starting page 17 (eq. 61).
2. The trick for using "unconventional Boys functions" is from an old paper of Ahlrichs which gives several (families of) 2 ``electron'' integrals in section 5.
3. This hopefully will close [BUG] Electron repulsion energy #216 and libcint/gbasis eri tolerance is 1e-4? #208 .
4. See contributing guidelines.

[San1357]

Hello mentors (@PaulWAyers, @marco-2023, @FanwangM),

I am Aayush Gupta, a selected contributor for this project under Winter of Code 5.0. I am excited to start working on the “2-electron integrals: better performance and more flexibility” task.

I have begun setting up the GBasis development environment and reviewing the documentation and attached notes on Gaussian integral evaluation, Obara–Saika, and Head–Gordon–Pople recursions.

For Week 1, I plan to focus on:

• Understanding the current GBasis integral implementation and overall code structure
• Studying the recursion algorithms and Boys function formulations
• Running existing tests to establish a performance and correctness baseline

Please let me know if there are any specific parts of the codebase or notes that you would recommend prioritizing first.

Looking forward to your guidance and collaboration on this project.

Best regards,
Aayush Gupta

[PaulWAyers]

@San1357 I've invited you to the organization, team, and discussion repository. @msricher , @marco-2023 , and I will be the lead mentors for this.

[San1357]

Thank you, @PaulWAyers

I have successfully joined the organization, gbasis team, and discussions repository.

Looking forward to working with you, @msricher, and @marco-2023 on this project.

[San1357]

Hi , @PaulWAyers
I tried installing the pre-release version using pip install --pre qc-gbasis, but it installs the same version (0.1.0) as the stable release.

Does this mean there is currently no separate pre-release (alpha/beta) version available on PyPI? If so, should contributors use the GitHub main branch (editable install) for development work?

[San1357]

[Update]
Hi, @PaulWAyers I have successfully set up the development environment.

• Created and activated a virtual environment
• Installed dependencies and built libcint
• Installed GBasis in editable (dev) mode
• Ran the QA tests using tox

I'm now ready to start working on the implementation. Please let me know if there is any additional setup or guideline I should follow before proceeding.

Thanks!

[PaulWAyers]

@San1357 I think this sounds good. We'll coordinate a meeting in the next few days. QC-Devs has two Winter of Code contributors, so we'll need to formulate a sensible plan so we can provide both of you with adequate supervision.

[San1357]

Hi @PaulWAyers,

The Ahlrichs paper link appears to be behind a paywall on RSC.
Would it be possible to share an accessible PDF copy or an alternative public reference for the "unconventional Boys functions" section?

Thank you!

[PaulWAyers]

I just added a link in the private discussion channel for gbasis content
https://github.com/orgs/theochem/discussions/2
That includes the whole folder with all the background sources (or most of them, at least) that we used when designing gbasis.

[San1357]

Hi @PaulWAyers ,
sharing a quick update from this week:

Completed so far

• Set up the development environment and ran the existing test suite successfully.
• Spent time going through the algorithm notes (from page 17, Eq. 61 onward) to understand the VRR → ETR → HRR recursion flow and the role of the Boys function.
• Reviewed the existing codebase, especially:
  • _two_elec_int.py
  • electron_repulsion.py
  • point_charge.py
• Started implementing the new code by completing the Boys function module:
  • Standard Coulomb Boys function using hyp1f1
  • Downward recursion for numerical stability at large (T)
  • Factory-style initialization to support different potential types
  • Added 14 unit tests (all passing)

Planned next steps

• Week 2: Implement VRR
• Week 3: Implement ETR
• Week 4: Implement HRR and complete the OS+HGP pipeline

Happy to discuss the approach further if helpful.
Let me know if you’d prefer that I open a draft PR for early feedback.

Thanks!

[San1357]

Hi @PaulWAyers @msricher @marco-2023 ,
sharing the Week 2 update:

Completed

• Implemented the Vertical Recursion Relation (VRR, Eq. 65) as the first
  recursion step of the OS+HGP pipeline.
• _vertical_recursion_relation() builds angular momentum on center A,
  computing [a+1,0|00]^m from [00|00]^m using Boys function values.
• Coefficients rho/zeta and 1/(2*zeta) are precomputed once to avoid
  redundant work inside the recursion loops.
• All three Cartesian components (x, y, z) handled with NumPy vectorized
  operations over primitive indices.
• Added 4 unit tests: base case passthrough, output shape, p-orbital step
  verified by hand, s-orbital edge case.

Planned next steps

• Week 3: Implement ETR — build [a0|c0]^0 from [a0|00]^m
• Week 4: Implement HRR and complete the OS+HGP pipeline

Thanks!