随机占位（Random Occupancy）

Group: Alloy
Class: RandomOccupancyCard
Source: src/NepTrainKit/ui/views/_card/random_occupancy_card.py

功能说明

在给定总成分约束下随机分配位点元素（site occupancy assignment），用于同成分多排布样本扩展。

它最适合的场景是：把 Composition Sweep 生成的目标配比真正落到原子占位上。如果你更关心完整工作流而不是单个参数，请先看下面的“操作示例”。

操作示例

场景：把 Composition Sweep 生成的目标配比真正落到原子占位上

输入： 一个带 Comp(...) 标签的结构，或一份手工填写的目标配比说明

目标： 从连续配比分布走到离散原子占位，得到可用于第一性原理或训练的数据结构

参数设置：

• source 先决定读取 Comp tag 还是手工 manual

• mode 决定精确落点还是随机落点

• samples 控制每个目标配比扩出多少个占位实例

输出： 同一目标配比会得到一批真实化学占位结构，而不是只停留在标签层面

怎么验证结果合理：

• 检查输出元素组成是否与目标配比大致一致

• 若全部退化成原元素，先检查 source 与 manual 是否设置正确

• 想做系统配比扫描时，记得把它放在 Composition Sweep 之后

适用场景与不适用场景

• 数据症状 (Dataset symptom): 同成分下占位排列单一，迁移泛化差。

• 目标任务 (Target objective): 增加位点排列多样性而保持总体成分。

• 建议添加条件 (Add-it trigger): 高熵或多元固溶体占位采样任务。

• 不建议添加条件 (Avoid trigger): 不需要占位随机化。

物理提示 (Physics caution): 重点检查目标配比、实际元素统计和标签是否一致，避免“标签写对了、占位落错了”。

输入前提

• 确认 source 与成分字符串格式。

• 若使用 group 过滤，结构需已有 group 数组。

参数说明（完整）

source (Source)

• UI Label: Source

• 字段映射 (Field mapping): 序列化键 source <-> 界面标签 Source。

• 控件标签 (Caption): Source。

• 控件解释 (Widget): 下拉选择 ComboBox（显示文本与序列化值可能不同）。

• 类型/范围 (Type/Range): enum(string)

• 默认值 (Default): "Auto (Comp tag)"

• 含义 (Meaning): 成分来源 (composition source)。

• 对输出规模/物理性的影响: 决定自动读取还是手工输入。

• 参数联动 / 生效条件: Auto (Comp tag) 适合接在 Composition Sweep 后；手工模式则要你自己保证 manual 内容可解析。

• 怎么判断该开还是该关: 先用默认值跑小样本；只有当你能明确说明它会改变当前结果分布时，再主动偏离默认设置。

• 物理直觉 / 典型值: 它决定程序走哪种离散策略；先选对模式，再去调该模式下真正起作用的数值参数。

• 推荐范围 (Recommended range):

  • 保守：自动优先

  • 平衡：手工兜底

  • 探索：双来源交叉核验

manual (Manual)

• UI Label: Manual

• 字段映射 (Field mapping): 序列化键 manual <-> 界面标签 Manual。

• 控件标签 (Caption): Manual。

• 控件解释 (Widget): 文本输入 LineEdit（或可编辑下拉）。

• 类型/范围 (Type/Range): string

• 默认值 (Default): ""

• 含义 (Meaning): 手动成分字符串 (manual composition)。

• 对输出规模/物理性的影响: 用于显式指定元素比例。

• 参数联动 / 生效条件: 只有当 source 走手工模式时它才会成为目标配比来源。

• 怎么判断该开还是该关: 只在你明确知道该字段会命中输入结构时填写；不确定时先用最小样本验证命中情况。

• 配置建议 (Practical note): Manual 可按任务替换为自定义值；建议先用最小样本验证后再批量生成。

mode (Mode)

• UI Label: Mode

• 字段映射 (Field mapping): 序列化键 mode <-> 界面标签 Mode。

• 控件标签 (Caption): Mode。

• 控件解释 (Widget): 下拉选择 ComboBox（显示文本与序列化值可能不同）。

• 类型/范围 (Type/Range): enum(string)

• 默认值 (Default): "Exact"

• 含义 (Meaning): 操作模式 (operation mode)。

• 对输出规模/物理性的影响: 改变执行逻辑路径，影响样本分布。

• 参数联动 / 生效条件: 它决定目标配比如何落到离散位点：更精确还是更随机。

• 怎么判断该开还是该关: 先用默认值跑小样本；只有当你能明确说明它会改变当前结果分布时，再主动偏离默认设置。

• 物理直觉 / 典型值: 它决定程序走哪种离散策略；先选对模式，再去调该模式下真正起作用的数值参数。

• 推荐范围 (Recommended range):

  • 保守：默认模式先验证

  • 平衡：按任务切换

  • 探索：探索模式配审计

samples (Samples)

• UI Label: Samples

• 字段映射 (Field mapping): 序列化键 samples <-> 界面标签 Samples。

• 控件标签 (Caption): Samples。

• 控件解释 (Widget): 数值输入 SpinBoxUnitInputFrame。

• 类型/范围 (Type/Range): int（单值输入）

• 默认值 (Default): [1]

• 含义 (Meaning): 每帧样本数 (samples per frame)。

