GPUMDkit

https://github.com/zhyan0603/gpumdkit
Admin
GPUMDkit is a Bash and Python command-line toolkit for GPUMD and NEP, molecular dynamics and...
Tokens:101,499
Snippets:1,482
Trust Score:8.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Hello World Example: Convert POSCAR to extxyz and Inspect

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/quick_start.html

A minimal end-to-end test to verify the installation by creating a POSCAR, converting it to extxyz, and checking the output.

```bash
cat > POSCAR << 'EOF'
Si
1.0
0 2.715 2.715
2.715 0 2.715
2.715 2.715 0
Si
1
direct
0 0 0
EOF
```

```bash
gpumdkit.sh -pos2exyz POSCAR model.xyz
```

```bash
head model.xyz
```

--------------------------------

### Install GPUMDkit

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/index.html

Clone the repository, navigate to the directory, and run the installation script.

```bash
git clone https://github.com/zhyan0603/GPUMDkit.git
cd GPUMDkit
source ./install.sh
```

--------------------------------

### Install GPUMDkit

Source: https://github.com/zhyan0603/gpumdkit/blob/main/README.md

Navigate to the cloned directory and run the installation script.

```bash
cd GPUMDkit; source ./install.sh
```

--------------------------------

### Install OVITO

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/en/calculator_scripts.md

Install the OVITO package, required for RDF calculation.

```bash
pip install ovito
```

--------------------------------

### CP2K Input Example

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/workflow_scripts.html

Example of providing input files for CP2K SCF batch pretreatment.

```text
dump.xyz template.inp H2O
```

--------------------------------

### Set up Conda Environment and Install Dependencies

Source: https://github.com/zhyan0603/gpumdkit/blob/main/README.md

Create and activate a conda environment for GPUMDkit, then install the required Python packages using pip.

```bash
conda create -n gpumdkit python=3.12
conda activate gpumdkit

pip install neptrain ase pymatgen dpdata
```

--------------------------------

### GPUMDkit CLI Examples

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/en/quick_start.md

Demonstrates common command-line operations for format conversion and calculation initiation.

```bash
gpumdkit.sh -pos2exyz POSCAR model.xyz
```

```bash
gpumdkit.sh -plt train
```

```bash
gpumdkit.sh -calc msd trajectory.xyz Li 10
```

--------------------------------

### Python Script Example

Source: https://github.com/zhyan0603/gpumdkit/blob/main/skills/gpumdkit-contributing/SKILL.md

Example of a Python script to be placed in the Scripts/calculators/ subdirectory.

```bash
# Python script example: Scripts/calculators/calc_new_feature.py
```

--------------------------------

### Set up Conda Environment

Source: https://github.com/zhyan0603/gpumdkit/blob/main/skills/gpumdkit-main/SKILL.md

Create and activate a Conda environment for GPUMDkit, installing necessary Python packages.

```bash
conda create -n gpumdkit python=3.12
conda activate gpumdkit
pip install neptrain ase pymatgen dpdata numpy scipy matplotlib
```

--------------------------------

### Install GPUMD-Kit Dependencies

Source: https://github.com/zhyan0603/gpumdkit/blob/main/skills/gpumdkit-sampling/SKILL.md

Install core dependencies like numpy and ase, and optional packages like neptrain or dpdata as needed.

```bash
pip install numpy ase matplotlib scikit-learn scipy dpdata
pip install neptrain  # For FPS by NepTrain
```

--------------------------------

### Tab Completion Examples

Source: https://github.com/zhyan0603/gpumdkit/blob/main/README.md

Demonstrates how to use Bash tab completion for GPUMDkit commands and their parameters. Pressing Tab suggests available options.

```shell
gpumdkit.sh -<Tab>
```

```shell
gpumdkit.sh -plt <Tab>
```

```shell
gpumdkit.sh -time <Tab>
```

--------------------------------

### Install ferrodispcalc Package

Source: https://github.com/zhyan0603/gpumdkit/blob/main/Scripts/calculators/README.md

Installs the ferrodispcalc package required for neighbor list, displacement, polarization, tilt, and plane workflows.

```bash
pip3 install git+https://github.com/MoseyQAQ/ferrodispcalc.git
```

--------------------------------

### Template-Based Temperature Series Setup

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/workflow_scripts.html

This shell loop automates the creation of directories for different temperatures, copies necessary files, and modifies a run template to set the temperature for each simulation. It's useful for setting up a series of simulations at varying temperatures.

```bash
for temp in 300 500 700 900; do
    mkdir -p "${temp}K"
    cp model.xyz "${temp}K/"
    cp nep.txt "${temp}K/"
    sed "s/TEMPERATURE/$temp/g" run_template.in > "${temp}K/run.in"
done
```

--------------------------------

### Step 1: Get averaged structures

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/polar_material_analysis.html

Averages structures from the last half of each trajectory for temperature-driven phase transition analysis.

