Make Dataset Card Guide

This manual does more than define individual parameters. It helps you answer three practical questions:

• Which card should I choose first?

• When is this card worth adding to the workflow?

• How do I decide whether its output is reasonable?

For documentation-maintenance conventions, see Writing Card Documentation.

Recommended learning path

If this is your first time using Make Dataset, follow this order:

1. Start with “Choose a card by goal” to identify the main operation.

2. Read the card’s worked example to establish sensible parameter scales.

3. Then use Recipes to assemble a multi-card workflow.

Tip

In a high-throughput workflow that ends with FPS Filter, first export the candidate pool as XYZ and remove obvious failures in NEP Dataset Display, then perform representative selection. The built-in NEP89 model or an existing model for the same chemical system can help with preliminary screening, but its predictions are not DFT labels. FPS Filter belongs near the end of the pipeline; it selects from candidates and does not replace structure generation.

Choose a card by goal

Goal	Recommended card	Typical prerequisite	Common misuse
Enlarge a cell to make room for defects or surface operations	Super Cell	Crystal Prototype Builder	Using Random Slab as a supercell builder
Generate standard structures directly from crystal prototypes	Crystal Prototype Builder	None	Trying to construct a missing crystal prototype manually with Super Cell
Generate disordered atomic coordinates at a fixed cell and composition	Random Packing	Geometry Filter	Treating it as a magnetic-disorder card
Reject short contacts, abnormal volumes, or abnormal densities	Geometry Filter	A strong perturbation, random-occupancy, surface, or defect generator	Using FPS Filter as a geometry-validity check
Add mild coordinate noise near equilibrium	Atomic Perturb	Super Cell / a relaxed input	Using a large Lattice Perturb as atomic thermal noise
Scale cell volume or selected lattice directions	Lattice Perturb / Lattice Strain	Super Cell	Using Atomic Perturb to change the lattice
Scan c/a along a tetragonal transformation or epitaxial path	Bain Path	Crystal Prototype Builder / Super Cell	Replacing a systematic Bain path with an arbitrary axial strain
Apply shear or angular strain	Shear Matrix Strain / Shear Angle Strain	A known target strain direction	Forcing a pure-shear problem through Lattice Strain
Generate surface slabs	Random Slab	Super Cell	Using vacancy generation to create a surface
Generate an ordered-alloy prototype with crystallographic A/B sublattices	Ordered Alloy Prototype	None	Using group in place of crystallographic sublattice identity
Enumerate integer-realizable alloy compositions and arrangements in a finite cell	Finite-Cell Alloy Occupancy	Ordered Alloy Prototype / Super Cell	Rounding continuous fractions while still labeling the result as exact
Create a random alloy at one composition	Random Doping	Composition Space Sampling 可选	用 Composition Space Sampling 代替具体占位落点
Scan several target compositions	Composition Space Sampling	None	Building a composition grid manually with Random Doping
Create a spatial composition gradient	Composition Gradient	A sufficiently large structure with enough layers	Using global random occupancy as a diffusion couple or layered gradient
Realize a target composition on discrete atomic sites	Random Occupancy	Composition Space Sampling	只做 Composition Space Sampling 就当已经生成随机合金
Replace sites that satisfy explicit conditions	Conditional Replace	Optional Group Label	Using Random Doping for deterministic rule-based replacement
Generate a family of random vacancies	Vacancy Defect Generation	Super Cell	Using Random Slab to create surface vacancies
Remove selected sites by element or group	Random Vacancy	Optional Group Label	Encoding complex site rules in Vacancy Defect Generation
Create interstitials or adsorbates	Insert Defect	Random Slab / Super Cell	Using substitutional doping in place of insertion
做层错样本或扫描指定滑移系统的 GSFE 路径	Stacking Fault / GSFE Path	Crystal Prototype Builder 的 fcc111 原型 / 已定向晶胞	Scanning (111) directly in a conventional cubic cell
Assign group labels for downstream group-aware operations	Group Label	Super Cell	Assuming group labels already exist inside a magnetic card
Initialize FM, AFM, and PM-like orders	Magnetic Order	Optional Group Label	Using Set Magnetic Moments to generate multiple magnetic orders
Generate an order-to-disorder gradient from FM/AFM toward PM-like states	Spin Disorder	Set Magnetic Moments / Magnetic Order	Using continuous moment rotation for discrete sign flips
Generate noncollinear random moments with a spatial correlation length	Correlated Random Spin	Set Magnetic Moments / Magnetic Order	Calling every correlated random texture a spin glass
Write moments to a structure without creating several magnetic branches	Set Magnetic Moments	None	Using Magnetic Order for a single static assignment
Rotate existing moments, scan canting, apply a global tilt, or generate a spiral	Magmom Rotation / Small-Angle Spin Tilt / Spin Spiral / Folded Helix	Set Magnetic Moments / Magnetic Order	Trying to rotate a structure with no initial moments
Generate displacement samples from vibrational modes	Vib Mode Perturb	A structure that already contains mode arrays	Treating arbitrary coordinate noise as mode-resolved sampling
Sample organic molecular conformations	Organic Mol Config	A recognizable molecular structure	Applying an inorganic perturbation workflow indiscriminately to molecules
Build a local solvent shell around an ion, polar center, or solute	Local Solvation	An existing solute or ionic structure	Treating generated shells as equilibrated or quantum-optimized solvation structures
Fill an entire periodic cell with solvent starting configurations	Solvent Box Fill	A valid, nonsingular periodic cell	Using a local-shell card to fill the whole periodic box
Create a containerized branching workflow	Card Group	Any shared input	Treating Card Group as a filter
Select representative structures from a clean candidate pool	FPS Filter	A candidate pool cleaned in NEP Dataset Display	Using FPS Filter as the first quality gate

