📦 结构采样

结构采样用于从轨迹中选择候选结构、生成扰动结构，或根据模型偏差挑选值得进一步计算的结构。

脚本位置： Scripts/sample_structures/

交互模式入口

gpumdkit.sh

选择：

2) Sample Structures

菜单如下：

+------------------------------------------------------+
|                 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              |
| 206) Split training and test sets                    |
+------------------------------------------------------+
| 000) Return to the main menu                         |
+------------------------------------------------------+
Input the function number:

常用功能：

菜单	方法	用途
201	uniform/random	从轨迹中均匀或随机抽帧
202	PyNEP notice	只打印提示；真正运行 PyNEP 请用 `gpumdkit.sh -pynep`
203	NepTrain FPS	使用 NepTrain 描述符的 FPS 采样
204	perturb	从 POSCAR/CONTCAR 生成扰动结构
205	force deviation	从 active learning 输出中选择高偏差结构
206	训练集/测试集划分	检查 extxyz 数据集并使用均匀、随机或 FPS 方法划分

均匀/随机采样

交互模式选择 201，会看到：

Input <extxyz_file> <sampling_method> <num_samples> [skip_num]
[skip_num]: number of initial frames to skip, default value is 0
Sampling_method: 'uniform' or 'random'
Example: train.xyz uniform 50
------------>>

例如输入：

dump.xyz uniform 50

或：

dump.xyz random 100 500

参数含义：

参数	含义
`dump.xyz`	输入轨迹
`uniform` / `random`	采样方法
`50` / `100`	采样结构数
`500`	可选，跳过前 500 帧

输出：

sampled_structures.xyz

NepTrain FPS

NepTrain 版本的 FPS。交互模式选择 203；也可以直接运行脚本：

python Scripts/sample_structures/parallel_neptrain_select_structs.py dump.xyz train.xyz nep.txt [threads]

描述符计算默认使用 1 个 CPU 工作进程。可将第 4 个可选参数设为正整数以启用并行计算，例如 4。每个工作进程会各自加载一份 NEP 模型，并使用 1 个原生 OpenMP 线程，因此用户指定的工作进程数就是描述符计算的总并行度。

交互模式选择 203，会看到：

Input <sample.xyz> <train.xyz> <nep_model> [threads]
[threads]: descriptor threads, default value is 1
Example: dump.xyz train.xyz nep.txt 4
------------>>

输入：

文件	含义
`dump.xyz`	候选结构
`train.xyz`	当前训练集
`nep.txt`	用于计算描述符的 NEP 模型
`threads`	可选的描述符工作进程数；默认值为 `1`

输出：

selected.xyz
select.png
pca_sample.txt
pca_train.txt
pca_selected.txt

运行时可以选择按最小距离阈值采样，或指定采样结构数。脚本随后会打印：

Choose selection method:
1) Select structures based on minimum distance
2) Select structures based on number of structures
------------>>

该功能需要 NepTrain，运行时会提示相关引用。

训练集和测试集划分

交互模式选择 206，可以检查一个 extxyz 数据集并将其划分为训练集和测试集。脚本会先显示元素种类、总帧数以及每帧原子数范围，然后询问测试集大小和选择方法。

交互入口：

gpumdkit.sh -> 2) Sample Structures -> 206

首先根据提示输入文件名：

Input <extxyz_file>
Example: data.xyz
------------>>

测试集大小支持两种输入形式：

输入	含义
`0.1`	选择约 10% 的结构作为测试集
`100`	选择恰好 100 个结构作为测试集

使用比例时，测试集帧数采用四舍五入（半数向上），并且至少选择一帧。测试集帧数必须小于数据集总帧数，以保证训练集不为空。

可以选择三种方法：

方法	行为	额外输入
Uniform	在整个数据集索引范围内均匀选择	无
Random	无放回随机选择	可选的整数随机种子
FPS	使用逐结构平均的 NEP 原子描述符选择多样化结构	与数据元素兼容的 `nep.txt`

随机划分时输入固定种子可以复现结果，直接回车则不固定种子。FPS 沿用功能 203 的 NepTrain 描述符思路：从第一帧开始，逐次选择距离当前已选结构最远的帧。

如果输入文件为 data.xyz，输出为：

data_train.xyz：所有未被选入测试集的结构；
data_test.xyz：选中的测试结构。

