README.md
1
2
3[](https://opensource.org/licenses/NCSA)
4[](https://qmcpack.readthedocs.io/en/develop/?badge=develop)
5
6[](https://github.com/QMCPACK/qmcpack/releases)
7[](https://spack.readthedocs.io/en/latest/package_list.html#qmcpack)
8
9[](https://github.com/QMCPACK/qmcpack/actions/workflows/ci-github-actions.yaml)
10[](https://codecov.io/gh/QMCPACK/qmcpack)
11
12QMCPACK is an open-source production-level many-body ab initio Quantum Monte Carlo code for computing the electronic structure of
13atoms, molecules, 2D nanomaterials and solids. The solid-state capabilities include metallic systems as well as insulators.
14QMCPACK is expected to run well on workstations through to the latest generation supercomputers. Besides high performance,
15particular emphasis is placed on code quality and reproducibility.
16
17# Obtaining and installing QMCPACK
18
19 Obtain the latest release from https://github.com/QMCPACK/qmcpack/releases or clone the development source from
20 https://github.com/QMCPACK/qmcpack. A full installation guide and steps to perform an initial QMC calculation are given in the
21 [extensive online documentation for QMCPACK](https://qmcpack.readthedocs.io/en/develop/index.html).
22
23# Prerequisites
24
25 * C++ 14 and C99 capable compilers.
26 * CMake v3.10.0 or later, build utility, http://www.cmake.org
27 * BLAS/LAPACK, numerical library. Use platform-optimized libraries.
28 * LibXml2, XML parser, http://xmlsoft.org/
29 * HDF5, portable I/O library, http://www.hdfgroup.org/HDF5/
30 * BOOST v1.61.0 or newer, peer-reviewed portable C++ source libraries, http://www.boost.org
31 * FFTW, FFT library, http://www.fftw.org/
32 * MPI, parallel library. Optional, but a near requirement for production calculations.
33 * Python3. Older versions are not supported as of January 2020.
34
35We aim to support open source compilers and libraries released within two years of each QMCPACK release. Use of software versions
36over two years old may work but is discouraged and untested. Proprietary compilers (Intel, PGI) are generally supported over the
37same period but may require use of an exact version. We also aim to support the standard software environments on machines such as
38Summit at OLCF, Theta at ALCF, and Cori at NERSC. Use of the most recently released compilers and library versions is particularly
39encouraged for highest performance and easiest configuration.
40
41Nightly testing currently includes the following software versions on x86:
42
43* Compilers
44 * GCC 10.2.0, 8.3.0
45 * Clang/LLVM 11.0.1
46 * Intel 19.1.1.217 configured to use C++ library from GCC 8.3.0
47 * PGI/NVIDIA HPC SDK 20.9 configured to use C++ library from GCC 8.3.0
48* Boost 1.75.0, 1.68.0
49* HDF5 1.12.0, 1.8.19
50* FFTW 3.3.8, 3.3.4
51* CMake 3.19.5, 3.13.2
52* MPI
53 * OpenMPI 4.1.0, 3.1.6
54 * Intel MPI 19.1.1.217
55* CUDA 11.2.1
56
57Workflow tests are performed with Quantum Espresso v6.7.0 and PySCF v1.7.5. These check trial wavefunction generation and
58conversion through to actual QMC runs.
59
60On a developmental basis we also check the latest Clang and GCC development versions, AMD AOMP and Intel OneAPI compilers.
61
62# Building with CMake
63
64 The build system for QMCPACK is based on CMake. It will auto-configure based on the detected compilers and libraries. Previously
65 QMCPACK made extensive use of toolchains, but the system has since been updated to eliminate the use of toolchain files for most
66 cases. Specific compile options can be specified either through specific environment or CMake variables. When the libraries are
67 installed in standard locations, e.g., /usr, /usr/local, there is no need to set environment or CMake variables for the packages.
68
69 See the manual linked at https://qmcpack.readthedocs.io/en/develop/ and https://www.qmcpack.org/documentation or buildable using
70 sphinx from the sources in docs/. A PDF version is still available at https://qmcpack.readthedocs.io/_/downloads/en/develop/pdf/
71
72## Quick build
73
74 If you are feeling lucky and are on a standard UNIX-like system such
75 as a Linux workstation:
76
77 * Safest quick build option is to specify the C and C++ compilers
78 through their MPI wrappers. Here we use Intel MPI and Intel
79 compilers. Move to the build directory, run CMake and make
80```
81cd build
82cmake -DCMAKE_C_COMPILER=mpiicc -DCMAKE_CXX_COMPILER=mpiicpc ..
83make -j 8
84```
85
86 * Substitute mpicc and mpicxx or other wrapped compiler names to suit
87 your system. e.g. With OpenMPI use
88```
89cd build
90cmake -DCMAKE_C_COMPILER=mpicc -DCMAKE_CXX_COMPILER=mpicxx ..
91make -j 8
92```
93
94* If you are feeling particularly lucky, you can skip the compiler
95 specification:
96```
97cd build
98cmake ..
99make -j 8
100```
101
102 The complexities of modern computer hardware and software systems are
103 such that you should check that the auto-configuration system has made
104 good choices and picked optimized libraries and compiler settings
105 before doing significant production. i.e. Check the details below.
106
107## Set the environment
108
109 A number of environment variables affect the build. In particular,
110 they can control the default paths for libraries, the default
111 compilers, etc. The list of environment variables is given below:
112
113| Environment variable | Description |
114|----------------------|-------------|
115| CXX | C++ compiler |
116| CC | C Compiler |
117| MKL_ROOT | Path for MKL |
118| HDF5_ROOT | Path for HDF5 |
119| BOOST_ROOT | Path for Boost |
120| FFTW_HOME | Path for FFTW |
121
122## CMake options
123
124 In addition to reading the environment variables, CMake provides a
125 number of optional variables that can be set to control the build and
126 configure steps. When passed to CMake, these variables will take
127 precedent over the environment and default variables. To set them
128 add -D FLAG=VALUE to the configure line between the CMake command and
129 the path to the source directory.
130
131 * General build options
132
133```
134 CMAKE_C_COMPILER Set the C compiler
135 CMAKE_CXX_COMPILER Set the C++ compiler
136 CMAKE_BUILD_TYPE A variable which controls the type of build (defaults to Release).
137 Possible values are:
138 None (Do not set debug/optmize flags, use CMAKE_C_FLAGS or CMAKE_CXX_FLAGS)
139 Debug (create a debug build)
140 Release (create a release/optimized build)
141 RelWithDebInfo (create a release/optimized build with debug info)
142 MinSizeRel (create an executable optimized for size)
143 CMAKE_SYSTEM_NAME Set value to CrayLinuxEnvironment when cross-compiling
144 in Cray Programming Environment.
145 CMAKE_C_FLAGS Set the C flags. Note: to prevent default debug/release flags
146 from being used, set the CMAKE_BUILD_TYPE=None
147 Also supported: CMAKE_C_FLAGS_DEBUG, CMAKE_C_FLAGS_RELEASE,
148 CMAKE_C_FLAGS_RELWITHDEBINFO
149 CMAKE_CXX_FLAGS Set the C++ flags. Note: to prevent default debug/release flags
150 from being used, set the CMAKE_BUILD_TYPE=None
151 Also supported: CMAKE_CXX_FLAGS_DEBUG, CMAKE_CXX_FLAGS_RELEASE,
152 CMAKE_CXX_FLAGS_RELWITHDEBINFO
153```
154
155 * Key QMC build options
156
157```
158 QMC_CUDA Enable legacy CUDA code path for NVIDIA GPU acceleration (1:yes, 0:no)
159 QMC_COMPLEX Build the complex (general twist/k-point) version (1:yes, 0:no)
160 QMC_MIXED_PRECISION Build the mixed precision (mixing double/float) version
161 (1:yes (GPU default), 0:no (CPU default)).
162 The CPU support is experimental.
163 Use float and double for base and full precision.
164 The GPU support is quite mature.
165 Use always double for host side base and full precision
166 and use float and double for CUDA base and full precision.
167 ENABLE_CUDA ON/OFF(default). Enable CUDA code path for NVIDIA GPU acceleration.
168 Production quality for AFQMC. Pre-production quality for real-space.
169 Use CUDA_ARCH, default sm_70, to set the actual GPU architecture.
170 ENABLE_OFFLOAD ON/OFF(default). Experimental feature. Enable OpenMP target offload for GPU acceleration.
171 ENABLE_TIMERS ON(default)/OFF. Enable fine-grained timers. Timers are on by default but at level coarse
172 to avoid potential slowdown in tiny systems.
173 For systems beyond tiny sizes (100+ electrons) there is no risk.
174```
175
176 * Additional QMC options
177
178```
179 QE_BIN Location of Quantum Espresso binaries including pw2qmcpack.x
180 QMC_DATA Specify data directory for QMCPACK performance and integration tests
181 QMC_INCLUDE Add extra include paths
182 QMC_EXTRA_LIBS Add extra link libraries
183 QMC_BUILD_STATIC ON/OFF(default). Add -static flags to build
184 QMC_SYMLINK_TEST_FILES Set to zero to require test files to be copied. Avoids space
185 saving default use of symbolic links for test files. Useful
186 if the build is on a separate filesystem from the source, as
187 required on some HPC systems.
188 QMC_VERBOSE_CONFIGURATION Print additional information during cmake configuration
189 including details of which tests are enabled.
190```
191
192 * libxml2 related
193
194```
195 LIBXML2_INCLUDE_DIR Include directory for libxml2
196 LIBXML2_LIBRARY Libxml2 library
197```
198
199* HDF5 related
200```
201 HDF5_PREFER_PARALLEL 1(default for MPI build)/0, enables/disable parallel HDF5 library searching.
202 ENABLE_PHDF5 1(default for parallel HDF5 library)/0, enables/disable parallel collective I/O.
203
204```
205
206 * FFTW related
207```
208 FFTW_INCLUDE_DIRS Specify include directories for FFTW
209 FFTW_LIBRARY_DIRS Specify library directories for FFTW
210```
211
212## Example configure and build
213
214In the build directory, run cmake with appropriate options, then
215make.
216
217* Using Intel compilers and their MPI wrappers. Assumes HDF5 and
218libxml2 will be automatically detected.
219
220```
221cd build
222cmake -DCMAKE_C_COMPILER=mpiicc -DCMAKE_CXX_COMPILER=mpiicpc ..
223make -j 8
224```
225
226## Special notes
227
228It is recommended to create a helper script that contains the
229configure line for CMake. This is particularly useful when using
230environment variables, packages are installed in custom locations,
231or the configure line may be long or complex. In this case it is
232recommended to add "rm -rf CMake*" before the configure line to remove
233existing CMake configure files to ensure a fresh configure each time
234that the script is called. and example script build.sh is given
235below:
236```
237export CXX=mpic++
238export CC=mpicc
239export ACML_HOME=/opt/acml-5.3.1/gfortran64
240export HDF5_ROOT=/opt/hdf5
241export BOOST_ROOT=/opt/boost
242
243rm -rf CMake*
244
245cmake \
246 -D CMAKE_BUILD_TYPE=Debug \
247 -D LIBXML2_INCLUDE_DIR=/usr/include/libxml2 \
248 -D LIBXML2_LIBRARY=/usr/lib/x86_64-linux-gnu/libxml2.so \
249 -D FFTW_INCLUDE_DIRS=/usr/include \
250 -D FFTW_LIBRARY_DIRS=/usr/lib/x86_64-linux-gnu \
251 -D QMC_EXTRA_LIBS="-ldl ${ACML_HOME}/lib/libacml.a -lgfortran" \
252 -D QMC_DATA=/projects/QMCPACK/qmc-data \
253 ..
254```
255
256## Additional examples:
257
258Set compile flags manually:
259```
260 cmake \
261 -D CMAKE_BUILD_TYPE=None \
262 -D CMAKE_C_COMPILER=mpicc \
263 -D CMAKE_CXX_COMPILER=mpic++ \
264 -D CMAKE_C_FLAGS=" -O3 -fopenmp -malign-double -fomit-frame-pointer -finline-limit=1000 -fstrict-aliasing -funroll-all-loops -Wno-deprecated -march=native -mtune=native" \
265 -D CMAKE_CXX_FLAGS="-O3 -fopenmp -malign-double -fomit-frame-pointer -finline-limit=1000 -fstrict-aliasing -funroll-all-loops -Wno-deprecated -march=native -mtune=native" \
266 ..
267```
268
269Add extra include directories:
270```
271 cmake \
272 -D CMAKE_BUILD_TYPE=Release \
273 -D CMAKE_C_COMPILER=mpicc \
274 -D CMAKE_CXX_COMPILER=mpic++ \
275 -D QMC_INCLUDE="~/path1;~/path2" \
276 ..
277```
278
279# Testing and validation of QMCPACK
280
281We highly encourage tests to be run before using QMCPACK. Details are given in the [QMCPACK
282manual](https://qmcpack.readthedocs.io/en/develop/index.html). QMCPACK includes extensive validation tests to ensure the
283correctness of the code, compilers, tools, and runtime. The tests should ideally be run each compilation, and certainly before any
284research use. The tests include checks of the output against known mean-field, quantum chemistry, and other QMC results.
285
286While some tests are fully deterministic, due to QMCPACK's stochastic nature some tests are statistical and can occasionally fail.
287We employ a range of test names and labeling to differentiate between these, as well as developmental tests that are known to
288fail. In particular, "deterministic" tests include this in their ctest test name, while tests known to be unstable (stochastically
289or otherwise) are labeled unstable using ctest labels.
290
291The tests currently use up to 16 cores in various combinations of MPI tasks and OpenMP threads. Current status for many
292combinations of systems, compilers, and libraries can be checked at https://cdash.qmcpack.org
293
294Note that due to the small electron and walker counts used in the tests, they should not be used for any performance measurements.
295These should be made on problem sizes that are representative of actual research calculations. As described in the manual,
296performance tests are provided to aid in monitoring performance.
297
298## Run the unit tests
299
300From the build directory, invoke ctest specifying only the unit tests
301```
302ctest -R unit
303```
304All of these tests should pass.
305
306## Run the deterministic tests
307
308From the build directory, invoke ctest specifying only tests
309that are deterministic and known to be reliable.
310```
311ctest -R deterministic -LE unstable
312```
313
314These tests currently take a few seconds to run, and include all the unit tests. All tests should pass. Failing tests likely
315indicate a significant problem that should be solved before using QMCPACK further. This ctest invocation can be used as part of an
316automated installation verification process.
317
318## Run the short (quick) tests
319
320 From the build directory, invoke ctest specifying only tests
321 including "short" to run that are known to be stable.
322```
323ctest -R short -LE unstable
324```
325
326 These tests currently take up to around one hour. On average, all
327 tests should pass at a three sigma level of reliability. Any
328 initially failing test should pass when rerun.
329
330## Run individual tests
331
332Individual tests can be run by specifying their name
333```
334ctest -R name-of-test-to-run
335```
336
337# Documentation and support
338
339For more information, consult QMCPACK pages at http://www.qmcpack.org, the manual at
340https://qmcpack.readthedocs.io/en/develop/index.html, or its sources in the docs directory.
341
342If you have trouble using or building QMCPACK, or have questions about its use, please post to the [Google QMCPACK
343group](https://groups.google.com/forum/#!forum/qmcpack), create a GitHub issue at https://github.com/QMCPACK/qmcpack/issues or
344contact a developer.
345
346# Contributing
347
348Contributions of any size are very welcome. Guidance for contributing to QMCPACK is included in Chapter 1 of the manual
349https://qmcpack.readthedocs.io/en/develop/introduction.html#contributing-to-qmcpack. We use a git flow model including pull
350request reviews. A continuous integration system runs on pull requests. See https://github.com/QMCPACK/qmcpack/wiki for details.
351For an extensive contribution, it can be helpful to discuss on the [Google QMCPACK
352group](https://groups.google.com/forum/#!forum/qmcpack), to create a GitHub issue, or to talk directly with a developer in
353advance.
354
355Contributions are made under the same UIUC/NCSA open source license that covers QMCPACK. Please contact us if this is problematic.
356
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}