```bash
gpumdkit.sh -calc avg-struct traj_*.xyz
```

--------------------------------

### Get Help for Displacement Calculator

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/polar_material_analysis.html

Displays detailed argument information for the displacement calculator.

```bash
gpumdkit.sh -calc disp -h
```

--------------------------------

### Setup Directories for Temperature-Dependent MD

Source: https://github.com/zhyan0603/gpumdkit/blob/main/skills/gpumdkit-workflows/SKILL.md

This script automates the creation of directories for molecular dynamics simulations at different temperatures, copying necessary files and modifying run input scripts.

```bash
# Setup directories for multiple temperatures
for temp in 300 500 700 900; do
    mkdir -p "${temp}K"
    cp model.xyz "${temp}K/"
    cp nep.txt "${temp}K/"
    sed "s/TEMPERATURE/$temp/g" run_template.in > "${temp}K/run.in"
done
```

--------------------------------

### Modular Function Example (Bash)

Source: https://github.com/zhyan0603/gpumdkit/blob/main/CONTRIBUTING.md

Demonstrates good practice by accepting parameters for input and output files, promoting reusability. Avoid hardcoding values unless required by specific programs like GPUMD or NEP.

```bash
# Good: accepts parameters
function convert_file() {
    local input_file=$1
    local output_file=$2
    # processing logic
}

# Avoid: hardcoded values (unless required by GPUMD/NEP)
function convert_file() {
    local input_file="hardcoded_input.xyz"
    # processing logic
}
```

--------------------------------

### Install and Activate GPUMDkit Environment

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/index.html

Use these commands to create a new conda environment for GPUMDkit, activate it, and install necessary Python packages.

```bash
conda create -n gpumdkit python=3.12
conda activate gpumdkit
pip install neptrain dpdata calorine
```

--------------------------------

### Get Help for Polarization Calculator

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/polar_material_analysis.html

Displays detailed argument information for the polarization calculator.

```bash
gpumdkit.sh -calc pol-abo3 -h
```

--------------------------------

### Add a New Format Conversion Script

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/zh/贡献指南.md

Example of creating a new Python script for format conversion within the Scripts/format_conversion directory.

```bash
# Example: Add a new format conversion script
touch Scripts/format_conversion/new_converter.py
```

--------------------------------

### Get Help for Plane Grid Plotting Tool

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/polar_material_analysis.html

Displays detailed argument information for the plane grid plotting tool.

```bash
gpumdkit.sh -plt plane-grid -h
```

--------------------------------

### Get Help for Octahedral Tilt Calculator

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/polar_material_analysis.html

Displays detailed argument information for the octahedral tilt calculator.

```bash
gpumdkit.sh -calc oct-tilt -h
```

--------------------------------

### VASP Input Directory Structure

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/workflow_scripts.html

Example directory structures for VASP input files, supporting multiple .vasp files or a single .xyz file.

```text
current directory/
├── POSCAR_1.vasp
├── POSCAR_2.vasp
└── POSCAR_3.vasp
```

```text
current directory/
└── sampled.xyz
```

--------------------------------

### Preprocessing and Sampling Sequence

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/structure_sampling.html

An example sequence of commands for preprocessing a trajectory and then sampling structures for training. Includes analyzer tools and a structure selection script.

```bash
gpumdkit.sh -min_dist_pbc dump.xyz
```

```bash
gpumdkit.sh -filter_box dump.xyz 13
```

```python
python Scripts/sample_structures/neptrain_select_structs.py dump.xyz train.xyz nep.txt
```

--------------------------------

### Get Help for Neighbor List Calculator

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/polar_material_analysis.html

Displays detailed argument information for the neighbor list calculator.

```bash
gpumdkit.sh -calc nlist -h
```

--------------------------------

### GPUMDkit Command Help Output

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/en/command_reference.md

Displays the main help table for GPUMDkit, outlining available commands and their brief descriptions. Use this to get an overview of the tool's capabilities.

```text
+-------------------------------------------------------------------------------------------------------+
|                          GPUMDkit 1.5.6 (dev) (2026-06-17) 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   |
+-------------------------------------------------------------------------------------------------------+
|                                         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         |                                                       |
+-------------------------------------------------------------------------------------------------------+
|                                            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     |
+-------------------------------------------------------------------------------------------------------+
| Detailed usage: gpumdkit.sh -<option> -h    Plot details: gpumdkit.sh -plt <type> -h                  |
+-------------------------------------------------------------------------------------------------------+
```

--------------------------------

### Get Help for Average Structure Calculator

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/polar_material_analysis.html

Displays detailed argument information for the average structure calculator.

```bash
gpumdkit.sh -calc avg-struct -h
```

--------------------------------

### GPUMD Input Directory Structure

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/workflow_scripts.html

Example directory structures for GPUMD MD sampling pretreatment, supporting .vasp files or a single .xyz file.

```text
current directory/
├── POSCAR_1.vasp
└── POSCAR_2.vasp
```

