Make Dataset Recipes

This page answers two questions:

In what order should multiple cards be connected?
What kind of output should each step produce?

Tip

The JSON examples below are card-configuration fragments. Their field names match the current to_dict() output, so you can compare them directly with the presets on each card page. The recipes are independent of screenshots and do not require a particular example file.

Each card chain generates a candidate pool, not a labeled training set. The final clean in NEP Dataset Display → FPS step means: remove obvious failures first, then select representative structures. An existing NEP model for the same chemical system may help with preliminary screening; otherwise begin with geometry checks and manual inspection. In either case, final labels still come from the chosen reference calculation.

High-entropy alloy

Goal

Start from one crystal prototype, scan a set of target compositions, realize each composition on atomic sites, and finally add modest random substitutions to broaden local chemical environments.

Input assumptions

A bulk parent structure is available, or one will be generated with Crystal Prototype Builder.
The target element set is Co,Cr,Ni,Al,Fe.
The desired candidate pool covers several compositions and several random occupations per composition.

Card order

Crystal Prototype Builder → Composition Space Sampling → Random Occupancy → Random Doping → 导出 xyz → NEP Dataset Display 清洗 → FPS

JSON for each step

Step 1. `Crystal Prototype Builder`

{
  "class": "CrystalPrototypeBuilderCard",
  "params": {
    "lattice": "fcc",
    "element": "Ni",
    "a_range": [3.52, 3.52, 0.1],
    "covera": 1.633,
    "auto_supercell": true,
    "max_atoms": 64,
    "rep": [2, 2, 2],
    "max_outputs": 1
  }
}

Expected output: One base fcc structure whose atom count is controlled by max_atoms, suitable as the parent for the composition scan.

Step 2. `Composition Space Sampling`

{
  "class": "CompositionSweepCard",
  "params": {
    "elements": "Co,Cr,Ni,Al,Fe",
    "order": "4,5",
    "method": "Sobol",
    "step": 0.1,
    "n_points": 24,
    "min_fraction": 0.05,
    "include_endpoints": true,
    "use_seed": true,
    "seed": 42,
    "max_outputs": 24,
    "budget_mode": "Equal+Reflow"
  }
}

Expected output: 24 structure copies labeled Comp(...). These labels define target compositions; atomic sites have not yet been reassigned.

Step 3. `Random Occupancy`

{
  "class": "RandomOccupancyCard",
  "params": {
    "source": "Auto (Comp tag)",
    "manual": "",
    "mode": "Exact",
    "samples": 2,
    "group_filter": "",
    "use_seed": true,
    "seed": 42
  }
}

Expected output: Two discrete occupations for every target composition. If Step 2 produced 24 composition points, this step usually produces about 48 random-alloy candidates.

Step 4. `Random Doping`

{
  "class": "RandomDopingCard",
  "params": {
    "rules": [
      {
        "target": "Ni",
        "dopants": {"Co": 1.0, "Cr": 1.0},
        "use": "count",
        "count_mode": "random",
        "count": [1, 2],
        "percent": [0.0, 1.0]
      }
    ],
    "doping_type": "Exact",
    "max_structures": 2,
    "use_seed": true,
    "seed": 123
  }
}

Expected output: Two additional local-substitution variants for each discrete occupation, broadening local chemical diversity.

Resulting candidate-pool coverage

Includes both quaternary and quinary target compositions
Realizes every target composition on actual atomic sites
Combines occupation diversity with additional local substitutions

Common failure modes

只做 Composition Space Sampling 就停止：这只定义目标配比，不代表已经得到真实随机合金。
Random Occupancy does not read Comp(...) as its source: realized occupations can then disagree with the targets.
Overly aggressive Random Doping rules: they can shift the realized composition away from the intended target.

Defect-rich surfaces

Goal

Construct several surface orientations from a bulk parent, then add adsorbates or interstitials and vacancies to combine surface and defect environments.

Input assumptions

