The domain of quantum chemistry needs a library in which the main kernels of Quantum Monte Carlo (QMC) methods are implemented. In the library proposed in this project, we expose the main algorithms in a simple language and provide a standard API and tests to enable the development of high-performance QMCkl implementations taking advantage of modern hardware.

See the source code to read the documentation.

To clone the repository, use:

git clone https://github.com/TREX-CoE/qmckl.git

Note for Users: The simplest way to obtain QMCkl is to download a source distribution package. This repository is primarily for maintainers who write the kernels in org-mode files and generate the source code and documentation from these files.

About Org-mode: Org-mode is a plain-text format, editable in any text editor—including VS Code (which offers excellent support) or Vim (via plugins). Emacs is used here not as a text editor but as a command-line tool to generate code from Org-mode files, much like cmake or autoconf. Contributors need not master Emacs; they can edit Org-mode files in their preferred environment, and our Makefile automates the rest.

Before building QMCkl, you should install the following dependencies:

TREXIO (TREX I/O) is a library for reading and writing wave function data files. While TREXIO is enabled by default and highly encouraged, it can be disabled during configuration with ./configure --without-trexio if needed.

• Repository: https://github.com/TREX-CoE/trexio

• Releases: https://github.com/TREX-CoE/trexio/releases

• Installation (from latest release):

  # Download the latest tar.gz from the releases page, then:
  tar -xzf trexio-*.tar.gz
  cd trexio-*
  ./configure --prefix=/path/to/install
  make
  make check
  sudo make install

• Setting PKG_CONFIG_PATH: If you installed TREXIO in a non-standard location (i.e., not /usr or /usr/local), you need to set the PKG_CONFIG_PATH environment variable:

  export PKG_CONFIG_PATH=/path/to/install/lib/pkgconfig:$PKG_CONFIG_PATH

  Alternatively, you can specify the TREXIO location during configuration:

  ./configure --with-trexio=/path/to/install

  Or set the environment variables directly:

  export TREXIO_CFLAGS="-I/path/to/install/include"
  export TREXIO_LIBS="-L/path/to/install/lib -ltrexio"

BLAS (Basic Linear Algebra Subprograms) and LAPACK (Linear Algebra PACKage) are required for linear algebra operations.

Performance Note: Generic BLAS implementations will result in low performance. Vendor-specific BLAS libraries such as Intel MKL or ARM Performance Libraries (ARMPL) are highly recommended for optimal performance.

• Installation on Ubuntu/Debian:

  sudo apt-get install libblas-dev liblapack-dev

• Installation on RHEL/CentOS/Fedora:

  sudo yum install blas-devel lapack-devel

• Recommended: Intel MKL (Math Kernel Library) or ARM Performance Libraries provide optimized BLAS/LAPACK. When using Intel compilers with --with-icc or --with-ifort, MKL is automatically used.

HDF5 is an optional dependency of TREXIO for data storage, but it is highly recommended and enabled by default in TREXIO's configuration.

• Installation on Ubuntu/Debian:

  sudo apt-get install libhdf5-dev

• Installation on RHEL/CentOS/Fedora:

  sudo yum install hdf5-devel

• Autotools: autoconf, automake, libtool

• C Compiler: GCC or Intel ICC

• Fortran Compiler: gfortran or Intel ifort/ifx

• pkg-config (optional): Helps find library dependencies

• Installation on Ubuntu/Debian:

  sudo apt-get install build-essential autoconf automake libtool pkg-config gfortran

• Installation on RHEL/CentOS/Fedora:

  sudo yum install gcc gcc-gfortran autoconf automake libtool pkgconfig

If you are working with the org-mode source files (maintainer mode):

• Emacs (>= 26): For tangling org-mode files

  sudo apt-get install emacs  # Ubuntu/Debian
  sudo yum install emacs      # RHEL/CentOS/Fedora

• Python 3: For build scripts

• AWK: Usually pre-installed