```text
current directory/
└── dump.xyz
```

--------------------------------

### GPUMDkit Skill Structure Example

Source: https://github.com/zhyan0603/gpumdkit/blob/main/skills/README.md

Defines the standard structure for a GPUMDkit skill, including metadata like name and description, and tool specifications. This format is compatible with the Agent Skills standard.

```markdown
---
name: skill-name
description: >
  Description of what the skill does and when to use it.
allowed-tools: Bash(gpumdkit *)
---

# Skill Title

## Content...

```

--------------------------------

### Create opencode Skills Symlinks

Source: https://github.com/zhyan0603/gpumdkit/blob/main/skills/README.md

Manually create symbolic links for GPUMDkit skills within the .opencode/skills directory. This setup is recommended for using GPUMDkit with the opencode agent tool.

```bash
# Run from GPUMDkit root directory
mkdir -p .opencode/skills
cd .opencode/skills
ln -s ../../skills/gpumdkit-main .
ln -s ../../skills/gpumdkit-format-conversion .
ln -s ../../skills/gpumdkit-calculators .
ln -s ../../skills/gpumdkit-analyzers .
ln -s ../../skills/gpumdkit-visualization .
ln -s ../../skills/gpumdkit-workflows .
ln -s ../../skills/gpumdkit-sampling .
ln -s ../../skills/gpumdkit-contributing .
cd ../..

```

--------------------------------

### Complete Module Docstring Example

Source: https://github.com/zhyan0603/gpumdkit/blob/main/skills/gpumdkit-contributing/SKILL.md

All scripts over 50 lines must include a module-level docstring with specific sections like script name, category, purpose, usage, arguments, output, author, and modification date.

```python
"""
=============================================================================
GPUMDkit: A User-Friendly Toolkit for GPUMD and NEP
Repository: https://github.com/zhyan0603/GPUMDkit
Citation: Z. Yan et al., GPUMDkit: A User-Friendly Toolkit for GPUMD and NEP,
          MGE Advances, 2026, 4, e70074 (https://doi.org/10.1002/mgea.70074)
=============================================================================
Script:     script_name.py
Category:   Category Name
Purpose:    One-line description of what this script does.
            Multi-line elaboration if needed.
Usage:      gpumdkit.sh -flag <param1> <param2> [optional]
            python3 script_name.py <param1> <param2> [optional]
Arguments:
  param1    Description of param1
  param2    Description of param2
  optional  Description of optional (default: value)
Output:
  <file>     (description of output)
Author:     Name (email)
Last-modified: YYYY-MM-DD
=============================================================================
"""

```

--------------------------------

### Install Calorine Package

Source: https://github.com/zhyan0603/gpumdkit/blob/main/Scripts/utils/nep_modifier/README.md

Install the calorine Python package, which is a dependency for the NEP Modifier tool. Choose between installing from PyPI or the latest version from GitLab.

```bash
pip install 'calorine>=3.4'
```

```bash
pip install git+https://gitlab.com/materials-modeling/calorine.git@master
```

--------------------------------

### Create Working Directory

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/active_learning_workflow.html

Creates the initial working directory for the active learning process.

```bash
mkdir ${work_dir}/01.select
```

--------------------------------

### Install GPUMD-Kit Dependencies

Source: https://github.com/zhyan0603/gpumdkit/blob/main/skills/gpumdkit-calculators/SKILL.md

Install core Python packages required for GPUMD-Kit calculators, including numpy, ase, scipy, calorine, matplotlib, and tqdm. Also installs the ferrodispcalc package from GitHub.

```bash
pip install numpy ase scipy calorine matplotlib tqdm
pip3 install git+https://github.com/MoseyQAQ/ferrodispcalc.git
```

--------------------------------

### Install Calorine Dependency

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/calculator_scripts.html

Installs the 'calorine' package, which is a dependency for NEP property prediction.

```bash
pip install calorine
```

--------------------------------

### Clone and Set Up Repository

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/zh/贡献指南.md

Clone your forked repository and set the upstream remote to keep your fork synchronized with the main project.

```bash
git clone https://github.com/YOUR_USERNAME/GPUMDkit.git
cd GPUMDkit
git remote add upstream https://github.com/zhyan0603/GPUMDkit.git
```

--------------------------------

### 在 gpumdkit.sh 中更新帮助信息

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/zh/贡献指南.md

更新 `gpumdkit.sh` 中的 `help_info_table()` 函数，以包含新添加的命令行标志及其简要描述。

```bash
function help_info_table(){
    echo "+====================================== Analysis ===============================================+"
    echo "| -analyze_bonds Analyze bond lengths in struct | -analyze_comp Analyze composition of extxyz      |"
    # ... 其余帮助表 ...
}
```

--------------------------------

### Install Optional Python Packages

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/quick_start.html

