Geometry Filter

Group: Filter | Class: GeometryFilterCard

What the card does

Geometry Filter 按显式阈值过滤候选结构：最短原子间距、单原子体积、质量密度和有效晶胞。它不计算能量，不修复结构，也不替代 FPS Filter。它的职责是在代表性采样和 DFT 前挡掉几何上已经明显不可用的结构。

空结构和含 NaN/Inf 坐标的结构始终被删除。其他阈值默认关闭，避免用一个通用数值误删含氢分子、slab 或带真空结构。

短距离检查会把整批结构交给原生邻居扫描一次完成；原生扩展不可用或遇到合法的奇异部分周期晶胞时，自动使用同一距离语义的 Python fallback。这个加速只改变响应时间，不改变阈值和筛选结果。

卡片中的保留/删除数量预览在后台计算，不会占用界面事件循环。连续调整参数时，中间请求会被合并，界面只采用最新参数对应的结果；正式运行仍会重新按当前参数处理完整输入。

Example workflow

Scenario: Short bonds after random occupation and strong perturbation

After Random Occupancy -> Atomic Perturb, a few alloy candidates contain atom pairs below 1.0 Å. Sending them to DFT wastes jobs, while including them in FPS contaminates descriptor space.

Input: A generated candidate pool. Objective: Remove short-bond and abnormal-volume structures before FPS. Parameters: min_pair_distance=1.2, min_volume_per_atom=5.0, max_volume_per_atom=40.0, with density checks disabled. Output: Only structures satisfying every enabled threshold. Verification: The nearest-distance distribution in NEP Dataset Display should have no low-end outliers, and FPS output should contain no obvious overlaps.

Parameters

Shortest Allowed Pair Distance（min_pair_distance）

float，默认 0 Å（关闭）。任意原子对允许的最近距离，是与元素种类无关的硬门槛。周期方向使用最小镜像距离，非周期分子即使没有晶胞也可以只做此项检查。

阈值应低于候选池中所有合理键长。不要把金属体系常用的 1.0~1.5 Å 直接用于含 H–H、O–H 或其他短键的混合数据集；这张卡不会根据共价半径自动调整阈值。

Min Volume Per Atom（min_volume_per_atom）

float, default 0.0 (disabled). Minimum volume per atom for rejecting overcompressed cells. Derive it from the material’s volume range. Avoid it for porous, slab, or vacuum-containing systems where it can reject valid structures.

Max Volume Per Atom（max_volume_per_atom）

float, default 0.0 (disabled). Maximum volume per atom for rejecting expanded or abnormal cells. A bulk pool may use a justified bound; slabs and molecular cells with vacuum generally should not.

Min Density（min_density）

float, default 0.0 (disabled). Minimum mass density. Enable only for bulk-like pools; keep zero for vacuum, pores, or surfaces.

Max Density（max_density）

float, default 0.0 (disabled). Maximum mass density for rejecting overcompressed structures. Use a material-specific physical upper bound, not one value across chemical systems.

Require a Finite, Nonzero-Volume Cell（require_finite_cell）

bool，默认 false。打开后，含 NaN/Inf 或行列式接近零的晶胞会被删除。任何体积或密度上下限只要开启，也会隐式要求有效的非零体积晶胞。晶体、slab、界面候选池建议开；孤立分子或非周期构型关掉。

Recommended presets

Short-distance gate

{
  "class": "GeometryFilterCard",
  "params": {
    "min_pair_distance": 1.2,
    "min_volume_per_atom": 0.0,
    "max_volume_per_atom": 0.0,
    "min_density": 0.0,
    "max_density": 0.0,
    "require_finite_cell": false
  }
}

First hard check after random perturbation, defect insertion, or random occupation.

Crystal candidate-pool cleaning

{
  "class": "GeometryFilterCard",
  "params": {
    "min_pair_distance": 1.1,
    "min_volume_per_atom": 5.0,
    "max_volume_per_atom": 60.0,
    "min_density": 0.0,
    "max_density": 0.0,
    "require_finite_cell": true
  }
}

Prevent zero-volume or extreme-volume crystal, defect, and surface structures from entering later stages.

Recommended combinations

Atomic Perturb -> Geometry Filter -> FPS Filter: add displacement diversity, reject short bonds, then sample representatives.
Random Occupancy -> Geometry Filter -> FPS Filter: gate alloy occupations geometrically before selecting DFT candidates.
Random Slab -> Insert Defect -> Geometry Filter: detect adsorbate-substrate overlaps after surface insertion.

Common questions

No output. At least one threshold is too strict. Inspect pair-distance and volume distributions and compare the limits with the actual system.

Density limits have no effect. Zero disables min_density and max_density; only positive limits participate.

A nonperiodic molecule was removed. Volume, density, or require_finite_cell checks reject zero-volume molecular cells. For molecular conformers, normally enable only min_pair_distance.

为什么不能给混合化学体系设置一个可靠的通用短键阈值？ 当前参数是统一的绝对距离，不读取元素对或键级。先查看数据中各元素对的合理距离范围；如果无法给出统一下界，应把阈值保持为 0，并在更合适的元素对检查工具中处理。

多个条件同时失败时预览怎么计数？ 预览按空结构、非有限坐标、无效晶胞、短距离、单原子体积、密度的顺序记录第一个失败原因，因此各原因计数之和等于删除总数，不代表后续条件一定通过。

Output labels

This filter preserves Config_type on retained structures.

Reproducibility

The card is deterministic: identical inputs and thresholds produce identical outputs.