QMCPACK Logo

QMCPACK is an open-source production-level many-body ab initio Quantum Monte Carlo code for computing the electronic structure of atoms, molecules, 2D nanomaterials and solids. The solid-state capabilities include metallic systems as well as insulators. QMCPACK is expected to run well on workstations through to the latest generation supercomputers. Besides high performance, particular emphasis is placed on code quality and reproducibility.

Obtaining and installing QMCPACK

Obtain the latest release from https://github.com/QMCPACK/qmcpack/releases or clone the development source from https://github.com/QMCPACK/qmcpack. A full installation guide and steps to perform an initial QMC calculation are given in the extensive online documentation for QMCPACK.

The CHANGELOG.md describes key changes made in each release as well as any major changes to the development version.

Documentation and support

For more information, consult QMCPACK pages at http://www.qmcpack.org, the manual at https://qmcpack.readthedocs.io/en/develop/index.html, or its sources in the docs directory.

If you have trouble using or building QMCPACK, or have questions about its use, please post to the Google QMCPACK group, create a GitHub issue at https://github.com/QMCPACK/qmcpack/issues or contact a developer.

Learning about Quantum Monte Carlo

To learn about the fundamentals of Quantum Monte Carlo through to their practical application to molecular and solid-state systems with QMCPACK, see the materials and tutorials from our most recent QMC workshop. These include a virtual machine to run examples without having to install QMCPACK yourself, and slides and recorded videos of introductory talks through to spin-orbit QMC.

Citing QMCPACK

Please cite J. Kim et al. J. Phys. Cond. Mat. 30 195901 (2018), https://doi.org/10.1088/1361-648X/aab9c3, and if space allows, P. Kent et al. J. Chem. Phys. 152 174105 (2020), https://doi.org/10.1063/5.0004860 . These papers are both open access.

Installing QMCPACK

Complete instructions for downloading, compiling, and installing QMCPACK are given in the manual. Guides are provided for installing QMCPACK on common workstations and supercomputers. We also provide build scripts are for many systems in the config directory. The following sections of this README give a brief overview.

Installation Prerequisites

Full list of prerequisites and details of regularly tested versions are given in the manual section on installation prerequisites.

We aim to support open source compilers and libraries released within two years of each QMCPACK release. Use of software versions over two years old may work but is discouraged and untested. Proprietary compilers (Intel, NVHPC) are generally supported over the same period but may require use of an exact version. We also aim to support the standard software environments on machines such as Frontier and Summit at OLCF, Aurora and Polaris at ALCF, and Perlmutter at NERSC. Use of the most recently released compilers and library versions is particularly encouraged for highest performance and easiest configuration.

Building with CMake

The build system for QMCPACK is based on CMake. It will auto-configure based on the detected compilers and libraries. When these are installed in standard locations, e.g., /usr, /usr/local, there is no need to set either environment or CMake variables.

See the manual linked at https://qmcpack.readthedocs.io/en/develop/ and https://www.qmcpack.org/documentation or buildable using sphinx from the sources in docs/. A PDF version is still available at https://qmcpack.readthedocs.io/_/downloads/en/develop/pdf/

Quick build

On a standard UNIX-like system such as a Linux workstation:

Safest quick build option is to specify the C and C++ compilers through their MPI wrappers. Here we use Intel MPI and Intel compilers. Move to the build directory, run CMake and make

cd build
cmake -DCMAKE_C_COMPILER=mpiicc -DCMAKE_CXX_COMPILER=mpiicpc ..
make -j 8

Substitute mpicc and mpicxx or other wrapped compiler names to suit your system. e.g. With OpenMPI use

cd build
cmake -DCMAKE_C_COMPILER=mpicc -DCMAKE_CXX_COMPILER=mpicxx ..
make -j 8

Non-MPI build:

cd build
cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DQMC_MPI=0 ..
make -j 8

If you are feeling particularly lucky, you can skip the compiler specification:

