DeePMD-kit Training: DPA3

Train a deep potential model using the DPA3 descriptor, an advanced message-passing architecture operating on Line Graph Series (LiGS). DPA3 is designed as a large atomic model (LAM) with high fitting accuracy and robust generalization across diverse chemical and materials systems.

Quick Start

dp --pt train input.json

Agent Responsibilities

1. Confirm the user has a working deepmd-kit environment with PyTorch backend.
2. Collect the minimum required information:
   • Training data paths (deepmd/npy or deepmd/hdf5 format)
   • Validation data paths
   • Element types (type_map)
   • Target number of training steps
   • Model size preference (L3/L6/L12 layers)
3. Generate a complete

   input.json

   training configuration.
4. Decide whether to use fixed or dynamic neighbor selection based on system diversity.
5. Run training and monitor the learning curve.
6. Freeze the trained model and optionally test it.

Workflow

Step 1: Prepare Training Data

Same format as other DeePMD models. Each system directory should contain:

system_dir/
├── type.raw
├── type_map.raw
└── set.000/
    ├── coord.npy
    ├── energy.npy
    ├── force.npy
    ├── box.npy
    └── virial.npy

DPA3 also supports the mixed type data format for multi-element systems.

Step 2: Write input.json

Standard DPA3 (fixed selection)

{
  "model": {
    "type_map": [
      "O",
      "H"
    ],
    "descriptor": {
      "type": "dpa3",
      "repflow": {
        "n_dim": 128,
        "e_dim": 64,
        "a_dim": 32,
        "nlayers": 6,
        "e_rcut": 6.0,
        "e_rcut_smth": 5.3,
        "e_sel": 120,
        "a_rcut": 4.0,
        "a_rcut_smth": 3.5,
        "a_sel": 30,
        "axis_neuron": 4,
        "fix_stat_std": 0.3,
        "a_compress_rate": 1,
        "a_compress_e_rate": 2,
        "a_compress_use_split": true,
        "update_angle": true,
        "smooth_edge_update": true,
        "edge_init_use_dist": true,
        "use_exp_switch": true,
        "update_style": "res_residual",
        "update_residual": 0.1,
        "update_residual_init": "const"
      },
      "activation_function": "silut:10.0",
      "use_tebd_bias": false,
      "precision": "float32",
      "concat_output_tebd": false,
      "seed": 1
    },
    "fitting_net": {
      "neuron": [
        240,
        240,
        240
      ],
      "resnet_dt": true,
      "precision": "float32",
      "activation_function": "silut:10.0",
      "seed": 1
    }
  },
  "learning_rate": {
    "type": "exp",
    "decay_steps": 5000,
    "start_lr": 0.001,
    "stop_lr": 3e-05
  },
  "loss": {
    "type": "ener",
    "start_pref_e": 0.2,
    "limit_pref_e": 20,
    "start_pref_f": 100,
    "limit_pref_f": 60,
    "start_pref_v": 0.02,
    "limit_pref_v": 1
  },
  "optimizer": {
    "type": "AdamW",
    "adam_beta1": 0.9,
    "adam_beta2": 0.999,
    "weight_decay": 0.001
  },
  "training": {
    "stat_file": "./dpa3.hdf5",
    "training_data": {
      "systems": [
        "./data/train_0",
        "./data/train_1",
        "./data/train_2"
      ],
      "batch_size": 1
    },
    "validation_data": {
      "systems": [
        "./data/valid_0"
      ],
      "batch_size": 1
    },
    "numb_steps": 1000000,
    "gradient_max_norm": 5.0,
    "seed": 10,
    "disp_file": "lcurve.out",
    "disp_freq": 100,
    "save_freq": 2000
  }
}

If you do not want to train on virial, set the virial prefactors to 0.

DPA3 uses different default loss prefactors compared to SE_E2_A. See the comparison table in the "Key Differences from SE_E2_A" section below.

The meaning of each parameter can be generated through

dp doc-train-input

grep

dp doc-train-input | grep -A 7 training/numb_steps
dp doc-train-input | grep -A 7 'model\[standard\]/descriptor\[dpa3\]/repflow/e_sel'

DPA3 with Dynamic Selection

For systems with highly variable neighbor counts (e.g., multi-element datasets), use dynamic selection by modifying the

repflow

"repflow": {
  "e_sel": 1200,
  "a_sel": 300,
  "use_dynamic_sel": true,
  "sel_reduce_factor": 10.0
}

When

use_dynamic_sel

e_sel / sel_reduce_factor

a_sel / sel_reduce_factor

Step 3: Run Training

dp --pt train input.json

To restart from a checkpoint:

dp --pt train input.json --restart model.ckpt.pt

Step 4: Monitor Training

The learning curve is written to

lcurve.out

#  step  rmse_val  rmse_trn  rmse_e_val  rmse_e_trn  rmse_f_val  rmse_f_trn  rmse_v_val  rmse_v_trn  lr

• rmse_e_*

  : energy RMSE per atom (eV/atom)

• rmse_f_*

  : force RMSE (eV/A)

• rmse_v_*

  : virial RMSE (eV/atom, only present if virial data is available)

• lr

  : current learning rate

Step 5: Freeze the Model

dp --pt freeze -o model.pth

Step 6: Test the Model

dp --pt test -m model.pth -s /path/to/test_system -n 30

Model Size Guide

Choose the number of layers based on accuracy vs. cost trade-off:

Benchmark RMSE (averaged over 6 representative systems, 0.5M steps):

Key Differences from SE_E2_A

Key Hyperparameters

Repflow (Descriptor)

n_dim

e_dim

a_dim

nlayers

e_rcut

e_rcut_smth

e_sel

a_rcut

a_rcut_smth

a_sel

update_style

update_residual

Activation Function

DPA3 uses

silut:10.0

tanh

"descriptor": {
  "type": "dpa3",
  "repflow": { ... },
  "activation_function": "tanh"
},
"fitting_net": {
  "activation_function": "tanh"
}

Optimizer

DPA3 uses AdamW by default (decoupled weight decay):

"optimizer": {
  "type": "AdamW",
  "adam_beta1": 0.9,
  "adam_beta2": 0.999,
  "weight_decay": 0.001
}

Gradient Clipping

Recommended for DPA3 to stabilize training:

"training": {
  "gradient_max_norm": 5.0
}

Agent Checklist

• Training data exists and is in deepmd format

• type_map

  matches the elements in the data
• Precision is set to

  float32

  (DPA3 default, not float64)
• AdamW optimizer is configured with weight_decay

• gradient_max_norm

  is set (recommended: 5.0)

• stop_lr

  is 3e-5 (not 3.51e-8 as in SE_E2_A)
• Virial loss prefactors are included if virial data is available

• stat_file

  is set to cache statistics (avoids recomputation on restart)
• Training completes without NaN in

  lcurve.out

• Model is frozen to

  .pth

  after training

References

• DPA3 descriptor documentation
• DPA3 paper
• Training documentation
• DeePMD-kit GitHub