The input is a relaxed bulk crystal.
The target task is a surface reaction, surface stability, or defect-rich slab model.

Card order

Super Cell → Random Slab → Insert Defect → Vacancy Defect Generation → export XYZ → clean in NEP Dataset Display → FPS

JSON for each step

Step 1. `Super Cell`

{
  "class": "SuperCellCard",
  "params": {
    "behavior_type": 0,
    "mode": "scale",
    "super_scale": [2, 2, 1],
    "target_cell": [20.0, 20.0, 20.0],
    "max_atoms": 200,
    "fixed_axis_flags": [false, false, true],
    "fixed_axis_scale": [1, 1, 1]
  }
}

Expected output: One parent structure enlarged in-plane while remaining one cell thick along the intended normal, ready for slab cutting.

Step 2. `Random Slab`

{
  "class": "RandomSlabCard",
  "params": {
    "h_range": [0, 1, 1],
    "k_range": [0, 1, 1],
    "l_range": [1, 3, 1],
    "layer_range": [4, 8, 1],
    "vacuum_range": [12, 18, 2]
  }
}

Expected output: Several low- to moderate-index slabs. Verify that the selected vacuum separates periodic images; the output count is already larger than in Step 1.

Step 3. `Insert Defect`

{
  "class": "InsertDefectCard",
  "params": {
    "mode": 1,
    "species": "H,O",
    "insert_count": 1,
    "structure_count": 2,
    "min_distance": 1.2,
    "max_attempts": 50,
    "use_seed": true,
    "seed": 7,
    "axis": 2,
    "offset": 1.5
  }
}

每步预期输出： 每个 slab 再生成 2 个上表面随机吸附候选；这里只做连续横向采样和最小距离约束，不识别顶位、桥位或空位。

Step 4. `Vacancy Defect Generation`

{
  "class": "VacancyDefectCard",
  "params": {
    "engine_type": 1,
    "num_condition": 1,
    "use_num": false,
    "concentration_condition": 0.03,
    "count_mode": "fixed",
    "max_structures": 3,
    "use_seed": true,
    "seed": 19
  }
}

Expected output: About three mild-vacancy variants for each existing surface-defect structure. Vacancy strength is controlled by concentration, not a fixed removal count.

Resulting candidate-pool coverage

Covers different slab orientations, thicknesses, and vacuum sizes
Combines surfaces with interstitials or adsorbates and vacancies
Keeps defect concentration controllable while broadening surface-defect environments

Common failure modes

Creating vacancies before cutting slabs: bulk removals are then mistaken for deliberately selected surface defects.
An undersized vacuum_range: interactions between periodic slab images contaminate the calculation.
An excessive concentration_condition: a thin slab can lose its surface framework.

GSFE path

Goal

Generate an unrelaxed GSFE path for a specified slip system. Use this recipe when stacking-fault energies, slip barriers, or local minima disagree with DFT and the training set lacks a systematic interlayer-displacement path.

Input assumptions

The material is an fcc metal or near-fcc alloy.
The goal is a complete periodic in-plane path on fcc (111), not a free surface with vacuum.
The outputs will receive DFT single-point calculations or short relaxations before being added to the training set.

Card order

Crystal Prototype Builder(fcc111) → Stacking Fault / GSFE Path → 导出 xyz → NEP Dataset Display 清洗 → DFT

JSON for each step

Step 1. `Crystal Prototype Builder`

{
  "class": "CrystalPrototypeBuilderCard",
  "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
  }
}

Expected output: One slab-oriented periodic cell. Its current (001) plane corresponds to the original fcc (111) plane, and the third cell vector is normal to the fault plane.

Step 2. `Stacking Fault / GSFE Path`

{
  "class": "StrictGSFEPathCard",
  "params": {
    "plane_hkl": [0, 0, 1],
    "slip_uvw": [1, 0, 0],
    "displacement_range": [0.0, 1.0, 0.1],
    "displacement_unit": "fraction_of_vector",
    "cut_mode": "middle",
    "cut_fraction": 0.5,
    "layer_index": 0,
    "wrap": true
  }
}

