成分空间采样（Composition Space Sampling）

Group: Alloy | Class: CompositionSweepCard

What the card does

Generate a composition design space from an element pool and selected component counts. The card expands binary through quinary combinations and samples target fractions on each simplex with a grid or Sobol sequence. It outputs structure copies labeled Comp(...); these labels are composition plans, not actual site occupations. Follow with Random Occupancy to assign discrete species.

Example workflow

Scenario: Predictions fail away from the training stoichiometry

A Co-Cr-Ni NEP is trained entirely on equiatomic CoCrNi. It performs well there, but its energy error triples at a composition such as Co30Cr20Ni50. All training compositions occupy one point of the simplex, so composition-dependent local chemistry is extrapolated.

Diagnosis: An alloy model should interpolate across the intended composition domain, not memorize one composition. First design a well-distributed set of target fractions, then realize each target with downstream site occupation so the training set contains distinct chemical environments.

Input: A relaxed equiatomic CoCrNi supercell, currently the only training composition.

Objective: Grid-sample all binary and ternary Co-Cr-Ni combinations up to about 500 targets, then realize them with Random Occupancy.

Parameters:

  • elements = Co,Cr,Ni

  • order = 2,3 (binary and ternary combinations)

  • method = Grid，step = 0.1

  • max_outputs = 500

Output: About 500 structure copies labeled Comp(Co=...,Cr=...,Ni=...). Atomic species are unchanged at this stage; the label records only the target composition.

How to verify that training-set quality improved:

  • After realization, labeling, and retraining, force MAE at several off-equiatomic tests should no longer deteriorate sharply with composition distance.

  • Plot the Comp fractions from Config_type and confirm coverage across each simplex. Reduce the grid step or use Sobol if corners or regions remain empty.

  • If points cluster near equiatomic compositions and omit boundaries, enable include_endpoints and set min_fraction to 0.

  • If the output budget undersamples some orders, raise max_outputs or choose Capacity-weighted so higher-order simplexes receive more points.

When to add this card

Add it when:

  • Model error grows markedly away from the training stoichiometry

  • A binary-to-multicomponent composition space needs systematic coverage

  • An alloy workflow needs target fractions before site occupation

Do not add it when:

  • Only one fixed stoichiometry is needed

  • A specific doping rule is already known and no composition scan is needed; use Random Doping

  • Only atomic arrangements at one composition are missing; use Random Occupancy

Parameters

Elements（elements）

str, default Co,Cr,Ni. Comma-separated element pool, for example Co,Cr,Ni,Al,Fe. At least two elements are required; the card forms all requested n-component subsets.

组合元数（order）

str，默认 2,3,4,5。决定采样二元、三元、四元或五元成分空间。界面用“二元（2）”“二元 + 三元（2,3）”等易读名称显示，保存时仍使用 2、2,3 等稳定值。也兼容旧版名称如 Binary、Ternary+Quaternary。当候选元素不足时，不可执行的元数会自动跳过。

采样方法（method）

str, default Grid. Grid uses a controlled uniform step and is convenient for binary or ternary spaces. Sobol gives more even limited-point coverage of four- or five-component simplexes.

成分步长（step）

float，默认 0.1，仅 Grid 模式生效。单位是成分分数，0.1 表示 10 个百分点。数值越小，网格越密、目标配比越多；典型值为 0.05-0.15。

每种元素组合的采样点数（n_points）

int，默认 50，仅 Sobol 模式生效。它表示每一种元素组合通过 min_fraction 约束后的目标有效点数，而不是过滤前的尝试数。operation 会继续补采样直到得到该数量；典型值为 25-200。

元素最小占比（min_fraction）

float, default 0.0, range 0-1. Minimum fraction of every included element. A value of 0.05 removes compositions below 5%; zero imposes no lower bound.

包含边界成分点（include_endpoints）

bool，默认 true，仅 Grid 模式。勾选后保留纯元素端点和某个元素占比为零的边界成分；关掉后只保留所有元素占比均大于零的内部点。

