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.

Mind: For GRACE force fields, most importantly if you require fine-tuning capabilities, please refer to the dedicated wiki page.

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 MaterialsProject'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

The following section, specifically Step 2, provides three examples of running different uMLFFs in VASP. Implementations vary between models, and the first step is always to understand how to call a particular model in Python directly before trying to have it called via the plugin. This also allows for easier and more comprehensive debugging.

Step 1: Compiling with Plugins support

To use Plugins, follow the instructions in the dedicated section of 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.

We will now look at three example models and how to run them via vasp_plugin.py. 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)

First, let's look at how to wire up some GRACE force fields via the Plugins infrastructure. To this end, we can check GRACE's documentation to find we need a Python environment, and then install the tensorpotential package. GRACE offers some examples for how to load and run their foundation models, so we adapt this approach 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)

Note that before running this code, you may need to download the model. Do so via grace_models download GRACE_2L_OMAT in a terminal of your choice. You can also get a list of all available foundation models via grace_models list. If you want to use a different model, remember to also update the GRACEModels enum in vasp_plugin.py.

Important: In case you want to run a fine-tuned GRACE model, there is another GRACE tutorial notebook for how to access these using the TPCalculator. In vasp_plugin.py, simply use that calculator and point to your fine-tuned model.

Mind: The recommended way for running GRACE force fields in VASP (particularly when fine-tuning capabilities are required) is documented on a dedicated wiki page. This example merely demonstrates an alternative way for an inference-only approach via Plugins.

Example B: Model inference with the UPET package

Next, let's use the models of the UPET package (see also the UPET documentation). The documentation clarifies how to load different models, so install the package into your environment and then 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

Next, let's use the DPA-3.1-3M-FT model. The model checkpoint needs to be downloaded separately from the package, as indicated and linked on its matbench-discovery page. The documentation links to the DeePMD-kit package (see pip installation instructions). Notice the file 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.

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