按规则生成空位（Random Vacancy）

Group: Defect | Class: RandomVacancyCard

What the card does

按规则从指定元素的候选位点中均匀随机选择原子并删除。每条规则控制“删除哪种元素、删除多少个、是否限制在已有 group 标签内”；没有被删除的原子坐标、晶胞和 PBC 保持不变。

How it differs from Vacancy Defect Generation:

Random Vacancy：规则驱动，按元素和已有 group 限定候选池，再随机选择具体位点，适合定向研究某类空位缺陷
Vacancy Defect Generation samples global counts or fractions for a broad defect-density distribution.

本卡不会识别表面、体相或化学子晶格。group 是输入结构中已经存在的 atoms.arrays["group"] 标签；如果规则填写了 group 而输入没有对应数组或标签，卡片会明确报错，不会退化成全元素删位。

Example workflow

Scenario: The model fails on surface oxygen vacancies

A LiCoO2 NEP predicts bulk properties well but triples its energy error for an oxygen-deficient slab. The training set contains no oxygen vacancies and therefore no undercoordinated Co environments adjacent to them.

Diagnosis: Removing O changes Co from octahedral toward five- or fourfold coordination and modifies local bonds. Add controlled vacancy structures, relax and label them, so these environments are in domain.

输入： 一个 LiCoO2 的 slab 结构，并且上游建模或导入流程已经写入 surface / bulk group 标签

Objective: Remove 1-3 O atoms only from the surface group and generate 20 site variants.

Parameters:

Rules：[{"element":"O","count_mode":"random","count":[1,3],"group":["surface"]}]
Maximum Outputs per Input：20
Enable Use Seed and set Seed to [42].

输出： 最多 20 个不重复的空位结构，每个结构中 1~3 个表面氧被删除，带 Vac(n=...) 标签。若可用位点组合不足，实际输出数会少于 20。

How to verify that training-set quality improved:

After DFT labeling and retraining, energy error on held-out oxygen-vacancy slabs should decrease.
Inspect nearest-neighbor distances around the removed sites for physical plausibility.
Keep the group restriction when only surface vacancies are relevant; otherwise bulk vacancies dilute the target family.
To cover both bulk and surface vacancies, add a separate rule with the intended region rather than mixing provenance.
删除操作不会自动弛豫空位近邻；进入训练集前应做几何检查，并按任务需要进行 DFT 弛豫或单点计算

When to add this card

Add it when:

Vacancy sites must be controlled by element and group
A specific element-vacancy family is under study
A downstream magnetic workflow requires a defined vacancy pattern on one sublattice

Do not add it when:

Only global concentration coverage is needed; use Vacancy Defect Generation
The structure has fewer than about 10 atoms and one removal would drastically change stoichiometry

Parameters

Rules（rules）

list[dict[str, Any]]，默认空列表。界面默认提供一条空规则；必须填写元素后才能运行。

Each rule controls one removal operation: species, amount, and region.

Field	Type	Description
`element`	string	Element to remove, such as `O`
`count_mode`	string	`fixed` 精确删除 `count[0]` 个原子；`random` 在闭区间 `count[0]..count[1]` 中随机
`count`	[min, max]	Use `[n,n]` for a fixed count and `[min,max]` for a range
`group`	string / list (optional)	限制只删除输入结构已有 group 标签内的原子。界面里可写 `surface_top,surface_bottom`

固定数量必须至少为 1；随机范围允许最小值为 0，以便把原始结构作为一个可能端点，但最大值必须至少为 1。请求上限不能超过候选原子数，也不能把结构全部删空。

多条规则按顺序执行。如果两条规则的候选池重叠，第二条只会看到第一条删除后剩余的原子。随机范围偶尔抽到不可行组合时，程序会丢弃这一次尝试并继续采样，不会因为一个随机分支终止整张卡片；如果所有尝试都无法留下至少一个原子，才会明确报错。

Max Structures（max_structures）

int，默认 1。每个输入帧最多保留多少个不同的空位版本。卡片按删除位点集合去重，因此可用组合不足时输出会少于该值。

Use roughly 10-30 variants for targeted validation and 30-50 for routine coverage. At 50-100, consider FPS because many site choices can be descriptor-near-duplicates.

Use Seed（use_seed）

bool，默认 false。打开后同一结构内容 + 同一参数 + 同一 seed 会得到完全相同的删除结果。不同输入结构会派生不同随机序列，改变数据集顺序不会改变单帧结果。

Seed（seed）

int, default 0. Random seed value.

Active only when use_seed=True.

Recommended presets

Single-element single vacancy (two outputs for rule validation)

{
  "class": "RandomVacancyCard",
  "check_state": true,
  "params": {
    "rules": [
      {"element": "O", "count_mode": "fixed", "count": [1, 1]}
    ],
    "max_structures": 2,
    "use_seed": true,
    "seed": 42
  }
}

Low-concentration single-element vacancies (20 outputs)

{
  "class": "RandomVacancyCard",
  "check_state": true,
  "params": {
    "rules": [
      {"element": "O", "count_mode": "random", "count": [1, 3]}
    ],
    "max_structures": 20,
    "use_seed": true,
    "seed": 42
  }
}

Multiple rules with group constraints (20 targeted surface outputs)

{
  "class": "RandomVacancyCard",
  "check_state": true,
  "params": {
    "rules": [
      {"element": "O", "count_mode": "random", "count": [1, 3], "group": ["surface"]},
      {"element": "Li", "count_mode": "fixed", "count": [1, 1], "group": ["surface"]}
    ],
    "max_structures": 20,
    "use_seed": true,
    "seed": 42
  }
}

Recommended combinations

Group Label → Random Vacancy：可按坐标规则生成 A/B 两组后定向删位；Group Label 不会自动识别 surface/bulk 或化学子晶格
已有 surface / bulk / sublattice 标签 → Random Vacancy：直接填写已有标签定向删位
Super Cell -> Random Vacancy: enlarge first to reduce periodic vacancy interactions
Random Vacancy -> FPS Filter: select representatives from a large site sample

Common questions

提示“需要填写元素”。 默认规则仍为空；填写要删除的元素符号，例如 O。

提示输入没有 group 或没有匹配原子。 本卡不会猜测或忽略 group。先确认输入结构确实带有对应 atoms.arrays["group"] 标签，或清空规则中的 group 限制。

生成数少于设置值。 输出会按删除位点集合去重。例如只有一个 O 位点且固定删除 1 个时，不论上限设置多大都只有一种结构。

删位后局部结构不合理。 本卡只删除原子，不移动剩余原子。在小胞中删除过多原子会产生不合理化学计量和强缺陷相互作用；应先扩胞，并在下游进行几何检查或弛豫。

多条规则交互异常。 规则顺序执行。如果一条规则删了大量原子，下一条规则的候选池会变小。随机模式会跳过偶发的不可行组合；如果持续提示无法生成非空结构，说明规则的固定数量或最小删除数已经互相冲突，应减少删除数、拆开 group，或先扩胞。

Output labels

Vac(n={number of removed atoms})

Reproducibility

勾选 use_seed 并固定 seed 后，随机序列由 seed 与单帧结构内容共同决定：同一结构可复现，不同结构不会机械复用同一组原子编号，数据集重新排序也不改变单帧结果。