Crystal Prototype Builder

Group: Lattice | Class: CrystalPrototypeBuilderCard

What the card does

Generate crystal structures directly from standard lattice prototypes such as fcc, bcc, hcp, and fcc111. After you choose an element and lattice constant, the card builds the template cell and can automatically repeat it toward a target atom count. This is a Generator card, so it does not require an input structure.

Example workflow

Scenario: the training set lacks samples for comparing crystal phases

You trained an NEP model on fcc Ni, and it reproduces the elastic and phonon properties of the fcc phase well. However, Ni may also have a metastable hcp phase. The model overestimates the hcp energy and fails to reproduce the fcc–hcp energy difference.

Diagnosis: The training set contains only one crystal phase, so the model naturally favors the only structure it has seen. Add clean fcc and hcp prototype structures so the model has reference points from which to learn the relative energies of the two phases. These prototypes need not be experimentally observed configurations; they act as anchors that help the model organize this region of configuration space.

Input: None. This Generator card does not depend on an upstream structure.

Goal: Generate both fcc and hcp Ni structures while scanning the lattice constant over a small range around the experimental value.

Parameters:

lattice = "fcc"，element = "Ni"，a_range = [3.52, 3.52, 0.05]
auto_supercell = true，max_atoms = 256
Add a second card with the same parameters but set lattice = "hcp".

Output: Ni supercells in the fcc and hcp phases, labeled Proto(fcc,a=...,rep=...) and Proto(hcp,a=...,rep=...).

How to verify that training-set quality improved:

After retraining, calculate the fcc–hcp energy difference and compare it with the DFT reference.
Check the atom count and symmetry of the output structures: fcc should be cubic and hcp should be hexagonal.
If the output contains far fewer atoms than max_atoms, automatic supercell selection could not find a suitable repetition. Disable auto_supercell and set Rep manually.

When to add this card

Add it when:

The training set lacks clean configurations of a standard crystal phase.
You need to compare the energies of different phases for a phase-stability study.
You need a structure factory as the starting point for a defect, surface, or magnetic workflow.

Do not add it when:

You already have enough experimental or DFT-relaxed structures and do not need synthetic prototypes.
The system is a complex multiphase material that cannot be represented by simple lattice prototypes.

Parameters

Lattice（lattice）

str, default: 'fcc'. Lattice prototype. Supported values are fcc, bcc, hcp, and fcc111.

Options	Meaning	When to choose it
`fcc`	Conventional face-centered-cubic cell	fcc bulk phases, alloy host lattices, and general strain or defect workflows
`bcc`	Conventional body-centered-cubic cell	bcc bulk phases, Bain paths, and vacancy or magnetic workflows
`hcp`	Hexagonal close-packed structure	hcp metastable phases and phase-stability comparisons
`fcc111`	Periodic slab-oriented cell whose third cell vector is normal to the fcc (111) plane	接 `Stacking Fault / GSFE Path`，扫 fcc (111) 面内滑移

fcc111 不是带真空的表面 slab；它仍然是周期 cell，只是把原始 fcc 的 (111) 面转成当前 cell 的 (001) 面。这样 Stacking Fault / GSFE Path 可以安全地按第三晶胞方向切开上下两半。

Element（element）

str，默认 'Cu'。元素符号，如 Cu、Ni、Si。对于化合物原型（如 rocksalt），这里只用第一个元素——后续需要用 Composition Space Sampling + Random Occupancy 来实现多元素分布。

A Range（a_range）

tuple[float, float, float], default: (3.6, 3.6, 0.1). Scan range for lattice constant a, in Å, expressed as [minimum, maximum, step]. A single-point range such as [3.52, 3.52, 0.1] produces one structure; [3.50, 3.60, 0.02] produces six. Smaller steps produce more structures, so use max_outputs to cap the total.

C/A（covera）

float, default: 1.633. The c/a ratio used only for the hcp prototype. The ideal value is approximately 1.633.

