Installing GauXC

Installing GauXC#

In this section, we will provide instructions on how to install GauXC with Skala support based on the conda-forge ecosystem. As part of this tutorial we will be

  • installing dependencies for building GauXC

  • configuring GauXC with different options

  • testing our the Skala implementation in GauXC

  • installing the GauXC library

  • reusing GauXC from the CMake build system

Prerequisites#

For this tutorial, we will use the mamba package manager for setting up the environment and installing dependencies. If you do not have mamba installed, you can download the miniforge installer.

First, we will create a new environment with all the required dependencies for building GauXC with Skala support. We provide three different configurations depending on whether you want to build GauXC with OpenMP, MPI, or CUDA support.

Note

A full list of dependencies can be found at GauXC dependencies in the CMake configuration documentation.

For this, create a file named environment.yml with the following content:

environment.yml#
name: gauxc-dev
channels:
  - conda-forge
dependencies:
  # build requirements
  - c-compiler
  - cxx-compiler
  - cmake >=3.15,<4
  - ninja
  - nlohmann_json >=3.9
   # host/runtime requirements
  - exchcxx >=1.0
  - gau2grid >=2.0.6
  - hdf5
  - libblas
  - pytorch >=2.0 cpu_*
environment.yml#
name: gauxc-dev
channels:
  - conda-forge
dependencies:
  # build requirements
  - c-compiler
  - cxx-compiler
  - cmake >=3.15,<4
  - ninja
  - nlohmann_json >=3.9
  # host/runtime requirements
  - openmpi  # pick mpich if that matches your stack
  - exchcxx >=1.0
  - gau2grid >=2.0.6
  - hdf5 * mpi_*
  - libblas
  - pytorch >=2.0 cpu_*
environment.yml#
name: gauxc-dev
channels:
  - conda-forge
dependencies:
  # build requirements
  - c-compiler
  - cxx-compiler
  - cuda-compiler
  - cmake >=3.15,<4
  - ninja
  - nlohmann_json >=3.9
  # host/runtime requirements
  - libxc >=7,<8
  - gau2grid >=2.0.6
  - hdf5
  - libblas
  - pytorch >=2.0 cuda*

Create and activate the environment:

mamba env create -n gauxc-dev -f environment.yml
mamba activate gauxc-dev

Verify that the toolchain is visible:

cmake --version
python -c "import torch; print(torch.__version__)"

Obtain GauXC with Skala#

Download the pre-packaged source bundle from the Skala release page:

curl -L https://github.com/microsoft/skala/releases/download/v1.1.1/gauxc-skala-r1.tar.gz | tar xzv

Tip

To verify the downloaded tarball you can obtain a checksum

curl -L https://github.com/microsoft/skala/releases/download/v1.1.1/gauxc-skala-r1.tar.gz > gauxc-skala-r1.tar.gz
curl -L https://github.com/microsoft/skala/releases/download/v1.1.1/gauxc-skala-r1.tar.gz.sha256 | sha256sum -c
tar xzvf gauxc-skala-r1.tar.gz

The archive expands into a gauxc directory that already contains the Skala patches.

Note

You can also obtain the latest version of GauXC with Skala support by downloading the skala branch of GauXC.

curl -L https://github.com/wavefunction91/GauXC/archive/refs/heads/skala.tar.gz | tar xzv

Configure and build#

Create an out-of-tree build directory and pick the configuration that matches your backend.

cmake -B build -S gauxc -G Ninja \
  -DGAUXC_ENABLE_OPENMP=on \
  -DGAUXC_ENABLE_MPI=off \
  -DGAUXC_ENABLE_CUDA=off \
  -DCMAKE_INSTALL_PREFIX=${CONDA_PREFIX}
cmake --build build

cmake -B build -S gauxc -G Ninja \
  -DGAUXC_ENABLE_OPENMP=on \
  -DGAUXC_ENABLE_MPI=on \
  -DGAUXC_ENABLE_CUDA=off \
  -DCMAKE_INSTALL_PREFIX=${CONDA_PREFIX}
cmake --build build

cmake -B build -S gauxc -G Ninja \
  -DGAUXC_ENABLE_OPENMP=on \
  -DGAUXC_ENABLE_MPI=off \
  -DGAUXC_ENABLE_CUDA=on \
  -DCMAKE_INSTALL_PREFIX=${CONDA_PREFIX}
cmake --build build

Note

To enable the C or Fortran bindings, set GAUXC_ENABLE_C or GAUXC_ENABLE_FORTRAN in your CMake configuration step. For a full list of available CMake options, see Available configurations for CMake build in the CMake configuration documentation.

Tip

If CMake cannot find libtorch, the Torch_DIR variable can be set to help discover the package. For conda-forge installed pytorch this should be set as -DTorch_DIR=${CONDA_PREFIX}/share/cmake/Torch and for pip installed pytorch the CMake config file will be in ${CONDA_PREFIX}/lib/python3.11/site-packages/torch/share/cmake/Torch where the Python version should be adjusted accordingly to the environment.

Quick verification#

After the build finishes, run the bundled regression test to confirm that Skala-enabled functionals are working correctly. The Skala implementation can run different traditional functionals, like PBE and TPSS, which can be compared against other libraries.

cd gauxc/tests/ref_data
../../../build/tests/standalone_driver onedft_input.inp

Expected output includes the total TPSS energy computed using a checkpoint compatible for the Skala implementation for the reference density matrix.

Tip

If the executable cannot locate libtorch or other shared libraries, double-check that LD_LIBRARY_PATH includes ${CONDA_PREFIX}/lib (activating the environment usually handles this).

Install the library#

Install into the active conda environment so downstream projects can pick up the CMake config files.

cmake --install build

This installs headers, libraries, and CMake config.

Note

For using GauXC in your own CMake project, check out Integrating GauXC into your build system in the CMake configuration documentation. Alternatively, you can follow the instructions in the GauXC in C++ tutorial for a full standalone example.

Troubleshooting#

Torch not found

ensure Torch_DIR points to the libtorch CMake package inside the active environment, or export Torch_DIR before running CMake.

CUDA mismatch

the CUDA toolkit selected by conda must match the version baked into the pytorch build; reinstall pytorch if necessary (e.g., pytorch ==2.3.* cuda118*).

Linker errors for BLAS/MPI

verify that the conda environment stayed active during the build and that cmake picked the toolchain from ${CONDA_PREFIX} via CMAKE_PREFIX_PATH.

Standalone driver cannot find densities

run it from gauxc/tests/ref_data since paths in density files are specified relative to the current directory.

Note

Need help? Open an issue on the Skala repository.

Contents