Running universal machine-learned force fields: Difference between revisions

Latest revision as of 12:12, 29 June 2026

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.^[1] 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:^[2] we need a Python environment with the tensorpotential package installed. GRACE provides examples for loading and running their foundation models,^[3] 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.^[4] 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.^[5] 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.^[6] That page links to the DeePMD-kit package.^[7] 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.

References

↑ Matbench Discovery, Materials Project.
↑ GRACE documentation: Setting up the environment.
↑ GRACE tutorial: using-grace-fm.ipynb.
↑ GRACE fine-tuning tutorial: validate.ipynb.
↑ UPET documentation: lab-cosmo/upet.
↑ DPA-3.1-3M-FT model page: Matbench Discovery.
↑ DeePMD-kit: deepmodeling/deepmd-kit; see the pip installation instructions.

[1] Matbench Discovery, Materials Project.

[2] GRACE documentation: Setting up the environment.

[3] GRACE tutorial: using-grace-fm.ipynb.

[4] GRACE fine-tuning tutorial: validate.ipynb.

[5] UPET documentation: lab-cosmo/upet.

[6] DPA-3.1-3M-FT model page: Matbench Discovery.

[7] DeePMD-kit: deepmodeling/deepmd-kit; see the pip installation instructions.

[1]

[2]

[3]

[4]

[5]

[6]

[7]

