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)
```bash
conda create -n gpumdkit -c gpumdkit -c conda-forge gpumdkit
conda activate gpumdkit
```
Some features require optional packages:
```bash
pip install neptrain calorine
```
### From Source
```bash
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:
```bash
conda activate gpumdkit
conda update -c gpumdkit -c conda-forge gpumdkit
```
Optional dependencies installed with pip can be updated separately if needed:
```bash
pip install --upgrade neptrain calorine
```
### Source Installation
If `GPUMDkit` was installed from the source repository, run:
```bash
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:
```bash
wget https://github.com/zhyan0603/GPUMDkit/archive/refs/heads/main.zip
```
## Usage
There are two options, *interactive mode* and *command-line mode*
#### Interactive Mode
---
1. Open your terminal.
2. Execute the `gpumdkit.sh` script:
```
gpumdkit.sh
```
3. 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 Plot and visualization tools |
| -calc Calculator tools | -time 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 -