Use Seed（use_seed）

bool, default false. Fix Sobol generation and combination selection for reproducible controlled comparisons.

Seed（seed）

int, default 0. Different values produce different sample designs.

Active only when use_seed=True.

每个输入的最大目标成分数（max_outputs）

int，默认 500。限制每个输入结构生成的目标配比总数，防止组合爆炸。超出预算时按 budget_mode 规则分配到各组合元数；典型值为 250-1500。

输出预算分配（budget_mode）

str，默认 Equal+Reflow。控制输出上限如何在不同组合元数之间分配。界面使用易读名称，保存值保持不变：

  • 均衡各元数（Equal+Reflow）：各元数先均分，未用完的名额再分给仍有候选点的元数，适合大多数场景。

  • 侧重更大的成分空间（Capacity-weighted）：按理论容量加权，更大的成分空间分到更多名额。

  • 旧版均分（Equal (legacy)）：保留旧行为，各元数均分且不回流余量。

Recommended presets

Quick survey (binary and ternary Grid, about 100 points)

{
  "class": "CompositionSweepCard",
  "check_state": true,
  "params": {
    "elements": "Co,Cr,Ni",
    "order": "2,3",
    "method": "Grid",
    "step": 0.1,
    "n_points": 50,
    "min_fraction": 0.0,
    "include_endpoints": true,
    "use_seed": false,
    "seed": 0,
    "max_outputs": 100,
    "budget_mode": "Equal+Reflow"
  }
}

Routine coverage (all combinations, Grid, about 500 points)

{
  "class": "CompositionSweepCard",
  "check_state": true,
  "params": {
    "elements": "Co,Cr,Ni,Al",
    "order": "2,3,4",
    "method": "Grid",
    "step": 0.1,
    "n_points": 50,
    "min_fraction": 0.0,
    "include_endpoints": true,
    "use_seed": false,
    "seed": 0,
    "max_outputs": 500,
    "budget_mode": "Equal+Reflow"
  }
}

High-dimensional exploration (all combinations, Sobol, about 1,500 points)

{
  "class": "CompositionSweepCard",
  "check_state": true,
  "params": {
    "elements": "Co,Cr,Ni,Al,Fe",
    "order": "2,3,4,5",
    "method": "Sobol",
    "step": 0.1,
    "n_points": 150,
    "min_fraction": 0.0,
    "include_endpoints": true,
    "use_seed": true,
    "seed": 42,
    "max_outputs": 1500,
    "budget_mode": "Capacity-weighted"
  }
}

Recommended combinations

  • Composition Space Sampling → Random Occupancy：先定义目标配比，再落到离散原子占位。合金 pipeline 的标准起手式。

  • Composition Space Sampling → Random Occupancy → Random Doping：配比覆盖 + 占位多样性 + 额外局部替位。

  • Composition Space Sampling → Random Occupancy → Atomic Perturb：成分 + 占位 + 坐标噪声。

Common questions

Output is unchanged. Check that elements has at least two entries, order is supported, and max_outputs is positive.

标签成分和原子实际组成不一致。 正常——Composition Space Sampling 只写目标配比标签，不改原子种类。需要接 Random Occupancy 才会真正替换原子。

Combinatorial explosion. A five-component Grid at step 0.05 can contain tens of thousands of points. Set max_outputs, validate a small design, then increase it deliberately.

Some orders have no output. Check budget allocation and the element count. With only three elements, orders 4 and 5 are skipped.

Sobol + min_fraction reports too few valid points. The closer the lower bound is to the equimolar value 1/order, the smaller the admissible region becomes. The operation resamples within an explicit attempt budget. If the target is still not reached, it raises ValueError with the accepted count, target count, and attempt count instead of silently returning a small dataset.

Output labels

Format: Comp(Co=0.3333,Cr=0.3333,Ni=0.3333). Each output carries its target fractions in Config_type.

Reproducibility

Enable use_seed and fix seed to reproduce an input order. Grid points are deterministic; the seed mainly affects subset selection and Sobol generation.