Auto Supercell（auto_supercell）

bool, default: true. When enabled, the card chooses repetition factors that approach Max Atoms. When disabled, set the repetition factors manually with Rep.

Max Atoms（max_atoms）

int, default: 512. Target maximum atom count, used only when auto_supercell is enabled. A typical range is 256–512.

Rep（rep）

tuple[int, int, int], default: (4, 4, 4). Repetition factors [na, nb, nc] along the three cell directions, used only when auto_supercell is disabled.

Max Outputs（max_outputs）

int, default: 200. Hard cap on the total number of output structures, preventing a lattice-constant scan or multi-prototype workflow from growing unexpectedly large.

Recommended presets

Single-point fcc Cu (1 output; a workflow starting point)

{
  "class": "CrystalPrototypeBuilderCard",
  "check_state": true,
  "params": {
    "lattice": "fcc",
    "element": "Cu",
    "a_range": [3.615, 3.615, 0.1],
    "covera": 1.633,
    "auto_supercell": true,
    "max_atoms": 256,
    "rep": [4, 4, 4],
    "max_outputs": 1
  }
}

fcc Cu lattice scan (5 points around the equilibrium lattice constant)

{
  "class": "CrystalPrototypeBuilderCard",
  "check_state": true,
  "params": {
    "lattice": "fcc",
    "element": "Cu",
    "a_range": [3.55, 3.65, 0.025],
    "covera": 1.633,
    "auto_supercell": true,
    "max_atoms": 256,
    "rep": [4, 4, 4],
    "max_outputs": 20
  }
}

Multiple-phase exploration (fcc and hcp, 5 points each)

{
  "class": "CrystalPrototypeBuilderCard",
  "check_state": true,
  "params": {
    "lattice": "hcp",
    "element": "Ni",
    "a_range": [3.50, 3.56, 0.015],
    "covera": 1.633,
    "auto_supercell": true,
    "max_atoms": 256,
    "rep": [4, 4, 4],
    "max_outputs": 20
  }
}

fcc111 GSFE 起点（1 个输出，接 Stacking Fault / GSFE Path）

{
  "class": "CrystalPrototypeBuilderCard",
  "check_state": true,
  "params": {
    "lattice": "fcc111",
    "element": "Ni",
    "a_range": [3.60, 3.60, 0.1],
    "covera": 1.633,
    "auto_supercell": false,
    "max_atoms": 256,
    "rep": [2, 2, 2],
    "max_outputs": 1
  }
}

Recommended combinations

Crystal Prototype Builder → Atomic Perturb: build the prototype, then add coordinate noise.
Crystal Prototype Builder → Composition Space Sampling → Random Occupancy：先生成干净模板，再进行成分修饰
Crystal Prototype Builder → Lattice Strain: build the prototype, then scan strain states.
Crystal Prototype Builder(fcc111) → Stacking Fault / GSFE Path：先生成 slab-oriented 周期 cell，再扫 fcc (111) 的 GSFE 路径

Common questions

Only one structure is produced. When the start and end of a_range are equal and the step is positive, the range contains a single point. Use different start and end values to perform a scan.

The atom count is far below max_atoms. Supercell repetition factors must be integers. If the primitive cell already contains many atoms, the next larger repetition may exceed max_atoms. Disable auto_supercell and set rep manually.

The hcp structure is not hexagonal. ASE’s hcp bulk builder requires a sensible covera value. Check that covera is around 1.6.

Stacking Fault / GSFE Path 报 slab-oriented 错误。 普通 fcc cell 的 (111) 面不等于当前 cell 的 (001) 面，第三晶胞方向也不垂直于这个面。用 lattice = "fcc111" 重新生成起点结构，再在层错卡中使用 plane_hkl = [0, 0, 1]。

Output labels

Proto({lattice type},a={lattice constant},rep={na}x{nb}x{nc})

Reproducibility

Deterministic. Identical parameters produce identical output.