Install additional packages like neptrain, dpdata, and calorine using pip if you need to use specific optional functions of GPUMDkit. Python will report missing dependencies if they are required by a function you attempt to use.

```bash
pip install neptrain dpdata calorine
```

--------------------------------

### GPUMDkit Entry Point and CLI Usage

Source: https://github.com/zhyan0603/gpumdkit/blob/main/AGENTS.md

Demonstrates the interactive mode and common command-line flag usage for GPUMDkit. Use `gpumdkit.sh` for general operations.

```bash
gpumdkit.sh                                # Interactive mode
```

```bash
gpumdkit.sh -h                             # Show all CLI flags
```

```bash
gpumdkit.sh -plt train                     # Plot NEP training
```

```bash
gpumdkit.sh -calc msd dump.xyz Li 10       # Calculate MSD
```

```bash
gpumdkit.sh -dp2xyz database train.xyz     # DeepMD npy → extxyz
```

--------------------------------

### Update GPUMDkit

Source: https://github.com/zhyan0603/gpumdkit/blob/main/Scripts/README.md

Updates the GPUMDkit installation to the latest version.

```bash
gpumdkit.sh -update
```

--------------------------------

### Step 5: Build temperature-order-parameter curve

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/polar_material_analysis.html

Creates a curve plotting the order parameter against temperature.

```bash
python plot_order_parameter.py
```

--------------------------------

### Calculator Tools Command Line Help

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/calculator_scripts.html

Overview of available calculator tools via the command line, including their usage and brief descriptions.

```text
+-------------------------------------------------------------------------------------------------------+
|                                      CALCULATOR TOOLS                                                 |
+-------------------------------------------------------------------------------------------------------+
| Usage: gpumdkit.sh -calc <type> [args...]                                                             |
+-------------------------------------------------------------------------------------------------------+
| ionic-cond <element> <charge>                 Calculate ionic conductivity from MSD data              |
| nep <input.xyz> <output.xyz> <nep_model>      Calculate energy/force/virial with a NEP model          |
| des <input.xyz> <output.npy> <nep_model> <el> Calculate NEP descriptors for one element               |
| doas <input.xyz> <nep_model> <output.txt>     Calculate density of atomistic states                   |
| neb <initial.xyz> <final.xyz> <n_images> <nep> Run NEB calculation with a NEP model                   |
| minimize <structure> <nep_model> [fmax] [n]   Minimize a structure with a NEP model                   |
| msd <trajectory.xyz> <element> <dt_fs> [n]    Calculate MSD from an extxyz trajectory                 |
| nlist [script args...]                        Build neighbor lists                                    |
| disp [script args...]                         Calculate displacement from trajectory                  |
| avg-struct [script args...]                   Calculate averaged structure                            |
| oct-tilt [script args...]                     Calculate octahedral tilt                               |
| pol-abo3 [script args...]                     Calculate local polarization for ABO3                   |
+-------------------------------------------------------------------------------------------------------+
```

--------------------------------

### Manual Active Learning Loop: Prepare DFT Calculations

Source: https://github.com/zhyan0603/gpumdkit/blob/main/skills/gpumdkit-workflows/SKILL.md

Step 3 of the manual active learning loop: prepares input files for DFT calculations.

```bash
# Step 3: Prepare SCF calculations
gpumdkit.sh  # Select: 3) Workflow -> 301
```

--------------------------------

### Define a Simple Custom Command

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/custom_commands.html

Define a custom command named 'hello' that prints a greeting and the GPUMDkit path. This command requires no arguments.

```bash
custom_hello() {
    echo "Hello, GPUMDkit user! This is a custom command."
    echo "Current GPUMDkit path: ${GPUMDkit_path}"
}
```

--------------------------------

### Select Structure Sampling Tool

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/structure_sampling.html

Navigate the interactive menu to choose the structure sampling module.

```bash
2) Sample Structures
```

--------------------------------

### 更新 Tab 补全脚本

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/zh/贡献指南.md

编辑 `Scripts/utils/completion.sh` 文件，将新标志添加到 `opts` 变量，并根据需要配置文件参数或二级选项的补全。

```bash
# 编辑 Scripts/utils/completion.sh
vim Scripts/utils/completion.sh
```

```bash
# 找到 local opts=... 行
local opts="-h -help -update -U -clean -time -plt -calc ... -your_new_flag ..."
#                                                        在此添加你的标志
```

```bash
# 找到需要文件参数的 case 并用 | 添加你的标志
-out2xyz|-out2exyz|-...|-your_new_flag)
    COMPREPLY=($(compgen -f -- "$cur")) ;;
```

```bash
case "$prev" in
    # ... 现有 case ...
    -your_new_flag)
        COMPREPLY=($(compgen -W "option1 option2 option3" -- "$cur")) ;;
    # ... 其余 case ...
esac
```

--------------------------------

### Get Help for a Specific Option

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/quick_start.html

Obtain detailed help for a specific option, such as plotting, by appending '-h' to the option.