Expected output: Eleven structures displaced along a periodic in-plane direction. The first and last represent equivalent periodic positions; intermediate structures provide points for the DFT GSFE curve.

Resulting candidate-pool coverage

Covers a complete slip period rather than one arbitrary fault displacement
Preserves hkl, uvw, and displacement in output labels for reconstructing the curve
Uses geometry that satisfies the slab-orientation contract, avoiding an invalid (111) scan in a conventional cubic cell

Common failure modes

直接把普通 fcc cubic cell 送进 Stacking Fault / GSFE Path：第三晶胞方向不垂直于目标 (111) 面，程序会报 slab-oriented 错误。
Treating fcc111 as a vacuum surface: it is a periodic oriented cell with no vacuum. Use Random Slab for a free surface.
Using a displacement step that is too coarse: 0.1 is suitable for an initial path, while 0.05 can resolve an insufficiently smooth peak region.

Magnetic data

Goal

Start from a magnetic parent, assign sublattice labels, generate FM, AFM, and PM-like branches, then rotate existing moments for local directional augmentation.

Input assumptions

The input structure is magnetic.
The candidate pool should cover several magnetic orders, not one MAGMOM initialization.

Card order

Group Label → Magnetic Order → Magmom Rotation

JSON for each step

Step 1. `Group Label`

{
  "class": "GroupLabelCard",
  "params": {
    "mode": "k_vector",
    "kvec": "111",
    "group_a": "A",
    "group_b": "B",
    "overwrite": false
  }
}

Expected output: One structure with a group array. If Magnetic Order uses group A/B mode, it reads these labels directly.

Step 2. `Magnetic Order`

{
  "class": "MagneticOrderCard",
  "params": {
    "format": "collinear",
    "axis": [0.0, 0.0, 1.0],
    "magmom_map": "Fe:2.2",
    "use_element_dirs": false,
    "default_moment": 0.0,
    "apply_elements": "Fe",
    "gen_fm": true,
    "gen_afm": true,
    "afm_mode": "group_ab",
    "afm_kvec": "111",
    "afm_group_a": "A",
    "afm_group_b": "B",
    "afm_zero_unknown": true,
    "gen_pm": true,
    "pm_count": 8,
    "pm_direction": "sphere",
    "pm_cone_angle": 30.0,
    "pm_balanced": true,
    "use_seed": true,
    "seed": 88,
    "max_outputs": 20
  }
}

每步预期输出： 得到 1 个 FM、1 个 AFM 和 8 个 PM 候选；afm_mode=group_ab 时，真正起作用的是 afm_group_a/b，不是 afm_kvec。

Step 3. `Magmom Rotation`

{
  "class": "MagneticMomentRotationCard",
  "params": {
    "elements": "Fe",
    "max_angle": 15.0,
    "num_structures": 3,
    "lift_scalar": true,
    "axis": [0.0, 0.0, 1.0],
    "disturb_magnitude": false,
    "magnitude_factor": [1.0, 1.0],
    "use_seed": true,
    "seed": 99
  }
}

Expected output: Three small-angle variants of each magnetic-order structure, adding samples near the noncollinear neighborhood.

Resulting candidate-pool coverage

Includes FM, AFM, PM-like, and small-angle branches
Makes the AFM sublattice assignment explicit and traceable
Controls random branches with a seed for repeatable comparisons

Common failure modes

Omitting magmom_map and a sensible default_moment: generated magnitudes become zero or otherwise unsuitable.
Selecting group A/B without a group array: the AFM branch lacks the intended sublattice definition.
Applying Magmom Rotation to a structure with no initial moments: there is nothing to rotate.

Organic conformations

Goal

Generate conformations for an organic molecule or molecular crystal, then add mild atomic perturbations to broaden the local structure distribution for NEP training.

Input assumptions

