🔧 工作流脚本

工作流脚本用于批量准备 DFT、MD 和 NEP 数据处理任务。

工作流脚本只准备目录、输入文件和链接，不替用户提交计算。

脚本位置： Scripts/workflow/

交互入口

普通用户优先使用交互菜单：

gpumdkit.sh

选择：

3) Workflow

菜单如下（菜单文字保持程序实际输出）：

+---------------------------------------------------------+
|                      WORKFLOW TOOLS                     |
+---------------------------------------------------------+
| 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:

菜单	工作流	适用场景
301	SCF 批处理预处理（SCF batch pretreatment）	为多个结构准备 DFT 单点目录
302	GPUMD MD 采样批处理预处理	为 GPUMD 采样准备多个目录
303	LAMMPS MD 采样批处理预处理	为 LAMMPS 采样准备多个目录

1. 准备 DFT 单点计算

本节先说明输入文件和单点目录的准备。

请在专用工作目录中操作，并把原始结构另行保存。脚本会在当前目录创建 struct_fp/、struct_md/、计算目录和 presub.sh 等内容。

VASP 单点预处理（301 -> 1）

输入可以是多个 .vasp 文件，或一个 extxyz 文件：

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

也可以是：

current directory/
└── sampled.xyz

脚本按以下顺序选择输入：

有一个或多个 .vasp 时优先处理 .vasp；
.vasp 和 .xyz 同时存在时给出提示，只处理 .vasp；
没有 .vasp 且只有一个 .xyz 时，将该 extxyz 转成 POSCAR；
没有 .vasp 且有多个 .xyz 时，让用户选择文件。

运行菜单：

gpumdkit.sh
# 选择 3 -> 301 -> VASP

运行后通常得到：

current directory/
├── struct_fp/
│   ├── POSCAR_1.vasp
│   └── ...
├── fp/
├── <prefix>_1/
├── <prefix>_2/
└── presub.sh

fp/ 由脚本创建。准备结束后，把已经确认的 INCAR、POTCAR 和 KPOINTS 放入 fp/；各计算目录会链接这里的文件。输入的 prefix 会成为计算目录前缀，之后用 out2xyz 提取结果时，目录名会写入 extxyz 的 config_type。

CP2K 单点预处理（301 -> 2）

先准备 extxyz 文件和模板。模板必须从 pos.xyz 读取坐标，参考模板为 Scripts/workflow/cp2k_template.inp。通过菜单运行：

gpumdkit.sh
# 选择 3 -> 301 -> CP2K

交互输入为：

<extxyz_file> <template.inp> <prefix_name>

例如：

dump.xyz template.inp H2O

脚本为每个结构创建 <prefix>_<index>/，并写入 input.inp 和 pos.xyz。

源码用户也可以直接调用脚本。下面的相对路径要求从 GPUMDkit 仓库根目录运行，并将输入文件名改为实际数据路径；也可以在数据目录中使用脚本的绝对路径。通过 Conda 安装的用户优先使用上面的菜单。

python Scripts/workflow/scf_batch_pretreatment_cp2k.py train.xyz template.inp calc

2. 准备 MD 采样目录

GPUMD（302）

把 .vasp 文件或一个 extxyz 文件放在专用工作目录中。输入选择规则与 VASP 预处理相同：.vasp 优先；没有 .vasp 且有多个 .xyz 时会让用户选择。

gpumdkit.sh
# 选择 3 -> 302

典型输入：

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

或：

current directory/
└── dump.xyz

运行后通常得到：

current directory/
├── struct_md/
│   ├── model_1.xyz
│   └── ...
├── md/
├── sample_1/
├── sample_2/
└── presub.sh

准备结束后，把已确认的 nep.txt 和每个样本对应的 run_*.in 放入 md/。例如 run_1.in 链接到 sample_1/run.in，run_2.in 链接到 sample_2/run.in。

LAMMPS（303）

把 .vasp 文件或一个 extxyz 文件放在专用工作目录中；两种格式同时存在时优先处理 .vasp。

gpumdkit.sh
# 选择 3 -> 303

运行后会在 struct_md/ 中创建 LAMMPS data 文件，并创建样本目录、md/ 和 presub.sh：

current directory/
├── struct_md/
│   ├── lammps_1.data
│   └── ...
├── md/
├── sample_1/
├── sample_2/
└── presub.sh

准备结束后，把已确认的 lmprun.in 和 nep.txt 放入 md/。

3. 运行前确认与结果检查

在按自己的执行流程提交前，逐项检查：

输入结构数量、原子和 type 顺序、晶胞以及生成目录数量；
fp/ 中的 INCAR、POTCAR、KPOINTS，或 md/ 中的 nep.txt、 run_*.in、lmprun.in；
每个样本目录的符号链接和文件名；
presub.sh 中的可执行文件、资源和调度设置。

presub.sh 只是脚本模板。它不会证明输入正确，也不会代表已经获准提交。先检查生成目录和链接，再由项目自己的执行流程运行。完成后检查退出状态、日志、温度、能量、压力、晶胞和轨迹，确认没有失败或不完整的样本。

4. 后处理与下一步

DFT 结果完成并经过检查后，使用与 DFT 程序相符的转换入口：

VASP 结果：

gpumdkit.sh -out2xyz <scf_results_directory>

如果 OUTCAR 包含完整的 BORN EFFECTIVE CHARGES 数据块，并且需要保留逐原子的 BEC 标签，可以使用：

gpumdkit.sh -out2xyz_bec <scf_results_directory>

CP2K 日志与结构文件：先进入 CP2K 结果根目录，再运行以下命令。它会递归扫描当前目录下的 .log 及配套 .xyz/.inp，成功转换后写入当前目录的 cp2k_exyz.xyz，并用 Logfile.txt 记录处理情况。

gpumdkit.sh -cp2k2xyz

VASP 的 -out2xyz/菜单 101 和带 BEC 的 -out2xyz_bec 会在当前目录生成 NEPdataset/train.xyz；Python 版 -out2exyz 会在当前目录写入 train.xyz。请根据转换入口继续使用实际生成的文件，并保留原始 DFT 输出。

主动学习式流程

需要开展 NEP 数据迭代时，按“MD 轨迹 → 几何筛选 → NepTrain FPS → DFT → 转换 → 数据集检查”的顺序操作，各阶段的检查要点见主动学习工作流。

使用建议

工作流脚本和集群、模板及软件版本有关，正式批量处理前先用少量结构检查。
保留模板和原始结构，并在继续前检查生成目录、链接和文件名。

AI 辅助与授权边界

工作流脚本和集群、模板、软件版本有关。agent 不得从示例或其他材料体系推断势函数、元素/type 映射、温度、时间步长、系综、压力、运行长度、筛选阈值、资源或收敛标准，也不能把 INCAR、POTCAR、KPOINTS、run.in、 CP2K 模板或 nep.txt 当作已批准文件。准备目录不等于授权运行 DFT、GPUMD、 LAMMPS 或 NEP；执行和调度提交必须由用户明确要求。

需要开发者直接调用源码时，先确认仓库根目录、解释器和依赖，再使用目标脚本自己的帮助。普通用户应优先使用已有菜单；没有 CLI 路由的功能不能凭空写成 CLI 命令。遇到解析错误、缺少文件、NaN/Inf、失败输出或未解释的警告时，应停止并报告。