Random Doping

Group: Alloy | Class: RandomDopingCard

What the card does

按规则表对指定元素位点做替位掺杂。可以精确控制”替换谁、换成什么、换多少”，支持按原子百分比、质量百分比或固定数量采样。规则填写了 group 时，输入必须真的带有对应标签；卡片不会把缺失的 group 当成“全部位点”。

和 Random Occupancy / Composition Space Sampling 的区别：

Composition Space Sampling：定义”目标配比空间”，不改原子占位
Random Occupancy realizes target fractions as discrete occupations, usually from a Comp(...) label.
Random Doping directly applies target, dopant, and amount rules. It is explicit and local, not a composition-space scan.

Example workflow

Scenario: A pure-element model fails on a doped system

A pure-Si NEP has converged energy and force errors, but force error increases by an order of magnitude on Si:Ge because Ge-centered local environments are absent from training.

Diagnosis: A set containing only Si-Si environments cannot represent Si-Ge or Ge-Ge chemistry. Generate actual Ge substitutions on Si sites, then relax and label them so the model learns dopant-centered environments.

Input: A relaxed pure-Si supercell.

Objective: Replace 3-8% of Si with Ge and generate 20 site arrangements per input.

Parameters:

Rules：target=Si, dopants=Ge, use=atomic_percent, percent=[3, 8]
Doping Type: Exact for a stable dopant count in comparisons.
Structures：[20]

Output: Twenty doped structures with 3-8% of Si sites changed to Ge and label Dop(n=...).

How to verify that training-set quality improved:

After DFT labeling and retraining, force MAE on a Si:Ge test set should approach the in-domain Si error.
Inspect dopant-centered nearest-neighbor distances and confirm they are chemically plausible.
If high-concentration tests remain out of domain, extend the training range deliberately, for example toward 15-20%.
For one dopant, Ge is equivalent to Ge:1.0.
For mixed dopants, use weights such as Ge:0.7,C:0.3.

When to add this card

Add it when:

Predictions on doped or alloy structures are much worse than on the pure system
Local chemistry around a specific dopant is missing
An explicit target, dopant, and amount rule is known without a full composition scan

Do not add it when:

需要系统扫配比空间 → 先用 Composition Space Sampling，再接 Random Occupancy
Only global occupation diversity is needed; use Random Occupancy

Parameters

Rules（rules）

list[dict[str, Any]], empty by default. Each rule defines a target element, dopants, an amount, and an optional group. Keep distinct physical defects in separate explicit rules rather than one ambiguous probability pool.

rule 内的典型字段：target（被替换元素）、dopants（替换元素及权重 dict）、ratio_type（dopants 权重采用 atom 原子比或 mass 质量比）、use（atomic_percent / mass_percent / count）、percent（百分比范围 [min, max] 或 [fixed]）、count（固定替换个数或随机范围）、count_mode（fixed / random）、group（可选，限制只在此 group 内操作）。

percent 必须落在 0~100；百分比换算成离散原子数时向下取整，因此小超胞的低百分比可能得到 0 个替换。明确设置 0% 会保留原结构，不会被强制改成 1 个掺杂原子。固定数量、随机数量或质量百分比范围会先按上界计算最大请求数；只要上界可能超过当前候选位点数，整条规则就会确定性报错，不会因 seed 不同而时而成功、时而失败，也不会静默截断。多种 dopant 的质量百分比换算会按 ratio_type 对应的原子分数计算平均质量；切换规则里的“原子比/质量比”会改变换算和元素分配。填写 group 后，如果输入没有 atoms.arrays["group"]、标签未命中或目标元素未命中，也会明确报错。

Doping Type（doping_type）

str，默认 Random。这个选项控制多个 dopant 如何分配到已经选定的替换位点，不改变 percent 或 count 推导出的替换总数。

