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)?