English · 简体中文 · Website · Documentation · Gallery
GPUMDkit is a toolkit for the GPUMD (Graphics Processing Units Molecular Dynamics) and NEP (neuroevolution potential) programs. It provides a unified command-line entry point for common scripts, format conversion, structure sampling, NEP data preparation, analysis, and visualization.
- 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.
conda create -n gpumdkit -c gpumdkit -c conda-forge gpumdkit
conda activate gpumdkitSome features require optional packages:
pip install neptrain calorinegit clone https://github.com/zhyan0603/GPUMDkit.git
cd GPUMDkit
source ./install.shGPUMDkit includes English and Chinese Agent Skills for AI-assisted GPUMDkit, GPUMD, and NEP workflows. After installation, run:
gpumdkit.sh -skillThen ask your agent to follow the printed instructions and install the relevant skills globally. Global installation is the normal recommendation; if the installation scope is not specified, the agent should ask whether to use the global or current-project directory before creating links.
If GPUMDkit was installed with Conda, update it using:
conda activate gpumdkit
conda update -c gpumdkit -c conda-forge gpumdkitOptional dependencies installed with pip can be updated separately if needed:
pip install --upgrade neptrain calorineIf GPUMDkit was installed from the source repository, run:
gpumdkit.sh -updateThis 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.zipFor a guided first run, see the Quick Start. Use the Command Reference when you already know the task and need exact syntax.
There are two options, interactive mode and command-line 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.8 (2026-10-20) 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:
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. For browser-based access to remote working directories, see the Remote Web Console guide.
gpumdkit.sh -h
the help information:
+-------------------------------------------------------------------------------------------------------+
| GPUMDkit 1.5.8 (2026-10-20) Command Help |
+-------------------------------------------------------------------------------------------------------+
| MAIN FUNCTIONS |
+-------------------------------------------------------------------------------------------------------+
| -h Show this help table | -plt <type> Plot and visualization tools |
| -calc <type> Calculator tools | -time <gpumd|wpe|nep|gnep> Time-consuming analyzer |
| -update Update GPUMDkit | -clean Clean extra files in current dir |
| -skill Show GPUMDkit agent skill info | -doctor Check Python environment |
| -prediction Write NEP prediction .out files | -prediction_dpa Write DPA prediction .out files |
| -server Start the GPUMDkit web server | |
+-------------------------------------------------------------------------------------------------------+
| FORMAT CONVERSION |
+-------------------------------------------------------------------------------------------------------+
| -out2xyz OUTCAR -> extxyz (shell) | -out2xyz_bec OUTCAR -> extxyz with BEC |
| -out2exyz OUTCAR -> extxyz (python) | -xyz2dp extxyz -> DeepMD npy |
| -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/data -> 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 |
| -shift_energy Interactive energy shift | |
+-------------------------------------------------------------------------------------------------------+
| Python option help: gpumdkit.sh -<option> -h Plot list: gpumdkit.sh -plt -h |
+-------------------------------------------------------------------------------------------------------+
gpumdkit.sh -plt -h
the help information:
+-----------------------------------------------------------------------------------------------+
| GPUMDkit 1.5.8 (2026-10-20) 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 net_force - Net force distribution |
+-----------------------------------------------------------------------------------------------+
| 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 doas - Density of atomistic states |
| D - Arrhenius diffusivity sigma - Arrhenius ionic conductivity|
| D_xyz - Directional Arrhenius D sigma_xyz - Directional Arrhenius sigma |
| D_PT - PT Arrhenius D sigma_PT - PT Arrhenius sigma |
+-----------------------------------------------------------------------------------------------+
| MD & Structural Analysis |
+-----------------------------------------------------------------------------------------------+
| thermo - thermo info in thermo.out thermo2 - Previous thermo style |
| rdf - Radial distribution function rdf_pmf - Potential of mean force |
| vac - Velocity autocorrelation cohesive - Cohesive energy curve |
| xrd - X-ray diffraction plane-grid - Displacement plane grid |
| xrd_comp - Compare XRD |
+-----------------------------------------------------------------------------------------------+
| Heat Transport |
+-----------------------------------------------------------------------------------------------+
| emd - EMD results emd2 - EMD all directions |
| nemd - NEMD results hnemd - HNEMD results |
| viscosity - Viscosity |
+-----------------------------------------------------------------------------------------------+
| Phonons |
+-----------------------------------------------------------------------------------------------+
| pdos - VAC and PDOS phonon - Phonon band structure |
| phonon_comp - Compare phonon band structures |
+-----------------------------------------------------------------------------------------------+
See the codes in plt_scripts for more details
To convert a VASP OUTCAR file to an extended XYZ format (extxyz) file, use the following command:
gpumdkit.sh -out2xyz <dir_of_OUTCARs>
Example: gpumdkit.sh -out2xyz .
To visualize the evolution of various terms and parity plots:
gpumdkit.sh -plt train
To visualize the prediction-mode parity results for structures in train.xyz:
gpumdkit.sh -plt prediction
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
After calculating phonons through gpumdkit.sh -> 4) Calculators -> 414) Calc phonon band structure, plot the result using the QPOINTS path definition:
gpumdkit.sh -plt phonon phonon_NEP.dat QPOINTS save
gpumdkit.sh -plt phonon phonon_DFT.dat
gpumdkit.sh -plt phonon_comp phonon_DFT.dat phonon_NEP.dat save
phonon accepts an optional data-file argument and uses phonon_NEP.dat by
default; when only the data file is supplied, it uses the default QPOINTS.
Comparison labels are read from filenames such as phonon_NEP.dat and
phonon_DFT.dat. Two or more phonon files can be supplied to
phonon_comp; use --qpoints FILE when the path file is not named QPOINTS.
Comparison files may use different q-path offsets at disconnected segments, but
must otherwise have the same q-point sampling and number of bands.
Refer to our documentation for more detailed examples and command options.
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.
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.
- 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 list the programs whose progress can be monitored:gpumd,wpe,nep,gnep.
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! 🌟
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.
BibTeX
@article{yan2026gpumdkit,
title = {GPUMDkit: A User-Friendly Toolkit for GPUMD and NEP},
author = {Yan, Zihan and Li, Denan and Wu, Xin and Liu, Zhoulin and Hua, Chen and Situ, Boyi and Yang, Hao and Tang, Shengjie and Tang, Benrui and Wang, Ziyang and Yi, Shangzhao and Wang, Huan and Huang, Dian and Li, Ke and Guo, Qilin and Chen, Zherui and Xu, Ke and Wang, Yanzhou and Wang, Ziliang and Tang, Gang and Liu, Shi and Fan, Zheyong and Zhu, Yizhou},
journal = {MGE Advances},
volume = {4},
pages = {e70074},
year = {2026},
doi = {10.1002/mgea.70074}
}In your manuscript you may write something like:
Data processing and figure generation were performed using GPUMDkit [x].





