Running universal machine-learned force fields

Mind: Available as of VASP 6.5.0

Universal machine-learned force fields (uMLFF, or alternatively: uMLIP for "universal machine-learned interatomic potentials") offer a fast alternative to the computational demands of DFT. Pre-trained uMLFFs can be used as an alternative to VASP-native force fields to drive any VASP simulation that uses or could use prediction-only mode (ML_MODE = run). This includes molecular dynamics simulations, ionic optimization (see IBRION), and advanced sampling techniques.

We utilize the Plugins feature to call pre-trained uMLFF models via Python and have them calculate forces and stresses.

Important: When employing uMLFFs, the accuracy and reliability of your calculations and results may vary. Thorough validation is advised.

Model selection

A dedicated list of publicly available models, including performance benchmarks, can be found, for example, at the Materials Project's Matbench Discovery. As a general rule of thumb, choose a model with good relevant metrics that was trained on a broad choice of datasets. Between models with similar metrics, choose a model with fewer parameters for faster inference.

Step-by-step instructions

Implementations vary between models. Always confirm how to call a particular model in Python directly before invoking it via the plugin; this allows for easier and more comprehensive debugging. Step 2 below works through three example models.

Step 1: Compiling with Plugins support

To use Plugins, follow the instructions on the Makefile.include wiki page. Note that a re-compilation of VASP is required to enable Plugins support.

Step 2: Setting up vasp_plugin.py

Most models specify how to call them from Python. The instructions for how to install the corresponding packages and load their calculator instances will differ from model to model, but the vasp_plugin.py file should always contain (at least) the following:

calculator = ...                                # different for each model

from vasp.force_field import AseForceField      # VASP force field wrapper class
force_field = AseForceField(calculator)         # apply wrapper class

def force_and_stress(constants, additions):     # to compute force and stress via the uMLFF model instead of VASP's DFT routines
    force_field.force_and_stress(constants, additions)

Copy or move the vasp_plugin.py file to your calculation folder. The following three examples show how to run different models. Use a dedicated Python virtual environment to install the required packages.

Mind: These examples are chosen for demonstration purposes and are not recommendations.

Example A: Model inference with the tensorpotential package (GRACE)

To wire up GRACE force fields via the Plugins infrastructure, check GRACE's documentation: we need a Python environment with the tensorpotential package installed. GRACE provides examples for loading and running their foundation models, which we adapt in vasp_plugin.py:

from tensorpotential.calculator.foundation_models import GRACEModels, grace_fm
calculator = grace_fm(GRACEModels.GRACE_2L_OMAT)

from vasp.force_field import AseForceField  # VASP force field wrapper class
force_field = AseForceField(calculator)         # apply wrapper class

def force_and_stress(constants, additions):     # to compute force and stress via the uMLFF model instead of VASP's DFT routines
    force_field.force_and_stress(constants, additions)

Before running this code, you may need to download the model:

grace_models download GRACE_2L_OMAT

List all available foundation models with:

grace_models list

If you want to use a different model, remember to also update the GRACEModels enum in vasp_plugin.py.

Important: To run a fine-tuned GRACE model, follow the GRACE tutorial notebook for accessing these via the TPCalculator class. In vasp_plugin.py, use that calculator and point it to your fine-tuned model.

Mind: GRACE force fields can also be run via a special compiler flag, documented on a separate wiki page. Future development might break feature parity, but as of VASP 6.6.0, both the plugins and the compiler-flag approach offer the same inference-only functionality.

Example B: Model inference with the UPET package

For the UPET package, the documentation clarifies how to load different models. Install the package into your environment and follow their instructions in vasp_plugin.py:

from upet.calculator import UPETCalculator
calculator = UPETCalculator(model="pet-mad-s", version="1.5.0", device="cuda")

from vasp.force_field import AseForceField      # VASP force field wrapper class
force_field = AseForceField(calculator)         # apply wrapper class

def force_and_stress(constants, additions):     # to compute force and stress via the uMLFF model instead of VASP's DFT routines
    force_field.force_and_stress(constants, additions)

Note that most models offer device choices depending on your CPU/GPU setup and preferences.

Example C: Model inference with the DeePMD-Kit package

For the DPA-3.1-3M-FT model, the checkpoint must be downloaded separately from the package, as linked on its Matbench Discovery page. That page links to the DeePMD-kit package. The checkpoint has a .pth file extension, which indicates the PyTorch workflow is the one we need.

The DeePMD-kit instructions are relatively straightforward, so adapt them for vasp_plugin.py:

from deepmd.calculator import DP
calculator = DP(model="/path/to/dpa-3.1-3m-ft.pth")

from vasp.force_field import AseForceField      # VASP force field wrapper class
force_field = AseForceField(calculator)         # apply wrapper class

def force_and_stress(constants, additions):     # to compute force and stress via the uMLFF model instead of VASP's DFT routines
    force_field.force_and_stress(constants, additions)

Step 3: Setting up your INCAR

Add the following tags to your INCAR file (the rest of your prior setup can stay largely the same):