@@ Line 1: / Line 1: @@
 {{Available|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 [[:Category:Machine-learned_force_fields|{{VASP}}-native force fields]] to drive any {{VASP}} simulation that uses or could use prediction-only mode ({{TAG|ML_MODE|run}}). This includes [[:Category:Molecular_dynamics|molecular dynamics simulations]], [[Structure_optimization|ionic optimization]] (see {{TAG|IBRION}}), and [[:Category:Advanced_molecular-dynamics_sampling|advanced sampling techniques]].
+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 [[:Category:Machine-learned_force_fields|{{VASP}}-native force fields]] to drive any {{VASP}} simulation that uses or could use prediction-only mode ({{TAG|ML_MODE|run}}). This includes [[:Category:Molecular_dynamics|molecular dynamics simulations]], [[Structure optimization|ionic optimization]] (see {{TAG|IBRION}}), and [[:Category:Advanced_molecular-dynamics_sampling|advanced sampling techniques]].
 We utilize the [[Plugins]] feature to call pre-trained uMLFF models via Python and have them calculate forces and stresses.
@@ Line 8: / Line 8: @@
 == Model selection ==
-A dedicated list of publicly available models, including performance benchmarks, can be found, for example, at MaterialsProject's [https://matbench-discovery.materialsproject.org/ 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.
+A dedicated list of publicly available models, including performance benchmarks, can be found, for example, at the Materials Project's Matbench Discovery.<ref>[https://matbench-discovery.materialsproject.org/ Matbench Discovery], Materials Project.</ref> 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.
+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 ===
@@ Line 32: / Line 32: @@
 </syntaxhighlight>
-Copy or move the <code>vasp_plugin.py</code> file to your calculation folder.
+Copy or move the <code>vasp_plugin.py</code> 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.
-We will now look at three example models and how to run them via <code>vasp_plugin.py</code>. Use a dedicated Python virtual environment to install the required packages.
 {{NB|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 [https://gracemaker.readthedocs.io/en/latest/gracemaker/install/#setting-up-the-environment documentation] to find we need a Python environment, and then install the <code>tensorpotential</code> package. GRACE offers [https://github.com/ICAMS/grace-tutorial/blob/main/3-foundation-models/1-python-ase/using-grace-fm.ipynb some examples] for how to load and run their foundation models, so we adapt this approach in <code>vasp_plugin.py</code>:
+: To wire up GRACE force fields via the [[Plugins]] infrastructure, check GRACE's documentation:<ref>GRACE documentation: [https://gracemaker.readthedocs.io/en/latest/gracemaker/install/#setting-up-the-environment Setting up the environment].</ref> we need a Python environment with the <code>tensorpotential</code> package installed. GRACE provides examples for loading and running their foundation models,<ref>GRACE tutorial: [https://github.com/ICAMS/grace-tutorial/blob/main/3-foundation-models/1-python-ase/using-grace-fm.ipynb using-grace-fm.ipynb].</ref> which we adapt in <code>vasp_plugin.py</code>:
 : <syntaxhighlight lang=py>
@@ Line 52: / Line 50: @@
 </syntaxhighlight>
-: Note that before running this code, you may need to download the model. Do so via <code>grace_models download GRACE_2L_OMAT</code> in a terminal of your choice. You can also get a list of all available foundation models via <code>grace_models list</code>. If you want to use a different model, remember to also update the <code>GRACEModels</code> enum in <code>vasp_plugin.py</code>.
+: Before running this code, you may need to download the model:
-: {{NB|important|In case you want to run a fine-tuned GRACE model, there is another GRACE [https://github.com/ICAMS/grace-tutorial/blob/main/3-foundation-models/3a-finetuning/validate.ipynb tutorial notebook] for how to access these using the <code>TPCalculator</code> class. In <code>vasp_plugin.py</code>, simply use that calculator and point to your fine-tuned model.}}
+: {{CB|grace_models download GRACE_2L_OMAT|:}}
-: {{NB|mind|Another way of running GRACE force fields in particular is via a special compiler flag, documented on a [[Running GRACE force fields in VASP|separate wiki page]]. Future development might break feature parity, but as of {{VASP}} 6.6.0, both [[plugins]] and compiler flag approach offer the same inference-only functionality.}}
+: List all available foundation models with:
+: {{CB|grace_models list|:}}
+: If you want to use a different model, remember to also update the <code>GRACEModels</code> enum in <code>vasp_plugin.py</code>.
+: {{NB|important|To run a fine-tuned GRACE model, follow the GRACE tutorial notebook for accessing these via the <code>TPCalculator</code> class.<ref>GRACE fine-tuning tutorial: [https://github.com/ICAMS/grace-tutorial/blob/main/3-foundation-models/3a-finetuning/validate.ipynb validate.ipynb].</ref> In <code>vasp_plugin.py</code>, use that calculator and point it to your fine-tuned model.}}
+: {{NB|mind|GRACE force fields can also be run via a special compiler flag, documented on a [[Running GRACE force fields in VASP|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 ====
-: Next, let's use the models of the <code>UPET</code> package (see also the [https://github.com/lab-cosmo/upet UPET documentation]). The documentation clarifies how to load different models, so install the package into your environment and then follow their instructions in <code>vasp_plugin.py</code>:
+: For the UPET package, the documentation clarifies how to load different models.<ref>UPET documentation: [https://github.com/lab-cosmo/upet lab-cosmo/upet].</ref> Install the package into your environment and follow their instructions in <code>vasp_plugin.py</code>:
 : <syntaxhighlight lang=py>
@@ Line 75: / Line 77: @@
 ==== 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 [https://matbench-discovery.materialsproject.org/models/dpa-3.1-3m-ft matbench-discovery] page. The documentation links to the [https://github.com/deepmodeling/deepmd-kit DeePMD-kit] package (see [https://docs.deepmodeling.com/projects/deepmd/en/stable/getting-started/install.html#install-python-interface-with-pip pip installation instructions]). Notice the file checkpoint has a <code>.pth</code> file extension, which indicates the PyTorch workflow is the one we need.
+: For the DPA-3.1-3M-FT model, the checkpoint must be downloaded separately from the package, as linked on its Matbench Discovery page.<ref>DPA-3.1-3M-FT model page: [https://matbench-discovery.materialsproject.org/models/dpa-3.1-3m-ft Matbench Discovery].</ref> That page links to the DeePMD-kit package.<ref>DeePMD-kit: [https://github.com/deepmodeling/deepmd-kit deepmodeling/deepmd-kit]; see the [https://docs.deepmodeling.com/projects/deepmd/en/stable/getting-started/install.html#install-python-interface-with-pip pip installation instructions].</ref> The checkpoint has a <code>.pth</code> file extension, which indicates the PyTorch workflow is the one we need.
 : The DeePMD-kit instructions are relatively straightforward, so adapt them for <code>vasp_plugin.py</code>:
@@ Line 110: / Line 112: @@
 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 {{FILE|OUTCAR}}.
+{{NB|mind|A valid {{FILE|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:
+==== {{FILE|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.
+==== {{FILE|POSCAR}} ====
+ Si diamond (lattice intentionally off-equilibrium to give the optimizer work)
+.0
+.5000000000000000    0.0000000000000000    0.0000000000000000
+.0000000000000000    5.5000000000000000    0.0000000000000000
+.0000000000000000    0.0000000000000000    5.5000000000000000
+   Si
+ Direct
+.0000000000000000  0.0000000000000000  0.0000000000000000
+.5000000000000000  0.5000000000000000  0.0000000000000000
+.5000000000000000  0.0000000000000000  0.5000000000000000
+.0000000000000000  0.5000000000000000  0.5000000000000000
+.2500000000000000  0.2500000000000000  0.2500000000000000
+.7500000000000000  0.7500000000000000  0.2500000000000000
+.7500000000000000  0.2500000000000000  0.7500000000000000
+.2500000000000000  0.7500000000000000  0.7500000000000000
+==== {{FILE|POTCAR}} ====
+Required for VASP to run. Use an Si {{FILE|POTCAR}}; it will not actually be used for the calculation.
+==== vasp_plugin.py ====
+We use [[Running universal machine-learned force fields#Example A: Model inference with the tensorpotential package (GRACE)|a GRACE model]] for this demonstration:
+: <syntaxhighlight lang=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)
+</syntaxhighlight>
+Then run:
+{{CB|mpirun -np 1 vasp_std|:}}
+VASP output should look something like:
+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
+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)
+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 {{FILE|CONTCAR}} shows the relaxed lattice:
+==== {{FILE|CONTCAR}} ====
+ Si diamond
+.0000000000000000
+.4461607390008595    0.0000000000000000    0.0000000000000000
+.0000000000000000    5.4461607390008595   -0.0000000000000000
+.0000000000000000   -0.0000000000000000    5.4461607390008595
+ ...
 == Recommendations and advice ==