选项	含义	什么时候选
`Random`	每个替换位点按 dopant 权重独立抽样	需要统计涨落和更多随机组成时
`Exact`	用最大余数法把权重换成整数计数，再随机打乱落点	对比实验需要每帧 dopant 计数尽量贴近目标比例时

Max Structures（max_structures）

int, default 1. Maximum doped variants per input. Low-concentration site sampling may use 10-50; high-dimensional alloy exploration should be followed by FPS and an explicit budget.

Use Seed（use_seed）

bool, default false. Enable for reproducibility in controlled comparisons.

Seed（seed）

int, default 0. Different values generate different substitution assignments.

Active only when use_seed=True.

Recommended presets

Low-concentration single dopant (Si:Ge, 1-2%)

{
  "class": "RandomDopingCard",
  "check_state": true,
  "params": {
    "rules": [
      {
        "target": "Si",
        "dopants": {"Ge": 1.0},
        "use": "atomic_percent",
        "percent": [1, 2]
      }
    ],
    "doping_type": "Exact",
    "max_structures": 20,
    "use_seed": true,
    "seed": 101
  }
}

Moderate mixed doping (Si:Ge/C, 3-8%)

{
  "class": "RandomDopingCard",
  "check_state": true,
  "params": {
    "rules": [
      {
        "target": "Si",
        "dopants": {"Ge": 0.7, "C": 0.3},
        "use": "atomic_percent",
        "percent": [3, 8]
      }
    ],
    "doping_type": "Exact",
    "max_structures": 20,
    "use_seed": true,
    "seed": 101
  }
}

High-concentration multielement exploration (Si:Ge/C/Sn, 8-20%)

{
  "class": "RandomDopingCard",
  "check_state": true,
  "params": {
    "rules": [
      {
        "target": "Si",
        "dopants": {"Ge": 0.5, "C": 0.3, "Sn": 0.2},
        "use": "atomic_percent",
        "percent": [8, 20]
      }
    ],
    "doping_type": "Random",
    "max_structures": 20,
    "use_seed": true,
    "seed": 101
  }
}

Recommended combinations

Group Label -> Random Doping: restrict doping to a sublattice or layer
Composition Space Sampling → Random Occupancy → Random Doping：先扫配比 → 落位 → 再补局部随机替换
Random Doping -> Atomic Perturb: add local coordinate diversity after substitution; physical labels still require relaxation

Common questions

输出和输入一样，没有替换。 空 rules 会保留输入；显式 0% 或小超胞中百分比向下取整为 0 时，也会得到未替换端点。target 不存在、group 缺失或标签未命中则会直接报错，不再生成假成功输出。

Dopant fraction differs from expectation. Small Random samples fluctuate; use Exact for stable counts. With mass_percent, atomic fractions also reflect target-dopant mass differences.

Bond lengths are abnormal. Substitution does not relax geometry. Relax before using such structures as physical training labels.

提示请求数量超过候选位点。 卡片不会替你把 10 个改成“最多能换的 4 个”。范围参数按上界校验；请降低 count 或 percent 上限、扩大超胞，或检查前一条规则是否已经消耗了相同 target/group 的候选位点。

多条规则之间的交互。 规则按顺序执行。如果多条规则操作重叠的 target/group 候选池，卡片会按各范围上界联合预检；只要前面的规则存在耗尽后续容量的可能，就会在随机采样前统一报错，而不是让同一工作流随 seed 时成时败。需要保留多条规则时，应改用互不重叠的 group；同一候选池上的多种 dopant 通常应合并到一条规则的 dopants 中。

Output labels

Dop(n={number of substituted atoms})

Reproducibility

勾选 use_seed + 固定 seed 可复现。同一候选位点顺序会复用同一随机路径，因此批量结构若原子排序完全一致，掺杂落点编号也可能一致；需要结构间更丰富的落点时，应使用不同 seed 或在上游生成不同占位顺序。建议把 seed 与 pipeline 配置一起版本化。