FPS Filter

Group: Filter | Class: FPSFilterDataCard

What the card does

基于结构级 NEP 均值描述符执行最远点采样（FPS），从大批量结构中挑选代表性子集。需要提供一个 NEP 模型文件（如内置的 nep89.txt 或你自己训练的模型）用于生成描述符。代表性是相对于这个模型的描述符空间而言的；换一个 NEP 模型，结构间距离和最终选择都可能改变。

The card provides two sampling strategies:

global：兼容原有行为，对全部结构执行一次全局 FPS；没有已有训练集时固定从输入第 1 个结构开始；
element_set: groups structures by element set, assigns at least one slot per group, distributes the remaining slots by the square root of group size, and starts FPS from each group center. This mode still uses the original structure-mean descriptor and does not enable experimental per-element mean/std features or robust scaling.

\[\mathbf{d}_i=\frac{1}{N_i}\sum_{a=1}^{N_i}\mathbf{d}_{ia}^{\mathrm{NEP}}\]

\[i_t=\arg\max_j\ \min_{i\in S_{t-1}}\lVert\mathbf{d}_j-\mathbf{d}_i\rVert_2,\quad S_t=S_{t-1}\cup\{i_t\}\]

Example workflow

Scenario: 2,000 candidates perform worse than 200 selected structures

Several generators produce 2,000 candidates and all are labeled by DFT, yet the retrained model is worse than one trained on 200 manually selected structures. Heavy duplication diluted effective diversity.

Diagnosis: Generated pools often contain statistical redundancy: 200 random vacancies may represent only 15 distinct local environments. FPS greedily chooses points farthest from the selected set in descriptor space, preserving diversity while removing near-duplicates.

Input: 2,000 cleaned candidates and a usable NEP model file.

Objective: Select 200 representative structures.

Parameters: set strategy="global", point nep_path to a NEP model, use n_samples=200, and set min_distance=0.01.

输出： 最多 200 个结构，以贪心最远点规则扩展描述符空间覆盖。FPS 不保证全局最优，也不保证关键物性误差一定优于随机抽样。

How to verify selection quality:

After retraining, compare the 200 FPS-selected structures with 200 random structures on the same independent test set; do not assume FPS must be better.
If 200 is insufficient, increase num_condition, for example to 500.
If selected structures remain redundant, test a larger min_distance_condition, such as 0.05-0.1.
FPS selects but never generates. A missing configuration family cannot appear unless it exists in the input pool.

Scenario: multiple chemical systems share one candidate pool

When a candidate pool contains unary, binary, and ternary structures, global FPS makes every structure compete for one budget. Choose element_set when every element set must retain at least one candidate. For example, V, Co, Ni, V-Co, V-Ni, Co-Ni, and V-Co-Ni form seven groups; if n_samples < 7, the card raises an explicit error instead of silently omitting groups.

已有训练集可作为 warm start，卡片会优先选择当前训练集尚未覆盖的区域。global 模式把全部已有结构作为距离起点；element_set 模式只比较元素集合相同的已有结构。已有训练集不计入 n_samples 输出数量。

这里“元素集合”只看出现过哪些元素，不看化学计量比。例如 H₂O 和 H₂O₂ 都属于 {H, O} 组。

When to add this card

Add it when:

A generation chain produced hundreds of structures and needs deduplication
The pool likely contains many duplicate or highly similar configurations
The dataset must be compressed while retaining coverage
The pool mixes multiple element sets and each group needs an explicit budget.

Do not add it when:

The pool is still small
The input pool has not yet been physically cleaned
No suitable NEP model is available for descriptors

Parameters

Descriptor NEP Model（nep_path）

str。指向用于生成 NEP 描述符的模型文件，界面默认使用内置 nep89.txt。路径为空或文件不存在时卡片直接报错。内置模型便于快速筛选；正式数据选择更适合使用覆盖候选化学体系和局域环境的模型。

Maximum Structures to Keep（n_samples）

