GSoC 2026: Better linking between `Libcint` and `GBasis`

[PaulWAyers]

Description

Gbasis uses libcint as a back end for efficient integral evaluation. Unfortunately, the default installation of GBasis (with PyPi) doesn't include libcint, and installation from source is not easy for some users. The primary goal of this project is to fix this. The secondary, subsidiary, goal is to provide better support for the very rich set of integrals that libcint supports.

📚 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 prepare a release of GBasis that includes libcint for PyPi. We want to support Windows, Linux, and Mac. Note that when we say libcint this includes libcint (generic C library) and its high-performance version qcint, for hardware platforms that support it. There might be multiple ways to do this, using, for example, Hatch. We are agnostic as to the way it is done, but we note that (a) compiling libcint can be hairy and (b) we want an automated workflow so that updating GBasis is easy and new versions of libcint are easily supported.

The C/Python interface can be written using a few different methods, such as the Python/C API, or Python's built-in foreign function interface library ctypes. Note that NumPy works with either of these.

🏁 Expected Outcomes

1. It becomes possible to pip install GBasis with the libcint integral engine.
2. More (most?) of the integrals in libcint are accessible from GBasis. (This is basically wrapping more integrals. It isn't always trivial. Evauation of angular momentum in GBasis vs. Libcint bindings #149 )
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	C, Python, OOP, DevOps
Preferred skills	Experience with building complex Python packages and linking C/Python
Project size	Large
Difficulty	Medium to Hard 🥵

🙋 Mentors

Marco Martínez-González	mmg870630_at_gmail_dot_com	@marco-2023
Michelle Richer	michellericher93_at_gmail_dot_com	@msricher
Toon Verstraelen	toon_dot_verstraelen_at_ugent_dot_be	@tovrstra
Paul Ayers	ayers_at_mcmaster_dot_ca	@PaulWAyers

📝 Notes

1. See the existing pyproject.toml and the current link to libcint.
2. Refer to our guidelines for contributors.

[aamrindersingh]

Hi @PaulWAyers ,

This is indeed a problem worth solving. Right now, using the libcint backend means manually running tools/install_libcint.sh with a C compiler and Common Lisp , not realistic for researchers and students who just want to run calculations. I have faced this personally. It should be as simple as pip install gbasis.

I looked at how h5py,PySCF,and pikepdf handle similar problems and I am thinking cibuildwheel + scikit-build-core + CMake. cibuildwheel is what NumPy and SciPy use for cross platform wheels, and scikit-build-core works nicely with CMake, which libcint already uses , a plus since we do not have have to write custom hooks now like Hatch would require.

The plan would be to compile libcint during wheel build using CMake and bundle the resulting .so/.dylib/.dll into the wheel, so users get everything with pip install.

Thanks, looking forward to your feedback

[adilraza99]

Hello @PaulWAyers,

I’d like to take a look at this issue.

I have started exploring how GBasis builds and connects to its integral backends, focusing on how libcint is compiled, packaged, and loaded at runtime.

From my initial exploration, GBasis dynamically loads libcint from within the package and falls back to the pure Python implementation when the library is not present. While reproducing the build, I also encountered failures on ARM/M-series Macs caused by x86-specific SIMD compiler flags, which may affect portability.

To move forward, I will focus on:

• reproducing and documenting the libcint build workflow
• verifying backend detection and loading behavior
• identifying the minimal requirements for successful linkage

I enjoy digging into build and integration details like this and will share updates as I learn more.

Thanks for your time and for maintaining this project.

[PaulWAyers]

Thanks to those interested. Keep in mind that one thing we'd like to ensure, to the extent possible, is that the distribution is maintainable with minimal effort on the part of the QC-Devs team. Not everyone on our team (indeed, only a small fraction of our team) will have the DevOps expertise to maintain the distribution, so automated procedures and clear protocols are important.

[adilraza99]

Hello @PaulWAyers,

Thank you for the guidance - that makes perfect sense.

I understand that keeping the distribution maintainable and minimizing long-term maintenance overhead is essential, especially since automated and reliable build procedures will benefit both users and future maintainers.

With that in mind, I’ll focus on understanding how the libcint build and packaging can be made reproducible and platform-aware, rather than relying on manual steps. I’ll also look into the portability issues I encountered during the build (for example, architecture-specific SIMD flags) to see how they might be handled in a maintainable way.

I’ll share concise updates as I learn more.

Thanks again for the direction.

[DPKamalnayan]

Hi @PaulWAyers ,
I undersand this poject as following solutions:

1. If you download GBasis, it’s like buying a car and then you have to build the engine(compile a complex c library libcint) yourself, which can be a tedious task.
   I will Pre-Build (compile) the engine, automate future compilation, vendor(i.e. bundle libcint and GBasis) and construct Foreign Function Interface(Python bindings).When a user types pip install gbasis, the engine will be ready to go, whether on a Mac, Windows, or Linux.

2. I understand there are actually two versions of the engine: a standard one (libcint) and a hardware intensive one (qcint) which only works on certain high-end computers.
   I will set up a smart automated software to use the qcint version if the hardware supports it, but stay libcint on older machines.

3. libcint is capable of doing hundreds of integrals, but GBasis only knows how to "ask" for a few of them.
   A Expanded Integral bridge (using tools like ctypes for efficient interface with NumPy) is needed. This allows GBasis to access almost everything libcint can perform.

4. Automated Maintenance: If someone fixes a bug in libcint, the GBasis team shouldn't have to manually rebuild everything for every type of computer all over again.
   A GitHub Actions workflow(Automated continuous integration and continuous delivery (CI/CD) workflow) will be established.Whenever there is an update, GitHub automatically builds, tests, and ships the new version to the world.

in short the goal is to make GBasis easy to install, more powerful by leveraging libcint fully and easy to maintain.
I hope to talk to you(@PaulWAyers ) about my GSoC proposal for more indepth discussion of the implementation of the above solutions.
Thanks, looking forward to your feedback.

[KumarShresth7]

Hello, @PaulWAyers ,
I am very interested in working on the project to bundle libcint with GBasis and expand its integral support. I have been looking through the repository, specifically install_libcint.sh, libcint.py, and the current PyPI release workflow, and I wanted to run my proposed approach by you to get your feedback.

Proposed Solution

1. Cross-Platform Binary Wheels via cibuildwheel
   Currently, GBasis expects users to run the bash script to compile libcint locally. To allow users to simply pip install qc-gbasis across Windows, Linux, and macOS, I propose the following:

Build Backend: Integrate the CMake build process directly into the Python build system. While Hatch was mentioned as a possibility, using scikit-build-core (or setuptools with a custom CMake extension) is usually the most robust way to handle CMake-based C libraries in Python. It will automatically invoke CMake to compile libcint (and qcint where applicable) during the wheel-building phase.

CI/CD Pipeline: Update .github/workflows/pypi_release.yaml to use cibuildwheel. This will spin up appropriate runners (including manylinux Docker containers for Linux) to compile the .so, .dylib, and .dll files and package them into platform-specific wheels.

2. Fixing Angular Momentum (Issue Evauation of angular momentum in GBasis vs. Libcint bindings #149) & Expanding Integrals
   Looking at tools/auto_intor_modify.py, I see the patch for generating the int1e_rxp (angular momentum) C code is already in place. Since the C functions are being generated, the NotImplementedError in CBasis.angular_momentum_integral is likely due to an issue in the ctypes bindings, potentially a mismatch in tensor shapes, handling of the imaginary components, or origin shifts.

I will debug the ctypes signature for int1e_rxp in libcint.py to resolve Issue #149.

For expanding the rest of the libcint integrals, I plan to systematically map the remaining functions using the INTEGRAL_REGEX pattern in the _LibCInt wrapper, write rigorous unit tests comparing the outputs to known benchmarks, and document them in the Jupyter notebooks.

Questions & Feedback
Before I draft my final proposal, I would love to get your thoughts on a few things:

Do you have a strong preference for the build backend? Hatch has great environment management, but scikit-build-core is specifically designed to bridge Python and CMake, which fits libcint perfectly.

Are there any specific libcint integrals (beyond angular momentum) that the community has been urgently requesting so I can prioritize those in the timeline?

Looking forward to your feedback!

Best regards,
Kumar Shresth (kumarshresth2004@gmail.com)

[PaulWAyers]

1. We don't have a strong preference for the build backend. There will be pros and cons for anything, I suspect. I think @msricher and @marco-2023 would be the resident QC-Devs experts on this.
2. I think the main libcint integrals that are "urgent" are those related to nuclear coordinates/gradient evaluation. The (3-center) integrals related to density-fitting methods may also be indicated. We mostly want to support "as much as possible" as we do not wish to limit gbasis users.

[KumarShresth7]

@PaulWAyers

Based on that, here is the plan I will proceed with:

1. Build System: scikit-build-core
   Since there is no strong preference, I will use scikit-build-core. It is currently the standard for bridging CMake and Python (used by numpy/scipy) and handles the libcint compilation logic very naturally.

I'll update pyproject.toml to drive the CMake compilation directly.

I'll set up cibuildwheel in the workflows to automatically generate wheels for Linux (manylinux), Windows, and macOS (Intel & Apple Silicon).

2. Integral Priority
   I will focus on supporting "as much as possible," with specific priority on the urgent items you mentioned:

Nuclear Gradients: verifying and exposing the ip (interaction point) integrals needed for forces/geometry optimization.

3-Center Integrals: implementing the loops and bindings for int3c2e to support density-fitting methods.

Fixing int1e_rxp: I'll also debug the angular momentum signature issue mentioned in #149.

I'll start by setting up the build system to get the wheels working, and then move on to the integral bindings. Let me know if anything else comes to mind!

[DPKamalnayan]

Hi @PaulWAyers,
From your feedback I understand that expansion of Integral bridge is the main task, specifically focusing on (a) nuclear coordinate gradient function (b)Density-Fitting/3-center Integrals function

well @PaulWAyers, for wider support to gbasis users and a robust solution to your specific problems I recommend a Generalized intelligent Dispatcher that can not only handle both gradients and 3-center integrals but also next 100 functions accessible on user demand.

Here is how the Dispatcher would be designed to handle these complex tasks:

1. )Handling Gradients (Nuclear Derivatives)
   A standard overlap integral returns a single value per orbital pair. A gradient integrals are trickier because they return three values (the derivative with respect to x, y, and z).
   • The Dispatcher Solution:When the dispatcher recognizes a function name containing _ip (integral of momentum/gradient) like cint1e_ipovlp_cart, it will automatically adjust the NumPy buffer size i.e. moving from 2D matrices to 3D arrays to accommodate the Cartesian components (x, y, z) of the forces.

2. )Handling 3-Center Integrals (Density Fitting)
   3-center integrals change the "rank" of the tensor. Instead of two orbitals interacting, you have two orbitals and one auxiliary function; hence the nested loops in the C-code expect three pointers to basis set info instead of two.
   • The Dispatcher’s Multi_Basis handling Solution: The dispatcher will be managing distinct basis sets (Standard and Auxiliary). It will verify dimensions and pass the correct memory pointers to libcint's 3-center API (such as cint2e_3c1e), returning the resulting 3-index tensors directly into NumPy.

