Add documentation to build GauXC

[awvwgk]

• add installation instructions for GauXC library
  • with OpenMP
  • with MPI
  • with CUDA
• list dependencies of GauXC (libtorch, ExchCXX, IntegratorXX, HDF5, HighFive, nlohmann_json, gau2grid, BLAS, ...)
• add instructions for obtaining checkpoints from Huggingface
• provide minimal example on how to use GauXC Skala library
• add instructions on using s-dftd3 library for evaluating dispersion correction for Skala

[kjh-giesbertz]

There seems to be something wrong in the cartesian version:

mol = gto.M(atom="He 0 0 0; Ne 0 0 2.0", basis="def2-qzvp", unit="Bohr", spin=0, cart=True)
gives
EXC (ref) = -1.35529407216016e+01
EXC (calc) = -1.33526784882510e+01
EXC Diff = -1.47762937552981e-02
| VXC (ref) |_F = 2.47705806355824e+01
| VXC (calc) |_F = 1.81479250598974e+01
RMS VXC Diff = 9.16350291581032e-02

mol = gto.M(atom="He 0 0 0; Ne 0 0 2.0", basis="def2-qzvp", unit="Bohr", spin=0, cart=False)
gives
EXC (ref) = -1.35529277410941e+01
EXC (calc) = -1.35529447345960e+01
EXC Diff = -1.25386206588653e-06
| VXC (ref) |_F = 1.65203073321537e+01
| VXC (calc) |_F = 1.65202505202321e+01
RMS VXC Diff = 1.28538169430761e-04

[kjh-giesbertz]

I have tried the use of cmake without installing gauxc first via the installation instructions and see how far cmake gets. I suppose this is how other programs aim to integrate skala via gauxc.

I encountered some problems:

1. (Mac specific) The standard apple compiler is a modified clang compiler where they explicitly switched off openmp support. There are different solutions for this specific case:
   • Switch the OpenMP to OFF in the CMakeLists.txt
   • Specify a different compiler via the CXX environment variable or overrule the C++ compiler while invoking cmake via -DCMAKE_CXX_COMPILER=
2. Torch could not be build
   I am still looking for a solution

[awvwgk]

1. (Mac specific) The standard apple compiler is a modified clang compiler where they explicitly switched off openmp support

This is a good point, I will add it to the troubleshooting

2. Torch could not be build

That's a required dependency for us and I see no realistic way to build libtorch reliably on a user machine. I will also add this into the troubleshooting to highlight that it is important to provide libtorch and that it cannot be built on the fly like other dependencies.

[tvogels]

This looks very nice / thorough and clear.

I was wondering what the best way to keep things like this in sync with the latest version:

set(Skala_GauXC_URL "https://github.com/microsoft/skala/releases/download/v1.1.0/gauxc-skala.tar.gz")
set(Skala_GauXC_SHA256 "e0346c62453eef58ba3ee52c257370ee8abcbf00fbb1b4ea2e0bb879225e06be")

Should we add something in the CI that alerts us when there is a mismatch?

And shall we also add an integration test for running this build once + testing it?

[awvwgk]

And shall we also add an integration test for running this build once + testing it?

I already added a new examples workflow which tests the GauXC example.

Should we add something in the CI that alerts us when there is a mismatch?

I updated the workflow to test both GauXC from the repo and from the release tarball (to check the path and checksum)

[awvwgk]

• add instructions on using s-dftd3 library for evaluating dispersion correction for Skala

I will need to iterate on this in a later PR, might also need some upstream changes since I mainly tested D3 from C and not C++. See dftd3/simple-dftd3#159

[kjh-giesbertz]

That's a required dependency for us and I see no realistic way to build libtorch reliably on a user machine. I will also add this into the troubleshooting to highlight that it is important to provide libtorch and that it cannot be built on the fly like other dependencies.

I dived a bit into this and have managed the following:

• co-pilot wrote a nice cmake snippet for me that actually downloads libtorch from pytorch taking into account some of the system specifics. It unpacks it and makes it available for the cmake build. At least it works for my mac now.
• Though GauXC is supposed to be able to handle the install nlohmann_json, it does fail in making the headers available, so I have actually installed it myself, like you also did in the conda environment. So I would remove the astrix in the GauXC dependencies

[awvwgk]

• Though GauXC is supposed to be able to handle the install nlohmann_json, it does fail in making the headers available, so I have actually installed it myself, like you also did in the conda environment. So I would remove the astrix in the GauXC dependencies

I changed the way we are fetching the header in wavefunction91/GauXC@ba001d4, will update our released tarball with the patch to make it more robust.

[awvwgk]

• co-pilot wrote a nice cmake snippet for me that actually downloads libtorch from pytorch taking into account some of the system specifics. It unpacks it and makes it available for the cmake build. At least it works for my mac now.

Maybe we can include this directly with our GauXC release, can you share the patch or directly make a PR against the skala branch in the GauXC repo (https://github.com/wavefunction91/GauXC/tree/skala)?

[Copilot]

Pull request overview

This pull request adds comprehensive documentation and examples for integrating the Skala machine learning functional into electronic structure packages via the GauXC library. The PR includes installation instructions for building GauXC with different parallelization backends (OpenMP, MPI, CUDA), Python utilities for exporting data to GauXC-compatible HDF5 format, and a complete C++ example demonstrating library integration.

Changes:

• Added Python export functionality to convert PySCF calculations to GauXC HDF5 format
• Created comprehensive documentation covering GauXC installation, configuration, and usage
• Provided C++ integration example with CMake build system
• Enhanced type flexibility for SkalaRKS/SkalaUKS to accept string XC functionals
• Added GitHub workflow for testing C++ examples

Reviewed changes

Copilot reviewed 27 out of 28 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
src/skala/pyscf/init.py	Updated type hints to allow string XC functionals
src/skala/gauxc/export.py	New module for exporting PySCF data to GauXC HDF5 format
tests/test_gauxc_export.py	Test coverage for HDF5 export functionality
examples/cpp/gauxc_integration/app/main.cxx	Complete C++ driver demonstrating GauXC integration
examples/cpp/gauxc_integration/cmake/*.cmake	CMake modules for dependency management
examples/cpp/gauxc_integration/environment-*.yml	Conda environment specifications for different backends
docs/gauxc/*.rst	Comprehensive documentation for installation and usage
docs/_static/bib/gauxc.bib	Bibliography for referenced papers
pyproject.toml	Added sphinx-design and sphinxcontrib-bibtex dependencies
environment-*.yml	Added h5py dependency to environment files
.github/workflows/examples.yml	CI workflow for testing C++ examples

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.