分支合并组（Card Group）

Group: Container | Class: CardGroup

What the card does

把共享同一输入的多张卡片装进一个容器里，依次运行后汇总输出。适合“同一个母相结构既要生成表面，又要生成体相空位”这类独立分支场景。

这里的“分支”是数据语义，不是同时占用多个线程：每张启用的子卡都读取同一份组输入，子卡按界面顺序逐张运行，前一张子卡的输出不会成为下一张子卡的输入。全部成功后，组把各分支输出合并为一个数据集。

What it is not: A Card Group is neither a filter nor a generator, and it does not support serial dependencies between child cards. Put dependent cards in sequence outside the group.

Example workflow

Scenario: Generate surface slabs and bulk vacancies from one parent structure

A relaxed Ni supercell must follow two independent paths: cut surface slabs with several orientations and create random bulk vacancies. A Card Group avoids importing the same data twice.

Input: A relaxed 4×4×4 Ni supercell.

目标： 把 Random Slab 和 Random Vacancy 放入同一组，共享输入，生成两个独立分支并统一导出

Parameters:

Drag Random Slab into the group and configure its slab parameters.
Drag Random Vacancy into the group and configure its vacancy rules.
card_list is maintained automatically as [{RandomSlabCard...}, {RandomVacancyCard...}].

Output: The union of both branches: surface slabs with several orientations and a set of vacancy structures, each carrying its own provenance label.

How to verify it: Inspect a sample and confirm distinct labels such as Slab(...) and Vac(...). If only one label appears, confirm that check_state is enabled for every child card.

When to use a Card Group

Use it when:

同一输入需要分别喂给多张彼此无依赖的卡片
Several branches should be enabled, disabled, and exported together.

Do not use it when:

Cards have a dependency (B consumes A’s output); connect them serially outside the group.
Only one card is needed.

Parameters

`card_list`

组内的子卡片列表，由界面拖入操作自动维护，不需要你手动编辑。每项是一个完整的卡片配置 dict（含 class、check_state、params 等字段）。界面中的顺序决定实际运行顺序，但不构成数据依赖。

关闭整个组时，组会直接把输入传给下游，不会改动各子卡原本的启用状态；重新开启组后，之前选择的分支仍会保留。

`filter_card`

dict 或 null，默认 null。选填：在组内末尾挂一张过滤卡（如 FPS Filter），对所有分支合并后的结果做统一筛选。一个组只允许一张后置过滤卡；若已有过滤卡，应先关闭或移走，再拖入另一张。

后置过滤结果就是最终组输出，也会成为下游卡片的输入。

Recommended presets

Empty container; drag cards into it in the interface

{
  "class": "CardGroup",
  "check_state": true,
  "card_list": [],
  "filter_card": null
}

带组内过滤（先生成独立分支，再 FPS 筛）

{
  "class": "CardGroup",
  "check_state": true,
  "card_list": [
    {"class": "RandomSlabCard", "check_state": true, "params": {}},
    {"class": "RandomVacancyCard", "check_state": true, "params": {}}
  ],
  "filter_card": {
    "class": "FPSFilterDataCard",
    "check_state": true,
    "params": {
      "nep_path": "path/to/nep.txt",
      "n_samples": 50,
      "min_distance": 0.0,
      "backend": "auto",
      "chunk_max_atoms": 100000,
      "strategy": "global",
      "existing_dataset_path": ""
    }
  }
}

Recommended combinations

Card Group(Random Slab, Insert Defect) → FPS Filter：从同一输入生成表面与缺陷分支 → 组外统一筛选
Card Group(Atomic Perturb, Lattice Perturb) -> export: add coordinate noise and lattice noise as separate branches from the same input
When branches have a strict dependency, use a top-level serial chain: Super Cell -> Random Slab -> Insert Defect.

Common questions

组输出为空。 检查组内每张子卡片是否勾选了 check_state、各自配置是否合法。任一启用子卡失败时，组会清空已收集的部分结果，停止后续分支并把失败传给工作流。

Branch results cannot be distinguished. Confirm that each child produces a distinct Config_type. The group does not add provenance; it relies on child-card labels.

组内过滤卡把结果全筛掉了。 filter_card 的过滤阈值可能过严，例如几何阈值不适合当前体系，或 FPS 描述符距离阈值导致提前停止。先看过滤卡自己的预览和错误信息，再调整参数。

想在组内串行。 不支持。组内所有卡片共享同一输入，是彼此独立的分支。串行依赖请拆到组外。

这里的“串行依赖”是指 A 的输出作为 B 的输入。分支合并组虽然为了资源安全逐张执行子卡，但数据上仍是独立分支。

Output labels

Card Group itself does not write a Config_type; each child card supplies its own label.

Reproducibility

Card Group has no randomness of its own. Reproducibility depends on the seed settings of its child cards.