Installation

Download

Download the source from the GPUMD repository, or clone it with Git:

git clone https://github.com/brucefan1983/GPUMD.git
cd GPUMD

The commands below refer to this repository directory.

Prerequisites

For NVIDIA GPUs, use a CUDA toolkit and driver that support the target GPU, with a compatible host compiler.

  • Make: the Linux makefile uses C++14. On Windows, use cl.exe from Microsoft Visual Studio and a 64-bit make.exe.

  • CMake (pre-release): use CMake 3.24 or newer and a host compiler with C++17 support. On Windows, use cl.exe from Microsoft Visual Studio.

For AMD GPUs, use ROCm/HIP and follow Building for AMD GPUs.

Compilation

Choose one build method. Both produce gpumd, nep, and tb by default.

Run make in src. Set CUDA_ARCH for your GPU and CUDA toolkit, for example:

cd src
make CUDA_ARCH=-arch=sm_89

This example targets an RTX 4090. The executables are written to src. To build only one executable, add its target name, for example make gpumd CUDA_ARCH=-arch=sm_89.

The makefile defaults to sm_60. CUDA 13.0 removed offline compilation support for Pascal GPUs, including sm_60; see the CUDA release notes. Check the comments at the beginning of src/makefile for other options. After changing compiler flags, GPU architecture, or optional libraries, run make clean before rebuilding.

Building for AMD GPUs (ROCm/HIP)

Use src/makefile.hip with a ROCm installation that provides hipcc, rocThrust/rocPRIM, hipBLAS, hipSOLVER, and hipFFT:

cd src
make -f makefile.hip

The default target architecture is gfx1100. To build for a different architecture, set HIP_ARCH, for example:

make -f makefile.hip HIP_ARCH=gfx90a

The executables are written to src. After changing build options, clean with make -f makefile.hip clean before rebuilding. CMake builds for AMD GPUs are not yet supported.

Running a program

Run the executable from the directory containing the input files, using its full path or adding its directory to PATH. For example, in a Linux shell after a Make build:

export PATH="/path/to/GPUMD/src:$PATH"

Replace /path/to/GPUMD/src with your executable directory; for a CMake build, use /path/to/GPUMD/build instead. Then run gpumd from the simulation directory or nep from the training directory. Follow the MD workflow or NEP training and prediction workflow for the required inputs and outputs. The repository’s examples directory provides examples for both programs.

GPU selection and multi-GPU execution

The nep executable uses all GPUs visible to the process. On CUDA systems, use CUDA_VISIBLE_DEVICES to select a subset, for example:

CUDA_VISIBLE_DEVICES=0 nep
CUDA_VISIBLE_DEVICES=0,1 nep

The gpumd executable also uses all visible GPUs when running standard NEP or temperature-dependent NEP models, and nep_spin spin models. For example:

CUDA_VISIBLE_DEVICES=0,1 gpumd

For ordinary MD, charge NEP models currently use the single-GPU implementation in gpumd. For replica dynamics, multi_replica assigns complete replicas of an energy NEP or charge NEP system to the visible GPUs. On managed clusters, request GPUs through the scheduler and use the device visibility configured by the scheduler.

For multi-GPU runs, GPUs with similar performance are recommended because synchronization can cause faster devices to wait for slower ones. For NEP molecular dynamics, GPUMD chooses the spatial partition direction automatically. The optional manual x, y, or z partition direction is documented with the potential keyword.

GNEP setup

GNEP trains NEP models using analytical gradients. See the method paper for details.

To compile the gnep executable, run make gnep in the src directory.

Prepare train.xyz and, optionally, test.xyz as for nep. Write the model and training settings in gnep.in. The following example uses default values except for type and the optional seed:

type         2 Ge Se
prediction   0
cutoff       8 4
n_max        4 4
basis_size   8 8
l_max        4
neuron       30
lambda_e     1.0
lambda_f     2.0
lambda_v     0.1
start_lr     1e-3
stop_lr      1e-7
weight_decay 0.0
batch        2
epoch        50
seed         20260831

The shared model and loss keywords have the same meanings as in nep.in. GNEP supports three-body angular descriptors, with l_max 4; four- and five-body descriptors are not supported. The default lambda_f is 2.0.

  • start_lr and stop_lr set the starting and final learning rates; both must be non-negative.

  • weight_decay is a non-negative weight-decay coefficient.

  • batch sets the global batch size and must be a positive integer; see below for multi-GPU use.

  • epoch sets the number of passes through the training set.

  • seed is an optional non-negative integer controlling parameter initialization and data shuffling. Without an explicit seed, data shuffling can differ between runs.

