dpgen Surface Workflows#

Overview#

dpgen init_surf generates initial training data for surface/slab systems, complementing dpgen init_bulk. It runs in two sequential stages 1:

• Stage 1 (00.place_ele): Build slab structures from a crystal prototype or an existing POSCAR, run VASP relaxation.
• Stage 2 (01.scale_pert): Scale and perturb the relaxed slabs, apply vacuum elongations, and generate POSCAR snapshots for DFT single-point calculations.

Entry point: dpgen/data/surf.py::gen_init_surf

init_surf param.json Configuration#

Full argument schema: dpgen/data/arginfo.py::init_surf_jdata_arginfo

Structure definition#

Stage 1 uses ASE's general_surface.surface() to cut slabs 2, then submits VASP relaxation jobs. Stage 2 reads the CONTCAR from relaxation (or POSCAR if skip_relax), applies scaling and vacuum elongation, then perturbs atom positions.

Perturbation parameters#

Vacuum parameters#

init_surf generates a sweep of vacuum thicknesses via poscar_elong 3, centering the slab in the elongated cell. Two specification methods 4:

Method A — fixed interval:

"vacuum_min": 2.0,
"vacuum_max": 8.0,
"vacuum_resol": [0.5]

Generates vacuum from vacuum_min to vacuum_max in steps of 0.5 Å.

Method B — two-zone interval (denser near surface, sparser far):

"vacuum_max": 8.0,
"vacuum_resol": [0.5, 2.0],
"mid_point": 3.0

Uses vacuum_resol[0] before mid_point and vacuum_resol[1] after.

Method C — count-based:

"vacuum_max": 8.0,
"vacuum_numb": 10,
"mid_point": 3.0,
"head_ratio": 0.6

Allocates vacuum_numb * head_ratio layers to the head (dense) region 5.

vacuum_min defaults to the maximum atomic radius of all elements if not set 6.

VASP INCAR Settings for Slabs#

ISIF = 2 is mandatory for slabs#

For slab structures with vacuum, use ISIF = 2 in relax_incar. This relaxes ionic positions only, keeping cell shape and volume fixed, which prevents the vacuum layer from collapsing during relaxation. Bulk systems typically use ISIF = 3 (full cell + ion relaxation). 7

Recommended relaxation INCAR for surface systems:

IBRION = 2
NSW = 100
ISIF = 2 ← critical for slabs
ISMEAR = 0
SIGMA = 0.05
LWAVE = .FALSE.
LCHARG = .FALSE.
ISYM = 0

For AIMD in stage 3 (md_incar):

IBRION = 0
ISIF = 2 ← keep cell fixed
TEBEG = 800
TEEND = 800
POTIM = 1.0

Selective Dynamics Flags: A Critical Warning#

dpgen strips selective dynamics flags when writing DFT input POSCARs during the run workflow. When LAMMPS trajectory frames are converted to POSCAR via sys.to_vasp_poscar() 8, the resulting dpdata.System objects lack a move field, so no F F F / T T T constraints are written.

Consequence: If bottom-layer atoms were fixed during LAMMPS MD exploration (via selective dynamics in the initial POSCAR), the FP calculation that follows will compute unconstrained forces on all atoms. This mismatch — constrained MD but unconstrained forces in training labels — produces inconsistent training data and degrades the model. 9 7

Recommended practice: Never rely on selective dynamics to freeze bottom-layer atoms in dpgen slab workflows. Instead, use a thick slab (≥ 6 layers) so that bottom layers naturally remain close to bulk positions without explicit constraints. 9

Training Data Strategy for Surface Systems#

scale_pert (box scaling + small displacements) is designed for periodic bulk crystals. For surface systems — especially those involving surface evaporation, desorption, or adsorption — it generates configurations too close to equilibrium to sustain MD trajectories at realistic temperatures. 9

Recommended initial dataset categories for reactive surface workflows:

Group sys_configs by environment type (one directory per structural environment, merge POSCARs from different temperatures into it); control temperature sampling via temps in model_devi_jobs. Use identical DFT settings (functional, ENCUT, KSPACING, pseudopotentials) across all data generation steps to avoid contradictory force labels. 9

Key Source Files#

Official docs: dpgen init_surf | Interactive config generator: https://dpgui.deepmodeling.com/input/dpgen-init-surf