```bash
gpumdkit.sh -plt train -h
```

--------------------------------

### MkDocs Build

Source: https://github.com/zhyan0603/gpumdkit/blob/main/CONTRIBUTING.md

Run this command if you have modified documentation files to ensure the documentation builds correctly.

```bash
# MkDocs build (if you modified documentation)
mkdocs build -f docs/mkdocs.yml
```

--------------------------------

### Get Calculator Help

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/en/polar_material_analysis.md

Access detailed argument information for specific GPUMDKit calculator functions using the -h flag.

```bash
gpumdkit.sh -calc nlist -h
```

```bash
gpumdkit.sh -calc disp -h
```

```bash
gpumdkit.sh -calc avg-struct -h
```

```bash
gpumdkit.sh -calc oct-tilt -h
```

```bash
gpumdkit.sh -calc pol-abo3 -h
```

```bash
gpumdkit.sh -plt plane-grid -h
```

--------------------------------

### 测试交互模式

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/zh/贡献指南.md

启动 `gpumdkit.sh` 进入交互模式，并导航到新添加的功能进行充分测试。

```bash
gpumdkit.sh
# 导航到你的新功能并充分测试
```

--------------------------------

### Basic GPUMDkit Usage

Source: https://github.com/zhyan0603/gpumdkit/blob/main/skills/gpumdkit-main/SKILL.md

Launch GPUMDkit in interactive mode or use command-line options. Use the -h flag for help.

```bash
# Interactive mode (menu-driven)
gpumdkit.sh

# Command-line mode
gpumdkit.sh -<option> [args...]

# Get help
gpumdkit.sh -h                    # General help
gpumdkit.sh -<option> -h          # Specific command help
gpumdkit.sh -plt -h               # Plot help
gpumdkit.sh -calc -h              # Calculator help
```

--------------------------------

### Add Command-Line Flag Handler

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/en/contributing_to_gpumdkit.md

Example of adding a new flag handler to the `case` statement in `gpumdkit.sh` for command-line argument parsing.

```bash
case $1 in
    # ... existing cases ...
    -analyze_bonds)
        if [ ! -z "$2" ] && [ "$2" != "-h" ] && [ ! -z "$3" ]; then
            python ${analyzer_path}/analyze_bonds.py $2 $3
        else
            echo " Usage: gpumdkit.sh -analyze_bonds <input.xyz> <cutoff_distance>"
            echo " Example: gpumdkit.sh -analyze_bonds structure.xyz 3.0"
            echo " Code path: ${analyzer_path}/analyze_bonds.py"
        fi ;; 
    # ... rest of cases ...
esac
```

--------------------------------

### Training Data Preparation with GPUMD-Kit

Source: https://github.com/zhyan0603/gpumdkit/blob/main/skills/gpumdkit-sampling/SKILL.md

Prepare training data by running MD simulations, filtering by distance, sampling diverse structures, and adding them to the training set.

```bash
# 1. Run MD simulation
# ... generate trajectory ...

# 2. Filter by distance
gpumdkit.sh -min_dist_pbc dump.xyz
gpumdkit.sh -filter_dist_pbc dump.xyz 1.0

# 3. Sample diverse structures
gpumdkit.sh  # Select: 2) Sample Structures -> 203

# 4. Add to training set
cat selected.xyz >> train.xyz
```

--------------------------------

### Prepare Training Data Workflow

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/custom_commands.html

This custom command automates the preparation of training data by converting VASP outputs to XYZ format, filtering outliers based on force values, and checking the quality of the filtered data using range analysis for energy. It streamlines the initial steps of setting up data for machine learning models.

```bash
custom_prep_training() {
    echo "Preparing training data..."

    # Convert VASP outputs
    gpumdkit.sh -out2xyz ./

    # Filter outliers
    gpumdkit.sh -filter_value train.xyz force 30

    # Check quality
    gpumdkit.sh -range filtered_force.xyz energy

    echo "Training data ready!"
}
```

--------------------------------

### Calculate Mean Squared Displacement (MSD)

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/index.html

Example of using the CLI mode to calculate the Mean Squared Displacement (MSD) from a trajectory file.

```bash
gpumdkit.sh -calc msd trajectory.xyz Li 10
```

--------------------------------

### 在 gpumdkit.sh 中添加命令行标志处理

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/zh/贡献指南.md

修改 `gpumdkit.sh` 脚本以识别并处理新的命令行标志，包括调用相应的 Python 脚本和提供帮助信息。

```bash
case $1 in
    # ... 现有 case ...
    -analyze_bonds)
        if [ ! -z "$2" ] && [ "$2" != "-h" ] && [ ! -z "$3" ]; then
            python ${analyzer_path}/analyze_bonds.py $2 $3
        else
            echo " Usage: gpumdkit.sh -analyze_bonds <input.xyz> <cutoff_distance>"
            echo " Example: gpumdkit.sh -analyze_bonds structure.xyz 3.0"
            echo " Code path: ${analyzer_path}/analyze_bonds.py"
        fi ;;
    # ... 其余 case ...
esac
```

