Running universal machine-learned force fields - Revision history

Liebetreu at 08:16, 17 June 2026

2026-06-17T08:16:00Z

← Older revision		Revision as of 08:16, 17 June 2026
Line 54:		Line 54:
	: 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>.		: 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>.
	: {{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.}}		: {{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.}}
	: {{NB\|mind\|Another way of running GRACE force fields via a ~~dedicated~~ compiler flag is documented on a [[Running GRACE force fields in VASP\|~~dedicated~~ 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.}}		: {{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.}}

	==== Example B: Model inference with the UPET package ====		==== Example B: Model inference with the UPET package ====

Liebetreu at 08:13, 17 June 2026

2026-06-17T08:13:49Z

← Older revision		Revision as of 08:13, 17 June 2026
Line 2:		Line 2:

	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]].
	~~{{NB\|mind\|For GRACE force fields, most importantly if you require fine-tuning capabilities, please refer to the [[Running GRACE force fields in VASP\|dedicated wiki page]].}}~~

	We utilize the [[Plugins]] feature to call pre-trained uMLFF models via Python and have them calculate forces and stresses.		We utilize the [[Plugins]] feature to call pre-trained uMLFF models via Python and have them calculate forces and stresses.
Line 17:		Line 16:
	=== Step 1: Compiling with Plugins support ===		=== Step 1: Compiling with Plugins support ===

	To use [[Plugins]], follow the [[Makefile.include#Plugins (optional)\|instructions ~~in the dedicated section of~~ the Makefile.include wiki page]]. Note that a re-compilation of VASP is required to enable Plugins support.		To use [[Plugins]], follow the [[Makefile.include#Plugins (optional)\|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 ===		=== Step 2: Setting up vasp_plugin.py ===
Line 54:		Line 53:

	: 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>.		: 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>.
	: {{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>. In <code>vasp_plugin.py</code>, simply use that calculator and point to your fine-tuned 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.}}
	: {{NB\|mind\|~~The recommended~~ way ~~for~~ running GRACE force fields ~~in VASP (particularly when fine-tuning capabilities are required)~~ is documented on a [[Running GRACE force fields in VASP\|dedicated wiki page]]. ~~This example merely demonstrates an alternative way for an inference-only approach via~~ [[~~Plugins~~]].}}		: {{NB\|mind\|Another way of running GRACE force fields via a dedicated compiler flag is documented on a [[Running GRACE force fields in VASP\|dedicated 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.}}

	==== Example B: Model inference with the UPET package ====		==== Example B: Model inference with the UPET package ====

Liebetreu: Liebetreu moved page Construction:Running universal machine-learned force fields in VASP to Running universal machine-learned force fields: Publish and align title with naming convention

2026-06-16T13:00:55Z

Liebetreu moved page Construction:Running universal machine-learned force fields in VASP to Running universal machine-learned force fields: Publish and align title with naming convention

← Older revision	Revision as of 13:00, 16 June 2026
(No difference)

Liebetreu at 12:59, 16 June 2026

2026-06-16T12:59:35Z

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

2026-06-11T15:12:02Z

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

← Older revision		Revision as of 15:12, 11 June 2026
Line 54:		Line 54:

	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>.		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>.
	{{NB\|important\|In case you want to run a fine-tuned GRACE model, there is ~~a similar~~ [https://github.com/ICAMS/grace-tutorial/blob/main/3-foundation-models/3a-finetuning/validate.ipynb tutorial] for how to access these using the <code>TPCalculator</code>. In <code>vasp_plugin.py</code>, simply use that calculator and point to your fine-tuned 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>. In <code>vasp_plugin.py</code>, simply use that calculator and point to your fine-tuned model.}}
	{{NB\|mind\|The recommended way for running GRACE force fields in VASP is documented on a [[Running GRACE force fields in VASP\|dedicated wiki page]]. This example merely demonstrates an alternative way via [[Plugins]].}}		{{NB\|mind\|The recommended way for running GRACE force fields in VASP is documented on a [[Running GRACE force fields in VASP\|dedicated wiki page]]. This example merely demonstrates an alternative way via [[Plugins]].}}

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

2026-06-11T12:18:16Z

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

← Older revision		Revision as of 12:18, 11 June 2026
Line 54:		Line 54:

	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>.		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>.
			{{NB\|important\|In case you want to run a fine-tuned GRACE model, there is a similar [https://github.com/ICAMS/grace-tutorial/blob/main/3-foundation-models/3a-finetuning/validate.ipynb tutorial] for how to access these using the <code>TPCalculator</code>. In <code>vasp_plugin.py</code>, simply use that calculator and point to your fine-tuned model.}}
	{{NB\|mind\|The recommended way for running GRACE force fields in VASP is documented on a [[Running GRACE force fields in VASP\|dedicated wiki page]]. This example merely demonstrates an alternative way via [[Plugins]].}}		{{NB\|mind\|The recommended way for running GRACE force fields in VASP is documented on a [[Running GRACE force fields in VASP\|dedicated wiki page]]. This example merely demonstrates an alternative way via [[Plugins]].}}

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

2026-06-11T12:09:42Z

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

← Older revision		Revision as of 12:09, 11 June 2026
Line 40:		Line 40:
	==== Example A: Model inference with the tensorpotential package (GRACE) ====		==== Example A: Model inference with the tensorpotential package (GRACE) ====

	First, let's look at how to wire some GRACE force fields up 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>:		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>:

	<syntaxhighlight lang=py>		<syntaxhighlight lang=py>

Liebetreu at 12:09, 11 June 2026

2026-06-11T12:09:09Z

← Older revision		Revision as of 12:09, 11 June 2026
Line 54:		Line 54:

	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>.		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>.

	{{NB\|mind\|The recommended way for running GRACE force fields in VASP is documented on a [[Running GRACE force fields in VASP\|dedicated wiki page]]. This example merely demonstrates an alternative way via [[Plugins]].}}		{{NB\|mind\|The recommended way for running GRACE force fields in VASP is documented on a [[Running GRACE force fields in VASP\|dedicated wiki page]]. This example merely demonstrates an alternative way via [[Plugins]].}}

Liebetreu at 12:07, 11 June 2026

2026-06-11T12:07:35Z

← Older revision		Revision as of 12:07, 11 June 2026
Line 13:		Line 13:
	== Step-by-step instructions ==		== Step-by-step instructions ==

	The following section, specifically Step 2, ~~demonstrates~~ three examples ~~for~~ 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 VASP plugin. This also allows for easier and more comprehensive debugging.		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 VASP plugin. This also allows for easier and more comprehensive debugging.

	=== Step 1: Compiling VASP with Plugins support ===		=== Step 1: Compiling VASP with Plugins support ===
Line 38:		Line 38:
	{{NB\|mind\|These examples are chosen for demonstration purposes and are not recommendations.}}		{{NB\|mind\|These examples are chosen for demonstration purposes and are not recommendations.}}

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

	First, let's look at how to wire some GRACE force fields up 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>:		First, let's look at how to wire some GRACE force fields up 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>:
Line 44:		Line 44:
	<syntaxhighlight lang=py>		<syntaxhighlight lang=py>
	from tensorpotential.calculator.foundation_models import GRACEModels, grace_fm		from tensorpotential.calculator.foundation_models import GRACEModels, grace_fm
	calculator=grace_fm(GRACEModels.GRACE_2L_OMAT)		calculator = grace_fm(GRACEModels.GRACE_2L_OMAT)

	from vasp.force_field import AseForceField # VASP force field wrapper class		from vasp.force_field import AseForceField # VASP force field wrapper class
Line 55:		Line 55:
	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>.		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>.

	{{NB\|mind\|The recommended way for running GRACE force fields in VASP is documented on a [[Running GRACE force fields in VASP \|~~different~~ wiki page]]. This example merely demonstrates an alternative way via [[Plugins]] ~~as a demonstration~~.}}		{{NB\|mind\|The recommended way for running GRACE force fields in VASP is documented on a [[Running GRACE force fields in VASP\|dedicated wiki page]]. This example merely demonstrates an alternative way via [[Plugins]].}}

	==== Example B: Model inference with UPET ~~Package~~ ====		==== 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>:		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>:
Line 74:		Line 74:
	Note that most models offer device choices depending on your CPU/GPU setup and preferences.		Note that most models offer device choices depending on your CPU/GPU setup and preferences.

	==== Example C: Model inference with DeePMD-Kit ~~Package~~ ====		==== Example C: Model inference with the DeePMD-Kit package ====

	Next, let's ~~instead~~ 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.		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.

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

Liebetreu at 12:01, 11 June 2026

2026-06-11T12:01:51Z

← Older revision		Revision as of 12:01, 11 June 2026
Line 13:		Line 13:
	== Step-by-step instructions ==		== Step-by-step instructions ==

	The following ~~two~~ examples ~~demonstrate~~ 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 VASP plugin. This also allows for easier and more comprehensive debugging.		The following section, specifically Step 2, demonstrates three examples for 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 VASP plugin. This also allows for easier and more comprehensive debugging.

	=== Step 1: Compiling VASP with Plugins support ===		=== Step 1: Compiling VASP with Plugins support ===
Line 35:		Line 35:
	Copy or move the <code>vasp_plugin.py</code> file to your VASP calculation folder.		Copy or move the <code>vasp_plugin.py</code> file to your VASP calculation folder.

	We will now look at ~~two~~ example models and how to run them in VASP via <code>vasp_plugin.py</code>. Use a dedicated Python virtual environment to install the required packages.		We will now look at three example models and how to run them in VASP 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.}}		{{NB\|mind\|These examples are chosen for demonstration purposes and are not recommendations.}}

	==== Example A: Model inference with ~~UPET~~ Package ====		==== Example A: Model inference with tensorpotential Package (GRACE) ====

	First, 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>:		First, let's look at how to wire some GRACE force fields up 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>:

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

			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>.

			{{NB\|mind\|The recommended way for running GRACE force fields in VASP is documented on a [[Running GRACE force fields in VASP \|different wiki page]]. This example merely demonstrates an alternative way via [[Plugins]] as a demonstration.}}

			==== Example B: Model inference with 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>:

	<syntaxhighlight lang=py>		<syntaxhighlight lang=py>
Line 55:		Line 74:
	Note that most models offer device choices depending on your CPU/GPU setup and preferences.		Note that most models offer device choices depending on your CPU/GPU setup and preferences.

	==== Example B: Model inference with DeePMD-Kit Package ====		==== Example C: Model inference with DeePMD-Kit Package ====

	Next, let's instead 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.		Next, let's instead 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.

← Older revision		Revision as of 12:59, 16 June 2026
Line 1:		Line 1:
	{{Available\|6.5.0}}		{{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 ~~essentially every~~ {{VASP}} simulation that uses ~~the~~ 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]].
	{{NB\|mind\|For GRACE force fields ~~and {{VASP}} ≥ 6.6.0~~, please refer to the [[Running GRACE force fields in VASP\|dedicated wiki page]].}}		{{NB\|mind\|For GRACE force fields, most importantly if you require fine-tuning capabilities, please refer to the [[Running GRACE force fields in VASP\|dedicated wiki page]].}}

	We utilize ~~{{VASP}}'s~~ [[Plugins]] feature to call pre-trained uMLFF models via Python and have them calculate forces and stresses.		We utilize the [[Plugins]] feature to call pre-trained uMLFF models via Python and have them calculate forces and stresses.
	{{NB\|important\|When employing uMLFFs, the accuracy and reliability of your calculations and results may vary. Thorough validation is advised.}}		{{NB\|important\|When employing uMLFFs, the accuracy and reliability of your calculations and results may vary. Thorough validation is advised.}}

Line 13:		Line 13:
	== Step-by-step instructions ==		== 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 ~~VASP~~ plugin. This also allows for easier and more comprehensive debugging.		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 ~~VASP~~ with Plugins support ===		=== Step 1: Compiling with Plugins support ===

	To ~~get VASP ready to~~ use [[Plugins]], follow ~~the instructions in the dedicated section of~~ the [[Makefile.include#Plugins (optional)\|Makefile.include]] ~~wiki page~~. Note that a re-compilation of VASP is required to enable Plugins support.		To use [[Plugins]], follow the [[Makefile.include#Plugins (optional)\|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 ===		=== Step 2: Setting up vasp_plugin.py ===
Line 33:		Line 33:
	</syntaxhighlight>		</syntaxhighlight>

	Copy or move the <code>vasp_plugin.py</code> file to your ~~VASP~~ calculation folder.		Copy or move the <code>vasp_plugin.py</code> file to your calculation folder.

	We will now look at three example models and how to run them ~~in VASP~~ via <code>vasp_plugin.py</code>. 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.}}		{{NB\|mind\|These examples are chosen for demonstration purposes and are not recommendations.}}

	==== Example A: Model inference with the tensorpotential package (GRACE) ====		==== 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>:		: 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>:

	<syntaxhighlight lang=py>		: <syntaxhighlight lang=py>
	from tensorpotential.calculator.foundation_models import GRACEModels, grace_fm		from tensorpotential.calculator.foundation_models import GRACEModels, grace_fm
	calculator = grace_fm(GRACEModels.GRACE_2L_OMAT)		calculator = grace_fm(GRACEModels.GRACE_2L_OMAT)
Line 53:		Line 53:
	</syntaxhighlight>		</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>.		: 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>.
	{{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>. In <code>vasp_plugin.py</code>, simply use that calculator and point to your fine-tuned 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>. In <code>vasp_plugin.py</code>, simply use that calculator and point to your fine-tuned model.}}
	{{NB\|mind\|The recommended way for running GRACE force fields in VASP is documented on a [[Running GRACE force fields in VASP\|dedicated wiki page]]. This example merely demonstrates an alternative way via [[Plugins]].}}		: {{NB\|mind\|The recommended way for running GRACE force fields in VASP (particularly when fine-tuning capabilities are required) is documented on a [[Running GRACE force fields in VASP\|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 ====		==== 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>:		: 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>:

	<syntaxhighlight lang=py>		: <syntaxhighlight lang=py>
	from upet.calculator import UPETCalculator		from upet.calculator import UPETCalculator
	calculator = UPETCalculator(model="pet-mad-s", version="1.5.0", device="cuda")		calculator = UPETCalculator(model="pet-mad-s", version="1.5.0", device="cuda")
Line 72:		Line 72:
	</syntaxhighlight>		</syntaxhighlight>

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

	==== Example C: Model inference with the DeePMD-Kit package ====		==== 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.		: 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.

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

	<syntaxhighlight lang=py>		: <syntaxhighlight lang=py>
	from deepmd.calculator import DP		from deepmd.calculator import DP
	calculator = DP(model="/path/to/dpa-3.1-3m-ft.pth")		calculator = DP(model="/path/to/dpa-3.1-3m-ft.pth")
Line 93:		Line 93:
	=== Step 3: Setting up your INCAR ===		=== 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):		Add the following tags to your {{FILE\|INCAR}} file (the rest of your prior setup can stay largely the same):

	{{TAG\|PLUGINS/FORCE_AND_STRESS\|True}}		{{TAG\|PLUGINS/FORCE_AND_STRESS\|True}}
Line 101:		Line 101:

	PLUGINS {		PLUGINS {
	FORCE_AND_STRESS = True		FORCE_AND_STRESS = True
	ML_MODE = run		ML_MODE = run
	}		}

	You may find one or the other style more intuitive to read; they are functionally identical.		You may find one or the other style more intuitive to read; they are functionally identical.
	{{NB\|important\|The {{TAG\|ML_MODE}} and {{TAG\|PLUGINS/ML_MODE}} tags differ in scope and purpose. ~~The latter~~ specifically controls ~~plugins behavior~~.}}		{{NB\|important\|The {{TAG\|ML_MODE}} and {{TAG\|PLUGINS/ML_MODE}} tags differ in scope and purpose. {{TAG\|ML_MODE}} controls {{FILE\|ML_FF}} interaction (not relevant here). {{TAG\|PLUGINS/ML_MODE}} specifically controls whether plugin-computed forces are added to VASP-computed forces or substitute them entirely. {{TAG\|PLUGINS/ML_MODE\|run}} ensures substitution.}}

	=== Step 4: Run calculation ===		=== Step 4: Run calculation ===

	Start your ~~VASP~~ 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.		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}}.

	== Recommendations and advice ==		== Recommendations and advice ==
Line 129:		Line 129:
	[[Category:Howto]]		[[Category:Howto]]
	[[Category:Machine-learned force fields]]		[[Category:Machine-learned force fields]]
			[[Category:Forces]]