Conditional Replace

Group: Alloy | Class: ConditionalReplaceCard

What the card does

按空间坐标条件对指定元素做区域选择性替换。用笛卡尔 x/y/z 坐标表达式（如 z>=8 and z<=10）筛选候选位点；所有命中位点都会被替换，未命中区域保持原样。多个替换元素后面的比例只决定它们如何分配到命中位点，不表示“替换多少位点”。适合表面钝化、界面修饰、层状材料选择性改性等场景。

与 Random Doping 的区别：Conditional Replace 用坐标表达式精确划定空间区域，输出一个结构并替换全部命中位点；Random Doping 按数量或浓度做部分替位，可以生成多个结构，也可以读取 Group Label 写入的 group 标签。

Example workflow

Scenario: Good bulk predictions but failed surface chemistry

An MgO NEP covers perfect crystals and relaxed clean surfaces and reproduces bulk elasticity and phonons, but its error rises tenfold for adsorbed or passivated surfaces. All training O atoms occupy bulk-like octahedral environments; low-coordination surface O and F-substituted surface sites are missing.

Diagnosis: Surface chemistry differs from the bulk through lower coordination and dangling bonds. Create region-specific substitutions, such as replacing O with F in the outer layers, so subsequent DFT labels teach the model those environments.

Input: An MgO slab spanning z = 0-16 Å with surface O at high z.

Objective: Replace O with F in the top 2 Å to model surface fluorination.

Parameters:

target = O
replacements = F:1.0
condition = z>=14 and z<=16
mode = 1（只有一种替换元素时，两个分配模式的结果相同）

输出： 1 个结构，满足 z 在 14-16 Å 的所有 O 被替换为 F，其余区域不变。带 Repl(O->F) 标签

How to verify that training-set quality improved:

After labeling and retraining, surface-adsorption force MAE should decrease and extreme errors should no longer concentrate at the surface.
Inspect output coordinates and confirm that only the surface region changed. Bulk substitutions indicate an incorrect condition.
For mixed passivation, use a recipe such as F:0.5,Cl:0.5.
If the surface interval is uncertain, validate the replacement recipe with all, then narrow the z condition after inspecting coordinates.

When to add this card

Add it when:

Surface, interface, or grain-boundary predictions are much worse than bulk predictions
Region-selective chemistry is needed for passivation, interface doping, or layer replacement
The target region can be expressed with x, y, and z coordinates

Do not add it when:

No spatial selection is needed; use Random Doping
The rule depends on topology or coordination rather than coordinates
只需要全局组合配比变化 → Composition Space Sampling + Random Occupancy

Parameters

目标元素（target）

str, empty by default. Element to replace, such as O or Si. A site must match both this element and condition.

替换元素及相对比例（replacements）

str，默认空。替换配方，支持逗号冒号 F:0.7,N:0.3 或 JSON dict {"F":0.7,"N":0.3} 两种写法。比例会被自动归一化，只用于在命中位点之间分配 F 和 N；它不是替换率，所有命中位点仍然都会被替换。只填 F 等价于 F:1.0。

位置筛选（condition）

str，默认 all。空间条件表达式，all 表示所有目标元素都命中。支持变量 x/y/z（笛卡尔坐标，单位 Å），比较运算符 </>/<=/>=/==/!=，逻辑 and/or/not，以及四则运算。相等判断可写 x=0 或 x==0，两者含义相同；内部使用 1e-4 Å 容差。

Examples:

z>=8 and z<=10: select target atoms between 8 and 10 Å along z
x>5 or y<2: select atoms in the specified xy regions
z<=4: select only the bottom layer

元素分配方式（mode）

int，默认 0。两个模式都会替换所有命中位点，区别只在多个替换元素的数量分配：

0 = 逐位随机分配：每个位点独立按相对比例抽取替换元素，最终计数可能偏离目标比例。
1 = 尽量匹配整体比例：先把比例换算成整数计数，再随机分配到命中位点，最终计数尽量接近目标比例。

只有一个替换元素时，两个模式的结果相同。

随机种子（seed）

int，默认 0。界面取消勾选“使用固定种子”时保存为 0，表示每次运行随机；勾选后保存输入的正整数，使位点分配可复现。

Recommended presets

Single-species surface passivation (O -> F in a narrow window)

{
  "class": "ConditionalReplaceCard",
  "check_state": true,
  "params": {
    "target": "O",
    "replacements": "F:1.0",
    "condition": "z>=14 and z<=16",
    "seed": 101,
    "mode": 1
  }
}

Mixed surface passivation (O -> F/N in a wider window)

{
  "class": "ConditionalReplaceCard",
  "check_state": true,
  "params": {
    "target": "O",
    "replacements": "F:0.7,N:0.3",
    "condition": "z>=6 and z<=14",
    "seed": 101,
    "mode": 0
  }
}

Global mixed replacement (all O -> F/N/Cl for exploration)

{
  "class": "ConditionalReplaceCard",
  "check_state": true,
  "params": {
    "target": "O",
    "replacements": "F:0.4,N:0.3,Cl:0.3",
    "condition": "all",
    "seed": 101,
    "mode": 0
  }
}

Recommended combinations

Crystal Prototype Builder → Conditional Replace：先生成表面或界面模板，再按坐标区域做元素替换。
Conditional Replace → Atomic Perturb：替换后加坐标噪声，松弛替换引入的局部应力。
Conditional Replace -> Random Doping: cover region-specific surface chemistry before global substitution diversity.

如果需要按 group 标签选择位点，应使用 Group Label → Random Doping；本卡不读取 group 标签。

Common questions

Output equals input. target is empty or absent, or condition rejects every candidate. Test with condition=all, then narrow the expression incrementally.

Unexpected sites were replaced. Inspect the structure’s coordinate range and correct the condition bounds. Vacuum in a slab can make z limits unintuitive.

The condition could not be parsed. Check that it uses only x/y/z variables and does not contain unsupported syntax such as === or function calls. =, ==, >=, <=, and != are all valid. An invalid expression raises ValueError explicitly.

随机模式为什么没有保留一部分原元素？ 这里的“随机”只表示在多个替换元素之间逐位随机分配，不表示随机决定是否替换。要控制替换数量或浓度，请使用 Random Doping。

Bond lengths are unreasonable after replacement. This operation changes species without relaxation. Relax the structure before treating it as a physical configuration.

Output labels

Formats: Repl(O->F) and Repl(O->F,N,Cl). A label is added only when a replacement occurs.

Reproducibility

A fixed nonzero seed reproduces an input. For mixed replacements it controls which site receives each species; seed=0 generates a new assignment each run.