Running QMCPACK¶

QMCPACK requires at least one xml input file, and is invoked via:

qmcpack [command line options] <XML input file(s)>

Command line options¶

QMCPACK offers several command line options that affect how calculations are performed. If the flag is absent, then the corresponding option is disabled:

• --dryrun Validate the input file without performing the simulation. This is a good way to ensure that QMCPACK will do what you think it will.

• --enable-timers=none|coarse|medium|fine Control the timer granularity when the build option ENABLE_TIMERS is enabled.

• help Print version information as well as a list of optional command-line arguments.

• noprint Do not print extra information on Jastrow or pseudopotential. If this flag is not present, QMCPACK will create several .dat files that contain information about pseudopotentials (one file per PP) and Jastrow factors (one per Jastrow factor). These file might be useful for visual inspection of the Jastrow, for example.

• --verbosity=low|high|debug Control the output verbosity. The default low verbosity is concise and, for example, does not include all electron or atomic positions for large systems to reduce output size. Use “high” to see this information and more details of initialization, allocations, QMC method settings, etc.

• version Print version information and optional arguments. Same as help.

Input files¶

The input is one or more XML file(s), documented in Input file overview.

Output files¶

QMCPACK generates multiple files documented in Output Overview.

Stopping a running simulation¶

As detailed in Input file overview, QMCPACK will cleanly stop execution at the end of the current block if it finds a file named project_id.STOP, where project_id is the name of the project given in the input XML. You can also set the max_seconds parameter to establish an overall time limit.

Using mixed precision¶

To achieve better performance or reduce memory footprint, mixed-precision version can be enabled. The current implementation uses single precision (SP) on most calculations, except for matrix inversions and reductions where double precision (DP) is required to retain high accuracy. All the constant spline data in wavefunction, pseudopotentials, and Coulomb potentials are initialized in double precision and later stored in SP. The mixed-precision code is as accurate as the fully double precision code up to a certain system size, and may have double the throughput. Cross checking and verification of accuracy is always required but is particularly important above approximately 1,500 electrons.

Running in parallel with MPI¶

QMCPACK is fully parallelized with MPI. When performing an ensemble job, all the MPI ranks are first equally divided into groups that perform individual QMC calculations. Within one calculation, all the walkers are fully distributed across all the MPI ranks in the group. Since MPI requires distributed memory, there must be at least one MPI per node. To maximize the efficiency, more facts should be taken into account. When using MPI+threads on compute nodes with more than one NUMA domain (e.g., AMD Interlagos CPU on Titan or a node with multiple CPU sockets), it is recommended to place as many MPI ranks as the number of NUMA domains if the memory is sufficient (e.g., one MPI task per socket). On clusters with more than one GPU per node (NVIDIA Tesla K80), it is necessary to use the same number of MPI ranks as the number of GPUs per node to let each MPI rank take one GPU.

Modern processors integrate multiple identical cores even with hardware threads on a single die to increase the total performance and maintain a reasonable power draw. QMCPACK takes advantage of this compute capability by using threads and the OpenMP programming model as well as threaded linear algebra libraries. By default, QMCPACK is always built with OpenMP enabled. When launching calculations, users should instruct QMCPACK to create the right number of threads per MPI rank by specifying environment variable OMP_NUM_THREADS. Assuming one MPI rank per socket, the number of threads should typically be the number of cores on that socket. Even in the GPU-accelerated version, using threads significantly reduces the time spent on the calculations performed by the CPU.

Nested threading is an advanced feature requiring experienced users to finely tune runtime parameters to reach the best performance.

For small-to-medium problem sizes, using one thread per walker or for multiple walkers is most efficient. This is the default in QMCPACK and achieves the shortest time to solution.

For large problems of at least 1,000 electrons, use of nested OpenMP threading can be enabled to reduce the time to solution further, although at some loss of efficiency. In this scheme multiple threads are used in the computations of each walker. This capability is implemented for some of the key computational kernels: the 3D spline orbital evaluation, certain portions of the distance tables, and implicitly the BLAS calls in the determinant update. Use of the batched nonlocal pseudopotential evaluation is also recommended.

Nested threading is enabled by setting OMP_NUM_THREADS=AA,BB, OMP_MAX_ACTIVE_LEVELS=2 and OMP_NESTED=TRUE where the additional BB is the number of second-level threads. Choosing the thread affinity is critical to the performance. QMCPACK provides a tool qmc-check-affinity (source file src/QMCTools/check-affinity.cpp for details), which might help users investigate the affinity. Knowledge of how the operating system logical CPU cores (/prco/cpuinfo) are bound to the hardware is also needed.

For example, on Blue Gene/Q with a Clang compiler, the best way to fully use the 16 cores each with 4 hardware threads is

OMP_NESTED=TRUE
MAX_ACTIVE_LEVELS=2


On Intel Xeon Phi KNL with an Intel compiler, to use 64 cores without using hardware threads:

OMP_NESTED=TRUE
OMP_WAIT_POLICY=ACTIVE
MAX_ACTIVE_LEVELS=2
OMP_PLACES=cores
KMP_HOT_TEAMS_MODE=1
KMP_HOT_TEAMS_MAX_LEVEL=2


Performance considerations¶

As walkers are the basic units of workload in QMC algorithms, they are loosely coupled and distributed across all the threads. For this reason, the best strategy to run QMCPACK efficiently is to feed enough walkers to the available threads.

In a VMC calculation, the code automatically raises the actual number of walkers per MPI rank to the number of available threads if the user-specified number of walkers is smaller, see “walkers/mpi=XXX” in the VMC output.

In DMC, for typical small to mid-sized calculations choose the total number of walkers to be a significant multiple of the total number of threads (MPI tasks * threads per task). This will ensure a good load balance. e.g., for a calculation on a few nodes with a total 512 threads, using 5120 walkers may keep the load imbalance around 10%. For the very largest calculations, the target number of walkers should be chosen to be slightly smaller than a multiple of the total number of available threads across all the MPI ranks. This will reduce occurrences worse-case load imbalance e.g. where one thread has two walkers while all the others have one.

Memory considerations¶

When using threads, some memory objects are shared by all the threads. Usually these memory objects are read only when the walkers are evolving, for instance the ionic distance table and wavefunction coefficients. If a wavefunction is represented by B-splines, the whole table is shared by all the threads. It usually takes a large chunk of memory when a large primitive cell was used in the simulation. Its actual size is reported as “MEMORY increase XXX MB BsplineSetReader” in the output file. See details about how to reduce it in 3D B-splines orbitals.

The other memory objects that are distinct for each walker during random walks need to be associated with individual walkers and cannot be shared. This part of memory grows linearly as the number of walkers per MPI rank. Those objects include wavefunction values (Slater determinants) at given electronic configurations and electron-related distance tables (electron-electron distance table). Those matrices dominate the $$N^2$$ scaling of the memory usage per walker.

Running on GPU machines¶

The GPU version is fully incorporated into the main source code. It works on any GPUs with OpenMP offload support including NVIDIA, AMD and Intel GPUs. Using batched drivers is required.

QMCPACK supports running on multi-GPU node architectures via MPI. Each MPI rank gets assigned a primary GPU based on the list of GPUs visible to it and its rank id in the smallest MPI communicator, usually the node local communicator, enclosing that list of GPUs. When there are more GPUs than the MPI ranks, excessive GPUs will be left idle. Please avoid this scenario in production runs. When there are more MPI ranks than GPUs, the primary GPU will be assigned in the following way. Performance portable implementation assigns GPUs to equal amount of blocks of MPI ranks. MPI ranks within a block are assigned the same GPU as their primary GPU. Legacy implementation assigns GPUs to MPI ranks in a round-robin order. It is guaranteed that MPI ranks are distributed among GPUs as evenly as possbile. Currently, for medium to large runs, 1 MPI task should be used per GPU per node. For very smaller system sizes, use of multiple MPI tasks per GPU might yield improved performance.

Performance considerations¶

To run with high performance on GPUs it is crucial to perform some benchmarking runs: the optimum configuration is system size, walker count, and GPU model dependent. The GPU implementation vectorizes operations over multiple walkers, so generally the more walkers that are placed on a GPU, the higher the performance that will be obtained. Performance also increases with electron count, up until the memory on the GPU is exhausted. A good strategy is to perform a short series of VMC runs with walker count increasing in multiples of two. For systems with 100s of electrons, typically 128–256 walkers per GPU use a sufficient number of GPU threads to operate the GPU efficiently and to hide memory-access latency. For smaller systems, thousands of walkers might be required. For QMC algorithms where the number of walkers is fixed such as VMC, choosing a walker count the is a multiple of the number of streaming multiprocessors can be most efficient. For variable population DMC runs, this exact match is not possible.

Memory considerations¶

In the GPU implementation, each walker has a buffer in the GPU’s global memory to store temporary data associated with the wavefunctions. Therefore, the amount of memory available on a GPU limits the number of walkers and eventually the system size that it can process. Additionally, for calculations using B-splines, this data is stored on the GPU in a shared read-only buffer. Often the size of the B-spline data limits the calculations that can be run on the GPU.

If the GPU memory is exhausted, first try reducing the number of walkers per GPU. Coarsening the grids of the B-splines representation (by decreasing the value of the mesh factor in the input file) can also lower the memory usage, at the expense (risk) of obtaining less accurate results. Proceed with caution if this option has to be considered.

EKCS12

Kenneth P. Esler, Jeongnim Kim, David M. Ceperley, and Luke Shulenburger. Accelerating quantum monte carlo simulations of real materials on gpu clusters. Computing in Science and Engineering, 14(1):40–51, 2012. doi:http://doi.ieeecomputersociety.org/10.1109/MCSE.2010.122.