Finite-Cell Alloy Occupancy

Group: Alloy | Class: FiniteCellAlloyOccupancyCard

Purpose

Generate alloy occupancies from integer counts that are actually realizable on a finite set of sites. If the input contains atoms.arrays["sublattice"], each sublattice is constrained independently; otherwise all sites form one site set named all.

A composition plan first fixes an integer count for every element, then generates unique randomized arrangements. The card never samples an arbitrary continuous fraction and rounds it silently, nor labels an indivisible target as Exact. Metadata records the request, actual counts and fractions, composition ID, and arrangement ID.

The main card UI is a visual rule editor. Choose All Sites or By Sublattice, add elements to each site set, and select a composition mode. Changing modes shows only the fraction or count fields that apply:

  • fixed_fraction: specify fixed target fractions. A divisible target is marked exact; otherwise the card uses a deterministic nearest-integer plan marked nearest_integer.

  • fraction_range: enumerate plans whose realized integer fractions fall within each element’s range.

  • count_range: enumerate plans whose integer counts fall within each element’s range and sum to the number of sites.

Example

Scenario: a nominal 20% target in a small-cell HEA repeatedly maps to the same realized composition

32 位点随机固溶体经过连续 Composition Space Sampling 后再取整，多个目标点可能都变成同一整数计数组合，训练集看似有很多组成，实际却重复。

Input: a periodic 32-atom A1/fcc supercell. Goal: enumerate realizable Fe/Co/Ni integer counts directly and generate four distinct arrangements for each composition. Parameters: use all in site_rules (or A for an input with a single A sublattice), select count_range, and give all three elements explicit integer ranges; set arrangements_per_composition=4, a fixed seed, and max_outputs. Output: each composition ID maps to a unique integer-count combination, and arrangement IDs are unique within a composition. How to verify improved training-set quality: aggregate the metadata counts, confirm every frame sums to 32 and composition IDs are unique, then compare retrained errors in slices based on realized fractions rather than the original continuous targets.

Parameters

Site partitioning and Site Rules (site_rules)

默认界面先显示 A/B 规则模板中的 X 占位符，但 X 不是可输出的元素。接入上游结构且规则尚未被手动编辑时，卡片会立即按首个输入结构的实际 site set、元素和当前比例生成安全规则。例如 Ni/Al 的 A/B 结构会自动得到真实的 Ni、Al 规则，而不会生成 X 原子。

{"A":{"composition":{"X":1.0},"elements":["X"],"mode":"fixed_fraction"},"B":{"composition":{"X":1.0},"elements":["X"],"mode":"fixed_fraction"}}

“无子晶格标签（all）”模板会建立 all 规则；“A/B 子晶格”模板会建立彼此独立的 A、B 规则。JSON 顶层 key 必须与输入的 site set 完全一致。有 sublattice 时逐个编辑 A、B 等标签；没有时使用 all。卡片不会把 all 静默套到每个子晶格，也不会使用 group 代替 sublattice。

规则仍由卡片自动管理时，载入上游结构会按实际标签和元素自动匹配：普通无标签结构使用 all，A1/A2/A3 等单子晶格原型使用单独的 A 规则，L1₂/B2/L1₀ 保持 A/B。界面会明确提示自动匹配结果。只要用户编辑过规则、主动选择过模板、粘贴过 JSON 或载入过持久化参数，卡片就不再自动覆盖，标签不匹配或仍含 X 时改为显示错误。

切换位点划分或应用模板会整体替换当前规则。已有手动编辑时，界面会先确认，避免误删元素、范围和 site set。

When an input structure is available, the UI shows the actual site count beside each rule and immediately reports missing or extra labels, invalid or duplicate elements, range errors, and infeasible integer plans. Persistence still uses the site_rules string. Advanced: View/Paste JSON is collapsed by default and can copy the current format or accept an older configuration. Invalid JSON never overwrites the current valid visual rules.

Fixed-composition example:

{"A":{"elements":["Fe","Co"],"mode":"fixed_fraction","composition":{"Fe":0.5,"Co":0.5}}}

可视化编辑器要求固定比例之和为 1，例如 0.5 + 0.5。旧项目或直接调用 operation 的 JSON 若使用 1 + 1 这类相对权重，底层仍会归一化以保持兼容；界面新建和修改规则时不再依赖这种隐式归一化。

Fraction-range example:

{"B":{"elements":["Al","Ni"],"mode":"fraction_range","fractions":{"Al":[0.25,0.75],"Ni":[0.25,0.75]}}}

Integer-count-range example:

{"A":{"elements":["Fe","Co"],"mode":"count_range","counts":{"Fe":[8,16],"Co":[8,16]}}}