• SWIG (>= 4.0, optional): For generating Python bindings

  sudo apt-get install swig   # Ubuntu/Debian
  sudo yum install swig       # RHEL/CentOS/Fedora

Prerequisites: Ensure all required dependencies are installed first.

1. Download a source distribution:

   • Get the latest release from: https://github.com/TREX-CoE/qmckl/releases

   tar -xzf qmckl-*.tar.gz
   cd qmckl-*

2. Configure the build:

   ./configure

   If TREXIO or other dependencies are in non-standard locations:

   export PKG_CONFIG_PATH=/path/to/trexio/lib/pkgconfig:$PKG_CONFIG_PATH
   ./configure

3. Build and test:

   make -j
   make -j check

4. Install:

   sudo make install
   sudo make installcheck

Out-of-source builds keep your source directory clean and allow multiple configurations simultaneously:

mkdir _build
cd _build
../configure --prefix=$PWD/_install
make -j
make -j check
make install

For development and debugging:

./configure --enable-debug --prefix=/path/to/install
make -j
make -j check

For high-performance builds with GCC:

./configure \
  CC=gcc \
  CFLAGS="-g -O2 -march=native -flto -fno-trapping-math -fno-math-errno -ftree-vectorize" \
  FC=gfortran \
  FCFLAGS="-g -O2 -march=native -flto -ftree-vectorize" \
  --enable-hpc
make -j
make -j check

For high-performance builds with Intel compilers (which include MKL for BLAS/LAPACK):

./configure \
  --with-icc \
  --with-ifort \
  --enable-hpc \
  --prefix=/path/to/install
make -j
make -j check

Alternatively, with newer Intel compilers:

./configure \
  --with-icx \
  --with-ifx \
  --enable-hpc \
  --prefix=/path/to/install
make -j
make -j check

If you are working with the org-mode source files (when .maintainer_mode file exists):

Additional Prerequisites: Emacs (>= 26), Python 3, AWK

./autogen.sh
./configure --prefix=$PWD/_install
make
make check

You can create different build configurations simultaneously:

./autogen.sh

# Debug build with GCC
mkdir -p _build_gcc_debug/_install
cd _build_gcc_debug
../configure --enable-debug --prefix=$PWD/_install
make -j
make -j check
cd ..

# Optimized build with Intel compilers
mkdir -p _build_intel_fast/_install
cd _build_intel_fast
../configure --prefix=$PWD/_install --enable-hpc --with-icc --with-ifort 
make -j
make -j check
cd ..

The Python API allows you to use QMCkl from Python.

• SWIG (>= 4.0) is required
• QMCkl shared library must be installed first

1. Install the QMCkl C library following the instructions above

2. Install the Python package:

   make python-install

3. Test the installation:

   make python-test

See test_api.py for examples of using the Python API.

Recommendation: Use virtual environments to avoid compatibility issues:

python3 -m venv qmckl_env
source qmckl_env/bin/activate
make python-install
make python-test

After installation, link your program against QMCkl by adding -lqmckl to your compiler options.

If QMCkl was installed with a custom prefix, update your library and include search paths:

export LIBRARY_PATH=$LIBRARY_PATH:/path/to/qmckl/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/qmckl/lib
export CPATH=$CPATH:/path/to/qmckl/include

If your project uses CMake, you can use the provided FindQMCKL.cmake module to automatically find and link QMCkl:

list(APPEND CMAKE_MODULE_PATH "/path/to/qmckl/cmake")
find_package(QMCKL REQUIRED)
target_link_libraries(your_target QMCKL::qmckl)

QMCkl can be installed using the GNU Guix package manager.

The qmckl.scm file contains the package definition:

guix package \
  --profile=$GUIX_PROFILE \
  --load-path=<path_to_trexio_scm> \
  --cores=<n_cores> \
  --install-from-file=qmckl.scm

Where <path_to_trexio_scm> should point to the directory containing TREXIO's trexio.scm file (e.g., ~/trexio/tools/).

