Running GRACE force fields in VASP

Mind: Available as of VASP 6.6.0

Pre-trained GRACE machine-learned force fields can be used as an alternative to VASP-native force fields to drive essentially every VASP simulation which uses the the prediction-only mode ML_MODE = run. This includes molecular dynamics simulations, ionic optimization (see IBRION) and advanced sampling techniques. To be able to use GRACE force fields VASP must be built with VASPml (-Dlibvaspml) and GRACE support (-DVASPML_ENABLE_GRACE), for details see the build customization options.

Warning: Due to an incompatibility in the interface layer GRACE force fields from versions 0.5.8 and 0.5.9 of tensorpotential cannot be used together with VASP. A fix is currently work in progress. In the meantime please use force fields from tensorpotential 0.5.7. Be aware that for these models the metadata.json file generation step is mandatory (see box below).

Models

The easiest way to obtain GRACE models is to download them via the tensorpotential package, directly with pip or within a dedicated conda environment.

Tip: The tensorpotential package is not a runtime dependency of VASP but the most convenient way of listing and retrieving available models. Besides downloading a model the package is neither required for compiling nor for running VASP with GRACE force fields.

Install tensorpotential and all its dependencies simply with:

pip install tensorpotential==0.5.7

After installation the command line tool grace_models becomes available. First, inspect available models with

grace_models list

which will produce output like this:

...
Available models:
...
================================================================================
GRACE-2L-OMAT
	DESCRIPTION: A two-layer semi-local GRACE model, fitted on the OMat24 dataset, with fixed 6 A cutoff.
	PATH: /fsc/home/singraber/.cache/grace/GRACE-2L-OMAT
	CHECKPOINT: AVAILABLE, BUT NOT DOWNLOADED
	LICENSE: Academic Software License
================================================================================
...

Select a model and download it with the following command:

grace_models download [MODEL_NAME]

Given the example model above the command would be grace_models download GRACE-2L-OMAT. The GRACE model will be automatically downloaded and unpacked to the directory ~/.cache/grace/.

Hint for models created with tensorpotential version < 0.5.9: VASP requires the file metadata.json to be present inside the model directory. This file is automatically shipped with tensorpotential for models created since version 0.5.9. If you have an older version and the file is not present, please try to upgrade tensorpotential and re-download the models. Or, alternatively, create it from the metadata.yaml file with a Python script containing the following code snippet:

#!/usr/bin/env python
import yaml
import json
import pathlib
import sys

path = pathlib.Path(sys.argv[1])

with path.open() as f:
    data = yaml.safe_load(f)

with path.with_suffix(".json").open('w') as f:
    json.dump(data, f)

Save the Python code in a file, e.g. grace_yaml2json.py, and run it with:

python grace_yaml2json.py ~/.cache/grace/MODEL_NAME/metadata.yaml

This will automatically generate the missing JSON file in the model directory.

Select GRACE model in VASP

In the INCAR file the GRACE force field method must be selected via ML_TYPE = grace and the model may be specified via ML_GRACE_MODEL. A minimal block of tags could look like this:

...
# MD related settings, etc.
...
# ML force field settings
ML_LMLFF       = .TRUE.
ML_LIB         = .TRUE.
ML_MODE        = run
ML_TYPE        = grace
ML_GRACE_MODEL = GRACE-2L-OMAT
...

Important: The GRACE force field predictions are automatically offloaded to the GPU if one is available. However, currently parallelism via MPI is not supported when running GRACE force fields. Hence, start VASP with mpirun -np 1 ....