PLUGINS/FORCE_AND_STRESS = True
PLUGINS/ML_MODE = run

Note that this can also be written differently:

PLUGINS {
   FORCE_AND_STRESS = True
   ML_MODE = run
}

You may find one or the other style more intuitive to read; they are functionally identical.

Important: The ML_MODE and PLUGINS/ML_MODE tags differ in scope and purpose. ML_MODE controls ML_FF interaction (not relevant here). PLUGINS/ML_MODE specifically controls whether plugin-computed forces are added to VASP-computed forces or substitute them entirely. PLUGINS/ML_MODE = run ensures substitution.

Step 4: Run calculation

Start your calculation the same way you usually would. If everything works as expected, you should notice a significant speedup and no electronic steps showing up in your OUTCAR.

Mind: A valid POTCAR is required to start the calculation, even though uMLFFs will not use it.

Example calculation: Si diamond

We demonstrate the approach for a cell structure optimization of an out-of-equilibrium Si diamond lattice. Set up a calculation folder with the following files:

INCAR

SYSTEM = Si diamond
PLUGINS {
  FORCE_AND_STRESS = True
  ML_MODE = run
}
IBRION = 2        # conjugate-gradient ionic relaxation
ISIF   = 3        # relax ions + cell shape + cell volume
NSW    = 200      # max ionic steps
EDIFFG = -0.01    # control force-convergence criterion
POTIM  = 0.2      # CG trial step
KSPACING = 0.25
LWAVE  = .FALSE.
LCHARG = .FALSE.

POSCAR

Si diamond (lattice intentionally off-equilibrium to give the optimizer work)
1.0
    5.5000000000000000    0.0000000000000000    0.0000000000000000
    0.0000000000000000    5.5000000000000000    0.0000000000000000
    0.0000000000000000    0.0000000000000000    5.5000000000000000
  Si
   8
Direct
 0.0000000000000000  0.0000000000000000  0.0000000000000000
 0.5000000000000000  0.5000000000000000  0.0000000000000000
 0.5000000000000000  0.0000000000000000  0.5000000000000000
 0.0000000000000000  0.5000000000000000  0.5000000000000000
 0.2500000000000000  0.2500000000000000  0.2500000000000000
 0.7500000000000000  0.7500000000000000  0.2500000000000000
 0.7500000000000000  0.2500000000000000  0.7500000000000000
 0.2500000000000000  0.7500000000000000  0.7500000000000000

POTCAR

Required for VASP to run. Use an Si POTCAR; it will not actually be used for the calculation.

vasp_plugin.py

We use a GRACE model for this demonstration:

from tensorpotential.calculator.foundation_models import GRACEModels, grace_fm
calculator = grace_fm(GRACEModels.GRACE_2L_OMAT)

from vasp.force_field import AseForceField  # VASP force field wrapper class
force_field = AseForceField(calculator)         # apply wrapper class

def force_and_stress(constants, additions):     # to compute force and stress via the uMLFF model instead of VASP's DFT routines
    force_field.force_and_stress(constants, additions)

Then run:

mpirun -np 1 vasp_std

VASP output should look something like:

  1 F= -.47087326E+02 E0= -.47087326E+02  d E =-.470873E+02
curvature:   0.00 expect dE= 0.000E+00 dE for cont linesearch  0.000E+00
trial: gam= 0.00000 g(F)=  0.470E-39 g(S)=  0.513E-01 ort = 0.000E+00 (trialstep = 0.100E+01)
search vector abs. value=  0.513E-01
  2 F= -.47121998E+02 E0= -.47121998E+02  d E =-.346718E-01
trial-energy change:   -0.034672  1 .order   -0.034453   -0.051264   -0.017642
step:   1.5247(harm=  1.5247)  dis= 0.00000  next Energy=   -47.126408 (dE=-0.391E-01)
  3 F= -.47126526E+02 E0= -.47126526E+02  d E =-.391998E-01
curvature:  -0.76 expect dE=-0.474E-05 dE for cont linesearch -0.474E-05
trial: gam= 0.00000 g(F)=  0.946E-39 g(S)=  0.622E-05 ort =-0.565E-03 (trialstep = 0.110E+01)
search vector abs. value=  0.622E-05
reached required accuracy - stopping structural energy minimisation

Notice especially the lack of electronic steps in the optimization. The CONTCAR shows the relaxed lattice:

CONTCAR

Si diamond
  1.0000000000000000
    5.4461607390008595    0.0000000000000000    0.0000000000000000
    0.0000000000000000    5.4461607390008595   -0.0000000000000000
    0.0000000000000000   -0.0000000000000000    5.4461607390008595
...

Recommendations and advice

• All else being equal, try picking models with good benchmark metrics, broader training datasets, and fewer parameters. The number of parameters directly affects inference speed.

Related tags and articles

Plugins, Running GRACE force fields in VASP

Files: Makefile.include

Tags: PLUGINS/ML_MODE, PLUGINS/FORCE_AND_STRESS