📦 结构采样

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

脚本位置： 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              |
+------------------------------------------------------+
| 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 输出中选择高偏差结构

均匀/随机采样

交互模式选择 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/neptrain_select_structs.py dump.xyz train.xyz nep.txt

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

Input <sample.xyz> <train.xyz> <nep_model>
Example: dump.xyz train.xyz nep.txt
------------>>

输入：

文件	含义
`dump.xyz`	候选结构
`train.xyz`	当前训练集
`nep.txt`	用于计算描述符的 NEP 模型

输出：

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，运行时会提示相关引用。

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–205 中。它适合在采样前先截取轨迹的一段，例如只保留平衡后的后半段轨迹。

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/neptrain_select_structs.py dump.xyz train.xyz nep.txt

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

常见问题

问题	建议
FPS 选出太多相似结构	调大距离阈值或限制最大选择数
扰动结构不合理	减小 `cell_pert` 和 `atom_pert`
`active.out` 和 `active.xyz` 不匹配	确保来自同一次 GPUMD active 运行
PCA 图异常	检查 `nep.txt` 是否和两个数据集元素一致