cd build
cmake ..
make -j 8

The complexities of modern computer hardware and software systems are such that you should check that the auto-configuration system has made good choices and picked optimized libraries and compiler settings before doing significant production. i.e. Check the details below.

Set the environment

A number of environment variables affect the build. In particular, they can control the default paths for libraries, the default compilers, etc. The list of environment variables is given below:

| Environment variable | Description | |----------------------|-------------| | CXX | C++ compiler | | CC | C Compiler | | MKL_ROOT | Path for MKL | | HDF5_ROOT | Path for HDF5 | | BOOST_ROOT | Path for Boost | | FFTW_HOME | Path for FFTW |

CMake options

In addition to reading the environment variables, CMake provides a number of optional variables that can be set to control the build and configure steps. When passed to CMake, these variables will take precedent over the environment and default variables. To set them add -D FLAG=VALUE to the configure line between the CMake command and the path to the source directory.

General build options

    CMAKE_C_COMPILER    Set the C compiler
    CMAKE_CXX_COMPILER  Set the C++ compiler
    CMAKE_BUILD_TYPE    A variable which controls the type of build (defaults to Release).
                        Possible values are:
                        None (Do not set debug/optmize flags, use CMAKE_C_FLAGS or CMAKE_CXX_FLAGS)
                        Debug (create a debug build)
                        Release (create a release/optimized build)
                        RelWithDebInfo (create a release/optimized build with debug info)
                        MinSizeRel (create an executable optimized for size)
    CMAKE_SYSTEM_NAME   Set value to CrayLinuxEnvironment when cross-compiling
                        in Cray Programming Environment.
    CMAKE_C_FLAGS       Set the C flags.  Note: to prevent default debug/release flags
                        from being used, set the CMAKE_BUILD_TYPE=None
                        Also supported: CMAKE_C_FLAGS_DEBUG, CMAKE_C_FLAGS_RELEASE,
                                        CMAKE_C_FLAGS_RELWITHDEBINFO
    CMAKE_CXX_FLAGS     Set the C++ flags.  Note: to prevent default debug/release flags
                        from being used, set the CMAKE_BUILD_TYPE=None
                        Also supported: CMAKE_CXX_FLAGS_DEBUG, CMAKE_CXX_FLAGS_RELEASE,
                                        CMAKE_CXX_FLAGS_RELWITHDEBINFO

Key QMCPACK build options

    QMC_COMPLEX           ON/OFF(default). Build the complex (general twist/k-point) version.
    QMC_MIXED_PRECISION   ON/OFF(default). Build the mixed precision (mixing double/float) version
                          Mixed precision calculations can be signifiantly faster but should be
                          carefully checked validated against full double precision runs,
                          particularly for large electron counts.
    QMC_GPU               Semicolon-separated list of GPU features to build (openmp,cuda,hip,sycl).
                          "openmp", "cuda", "hip" and "sycl" for GPU acceleration via OpenMP offload, CUDA, HIP and SYCL.
                          Recommended values: "openmp;cuda" for NVIDIA, "openmp;hip" for AMD, "openmp;sycl" for Intel.
                          Its default value is set to the recommended value if QMC_GPU_ARCHS indicates a specific vendor
                          or left empty otherwise.
    QMC_GPU_ARCHS         Specify GPU architectures. For example, "gfx90a" targets AMD MI200 series GPUs.
                          "intel_gpu_pvc" targets Intel Data Center GPU Max 1xxx.
                          "sm_80;sm_70" creates a single executable running on both NVIDIA A100 and V100 GPUs.
                          Mixing vendor "gfx90a;sm_70" is not supported. If not set, atempt to derive it
                          from CMAKE_CUDA_ARCHITECTURES or CMAKE_HIP_ARCHITECTURES if available and then
                          atempt to auto-detect existing GPUs.

Additional QMCPAC

Qmcpack

Install / Use

README