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.
- 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.shIf 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.zipThere 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.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:
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:
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 |
+-------------------------------------------------------------------------------------------------------+
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 |
+-----------------------------------------------------------------------------------------------+
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 .
To visualize the evolution of various terms and parity plots:
gpumdkit.sh -plt train
To visualize the parity plots:
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
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].