--------------------------------

### Run Ionic Transport Analysis with GPUMD-Kit

Source: https://github.com/zhyan0603/gpumdkit/blob/main/skills/gpumdkit-calculators/SKILL.md

Execute MD simulations, calculate Mean Squared Displacement (MSD), and then compute ionic conductivity. Finally, visualize the results.

```bash
# 1. Run MD with compute_msd in run.in
# 2. Calculate MSD
gpumdkit.sh -calc msd dump.xyz Li 10
# 3. Calculate conductivity
gpumdkit.sh -calc ionic-cond Li 1
# 4. Visualize
gpumdkit.sh -plt msd
gpumdkit.sh -plt sdc
```

--------------------------------

### Step 2: Build neighbor lists

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/polar_material_analysis.html

Builds neighbor lists from the averaged structure file 'model.xyz' for displacement and polarization calculations.

```bash
gpumdkit.sh -calc nlist model.xyz
```

--------------------------------

### Python 脚本参数解析和依赖通知

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/zh/贡献指南.md

Python 脚本应使用 `sys.argv` 进行参数解析，并提供清晰的使用和示例信息。如果使用重型包，应添加 `print_dependency_notice()`。

```python
import sys

# ...
print("Usage: ...")
print("Example: ...")

# 如果你的脚本使用重型/特殊包（`NepTrain`、`calorine`、`dpdata`），请添加
# print_dependency_notice() 函数以通知用户引用建议
```

--------------------------------

### Launch NEP Modifier Utility

Source: https://github.com/zhyan0603/gpumdkit/blob/main/Scripts/utils/README.md

Starts an interactive utility for editing NEP model files. Refer to the specific README files for detailed usage.

```bash
gpumdkit.sh -nep_modifier
```

--------------------------------

### Change Directory to SLURM Submit Directory

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/active_learning_workflow.html

Ensures the correct working directory is set for the job submission. This command should be executed before proceeding with other setup steps.

```bash
cd $SLURM_SUBMIT_DIR
```

--------------------------------

### Analyze Perovskite Structures with GPUMD-Kit

Source: https://github.com/zhyan0603/gpumdkit/blob/main/skills/gpumdkit-calculators/SKILL.md

Build neighbor lists for specific elements, calculate atomic displacements, and determine octahedral tilts and polarization for ABO3 perovskites.

```bash
# 1. Build neighbor lists
gpumdkit.sh -calc nlist -i model.xyz -c 4 -n 12 -C Ti -E O
gpumdkit.sh -calc nlist -i model.xyz -c 4 -n 12 -C Ti -E Pb
# 2. Calculate displacements
gpumdkit.sh -calc disp -i movie.xyz -n nl-Ti-O.dat -o disp.dat
# 3. Calculate tilt
gpumdkit.sh -calc oct-tilt -i movie.xyz -n nl-Ti-O.dat -o tilt.dat
# 4. Calculate polarization
gpumdkit.sh -calc pol-abo3 -i movie.xyz --nl-ba nl-Ti-Pb.dat --nl-bo nl-Ti-O.dat --bec Pb=2.5 Ti=4.0 O=-2.0
```

--------------------------------

### Python Script Parameter Parsing

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/zh/贡献指南.html

Use sys.argv for parameter parsing in Python scripts, consistent with existing scripts. Provide clear usage and example information.

```python
# Write clear, maintainable code
# Use meaningful variable names
# Use sys.argv for parameter parsing (consistent with most existing scripts)
# Provide clear usage information: print("Usage: ...") and print("Example: ...")
# If your script uses heavy/special packages (NepTrain, calorine, dpdata), add a print_dependency_notice() function to notify users of suggested citation
```

--------------------------------

### Get Specific Frame from extxyz

Source: https://github.com/zhyan0603/gpumdkit/blob/main/Scripts/format_conversion/README.md

Use this script to extract a specific frame from an extxyz file by its index. Ensure the extxyz file and frame index are provided.

```python
python get_frame.py <extxyz_file> <frame_index>
```

```sh
python get_frame.py dump.xyz 1000
```

```sh
gpumdkit.sh -get_frame dump.xyz 1000
```

--------------------------------

### Launch GPUMDkit Interactive Menu

Source: https://github.com/zhyan0603/gpumdkit/blob/main/Scripts/README.md

Run this command to launch the interactive menu for GPUMDkit. Navigate through numbered options to access different functionalities.

```bash
gpumdkit.sh
```

```text
         ____ ____  _   _ __  __ ____  _    _ _
        / ___|  _ \| | | |  \/  |  _ \| | _(_) |_
       | |  _| |_) | | | | |\/| | | | | |/ / | __|
       | |_| |  __/| |_| | |  | | |_| |   <| | |_
        \____|_|    \___/|_|  |_|____/|_|\_\_|__|

        GPUMDkit Version 1.5.6 (dev) (2026-06-17)
  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: 
```