In short as you say @PaulWAyers "to support as much as possible", If a user wants a weird new integral tomorrow 😄 ,they just pass the name of the libcint function to your dispatcher. You don’t have to write any new code; the bridge is already built smart enough to handle it.

Thanks, looking forward to your feedback.
@DPKamalnayan

[msricher]

scikit-build is the way to go, I think, because you can then build LibCint with CMake very easily, which is the supported build method for that project. In your CMake build script, you can also choose between cint and the x86_64-optimized qc-int sources, and also between fetching and building the code into a static library yourself or using the shared libcint library on the system. Then if there is any C/++ glue code, it can also be built and linked to LibCint during the Cmake build step.

See here.

[San1357]

Hi @PaulWAyers @marco-2023 @msricher, @tovrstra

This is Aayush Gupta. I'm interested in working on this project for GSoC 2026. I recently completed issue #221 (2-electron integrals using Obara-Saika and Head-Gordon-Pople recursions) through PR #245 which was merged into master with the help & guidance of @PaulWAyers @msricher & @marco-2023 , so I'm already comfortable with the GBasis codebase.

---

What I Found in the Code

Over the past week I've been studying the existing libcint integration in detail — specifically libcint.py, pyproject.toml, install_libcint.sh, and how the CBasis class is structured — to understand exactly what needs to change before writing a proposal.