You can choose between development (qmckl-dev) and stable (qmckl-hpc) versions by modifying the return value in qmckl.scm.

Error message:

configure: error: Package requirements (trexio) were not met:
Package 'trexio', required by 'virtual:world', not found

Solution:

1. Ensure TREXIO is installed (see TREXIO installation)
2. If installed in a non-standard location, set PKG_CONFIG_PATH:

   export PKG_CONFIG_PATH=/path/to/trexio/lib/pkgconfig:$PKG_CONFIG_PATH

3. Or use --with-trexio:

   ./configure --with-trexio=/path/to/trexio

Error message:

configure: error: BLAS was not found.
configure: error: LAPACK was not found.

Solution: Install BLAS and LAPACK development packages:

• Ubuntu/Debian: sudo apt-get install libblas-dev liblapack-dev
• RHEL/CentOS: sudo yum install blas-devel lapack-devel

Error message:

Error: Emacs is required for org-mode.

Solution:

• If you're a user (not a maintainer), download a source distribution instead of cloning the repository
• If you're a maintainer, install Emacs: sudo apt-get install emacs or sudo yum install emacs

Solution: Install HDF5 development package:

• Ubuntu/Debian: sudo apt-get install libhdf5-dev
• RHEL/CentOS: sudo yum install hdf5-devel

• Documentation: https://trex-coe.github.io/qmckl/index.html
• Issues: https://github.com/TREX-CoE/qmckl/issues
• TREX Project: https://trex-coe.eu

Verificarlo is a tool for numerical verification. QMCkl can be built with Verificarlo support, but it is not a required dependency.

All Verificarlo functions are only called when explicitly enabled and are ignored otherwise.

To enable Verificarlo support:

./configure \
  CC="verificarlo-f" \
  FC="verificarlo-f" \
  --prefix=$PWD/_install \
  --enable-vfc_ci \
  --host=x86_64
make -j
make -j check

Building without the --enable-vfc_ci flag will ignore all Verificarlo-related code.

Run ./configure --help to see all available options. Common options include:

• --prefix=/path/to/install - Installation directory
• --enable-hpc - Enable HPC-optimized functions
• --enable-debug - Build with debugging symbols and checks
• --with-icc - Use Intel icc C compiler
• --with-ifort - Use Intel ifort Fortran compiler
• --with-icx - Use Intel icx C compiler (newer)
• --with-ifx - Use Intel ifx Fortran compiler (newer)
• --with-trexio=/path - Specify TREXIO installation directory
• --without-trexio - Build without TREXIO support (not recommended)
• --with-qmckldgemm=/path - Use custom QMCKL DGEMM library
• --without-openmp - Disable OpenMP support
• --enable-python - Enable Python API build
• --enable-vfc_ci - Enable Verificarlo support
• --enable-malloc-trace - Enable malloc/free debugging
• --enable-prof - Enable profiling
• --with-efence - Use ElectricFence library for memory debugging

QMCkl has been tested on:

• CPUs: x86 and ARM CPUs
• Operating Systems: Ubuntu, Debian, RHEL, CentOS, Fedora, macOS (with Homebrew or MacPorts)
• Compilers: GCC, Intel ICC/ICX, Intel ifort/ifx

QMCkl is licensed under the BSD 3-Clause License. See the LICENSE file for details.

Copyright (c) 2020, TREX Center of Excellence

If you use QMCkl in your research, please cite:

arXiv:2512.16677v1

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes (in org-mode files if you're modifying code)
4. Run tests with make check
5. Submit a pull request

For major changes, please open an issue first to discuss the proposed changes.

TREX: Targeting Real Chemical Accuracy at the Exascale project has received funding from the European Union's Horizon 2020 - Research and Innovation program - under grant agreement no. 952165. The content of this document does not represent the opinion of the European Union, and the European Union is not responsible for any use that might be made of such content.