--------------------------------

### Ionic Conductivity Calculation Output

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/en/calculator_scripts.md

Example output format for the ionic conductivity calculation, showing diffusivity and ionic conductivity values for x, y, z, and total directions.

```text
Diffusivity (D):
  D_x: 4.153e-07 cm^2/s
  D_y: 4.174e-07 cm^2/s
  D_z: 2.610e-07 cm^2/s
  D_total: 3.646e-07 cm^2/s
------------------------------
Ionic Conductivity:
  Sigma_x: 2.576e-02 mS/cm
  Sigma_y: 2.589e-02 mS/cm
  Sigma_z: 1.619e-02 mS/cm
  Sigma_total: 2.261e-02 mS/cm
```

--------------------------------

### Launch GPUMDkit Interactive Mode

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/format_conversion.html

To access the format conversion tools, first launch the GPUMDkit interactive shell. Then, select option '1' for Format Conversion from the main menu.

```bash
gpumdkit.sh
```

```bash
1) Format Conversion
```

--------------------------------

### Average Selected Frames in Trajectory

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/en/polar_material_analysis.md

Generates an averaged structure from a selected slice of frames in an input trajectory file. Specify start, stop, and step indices for the slice.

```bash
gpumdkit.sh -calc avg-struct -i movie.xyz -s 100 -t 500 -p 2 -o avg_slice.xyz
```

--------------------------------

### Organize Workflow Files

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/active_learning_workflow.html

Creates necessary directories and moves input files to their respective locations. This step ensures proper file organization for the simulation and common resources.

```bash
mkdir 00.md common
```

```bash
mv ${work_dir}/{nep.txt,nep.in,*.xyz,run_*.in,INCAR,KPOINTS,POTCAR} ./common
```

```bash
cp ${work_dir}/common/$sample_xyz_file ${work_dir}/00.md
```

--------------------------------

### Launch NEP Modifier Interactively

Source: https://github.com/zhyan0603/gpumdkit/blob/main/Scripts/utils/nep_modifier/README.md

Start the NEP Modifier tool in interactive mode by running the script. The tool will prompt for input files and then present a menu of operations.

```bash
python nep_modifier.py
```

--------------------------------

### Renumber LAMMPS Atom IDs

Source: https://github.com/zhyan0603/gpumdkit/blob/main/Scripts/utils/README.md

Rewrites atom IDs in LAMMPS dump files to start from 1 in each frame. Specify the input and output dump file names.

```bash
gpumdkit.sh -re_atoms dump.lammpstrj renumbered.lammpstrj
```

--------------------------------

### Register New Feature in Main Script

Source: https://github.com/zhyan0603/gpumdkit/blob/main/skills/gpumdkit-contributing/SKILL.md

Example of how to register a new interactive feature's wrapper function within the main gpumdkit.sh script's case statement.

```bash
"413") f413_new_feature ;;
   
```

--------------------------------

### Add New Interactive Script Wrapper

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/en/contributing_to_gpumdkit.md

Example of a shell function to wrap a new Python script for interactive mode. It prints header information and captures arguments for the script.

```bash
function f111_new_converter(){
echo " >-------------------------------------------------<"
echo " | Calling the script in Scripts/format_conversion |"
echo " | Script: new_converter.py                        |"
echo " | Developer: Your Name (your@email.com)           |"
echo " >-------------------------------------------------<"
echo " Input <required_param1> <required_param2>"
echo " Example: input.xyz output.lmp"
echo " ------------>>"
read -r -a converter_args
echo " ---------------------------------------------------"
python ${GPUMDkit_path}/Scripts/format_conversion/new_converter.py "${converter_args[@]}"
echo " Code path: ${GPUMDkit_path}/Scripts/format_conversion/new_converter.py"
echo " ---------------------------------------------------"
}
```

--------------------------------

### Active-Learning Workflow Steps

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/en/workflow_scripts.md

Outlines the common steps involved in an active learning loop for improving NEP models, from MD simulation to retraining.

```text
1. run MD with the current `nep.txt`;
2. collect `dump.xyz` or `active.xyz`;
3. remove unphysical structures;
4. select diverse or uncertain structures;
5. run DFT single-point calculations;
6. convert DFT results to extxyz;
7. append new structures to `train.xyz`;
8. retrain the NEP model.
```

--------------------------------

### Calculate Displacements

Source: https://github.com/zhyan0603/gpumdkit/blob/main/skills/gpumdkit-calculators/SKILL.md

Computes atomic displacements from a trajectory using a pre-built neighbor list. Supports optional frame slicing with start, stop, step, and last fraction parameters.

```bash
gpumdkit.sh -calc disp -i <trajectory.xyz> -n <neighbor_list> -o <output>

# Example
gpumdkit.sh -calc disp -i movie.xyz -n nl-Pb-O.dat -o displacements.dat

# Optional frame slicing: -s <start> -t <stop> -p <step> -l <last_fraction>
```

