Ordered Alloy Prototype

Group: Alloy | Class: OrderedAlloyPrototypeCard

Purpose

Generate periodic structures with explicit crystallographic sublattice identity. Initial support covers A1/fcc, A2/bcc, A3/hcp, L1₂/A3B, B2/AB, and L1₀/AB. Sublattices are stored in the per-atom array atoms.arrays["sublattice"] and do not consume group, so magnetic-order layers, alternating layers, or region labels can still be added independently downstream.

This card creates only the cell, periodic boundaries, fractional coordinates, and sublattices. Element occupancy may use real elements immediately or the X placeholder, then pass to Finite-Cell Alloy Occupancy to generate ordered or partially disordered alloys with realizable integer counts.

Example

Scenario: high test error for L1₂ phases, but corner/face-center identity was not retained in the training set

The model’s force error for A3B ordered phases is much higher than for random solid solutions. The original training set merged all fcc sites into one set, so it could not systematically cover local environments where the A and B sublattices are disordered independently.

Input: none. Goal: first generate a periodic 32-atom L1₂ supercell with a strict A:B sublattice ratio of 24:8. Parameters: prototype="L12/A3B", a_range=[3.6,3.6,0.1], sublattice_elements="A:X,B:X", manual rep=[2,2,2], and max_atoms=32. Output: one periodic 32-atom structure whose sublattice array contains 24 A and 8 B entries. How to verify improved training-set quality: after constraining A/B occupancies downstream and obtaining DFT labels, compare energy and force errors in slices by prototype and sublattice disorder. Do not rely only on the aggregate RMSE.

Parameters

Prototype（prototype）

str, default "L12/A3B". Selects the crystal prototype and its fixed fractional coordinates and sublattice topology.

Option	Basis sites	Sublattice counts
A1/fcc	4	A=4
A2/bcc	2	A=2
A3/hcp	2	A=2
L12/A3B	4	A=3，B=1
B2/AB	2	A=1，B=1
L10/AB	4	A=2，B=2

Lattice Range（a_range）

tuple[float, float, float], default [3.6, 3.6, 0.1]; the start, stop, and step of lattice constant a, in Å.

Scan a narrow range when volume response is needed. Set start equal to stop when only one structure is required. Every scan point is subject to max_outputs.

c/a（covera）

float, default 1.0. A3/hcp and L1₀ use this value for c/a; cubic A1, A2, L1₂, and B2 fix it at 1 and disable the input in the UI so it cannot appear effective when it is not.

For A3, the ideal close-packed value of about 1.633 is a common starting point. For L1₀, use a tetragonal distortion range appropriate to the target system. Do not use this parameter as a substitute for a systematic downstream strain scan.

Sublattice Elements（sublattice_elements）

str, default "A:X,B:X". Assign basis occupancy as label:element, for example A:Fe,B:Al; X means the element has not yet been chosen.

Element selection carries no material prior: the card does not assume transition metals belong on A or restrict main-group elements to B. When the prototype changes, the UI reports the required labels and basis counts. A single-sublattice prototype shows only A instead of retaining an unused B configuration. Unknown labels fail explicitly.

Auto Supercell（auto_supercell）

bool, default true. When enabled, the card automatically chooses three-axis repeat counts without exceeding max_atoms.

Automatic mode is useful for quickly approaching the atom budget. For auditable fixed counts such as 24:8 or 8:8, manual repeats are usually clearer.

Max Atoms（max_atoms）

int, default 128. Hard upper bound on atoms in each output structure.

If the basis itself or manual rep exceeds this bound, the operation raises ValueError instead of silently reducing repeat counts or returning an over-budget structure.

Rep（rep）

tuple[int, int, int], default [2, 2, 2]. Manual repeat counts along the three lattice vectors.

Applies when auto_supercell=false. For L1₂, [2,2,2] produces exactly 32 atoms with A:B=24:8.

Max Outputs（max_outputs）

int, default 200. Maximum structures returned by the lattice-constant scan.

For a dense scan, this is a second budget gate independent of atom count. Once reached, the scan stops in deterministic a_range order.

Recommended presets

L1₂ 32-atom occupancy template

{
  "class": "OrderedAlloyPrototypeCard",
  "params": {
    "prototype": "L12/A3B",
    "a_range": [3.6, 3.6, 0.1],
    "covera": 1.0,
    "sublattice_elements": "A:X,B:X",
    "auto_supercell": false,
    "max_atoms": 32,
    "rep": [2, 2, 2],
    "max_outputs": 1
  }
}

L1₀ tetragonal-parameter scan

{
  "class": "OrderedAlloyPrototypeCard",
  "params": {
    "prototype": "L10/AB",
    "a_range": [3.7, 3.9, 0.1],
    "covera": 0.95,
    "sublattice_elements": "A:Fe,B:Pt",
    "auto_supercell": true,
    "max_atoms": 64,
    "rep": [2, 2, 2],
    "max_outputs": 3
  }
}

Recommended combinations

• Ordered Alloy Prototype → Finite-Cell Alloy Occupancy: first fix crystallographic sublattices, then generate occupancy from integer counts on each sublattice.

• Ordered Alloy Prototype → Lattice Strain → Atomic Perturb: add strain and local vibrational environments to the ordered phase.

• Ordered Alloy Prototype → Magnetic Order: keep crystallographic sublattice separate from magnetic group, then construct magnetic order independently.

Troubleshooting

The card reports an unknown sublattice label. Initial prototypes use only A/B. The occupancy mapping may retain both A and B to support prototype switching, but it cannot introduce arbitrary new labels.

The manual supercell exceeds max_atoms. The card fails explicitly and does not change the requested repeat counts. Reduce rep or raise the atom budget.

Why is there no relaxation? This card only generates a geometric prototype. Relaxation, potential evaluation, LAMMPS, chemical MC, and DFT submission are outside its scope.

Output labels

Config_type appends OrderedProto(<prototype>,a=<a>,rep=<na>x<nb>x<nc>). The ordered_alloy_prototype metadata records the prototype, lattice parameters, repeat counts, sublattice elements, and realized sublattice counts.

Reproducibility

This card performs no random sampling. The same parameters always produce identical cell, PBC, fractional coordinates, elements, and sublattice array.