int，默认 100。FPS 过滤后保留结构数的上限。这是输出数量，不是上游生成数量。若候选数更少，最多保留全部候选；若距离阈值提前触发，实际输出也会少于该值。

Descriptor Distance Cutoff（min_distance）

float，默认 0。描述符空间中的最小距离阈值，没有物理单位，而且数值尺度依赖 NEP 模型。

0：关闭距离提前停止，按数量上限选择；
>0：下一个最远候选与已覆盖集合的距离低于该值时提前停止。

值越大去重越激进，也越可能选不够目标数量。不要把某个模型上合适的阈值直接照搬到另一个模型。

Backend（backend）

str, default 'auto'. Descriptor backend. Keep automatic selection unless diagnosing performance or backend differences.

Chunk Max Atoms（chunk_max_atoms）

int, default 100000. Maximum total atom count in each descriptor calculation chunk, with the same meaning on CPU and CUDA. Reduce it when device or host memory is insufficient. This is not a structure count; it limits the sum of atoms across all structures in the chunk.

Sampling Strategy（strategy）

str, default "global". Available values:

Value	Behavior
`global`	兼容旧流程；全部结构共享一个预算，没有 warm start 时从输入索引 0 开始
`element_set`	Groups by element set, allocates slots by square root, and starts FPS from the descriptor center of each group.

Legacy card JSON without this field restores as global, preventing silent output changes when older workflows are loaded.

Existing Dataset Path（existing_dataset_path）

str，默认空字符串。指向已有 .xyz 或 .extxyz 训练集，作为描述符覆盖的 warm start。global 模式与全部已有结构比较；element_set 只与同元素集合结构比较。路径不存在、无法读取或不含结构时明确报错。

Recommended presets

Legacy-compatible workflow

{
  "class": "FPSFilterDataCard",
  "check_state": true,
  "params": {
    "nep_path": "path/to/nep.txt",
    "n_samples": 100,
    "min_distance": 0.0,
    "backend": "auto",
    "chunk_max_atoms": 100000,
    "strategy": "global",
    "existing_dataset_path": ""
  }
}

Balanced sampling across element sets

{
  "class": "FPSFilterDataCard",
  "check_state": true,
  "params": {
    "nep_path": "path/to/nep.txt",
    "n_samples": 330,
    "min_distance": 0.01,
    "backend": "auto",
    "chunk_max_atoms": 100000,
    "strategy": "element_set",
    "existing_dataset_path": "path/to/train.xyz"
  }
}

Recommended combinations

任意生成链 → Geometry Filter → FPS Filter：先去掉明显坏结构，再做代表性筛选
FPS Filter -> DFT export: bound the number of expensive labels
Merged branch outputs -> FPS Filter: select across all branches consistently

Common questions

NEP file does not exist. Correct nep_path to an existing model file.

输出数量远小于目标上限。 描述符距离阈值太严，无法选出足够多满足距离约束的结构。降低该阈值，或设为 0 只按数量停止。

Balanced mode reports an insufficient target count. n_samples is smaller than the number of element-set groups. Increase the target or remove chemical systems that are not needed in this run upstream.

The existing training set does not change the result. The warm start compares only structures with matching element sets. Check that the candidate pool and existing training set use consistent element sets and that the NEP model supports those elements.

Coverage remains incomplete. FPS cannot create absent environments. Add the missing diversity upstream.

描述符计算很慢。 大批量时描述符计算可能耗时。chunk_max_atoms 控制单批总原子数；它不是最终 FPS 的分块采样参数，减小它只降低计算峰值内存，不会改变选择算法。

Output labels

No dedicated Config_type is added; selected structures preserve their existing labels.

Reproducibility

There is no randomness: identical inputs and parameters produce identical output. global retains the original index-0 starting point, so reordering the input may change the selection; element_set starts from each group descriptor center and is more stable to input order. Near-duplicate structures with identical features may exchange original indices, but their coverage is equivalent.