每种组成的排布数（arrangements_per_composition）

int, default 1. The number of distinct atomic arrangements requested for each realized integer-count combination.

If a composition has fewer theoretically unique arrangements than requested, only the realizable number is returned. For example, two sites occupied by one Fe and one Co have only two arrangements; requesting ten does not duplicate results to reach the requested count.

使用固定种子（use_seed）

bool, default true. When enabled, composition-budget sampling and each composition’s arrangements are derived from a fixed seed.

The feasible composition domain itself does not depend on the seed. The seed only determines which plans are selected when over budget and which specific sites receive each element.

Seed（seed）

int, default 0. Base seed for the deterministic random path.

Applies when use_seed=true. Identical inputs, rules, and seed produce the same composition/arrangement order and occupancy. Changing the seed does not alter realized counts, but usually changes arrangements.

每个输入的最大输出数（max_outputs）

int, default 200. Hard limit on the number of structures returned for one input structure.

预算不足以覆盖全部组成时，operation 先在整数计划索引空间中按固定步长确定性选择可覆盖的组成，再采用“组成优先”的轮转调度：先为每个选中组成生成第 1 个排布，再生成各组成的第 2 个排布，以此类推。因此，小预算不会先被单一组成的多个排布耗尽。

输入结构与规则都可用时，UI 用数据集中的首个输入结构计算位点数和可行整数组成数，并显示输出上限估计。这个数字是 可行组成数 × 每组成请求排布数 的上界；某些组成的唯一排布数不足时，实际输出会更少。没有输入时只提示先载入上游结构，不显示伪精确数字。

Recommended presets

32-site binary random solid solution

{
  "class": "FiniteCellAlloyOccupancyCard",
  "params": {
    "site_rules": "{\"A\":{\"elements\":[\"Fe\",\"Co\"],\"mode\":\"count_range\",\"counts\":{\"Fe\":[8,24],\"Co\":[8,24]}}}",
    "arrangements_per_composition": 4,
    "use_seed": true,
    "seed": 17,
    "max_outputs": 68
  }
}

L1₂ 子晶格部分无序

{
  "class": "FiniteCellAlloyOccupancyCard",
  "params": {
    "site_rules": "{\"A\":{\"elements\":[\"Fe\",\"Co\",\"Ni\"],\"mode\":\"fraction_range\",\"fractions\":{\"Fe\":[0.25,0.5],\"Co\":[0.25,0.5],\"Ni\":[0.0,0.5]}},\"B\":{\"elements\":[\"Al\",\"Ta\"],\"mode\":\"count_range\",\"counts\":{\"Al\":[4,8],\"Ta\":[0,4]}}}",
    "arrangements_per_composition": 3,
    "use_seed": true,
    "seed": 23,
    "max_outputs": 120
  }
}

Recommended combinations

  • Ordered Alloy Prototype → Finite-Cell Alloy Occupancy: cover ordered and sublattice-disordered occupancies for L1₂, B2, and L1₀.

  • Crystal Prototype Builder → Super Cell → Finite-Cell Alloy Occupancy: for an ordinary FCC/BCC structure without sublattice, use the single all site set to generate a random solid solution.

  • Finite-Cell Alloy Occupancy → Atomic Perturb → Lattice Strain: add coordinate and lattice perturbations after occupancy is fixed; leave magnetic moments to Magnetic Order or Spin Disorder.

Troubleshooting

The card reports missing rules or unknown site sets. Every top-level key must match an actual input sublattice label. An ordinary unlabeled structure can use only all; the operation does not fall back to group.

The card reports no integer solution. The sum of element count lower bounds may exceed the number of sites, or the upper bounds may sum to less than the number of sites. Fraction ranges are first converted to integer bounds realizable by the current cell before the sum is checked.

输出少于 arrangements_per_composition。 该组成的理论排布数已耗尽，或触发了 max_outputs。这不是随机失败，卡片不会用重复排布伪造样本数。触发总输出上限时，卡片优先覆盖不同组成，再为同一组成增加排布。

提示仍含占位元素 X。 X 只用于没有输入时展示规则结构，operation 会拒绝生成含 X 的结果。接入真实结构后可让未编辑的规则自动匹配，也可以手动把 X 替换为实际元素。

Output labels

Config_type appends FiniteAlloy(comp=<composition_id>,arr=<arrangement_id>). The finite_cell_alloy metadata is a JSON string containing realized counts and fractions, requested rules, realization status, composition ID, arrangement ID, and derived seed for every site set.

Reproducibility

Runs are strictly reproducible with fixed use_seed=true and seed. Over-budget composition sampling uses deterministic index order, and arrangements are deduplicated by per-site element sequence without depending on set iteration order.