The input contains organic molecules or is a molecular crystal.
The data should cover both torsional conformations and local thermal-like noise, not only rigid translation.

Card order

Organic Mol Config → Atomic Perturb → export XYZ → clean in NEP Dataset Display → FPS

JSON for each step

Step 1. `Organic Mol Config`

{
  "class": "OrganicMolConfigPBCCard",
  "params": {
    "perturb_per_frame": 8,
    "torsion_range_deg": [-25.0, 25.0],
    "max_torsions_per_conf": 2,
    "gaussian_sigma": 0.01,
    "pbc_mode": "molecule in box",
    "local_cutoff": 5,
    "local_subtree": 100,
    "bond_detect_factor": 1.15,
    "bond_keep_min_factor": 0.75,
    "bond_keep_max_factor": 1.30,
    "bond_keep_max_enable": true,
    "nonbond_min_factor": 0.80,
    "max_retries": 50,
    "mult_bond_factor": 1.10,
    "nonpbc_box_size": 20.0,
    "bo_c_const": 0.35,
    "bo_threshold": 0.25,
    "use_seed": true,
    "seed": 5
  }
}

Expected output: Eight conformational variants per input frame. Their main changes come from torsions and local Gaussian displacements, not lattice deformation.

Step 2. `Atomic Perturb`

{
  "class": "PerturbCard",
  "params": {
    "engine_type": 0,
    "max_distance": 0.03,
    "max_num": 3,
    "identify_organic": true,
    "use_element_scaling": false,
    "element_scalings": {},
    "use_seed": true,
    "seed": 6
  }
}

Expected output: Three mildly perturbed variants of every conformation. With organic=true, molecular clusters are protected from independent atomic displacements that would otherwise damage their internal topology.

Resulting candidate-pool coverage

Covers torsional conformations and local thermal-like noise
Better preserves intramolecular bond topology
Suitable for an initial or augmentation set for organic systems

Common failure modes

Leaving organic disabled: independent atomic perturbations can distort intramolecular bonds.
Using an overly wide torsion_range_deg: candidates are more likely to be extremely high energy or self-intersecting.
Applying large atomic perturbations before conformational sampling: physical torsion changes become mixed with unphysical bond breaking.

Make Dataset Recipes

High-entropy alloy

Goal

Input assumptions

Card order

JSON for each step

Step 1. Crystal Prototype Builder

Step 2. Composition Space Sampling

Step 3. Random Occupancy

Step 4. Random Doping

Resulting candidate-pool coverage

Common failure modes

Defect-rich surfaces

Goal

Input assumptions

Card order

JSON for each step

Step 1. Super Cell

Step 2. Random Slab

Step 3. Insert Defect

Step 4. Vacancy Defect Generation

Resulting candidate-pool coverage

Common failure modes

GSFE path

Goal

Input assumptions

Card order

JSON for each step

Step 1. Crystal Prototype Builder

Step 2. Stacking Fault / GSFE Path

Resulting candidate-pool coverage

Common failure modes

Magnetic data

Goal

Input assumptions

Card order

JSON for each step

Step 1. Group Label

Step 2. Magnetic Order

Step 3. Magmom Rotation

Resulting candidate-pool coverage

Common failure modes

Organic conformations

Goal

Input assumptions

Card order

JSON for each step

Step 1. Organic Mol Config

Step 2. Atomic Perturb

Resulting candidate-pool coverage

Common failure modes

Step 1. `Crystal Prototype Builder`

Step 2. `Composition Space Sampling`

Step 3. `Random Occupancy`

Step 4. `Random Doping`

Step 1. `Super Cell`

Step 2. `Random Slab`

Step 3. `Insert Defect`

Step 4. `Vacancy Defect Generation`

Step 1. `Crystal Prototype Builder`

Step 2. `Stacking Fault / GSFE Path`

Step 1. `Group Label`

Step 2. `Magnetic Order`

Step 3. `Magmom Rotation`

Step 1. `Organic Mol Config`

Step 2. `Atomic Perturb`