Skip to content

8.9 Train, validate and deploy VASP-native machine-learned force fields

These are unexecuted teaching inputs and starting settings to test. Original figures are schematics, not computed results. Use licensed VASP and PAW data, replace every placeholder, record the executable version and validate convergence.

8.9.1 Model, units and provenance

Use eV for energy, Å for length and eV/Å for force; 1 kbar = 0.1 GPa. State normalization per atom, molecule, primitive cell or simulation cell. Record PAW identifiers, release, ZVAL, ENMAX and permitted hashes; never redistribute POTCAR. SCF convergence addresses the chosen electronic problem; convergence of the target property requires separate tests.

 Train, validate and deploy VASP-native machine-learned force fields — original conceptual schematic

Original schematic. Curves explain concepts; blank data areas await verified learner results. No calculation is claimed.

8.9.2 Worked case: procedure, interpretation and checks

Intuition and scope

A force field is a model of an energy landscape. Learning that landscape can make long trajectories feasible, but a fast wrong landscape produces wrong results efficiently. The essential question is whether the model covers the environments and thermodynamic conditions your production run will actually visit.

This case concerns VASP-native MLFF and its own training database/model files. It is not a MACE tutorial. MACE is a separate machine-learning framework with its own architectures, checkpoints, training procedures and deployment interfaces. A MACE checkpoint is not an ML_FF file, and renaming it does not convert it. A model trained on VASP-labelled configurations is not thereby a VASP-native model. MACE’s official documentation describes its separate ASE and other interfaces. MACE documentation

Version gate. The string-valued ML_MODE workflow begins with VASP 6.4.0. Older releases use other controls; do not translate an old tutorial by guesswork. Verify the executable, build options, supported hardware and exact tags before preparing production. Newer capabilities are release-specific and outside this baseline lesson. ML_MODE

Prerequisites. Reliable DFT energies, forces and, for variable-cell work, stresses; a consistent PAW/functional/spin/dispersion reference; validated MD integration; enough budget for held-out reference calculations. Define the domain in a model card: elements, compositions, phases, temperatures, densities, charge/spin states, defects, surfaces and intended observables. “Contains the same elements” is an inadequate domain definition.

Stage 1: establish a coherent training domain

Create several physically motivated training segments: moderate thermal disorder around the main state, controlled volume or strain variation if needed, relevant defects and coordination environments, and transitions the final run may encounter. Avoid unrealistic close-contact configurations created merely to make the dataset “diverse.” They can dominate a loss function without improving the intended domain. If repulsive configurations are needed for stability, generate and validate them deliberately.

Keep one DFT reference definition. Combining incompatible functionals, U values, spin states or inconsistent energy zeroes requires an explicit multi-model strategy, not blind file concatenation. Preserve all input provenance and map every label back to the source calculation. Stress component order, sign and units must be audited when importing external data.

On-the-fly training can alternate model-driven steps with DFT evaluations when the internal criterion requests new information. This supports efficient data collection, but its uncertainty estimate is a model diagnostic, not a proof of error bounds everywhere. VASP MLFF overview

Use separate directories for every stage. The training output database is ML_ABN; when continuing training from it, provide a reviewed copy as ML_AB. Before copying, verify successful completion, a nonempty parsed database and matching provenance. The model output ML_FFN is distinct from the database. Do not overwrite the only copies of either. The official hands-on tutorial is a useful executable-oriented companion; do not reuse its material-specific convergence choices without testing. Official MLFF MD tutorial

Stage 2: split by physical independence and validate

Randomly splitting adjacent frames from one trajectory can leak nearly identical structures into train and test. Hold out entire trajectory segments, independent starts, temperature windows or structural families that reflect the intended generalization test. Do not tune hyperparameters on the final test set.

On held-out snapshots compare DFT and ML:

  • Energy errors in eV/atom, with a clearly defined common energy reference.
  • Force component RMSE and maximum absolute errors in eV/Å; inspect species- and environment-resolved tails.
  • Stress errors with verified units/sign, when pressure or elasticity is relevant.
  • Error versus temperature, density, coordination, bond length and the actual reaction/defect coordinate.
  • Derived quantities: stable structures, RDF, volume distribution, diffusion or barrier-related energies, according to the intended use.

A low average force RMSE can hide a catastrophic minority environment. Examine outliers with their structures and reference convergence. If reference SCF failed, the label is not automatically ground truth. If the model fails an intended environment, return to data collection and retraining, then use an untouched final test.

A parity plot must include actual computed held-out points and a stated split. Until those calculations exist, show a diagram of the validation process, not a fabricated near-diagonal cloud.

Stage 3: refit and deploy cautiously

For the fast native prediction route, refit the reviewed training database, then pass the generated model to a fresh production directory. The fast model does not retain Bayesian error estimates; independent spot checks remain important. ML_MODE=run performs model prediction only and does not secretly call DFT to rescue extrapolation. ML_LFAST

Start with a short deployment pilot. Revalidate NVE conservation and the target ensemble’s behaviour. Run periodic independent DFT evaluations of representative and suspicious production snapshots; choose them by a documented rule rather than only selecting easy-looking structures. A model can conserve its own energy perfectly while predicting the wrong physics. Increasing the timestep because forces are cheaper is a separate numerical change requiring new tests.

Record model hash, VASP version, database lineage, refit settings, validation split, error metrics, approved domain and known exclusions. Keep native-MLFF and external-model runs clearly labelled in every figure. If comparing MACE, pin the exact checkpoint and software version; foundation-model defaults may change, and pretraining level of theory may differ from your chosen DFT reference. MACE foundation models

Traps: treating internal estimated error as calibrated confidence; validating on training frames; equating energy RMSE with force quality; assuming pure prediction retrains itself; mixing database and model file names; applying a bulk-only model to reactive surfaces; confusing MACE, VASP-native MLFF and any other external-potential interface.

Exercise. Write a one-page model card before training. Include a negative test outside the intended domain and state what evidence would forbid deployment. After validation, compare the proposed domain with the demonstrated domain and narrow the claims when necessary.

8.9.3 Unexecuted inputs and analysis scaffolds

These are unexecuted teaching inputs and starting settings to test. Original figures are schematics, not computed results. Use licensed VASP and PAW data, replace every placeholder, record the executable version and validate convergence.

8.9.3.1 Input block 1

# UNEXECUTED native-MLFF training delta; requires supported VASP build
ML_LMLFF = .TRUE.
ML_MODE = train
# Add the validated MD ensemble/timestep and consistent DFT settings.
# Start without ML_AB only when intentionally beginning a new database.

8.9.3.2 Input block 2

# UNEXECUTED refit-stage delta; reviewed ML_AB must be present
ML_LMLFF = .TRUE.
ML_MODE = refit

8.9.3.3 Input block 3

# File flow, not a command to run blindly:
validated training/ML_ABN -> refit/ML_AB
successful refit/ML_FFN -> production/ML_FF

8.9.3.4 Input block 4

# UNEXECUTED prediction-stage delta; validated ML_FF must be present
ML_LMLFF = .TRUE.
ML_MODE = run
# Reapply the validated production MD settings and output cadence.

8.9.5 Technical sources