Run gnep from the directory containing the input files, using its full path or adding its directory to PATH. GNEP uses all visible GPUs on one node. On CUDA systems, select them with CUDA_VISIBLE_DEVICES, for example:

CUDA_VISIBLE_DEVICES=0 gnep
CUDA_VISIBLE_DEVICES=0,1 gnep
CUDA_VISIBLE_DEVICES=0,1,2,3 gnep

Global batch size and multi-GPU efficiency

batch is the total number of configurations per batch across all visible GPUs; it does not grow with the GPU count. For example, batch 4 selects a global batch of four configurations on either one or four GPUs. Keep the batch size, dataset, seed, and number of epochs fixed when comparing GPU counts. Changing the batch size can change the training trajectory.

Each participating GPU needs at least one configuration from the batch. batch 1 therefore uses only one GPU per step. Use a batch size of at least 2 for two GPUs or 4 for four GPUs, with enough training configurations to fill those batches. A batch containing fewer configurations than visible GPUs uses fewer GPUs.

Small configurations or small batches may run faster on one GPU. Choose the batch size according to GPU memory, training convergence, and measured performance for the intended dataset.

NetCDF setup

The dump_netcdf command requires netCDF-C 4.6.3 or newer. The steps below use Make; append the flags after the existing variable definitions in src/makefile.

Install NetCDF

Install netCDF-C 4.6.3 or a newer release, following its build instructions. For uncompressed output, a minimal configuration is:

./configure --prefix=<path> --disable-netcdf-4 --disable-dap
make -j
make install

Here, <path> is the installation directory. This configuration avoids HDF5 and zlib dependencies. For compression deflate output, omit --disable-netcdf-4 and build with NetCDF4/HDF5 and zlib support. If a newer release reports a missing xml2-config, add --disable-libxml2 to use its bundled XML parser.

Compile GPUMD

Append the following to src/makefile, replacing <path> with the NetCDF installation directory:

CFLAGS += -DUSE_NETCDF
INC += -I<path>/include
LDFLAGS += -L<path>/lib -Xlinker=-rpath -Xlinker=<path>/lib
LIBS += -lnetcdf

The library path is used both when linking and when running GPUMD. Run make clean in src, then rebuild as described under Compilation.

PLUMED setup

The plumed command requires a PLUMED installation. The steps below use Make; append the flags after the existing variable definitions in src/makefile.

Install PLUMED

Download a PLUMED release and follow its installation instructions. For example, the following configuration can be used with PLUMED 2.8.2:

./configure --prefix=<path> --disable-mpi --enable-openmp --enable-modules=all
make -j6
make install

Here, <path> is the installation directory. Set the runtime environment, for example in your shell startup file:

export PLUMED_KERNEL=<path>/lib/libplumedKernel.so
export LD_LIBRARY_PATH=<path>/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
export PATH=<path>/bin:$PATH

Replace <path> with the same installation directory and open a new shell if you edited its startup file.

Compile GPUMD

Append the following to src/makefile:

CFLAGS += -DUSE_PLUMED
INC += -I<path>/include
LDFLAGS += -L<path>/lib
LIBS += -lplumed -lplumedKernel

Run make clean in src, then rebuild as described under Compilation.

DP potential support

The DP interface uses the DeePMD-kit C++ library and is enabled at compile time with USE_DEEPMD.

Supported model formats

  • .pb: TensorFlow backend.

  • .pth: PyTorch TorchScript backend.

  • .pt2: PyTorch AOTInductor backend.

The installed DeePMD-kit version and backend must support the model being used. Follow the model-freezing instructions for that version to produce the appropriate file. The DeePMD-kit C++ API selects the backend from the model file.

Install the DeePMD-kit C++ interface

Install DeePMD-kit with the backend and GPU support required by your model, following its installation documentation. The GPUMD interface includes DeepPot.h and links to libdeepmd_cc. Check that both the headers and the C++ library are installed; a working dp command alone does not verify their availability. Use a C++ compiler and ABI compatible with the installed DeePMD-kit library.

Compile GPUMD

Use the src directory of the current GPUMD repository. For a Linux installation with headers in <path>/include/deepmd and libraries in <path>/lib, append the following after the existing flag definitions in src/makefile:

CFLAGS += -DUSE_DEEPMD
INC += -I<path>/include/deepmd
LDFLAGS += -L<path>/lib -Xlinker=-rpath -Xlinker=<path>/lib
LIBS += -ldeepmd_cc

Replace <path> with the DeePMD-kit installation prefix. If using a Python wheel, set the include and library paths to the actual locations supplied by that package. Keep the existing CUDA libraries in LIBS. Adding -ldeepmd_cc to LIBS places it after the object files in the link command. The DeePMD-kit C++ interface documentation describes backend and runtime library requirements.

From src, rebuild with the selected GPU architecture, for example:

make clean
make gpumd -j CUDA_ARCH=-arch=sm_89

This example targets an RTX 4090. If backend dependencies are installed in another directory, add that directory to the runtime library search path before running GPUMD, for example:

export LD_LIBRARY_PATH=/path/to/backend/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}

Run GPUMD

The interface requires a setting file and a frozen DP model file. The setting file lists the number of atom types and their chemical symbols in exactly the same order as the model type map. For example, dp_settings.txt for a model with type map O H contains:

dp 2 O H

Select one model in run.in, for example:

potential dp_settings.txt frozen_model.pb

For another backend, replace the model filename with the corresponding .pth or .pt2 file. The model type map can be inspected with DeePMD-kit, for example:

python -c "from deepmd.infer import DeepPot; print(DeepPot('frozen_model.pb').get_type_map())"

Run the compiled gpumd executable from the directory containing run.in and model.xyz.

NNAP support

GPUMD supports NNAP (Neural-Network Atomic Potentials) through jse. This interface is a development version. The instructions below describe a Linux build with CUDA.

Prerequisites

In addition to the GPUMD build requirements, install jse 4.1.0 or newer with a working JNI build (jse --jnibuild). Prepare an NNAP model (.json or .jnn) and a corresponding GPUMD setting file as shown below. For the complete jse installation and usage guides, see jse and jse-skill. For support, contact Qing’an Li (liqa1024@vip.qq.com) or Ke Xu (twtdq@qq.com).

Installation details

Prepare the environment

Check the system environment:

nvcc --version

Set the installation directory:

export install_dir="$HOME/software/GPUMD-NNAP"
mkdir -p ${install_dir}
cd ${install_dir}

Install jse

Install jse from the dev channel to obtain the latest development version (for linux):

bash <(curl -fsSL https://raw.githubusercontent.com/liqa1024/jse/dev/scripts/get.sh)

Optionally, manually run the JNI build to detect any potential environment issues in advance:

jse --jnibuild
jse -t 'jse.gpu.CudaCore.InitHelper.init()'

Configure and compile GPUMD-NNAP

Detect the required paths using jse and export them as environment variables:

export JSE_JAR_PATH=$(jse -t 'println(jse.code.OS.JAR_PATH)')
export JVM_INCLUDE=$(jse -t 'println(jse.clib.JVM.INCLUDE_DIR)')
export JVM_LLIB_DIR=$(jse -t 'println(jse.clib.JVM.LLIB_DIR)')

Enable NNAP support and add the jse class path by modifying CFLAGS:

CFLAGS += -DUSE_NNAP -DJVM_CLASS_PATH=\"-Djava.class.path=$(JSE_JAR_PATH)\"

Add the JVM header paths by modifying INC:

INC += -I$(JVM_INCLUDE) -I$(JVM_INCLUDE)/linux

Here $(JVM_INCLUDE)/linux corresponds to Linux; for other systems, replace it with the corresponding platform directory.

Add the JVM library search paths and library:

LDFLAGS += -L$(JVM_LLIB_DIR) -Xlinker -rpath -Xlinker $(JVM_LLIB_DIR)
LIBS += -ljvm

Here, JSE_JAR_PATH, JVM_INCLUDE, and JVM_LLIB_DIR should be replaced by the actual paths obtained from the jse commands above, or exported as environment variables before running make.

Rebuild the MD executable from the src directory:

make clean
make gpumd -j

If compilation is successful, the gpumd executable is generated.

Run the NNAP test

In the GPUMD input file, use the NNAP potential as follows:

potential nnap.txt CuZr-sphs.json

An example GPUMD setting file nnap.txt file is:

nnap 2 Cu Zr

The element order in nnap.txt must be consistent with that in the NNAP potential file CuZr-sphs.json.

For example, if the NNAP potential file uses the element order Zr Cu, then nnap.txt should be written as:

nnap 2 Zr Cu

Run the test with:

gpumd

References