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.exefrom 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.exefrom 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.
Configure and build from the repository root:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel
The executables are placed in build with a single-configuration generator, or normally in build/Release with Visual Studio.
CMAKE_BUILD_TYPE selects the configuration for generators such as Unix Makefiles and Ninja; --config selects it for generators such as Visual Studio.
Omit --parallel for serial compilation.
The GPU architecture defaults to native.
To choose it explicitly, add -DCMAKE_CUDA_ARCHITECTURES to the configure command, for example for an RTX 4090:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_CUDA_ARCHITECTURES=89
To build only one executable, add its target name:
cmake --build build --config Release --target gpumd --parallel
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.
To compile the gnep executable, configure with CMake as described in the Compilation section above, then run:
cmake --build build --config Release --target gnep
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_lrandstop_lrset the starting and final learning rates; both must be non-negative.weight_decayis a non-negative weight-decay coefficient.batchsets the global batch size and must be a positive integer; see below for multi-GPU use.epochsets the number of passes through the training set.seedis 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.
CMake uses PKG_NNAP to control NNAP support:
-D PKG_NNAP=yes
Add environment variable to import jse jar path:
export JSE_JAR_PATH=$(jse -t 'println(jse.code.OS.JAR_PATH)')
In Windows, you need to additionally specify the JVM library path (PowerShell):
$env:JSE_JAR_PATH = "$(jse -t 'println(jse.code.OS.JAR_PATH)')"
$env:JVM_LIB_PATH = "$(jse -t 'println(jse.clib.JVM.LIB_PATH)')"
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
jse-skill: https://github.com/liqa1024/jse-skill
jsex-NNAP: https://github.com/liqa1024/jsex-NNAP