两个输出文件都会保持各自结构在原始输入中的先后顺序。也可以直接运行脚本，但后续选择仍采用交互方式：

python Scripts/sample_structures/split_train_test.py data.xyz

均匀和随机划分需要 numpy 与 ase；FPS 还需要 NepTrain、scipy，以及与数据集元素兼容的 NEP 模型。

PyNEP 旧入口

PyNEP FPS 仍然保留兼容，但只通过 -pynep 入口调用。

如果在交互菜单中选择 202，会看到：

+-------------------------------------------------+
| Function 202 is no longer supported here.       |
| PyNEP package is no longer actively maintained. |
| Please use 203) NepTrain sampling instead.      |
| If you still need PyNEP compatibility, run:     |
|                 gpumdkit.sh -pynep              |
+-------------------------------------------------+

串行 PyNEP

python Scripts/sample_structures/pynep_select_structs.py dump.xyz train.xyz nep.txt

并行 PyNEP

python Scripts/sample_structures/parallel_pynep_select_structs.py dump.xyz train.xyz nep.txt 8

最后一个参数是 CPU 线程数。

GPUMDkit 入口

gpumdkit.sh -pynep

随后输入：

dump.xyz train.xyz nep.txt 8

这个入口需要 pynep。

结构扰动

交互模式选择 204；也可以直接运行脚本：

python Scripts/sample_structures/perturb_structure.py POSCAR 20 0.03 0.2 uniform

交互模式选择 204，会看到：

Input <input.vasp> <pert_num> <cell_pert_fraction> <atom_pert_distance> <atom_pert_style>
The default parameters for perturb are 20 0.03 0.2 uniform
Example: POSCAR 20 0.03 0.2 uniform
------------>>

参数含义：

参数	含义
`POSCAR`	输入结构
`20`	生成结构数
`0.03`	晶胞扰动比例
`0.2`	原子扰动距离，单位 Angstrom
`uniform`	扰动方式，可选 `normal`、`uniform`、`const`

输出：

POSCAR_01.vasp、POSCAR_02.vasp 等

该功能需要 dpdata。使用此功能时建议引用 dpdata 包。

最大力偏差结构选择

该功能需要配合 GPUMD 的 active 命令使用。active 通过委员会评审机制，让多条势函数对同一结构进行预测，并记录每个结构的最大力偏差。select_max_modev.py 会从 active.out 和 active.xyz 中选择力偏差较大的结构，写入 selected.xyz。

交互模式选择 205；也可以直接运行脚本：

python Scripts/sample_structures/select_max_modev.py 200 0.15

交互模式选择 205，会看到：

+----------------------------------------------------+
| Select max force deviation structs from active.xyz |
|     generated by the active command in gpumd.      |
+----------------------------------------------------+
Input <structs_num> <threshold> (eg. 200 0.15)
------------>>

需要当前目录下有：

active.out
active.xyz

输出：

selected.xyz

帧范围提取

frame_range.py 是一个独立的 CLI 工具，不在结构采样交互菜单 201–206 中。它适合在采样前先截取轨迹的一段，例如只保留平衡后的后半段轨迹。

gpumdkit.sh -frame_range dump.xyz 0 0.8
python Scripts/sample_structures/frame_range.py dump.xyz 0 0.8

这会写入轨迹 0% 到 80% 的帧。参数使用轨迹比例，范围为 0 到 1。

示例命令

下面是一个常见的采样前处理顺序：先用分析工具检查和过滤候选轨迹，再进行 FPS 采样。前两个命令属于分析工具，最后一步属于本页的结构采样。

gpumdkit.sh -min_dist_pbc dump.xyz
gpumdkit.sh -filter_box dump.xyz 13
python Scripts/sample_structures/parallel_neptrain_select_structs.py dump.xyz train.xyz nep.txt 4

最后一步也可以在交互模式中选择 2) 结构采样 → 203。

常见问题

问题	建议
FPS 选出太多相似结构	调大距离阈值或限制最大选择数
扰动结构不合理	减小 `cell_pert` 和 `atom_pert`
`active.out` 和 `active.xyz` 不匹配	确保来自同一次 GPUMD active 运行
PCA 图异常	检查 `nep.txt` 是否和两个数据集元素一致
FPS 划分无法加载模型	检查 NepTrain 是否安装，并确认 `nep.txt` 支持数据集中的全部元素
随机划分每次结果不同	输入固定的整数随机种子