插隙与表面吸附（Insert Defect）
Group: Defect | Class: InsertDefectCard
What the card does
为每个输入结构生成两类未弛豫候选：
体相随机插隙：在晶胞内部按分数坐标均匀随机取点并插入原子。
上表面随机吸附：在指定晶格方向的上表面随机取横向位置，并放到原始宿主最高原子平面上方的固定高度。
两种模式都用最小原子间距排除明显碰撞。该距离同时检查候选点到宿主原子和此前已插入原子的距离。
这张卡不识别晶体学间隙位或化学吸附位：不会自动寻找四面体、八面体、顶位、桥位或空位，也不会弛豫坐标。它适合生成连续随机候选，再交给 DFT、几何优化、能量筛选或 FPS Filter；需要确定的物理路径时，应使用专门的位点或路径构造工具。
工作原理
体相随机插隙
每次在 [0,1)^3 中抽取一个分数坐标并映射到晶胞。候选点满足 min_distance 后才会插入。若一个输出需要多个原子，后插入的原子也会避开先插入的原子。
上表面随机吸附
axis 指定 slab 真空所在的晶格方向 a、b 或 c。程序以原始宿主原子的最大分数坐标确定上表面，在该平面内随机取点，再沿真实表面法向移动 offset。
对于倾斜晶胞，法向由对应的倒易方向计算，而不是直接沿晶格矢量移动。多个吸附原子始终以同一个原始宿主平面为参考，不会逐个向上堆叠。当前只生成上表面候选。
完整输出约束
每个输出必须插满 insert_count 个原子。任何一个原子在 max_attempts 次尝试后仍无法放置时，卡片会明确报错，不返回未修改或只完成一部分的伪成功结构。
Example workflow
场景：训练集缺少表面吸附初始构型
模型在洁净表面和少量弛豫吸附构型上表现正常，但对随机初始吸附位置的能量和力误差很大。这说明训练集只覆盖了稳定极小值，缺少优化路径起点和高能横向位置。
输入： 带真空层的 slab，真空沿晶格 c。
目标： 在上表面放置一个 O 原子，生成 50 个横向位置不同的候选。
参数：
Insertion mode：Random upper-surface adsorptionInserted species and weights：OAtoms inserted per output：1Outputs per input：50Minimum atom distance：1.4 ÅVacuum / surface-normal direction：Lattice c directionHeight above top atomic plane：1.8 ÅUse seed：开启，便于比较后续筛选方案
验证：
每个输出应比输入多一个 O，并带
Ins(ad,n=1)标签。插入原子到所有宿主原子的最近距离应不小于
1.4 Å。50 个 O 应处于相同法向高度，但横向位置不同。
几何优化或 DFT 标注后，再检查模型对吸附初始构型的能量和力误差是否下降。
Parameters
模式与元素
Insertion Mode（mode）
int，默认 0。
0：体相随机插隙，在整个晶胞内连续随机取点。1：上表面随机吸附，在指定上表面随机取横向位置。
Inserted Species and Weights（species）
str，默认空，运行时必填。可填写单一元素 Li，或使用相对权重 Li:7, Na:3。多个插入原子会分别独立抽样，因此权重表示概率，不保证单个输出达到精确组成。
元素符号必须有效，权重必须为有限正数。重复元素的权重会合并。
输出数量
Atoms Inserted per Output（insert_count）
int，默认 1。每个成功输出必须插入的原子数，界面范围为 1–20。
Outputs per Input（structure_count）
int，默认 10。每个输入结构生成的完整输出数，界面范围为 1–1000。
几何与尝试预算
Minimum Atom Distance（min_distance）
float，默认 1.4 Å。候选点到宿主原子和已插入原子的最小允许距离。必须为有限正数。
该值只排除明显近距离碰撞，不代表化学合理的键长。不同元素体系应按原子尺寸和预期局域环境调整。
Placement Attempts per Atom（max_attempts）
int，默认 200。每个待插入原子的最大随机尝试次数。达到上限仍找不到满足距离的位置时，整个操作报错。
连续触发上限通常说明晶胞过密、插入数过多或 min_distance 过大；单纯继续提高尝试次数未必有效。
Surface adsorption
Vacuum / Surface-normal Direction（axis）
int，默认 2，仅在吸附模式生效。
0：真空沿晶格a1：真空沿晶格b2：真空沿晶格c
这里选择的是晶格方向，不等同于笛卡尔 x、y、z。程序会据此计算真实表面法向。
Height Above Top Atomic Plane（offset）
float，默认 1.5 Å，仅在吸附模式生效。表示候选原子到原始宿主最高原子平面的法向距离，必须为有限正数。
该参数不会自动扩大晶胞。应先确保 slab 有足够真空容纳吸附原子。
Randomness
Use Seed（use_seed）
bool，默认 false。启用后可复现同一输入结构的元素选择和几何位置。
Seed（seed）
int，默认 0，仅在 use_seed=true 时生效。种子会与结构内容共同派生，因此几何不同的输入帧不会机械地获得相同分数坐标。
推荐配置
体相单原子插隙
{
"class": "InsertDefectCard",
"check_state": true,
"params": {
"mode": 0,
"species": "Li",
"insert_count": 1,
"structure_count": 50,
"min_distance": 1.4,
"max_attempts": 200,
"use_seed": true,
"seed": 42,
"axis": 2,
"offset": 1.5
}
}
上表面混合吸附候选
{
"class": "InsertDefectCard",
"check_state": true,
"params": {
"mode": 1,
"species": "O:3, H:1",
"insert_count": 2,
"structure_count": 50,
"min_distance": 1.2,
"max_attempts": 300,
"use_seed": true,
"seed": 42,
"axis": 2,
"offset": 1.8
}
}
Recommended combinations
Random Slab→Insert Defect：先生成带真空层的表面，再放置上表面吸附候选。Insert Defect→ 几何优化或 DFT：本卡输出是未弛豫随机候选。Insert Defect→FPS Filter：大量候选经过描述符筛选后再进入昂贵计算。
Common questions
为什么没有四面体或八面体位点选项？
当前算法不做晶体学位点识别，只在连续空间随机采样。需要确定间隙位时，应使用专门的位点生成方法。
为什么运行直接报“无法放置”？
卡片不会返回插入数不足的结构。先检查 Minimum atom distance、插入原子数和晶胞可用空间，再决定是否增加尝试次数。
为什么吸附原子可能位于晶胞范围外？
卡片保持原晶胞和宿主坐标不变，也不会静默包裹吸附原子。请先在表面法向留出足够真空，或在后续计算前明确扩展晶胞。
如何生成下表面吸附？
当前只生成所选晶格方向的上表面。可先翻转 slab，或使用明确支持上下表面的专门工具。
Output labels
体相插隙：
Ins(int,n={插入数})上表面吸附：
Ins(ad,n={插入数})
兼容性
内部 card_name、类名和参数键保持不变。旧版顶层参数和当前 params 对象都可以读取；显示名称和失败语义已收紧。