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-09-23)
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-09-23) 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 |
| -server Start the GPUMDkit web server | |
| -prediction Write NEP prediction .out files | -prediction_dpa Write DPA prediction .out files |
+-------------------------------------------------------------------------------------------------------+
| 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 -> 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-09-23) 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/3 - Thermo in different styles |
| 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 test
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 see calculator options likegpumd,nep.
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.
In your manuscript you may write something like:
Data processing and figure generation were performed using GPUMDkit [x].