--------------------------------

### Extract Frames by Fractional Range

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/command_reference.html

Extracts frames from an XYZ file within a specified fractional range. Provide the input XYZ file, start fraction, and end fraction.

```bash
gpumdkit.sh -frame_range <input.xyz> <start_frac> <end_frac>
```

--------------------------------

### Structure Sampling Tools Menu

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/structure_sampling.html

Overview of available structure sampling tools within the GPUMDkit interactive menu.

```bash
+------------------------------------------------------+
|                 SAMPLE STRUCTURE TOOLS               |
+------------------------------------------------------+
| 201) Sample structures from extxyz                   |
| 202) PyNEP sampling [deprecated]                    |
| 203) FPS sampling by NepTrain [preferred]            |
| 204) Perturb structure                               |
| 205) Select max force deviation structs              |
+------------------------------------------------------+
| 000) Return to the main menu                         |
+------------------------------------------------------+
Input the function number:
```

--------------------------------

### Implement Command-Line Analyzer Script

Source: https://github.com/zhyan0603/gpumdkit/blob/main/CONTRIBUTING.md

Create a Python script for command-line analysis. Ensure it handles argument parsing and includes usage instructions.

```python
import sys

if len(sys.argv) != 3:
    print("Usage: gpumdkit.sh -analyze_bonds <input.xyz> <cutoff_distance>")
    print("Example: gpumdkit.sh -analyze_bonds structure.xyz 3.0")
    sys.exit(1)

input_file = sys.argv[1]
cutoff = float(sys.argv[2])

# Your implementation here
```

--------------------------------

### Create Claude Code Skills Symlinks (One-liner)

Source: https://github.com/zhyan0603/gpumdkit/blob/main/skills/README.md

A concise one-liner command to create symbolic links for all GPUMDkit skills in the .claude/skills directory. This automates the setup for Claude Code.

```bash
mkdir -p .claude/skills && cd .claude/skills && for skill in ../../skills/gpumdkit-*/; do ln -s "$skill" .; done && cd ../..

```

--------------------------------

### Enter Interactive Mode

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/en/polar_material_analysis.md

Access the GPUMDKit calculator tools by running the main script and selecting the 'Calculators' option.

```bash
gpumdkit.sh
# choose 4) Calculators
```

--------------------------------

### View GPUMDkit Help Information

Source: https://github.com/zhyan0603/gpumdkit/blob/main/README.md

Use the -h flag to display the main help table for GPUMDkit. This provides an overview of available functions and options.

```bash
gpumdkit.sh -h
```

--------------------------------

### Sample Structures using NepTrain

Source: https://github.com/zhyan0603/gpumdkit/blob/main/Scripts/README.md

Selects structures for Neural Equipotential (NEP) training using a uniform sampling strategy. This is an example of accessing a sub-menu within the 'gpumdkit.sh' interactive mode.

```bash
gpumdkit.sh
```

```bash
python Scripts/sample_structures/sample_structures.py train.xyz uniform 100
```

--------------------------------

### Interactive Workflow Selection

Source: https://github.com/zhyan0603/gpumdkit/blob/main/Scripts/workflow/README.md

Demonstrates how to navigate the GPUMDkit interactive shell to access workflow functionalities, specifically SCF and MD sample batch pretreatment.

```bash
         ____ ____  _   _ __  __ ____  _    _ _
        / ___|  _ \| | | |  \/  |  _ \| | _(_) |_
       | |  _| |_) | | | | |\/| | | | | |/ / | __|
       | |_| |  __/| |_| | |  | | |_| |   <| | |_
        \____|_|    \___/|_|  |_|____/|_|\_\_|__|

        GPUMDkit Version 1.5.6 (dev) (2026-06-17)
  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:
 3
 ------------>>
 301) SCF batch pretreatment
 302) MD sample batch pretreatment (gpumd)
 303) MD sample batch pretreatment (lmp)
 000) Return to the main menu
 ------------>>
 Input the function number:
```

--------------------------------

### Get averaged structures from trajectories

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/htmls/en/polar_material_analysis.html

Iterates through trajectory files ending in 'K.xyz' and computes the averaged structure from the last 50% of frames. This is useful for obtaining representative structures at different temperatures.

```bash
for f in *K.xyz; do
  tag="${f%.xyz}"
  gpumdkit.sh -calc avg-struct -i "$f" -l 0.5 -o "${tag}-avg.xyz"
done
```

--------------------------------

### 提交修改

Source: https://github.com/zhyan0603/gpumdkit/blob/main/docs/tutorials/zh/贡献指南.md

使用 `git add .` 暂存所有更改，然后使用 `git commit -m "..."` 提交更改，并附带清晰的描述信息。

```bash
git add .
git commit -m "你的描述性信息"
```
Tokens:
Raw