Cards that are easy to confuse

Random Slab vs Vacancy Defect Generation

• Random Slab changes surface orientation and cell geometry, introducing vacuum and free surfaces.

• Vacancy Defect Generation removes sites from an existing bulk or surface structure; it does not create a surface by itself.

• For surface defects, usually run Random Slab first, then Insert Defect or Vacancy Defect Generation.

Random Doping vs Composition Space Sampling vs Random Occupancy

• Composition Space Sampling 负责定义“目标配比空间”，输出仍是带目标配比标签的结构副本。

• Random Occupancy realizes each target composition on discrete atomic sites.

• Random Doping is better for applying explicit random substitution rules than for scanning a complete composition space.

Ordered Alloy Prototype vs Finite-Cell Alloy Occupancy

• Ordered Alloy Prototype creates the cell, periodic boundaries, fractional coordinates, and crystallographic A/B sublattices; it does not enumerate compositions.

• Finite-Cell Alloy Occupancy accepts existing sites or sublattices, first determines realizable integer counts, and then generates unique arrangements.

• To cover ordered-to-partially-disordered paths for L1₂, B2, and L1₀, generate the prototype first and then apply finite-cell occupancy.

Atomic Perturb vs Vib Mode Perturb

• Atomic Perturb adds model-free random displacements for quick near-equilibrium augmentation.

• Vib Mode Perturb uses existing normal modes to sample selected regions of vibrational-coordinate space.

• Vib Mode Perturb cannot operate until the input contains recognized mode arrays.

层错只保留一个新建入口

• 新任务统一使用 Stacking Fault / GSFE Path，显式填写 plane_hkl、位于面内的 slip_uvw、切面位置和位移路径。

• 它不限材料和晶面，但要求输入已经定向：第三晶胞方向必须垂直于 plane_hkl。普通 cubic fcc cell 若要扫原始 (111) 面，应先用 Crystal Prototype Builder 的 fcc111 原型或自行构造已定向晶胞。

• 旧 StackingFaultCard 仍保留在序列化注册表中，用于载入历史 JSON；因为它自动从全局笛卡尔轴推导滑移方向，所以不再显示在“添加新卡片”和“查找卡片”中。

Set Magnetic Moments vs Magnetic Order vs Magmom Rotation

• Set Magnetic Moments writes one consistent moment state and is intended for static initialization.

• Magnetic Order branches into FM, AFM, and PM-like initial states.

• Magmom Rotation perturbs existing directions and is suitable for local noncollinear augmentation.

Magnetic cards use the NEP / Show NEP spin:R:3 EXTXYZ field as their external contract. Internally, they also keep ASE initial_magmoms in sync for ASE operations and legacy workflows; exported files retain only spin. Existing moments are read from spin first and fall back to legacy initial_magmoms only when spin is absent. Scalar mode converts values to three-component spin vectors using the card’s explicit Axis; a zero Axis fails clearly instead of silently assuming a direction.

Browse by category

• Lattice: Super Cell、Crystal Prototype Builder、Random Packing、Lattice Strain、Bain Path、Lattice Perturb、Shear Matrix Strain、Shear Angle Strain

• Perturbation: Atomic Perturb、Vib Mode Perturb

• Alloy: Ordered Alloy Prototype、Finite-Cell Alloy Occupancy、Composition Space Sampling、Composition Gradient、Random Occupancy、Random Doping、Conditional Replace

• Defect / Surface: Random Slab、Random Vacancy、Vacancy Defect Generation、Insert Defect、Stacking Fault / GSFE Path、Layer Copy

• Magnetism: Set Magnetic Moments、Magnetic Order、Spin Disorder、Correlated Random Spin、Magmom Rotation、Small-Angle Spin Tilt、Spin Spiral、Folded Helix

• Filter / Container: Geometry Filter、FPS Filter、Card Group

• Organic: Organic Mol Config、Local Solvation、Solvent Box Fill