• 对输出规模/物理性的影响: 控制输出体量和统计稳定性。

• 参数联动 / 生效条件: 每个目标配比会展开成多少个离散占位样本，与上游 Comp(...) 点数相乘后就是这一段的主要输出规模。

• 物理直觉 / 典型值: 它主要决定每帧会扩出多少个结构，直接影响后续计算预算与重复率。

• 推荐范围 (Recommended range):

  • 保守：1-3

  • 平衡：5-10

  • 探索：20+ 需去重

group_filter (Group Filter)

• UI Label: Group Filter

• 字段映射 (Field mapping): 序列化键 group_filter <-> 界面标签 Group Filter。

• 控件标签 (Caption): Group Filter。

• 控件解释 (Widget): 文本输入 LineEdit（或可编辑下拉）。

• 类型/范围 (Type/Range): string

• 默认值 (Default): ""

• 含义 (Meaning): 分组过滤条件 (group filter)。

• 对输出规模/物理性的影响: 限制操作仅作用于指定 group。

• 参数联动 / 生效条件: 只有输入结构已带 group 数组时，这个过滤条件才会真正限制可占位的区域。

• 怎么判断该开还是该关: 先用默认值跑小样本；只有当你能明确说明它会改变当前结果分布时，再主动偏离默认设置。

• 配置建议 (Practical note): Group Filter 可按任务替换为自定义值；建议先用最小样本验证后再批量生成。

use_seed (Use Seed)

• UI Label: Use Seed

• 字段映射 (Field mapping): 序列化键 use_seed <-> 界面标签 Use Seed。

• 控件标签 (Caption): Use Seed。

• 控件解释 (Widget): 勾选开关 CheckBox。

• 类型/范围 (Type/Range): bool

• 默认值 (Default): false

• 含义 (Meaning): 是否启用固定随机种子 (deterministic seed switch)。

• 对输出规模/物理性的影响: 开启后可复现实验；关闭后每次采样分布会变化。

• 怎么判断该开还是该关: 做可复现实验或要对比不同参数时开启；纯探索阶段可以先关闭以增加随机覆盖。

• 配置建议 (Practical note):

  • 开启：需要可复现对比时开启。

  • 关闭：探索阶段可关闭以增加随机覆盖。

seed (Seed)

• UI Label: Seed

• 字段映射 (Field mapping): 序列化键 seed <-> 界面标签 Seed。

• 控件标签 (Caption): Seed。

• 控件解释 (Widget): 数值输入 SpinBoxUnitInputFrame。

• 类型/范围 (Type/Range): int（单值输入）

• 默认值 (Default): [0]

• 含义 (Meaning): 随机种子值 (random seed value)。

• 对输出规模/物理性的影响: 只影响随机路径，不改变物理模型本身。

• 参数联动 / 生效条件: seed 只有在 use_seed=true 时才真正固定随机路径。

• 物理直觉 / 典型值: 先从小范围试跑并抽查输出，再决定是否扩大范围；范围越宽，覆盖越广，但极端构型风险也越高。

• 推荐范围 (Recommended range):

  • 保守：0（随机）

  • 平衡：1-99（可复现）

  • 探索：100-9999（多 seed 对比）

推荐预设（可直接复制 JSON）

保守（Safe）

{
  "class": "RandomOccupancyCard",
  "check_state": true,
  "source": "Auto (Comp tag)",
  "manual": "",
  "mode": "Exact",
  "samples": [
    1
  ],
  "group_filter": "",
  "use_seed": false,
  "seed": [
    0
  ]
}

平衡（Balanced）

{
  "class": "RandomOccupancyCard",
  "check_state": true,
  "source": "Auto (Comp tag)",
  "manual": "",
  "mode": "Exact",
  "samples": [
    1
  ],
  "group_filter": "",
  "use_seed": false,
  "seed": [
    0
  ]
}

激进/探索（Aggressive/Exploration）

{
  "class": "RandomOccupancyCard",
  "check_state": true,
  "source": "Auto (Comp tag)",
  "manual": "",
  "mode": "Exact",
  "samples": [
    20
  ],
  "group_filter": "",
  "use_seed": true,
  "seed": [
    0
  ]
}

推荐组合

• Group Label -> Random Occupancy: 将占位变化限制在指定 group。

• 先明确“目标配比”还是“具体落位”，再决定接 Composition Sweep、Random Occupancy 还是 Random Doping。

• 涉及 group 或局部位点限制时，可先接 Group Label 或规则类卡片再执行替换。

常见问题与排查

• 结果没有变化时，先检查目标元素、规则字符串或 Comp tag 来源是否真的命中了输入结构。

• 如果输出成分偏离预期，优先检查是“目标配比定义”问题，还是“离散落位/随机替换”步骤把分布拉偏。

• 这组卡片不会自动替你决定工作流分工；需要系统扫配比时先用 Composition Sweep，需要真实落位时再接 Random Occupancy 或 Random Doping。

输出标签 / 元数据变更

• 该卡片输出的 Config_type 标签模式：

  • Occ({...}{...})

可复现性说明

• 设置 use_seed=true 且固定 seed，可在相同输入顺序下复现实验。

• 上游随机卡片或输入顺序变化仍会改变最终样本集合。

• 建议把 seed 与 pipeline 配置一起版本化记录。