Here are a few specific observations from reading the code that shaped my approach:

1. _LibCInt loads the shared library via a hardcoded path on line 221:

_libcint: CDLL = cdll.LoadLibrary((Path(__file__).parent / "lib" / "libcint.so"))

This works locally on Linux but breaks on Mac (.dylib) and Windows (.dll), and won't survive pip install unless the correct platform binary is bundled and the loading logic is made platform-aware.

2. pyproject.toml currently uses setuptools as the build backend and only includes the pre-compiled .so as package data:

[build-system]
requires = ["setuptools>=64", "setuptools-scm>=8"]
build-backend = "setuptools.build_meta"

[tool.setuptools.package-data]
gbasis = ["integrals/include/cint*.h", "integrals/lib/libcint.so*"]

There's no build step that compiles libcint from source — so if a user doesn't already have the .so, it simply won't work.

3. install_libcint.sh defaults to building qcint (line 7) which is x86-specific. This means ARM/M-series Mac users would need to explicitly set USE_LIBCINT=1 to fall back to generic libcint. The packaging solution should handle this detection automatically rather than requiring manual intervention.

4. CBasis.__init__ already has a clean pattern using make_int1e and make_int2e to register integrals (lines 560–583) — wrapping additional integrals from issue Evauation of angular momentum in GBasis vs. Libcint bindings #149 would just mean extending this list with the correct libcint function names, which is relatively straightforward once packaging is solved.

