README.md
July 17, 2026 · View on GitHub
English · 简体中文 · Website · Documentation · Gallery
GPUMDkit is a toolkit for the GPUMD (Graphics Processing Units Molecular Dynamics) and NEP (neuroevolution potential) program. It offers a user-friendly command-line interface to streamline common scripts and workflows, simplifying tasks such as script invocation, format conversion, structure sampling, NEP construction workflow, and various analysis, aiming to improve user productivity.
Features
- Data Preparation: Convert, label, sample, split, filter, and inspect atomistic datasets.
- Workflow Automation: Prepare batch DFT/MD calculations and active-learning workflows.
- Calculation and Analysis: Calculate and analyze structural, transport, and NEP-related properties.
- Visualization and Post-processing: Visualize NEP training, molecular dynamics, diffusion, and thermal-transport results.
- Flexible Interface: Use an interactive menu or direct command-line options.
Installation
Conda (Recommended)
conda create -n gpumdkit -c gpumdkit -c conda-forge gpumdkit
conda activate gpumdkit
Some features require optional packages:
pip install neptrain calorine
From Source
git clone https://github.com/zhyan0603/GPUMDkit.git
cd GPUMDkit
source ./install.sh
Update
Conda Installation
If GPUMDkit was installed with Conda, update it using:
conda activate gpumdkit
conda update -c gpumdkit -c conda-forge gpumdkit
Optional dependencies installed with pip can be updated separately if needed:
pip install --upgrade neptrain calorine
Source Installation
If GPUMDkit was installed from the source repository, run:
gpumdkit.sh -update
This command checks the currently installed Git branch and pulls the latest updates from the same branch.
Alternatively, download the latest source archive manually:
wget https://github.com/zhyan0603/GPUMDkit/archive/refs/heads/main.zip
Usage
There are two options, interactive mode and command-line mode
Interactive Mode
-
Open your terminal.
-
Execute the
gpumdkit.shscript:gpumdkit.sh -
Follow the on-screen prompts to interactively select and run the desired function.
____ ____ _ _ __ __ ____ _ _ _ / ___| _ \| | | | \/ | _ \| | _(_) |_ | | _| |_) | | | | |\/| | | | | |/ / | __| | |_| | __/| |_| | | | | |_| | <| | |_ \____|_| \___/|_| |_|____/|_|\_\_|\__| GPUMDkit Version 1.5.6 (dev) (2026-07-10) Core Developer: Zihan YAN (yanzihan@westlake.edu.cn) Main Contributors: Denan LI, Xin WU, Zhoulin LIU & Chen HUA ---------------------- GPUMD ------------------------ 1) Format Conversion 2) Sample Structures 3) Workflow 4) Calculators 5) Analyzer 6) Visualization 7) Utilities 8) Help 0) Exit ------------>> Input the function number:
Command-Line Mode
For users familiar with the GPUMDkit , the command-line mode allows for faster execution by directly passing arguments to gpumdkit.sh. Here are some examples:
Example 1: View help information
gpumdkit.sh -h
the help information:
+-------------------------------------------------------------------------------------------------------+
| GPUMDkit 1.5.6 (dev) (2026-07-10) Command Help |
+-------------------------------------------------------------------------------------------------------+
| MAIN FUNCTIONS |
+-------------------------------------------------------------------------------------------------------+
| -h Show this help table | -plt <type> Plot and visualization tools |
| -calc <type> Calculator tools | -time <gpumd|nep> Time-consuming analyzer |
| -update Update GPUMDkit | -clean Clean extra files in current dir |
| -skill Show GPUMDkit agent skill info | -doctor Check Python environment |
+-------------------------------------------------------------------------------------------------------+
| FORMAT CONVERSION |
+-------------------------------------------------------------------------------------------------------+
| -out2xyz OUTCAR -> extxyz (shell) | -out2exyz OUTCAR -> extxyz (python) |
| -cp2k2xyz CP2K log -> xyz | -xdat2exyz XDATCAR -> extxyz |
| -cif2pos cif -> POSCAR | -cif2exyz cif -> extxyz |
| -pos2exyz POSCAR -> extxyz | -exyz2pos extxyz -> POSCAR |
| -pos2lmp POSCAR -> LAMMPS data | -lmp2exyz LAMMPS dump -> extxyz |
| -traj2exyz ASE traj -> extxyz | -replicate Replicate structure |
| -addgroup Add group labels | -addweight Add structure weight in extxyz |
| -clean_xyz Clean extra info in extxyz | -get_frame Extract specific frame |
| -frame_range Extract frames by range | -dp2xyz DeepMD npy -> extxyz |
+-------------------------------------------------------------------------------------------------------+
| ANALYSIS |
+-------------------------------------------------------------------------------------------------------+
| -range Energy/force/virial statistics | -analyze_comp Analyze composition |
| -chem_species Analyze chemical species | -cbc Charge balance check |
| -min_dist Min distance (no PBC) | -min_dist_pbc Min distance with PBC |
| -filter_dist Filter by min_dist (no PBC) | -filter_dist_pbc Filter by min_dist (PBC) |
| -pda Probability density analysis | -filter_box Filter by box-edge length |
| -pynep Deprecated PyNEP sampling | -nep_modifier Modify NEP model interactively |
+-------------------------------------------------------------------------------------------------------+
| Python option help: gpumdkit.sh -<option> -h Plot list: gpumdkit.sh -plt -h |
+-------------------------------------------------------------------------------------------------------+
Example 2: View help information for -plt
gpumdkit.sh -plt -h
the help information:
+-----------------------------------------------------------------------------------------------+
| GPUMDkit 1.5.6 (dev) (2026-07-10) PLOT & VISUALIZATION TOOLS |
+-----------------------------------------------------------------------------------------------+
| Usage: gpumdkit.sh -plt <type> List: gpumdkit.sh -plt -h |
+-----------------------------------------------------------------------------------------------+
| NEP Training & Evaluation |
+-----------------------------------------------------------------------------------------------+
| train - NEP training results prediction - NEP prediction results |
| train_test - NEP train and test results parity_density - Parity density plot |
| train_density - Training results density plot restart - Parameters in nep.restart |
| charge - Charge distribution born_charge - Born effective charges |
| dimer - Dimer energy/force curve force_errors - Force errors |
| des - Descriptors lr - Learning rate for gnep |
+-----------------------------------------------------------------------------------------------+
| Diffusion & Transport |
+-----------------------------------------------------------------------------------------------+
| msd - Mean square displacement msd_conv - MSD convergence |
| msd_all - MSD for all species sdc - Self diffusion coefficient |
| msd_sdc - MSD and SDC together sigma - Arrhenius ionic conductivity|
| D - Arrhenius diffusivity sigma_xyz - Directional Arrhenius sigma |
| D_xyz - Directional Arrhenius D |
+-----------------------------------------------------------------------------------------------+
| MD & Structural Analysis |
+-----------------------------------------------------------------------------------------------+
| thermo - thermo info in thermo.out thermo2/3 - Thermo in different styles |
| rdf - Radial distribution function rdf_pmf - Potential of mean force |
| vac - Velocity autocorrelation cohesive - Cohesive energy curve |
| net_force - Net force distribution plane-grid - Displacement plane grid |
| doas - Density of atomistic states |
+-----------------------------------------------------------------------------------------------+
| Heat Transport |
+-----------------------------------------------------------------------------------------------+
| emd - EMD results nemd - NEMD results |
| hnemd - HNEMD results viscosity - Viscosity |
+-----------------------------------------------------------------------------------------------+
| Phonons |
+-----------------------------------------------------------------------------------------------+
| pdos - VAC and PDOS |
+-----------------------------------------------------------------------------------------------+
Example 3: Convert VASP OUTCARs to extxyz
To convert a VASP OUTCARs to an extended XYZ format (extxyz) file, use the following command:
gpumdkit.sh -out2xyz <dir_of_OUTCARs>
Example: gpumdkit.sh -out2xyz .
Example 4: Plot loss and parity plots
To visualize the evolution of various terms and parity plots:
gpumdkit.sh -plt train
Example 5: Plot the parity plots
To visualize the parity plots:
gpumdkit.sh -plt test
Example 6: Plot thermo evolution
To visualize thermo evolution from thermo.out :
gpumdkit.sh -plt thermo
You can also save images as PNG if your device doesn't support visualization:
gpumdkit.sh -plt thermo save
Refer to our documentation for more detailed examples and command options.
Custom Commands
GPUMDkit now supports custom commands via ~/.gpumdkit.in.
You can add your own shortcuts (e.g., gpumdkit.sh -yourcommand) by defining functions in this file. This allows you to extend GPUMDkit with personal scripts. See custom command documentation for details.
Tab Completion Support
gpumdkit.sh provides optional Bash Tab completion to enhance the command-line experience. This feature allows you to auto-complete primary options (e.g., -h, -plt, -calc) and their secondary parameters (e.g., thermo, train) by pressing the Tab key.
Usage Examples
- Type
gpumdkit.sh -<Tab>to see all available options. - Type
gpumdkit.sh -plt <Tab>to list plotting sub-options likethermo,train, etc. - Type
gpumdkit.sh -time <Tab>to see calculator options likegpumd,nep.
Join Us
We’d love your help to improve GPUMDkit! Contribute by:
- Adding Python/Shell scripts via Pull Requests.
- Report issues or suggest features via issues.
- Contacting me at yanzihan@westlake.edu.cn.
Also, welcome to join our QQ group (825696376). Let’s build something useful together! 🌟
Citation
GPUMDkit is an open-source tool freely available for everyone. If you find it helpful in your research or workflow, please ⭐ star us on GitHub. Additionally, if GPUMDkit contributes to your published work, please cite our paper:
Z. Yan*, D. Li, X. Wu, Z. Liu, C. Hua, B. Situ, H. Yang, S. Tang, B. Tang, Z. Wang, S. Yi, H. Wang, D. Huang, K. Li, Q. Guo, Z. Chen, K. Xu, Y. Wang, Z. Wang, G. Tang, S. Liu, Z. Fan, and Y. Zhu*. GPUMDkit: A User-Friendly Toolkit for GPUMD and NEP. MGE Advances, 2026, 4, e70074.
In your manuscript you may write something like:
Data processing and figure generation were performed using GPUMDkit [x].