---

Proposed Approach

1. Packaging

• My plan is to migrate the build backend from setuptools to scikit-build-core since libcint already uses CMake — this feels like the most natural fit and avoids writing custom hooks that tools like Hatch would require. The proposed pyproject.toml change would look like:

[build-system]
requires = ["scikit-build-core>=0.9"]
build-backend = "scikit_build_core.build"

• I would write a CMakeLists.txt at the GBasis root that fetches a pinned version of libcint via FetchContent, compiles it, and installs the resulting shared library into gbasis/integrals/lib/. The _LibCInt loading logic would also be updated to handle .so, .dylib, and .dll based on platform rather than hardcoding .so.

• For cross-platform wheel building, I would configure cibuildwheel to handle platform-specific dependencies — the main challenge being OpenMP and ARM support:

[tool.cibuildwheel]
build = ["cp39-*", "cp310-*", "cp311-*", "cp312-*"]

[tool.cibuildwheel.macos]
before-build = "brew install libomp"

[tool.cibuildwheel.linux]
before-build = "yum install -y libgomp"

• For ARM/M-series Macs, the CMake config would automatically detect the architecture and build generic libcint instead of qcint — no manual USE_LIBCINT=1 required. GitHub Actions would run cibuildwheel on all three platforms and automatically upload wheels to PyPI on each release. Pinning the libcint version in one place in CMakeLists.txt means updating to a new release only requires changing that one line — everything else is automated.

• For libcint vs qcint, my current thinking is build-time detection — check if the target is x86 with AVX support and compile qcint accordingly, otherwise fall back to libcint. But I wanted to ask: would runtime detection be preferred?

2. Integral Priority

Based on your earlier comment about priorities, I plan to focus on:

1. Nuclear gradient integrals —

• the _ip family (e.g. int1e_ipovlp, int1e_ipkin, int1e_ipnuc) needed for force/geometry optimization.

• These are partially present in the codebase (lines 570–573) but not fully exposed yet.

2. 3-center integrals (e.g. int3c2e) —

• needed for density-fitting methods.
• These require handling a third basis set pointer in the libcint API which is different from the existing make_int2e pattern.

3. Remaining integrals from issue Evauation of angular momentum in GBasis vs. Libcint bindings #149 —

• carefully verifying convention differences (like angular momentum sign) before exposing them.

3. Automated Workflow

I would set up a clear GitHub Actions CI/CD pipeline with documented protocols so that updating libcint requires minimal DevOps knowledge — just changing a version pin, everything else runs automatically.

---

Questions

1. For OpenMP on Windows with MSVC — should I use /openmp flag with MSVC, or would you recommend using MinGW instead? Also, is there a preferred way to handle OpenMP for Mac and Linux in the cibuildwheel config?

2. Build-time vs runtime detection for qcint — any preference?

( My thoughts - I'm leaning towards build-time detection since it follows the same approach as NumPy/SciPy, is more reliable, and fits naturally with cibuildwheel which is designed around per-platform wheel building. But wanted to confirm if you have a preference.)

---

Thank you — looking forward to your feedback.

[dhruvch12]

Hello @marco-2023 @msricher @tovrstra @PaulWAyers

I am very interesting for this GSoC project. For understanding the packaging pain points, I reproduced the local installation failures on Windows (primarily failing around the outdated GCC requirements for dependencies and the missing libcint linkage).

For solving this primary PyPi distribution goal, I believe implementing cbuildwheel via GitHub Actions is the most sustainable path to distribute pre-compiled cross-platform binaries. I have started prototyping a workflow on my fork to test this. I currently have the base pipeline running and am working on injecting the libcint C-make build steps into the CIBW_BEFORE_ALL environment to compile the library inside the many linux containers before the Python wheel builds.

Regarding the secondary goal of wrapping the remaining integrals—do you have a strong architectural preference between using ctypes versus the Python/API for ensuring memory safety when passing the NumPy arrays to the C backend?

Looking forward to contributing!

I am waiting eagerly for your reply.
Thanks!

Regards,
Dhruv Chaudhary