Running machine-learned force fields in LAMMPS: Difference between revisions

From VASP Wiki
No edit summary
 
(18 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Quick How-To for experienced '''VASP'''/'''LAMMPS''' users ==
[https://www.lammps.org LAMMPS] is a very popular molecular dynamics (MD) package which implements lots of advanced simulation methods. Although {{VASP}} itself also offers [[:Category:Molecular_dynamics|MD simulations]] LAMMPS provides more flexibility and additional methods (e.g. thermostats/barostats, grouping atoms, etc.). This page describes how to make pre-trained {{VASP}} machine-learned force fields available within LAMMPS. On a technical level this is achieved by patching the LAMMPS source code in such way that a new [https://docs.lammps.org/pair_style.html <code>pair_style</code>] named <code>vasp</code> is available in the LAMMPS script language. The patched LAMMPS source is compiled and then linked to the [[VASPml library]]. The first section describes in detail how to patch and compile LAMMPS. The second section explains how the {{VASP}} {{FILE|ML_FF}} file can be loaded in a LAMMPS script.
{{NB|warning|The VASPml library and therefore also the LAMMPS interface are experimental features. Please carefully check results and, if feasible, compare against similar VASP MD simulations.}}


1. Just like in '''VASP''' pick a template from the <code>arch</code> directory and copy it to the base directory, e.g.
= Building LAMMPS with VASPml patch =


<code>
Before starting the LAMMPS build please compile {{VASP}} with the [[VASPml library#Build instructions|VASPml library]]. To confirm that everything is ready we can check for the presence of the following files:
cp arch/makefile.include.gnu makefile.include
</code>


2. Modify the build settings in <code>makefile.include</code> according to your system.
* <code>/path/to/vasp/build/VERSION/vaspml/lib/libvaspml.a</code>
3. Compile a patched version of '''LAMMPS''' with support for '''VASP''' machine-learned force fields:
* <code>/path/to/vasp/build/VERSION/vaspml/include/InterfaceLAMMPS.hpp</code>


<code>
where <code>VERSION</code> is any of <code>std</code>, <code>gam</code> or <code>ncl</code>. It does not matter which {{VASP}} build version is used because the VASPml library will be identical in all three cases.
make lammps -j
</code>


4. Switch to the <code>examples/lammps/CsPbBr3</code> directory and try to run the example MD simulation, e.g. with
Next, we need to obtain the LAMMPS source code with the patch for VASPml. Please clone the following repository to your hard disk and change into the LAMMPS root directory:


<code>
git clone https://github.com/vasp-dev/lammps
mpirun -np 4 ../../../bin/lmp_mpi -in in.lmp
cd lammps
</code>


5. Inspect the '''LAMMPS''' input script <code>in.lmp</code> and modify it to your needs.
At this point looking around in the git repository will show the files from the <code>develop</code> branch (the main development branch of LAMMPS). However, the patch files are located in another branch, hence we need to switch with this command:


If unsure, consult the following detailed documentation sections below:
git checkout vasp-mlff


- [Build instructions](#build-instructions)
Then, while still in the LAMMPS root directory we need to create a symbolic link from <code>lammps/lib/vasp/vaspml</code> to the actual location of the VASPml folder:
    - [Prerequisites](#prerequisites)
    - [Build library and applications](#build-library-and-applications)
    - [Automatic patching and compilations of **LAMMPS**](#automatic-patching-and-compilations-of-lammps)
- [Running '''LAMMPS''' with '''VASP''' machine-learned force field](#running-lammps-with-vasp-machine-learned-force-field)
    - ['''LAMMPS''' input scripts](#lammps-input-scripts)
    - ['''LAMMPS''' input data file](#lammps-input-data-file)
    - [Example directory](#example-directory)


== Build instructions ==
ln -s /path/to/vasp/build/std/vaspml lib/vasp/


In future the source of '''VASPml''' will be distributed as part of the official '''VASP''' release. The build process of '''VASP''' will include the steps necessary to compile and link also the '''VASPml''' library and interfaces. However, at this point (and most likely even when integrated into '''VASP''') it is possible to build '''VASPml''' completely independent of '''VASP'''. The following sections describe details of such an independent build of '''VASPml'''.
Again, it is not important which of the three {{VASP}} build directories (<code>std</code>, <code>gam</code> or <code>ncl</code>) is used because the VASPml library is the same. For the remaining steps we need to change into the <code>src</code> directory:


=== Prerequisites ===
cd src


1. '''VASPml''' requires a C++ compiler conforming to the C++17 language standard, for example, compilers which are part of:
The source files for the <code>pair_style vasp</code> are part of the optional package <code>ML-VASP</code> which can be activated with this command:
    - GNU Compiler Collection
    - Intel oneAPI Base Toolkit
    - NVIDIA HPC SDK
    - NEC SDK
2. Numerical libraries: LAPACK and BLAS, which are distributed for example as part of:
    - OpenBLAS
    - Intel oneAPI Math Kernel Library (part of Base Toolkit)
    - NVIDIA HPC SDK
    - NEC NLC (NEC Numeric Library Collection)
3. An MPI (Message Passing Interface) implementation, e.g. in
    - OpenMPI
    - Intel MPI (part of Intel oneAPI HPC Toolkit)
    - NVIDIA HPC SDK (OpenMPI)
    - NEC MPI


=== Build library and applications ===
make yes-ml-vasp


Similar to '''VASP''' also '''VASPml''' requires to enter compiler details and library paths into a file named <code>makefile.include</code> before the build process can be started. Template files for this file can be found in the <code>arc</code> subdirectory. Usually, it is convenient to start from one of these files. Hence, first copy it to the base directory and rename it to <code>makefile.include</code>, e.g.
Before we can finally start the build process it is necessary to adapt the LAMMPS makefile in <code>MAKE/Makefile.mpi</code>. Modify the <code>CC</code> and <code>LINK</code> variables to match the compiler used during the [[VASPml library#Build instructions|VASPml build process]] (<code>CXX_ML</code> variable). Also match the compiler flags in <code>CCFLAGS</code> and <code>LINKFLAGS</code> to <code>CXXFLAGS_ML</code>. Flags do not need to be identical but at least compatible compiler features should be used. Since VASPml requires BLAS and LAPACK we may also need to complete the <code>LIB</code> variable with the required libraries and their paths. For the GNU compiler with openBLAS it may look like this:


<code>
...
cp arch/makefile.include.gnu makefile.include
CC =    mpic++
</code>
CCFLAGS = -g -O3 -std=c++17
...
LINK =    mpic++
LINKFLAGS = -g -O3 -std=c++17
LIB = -L${OPENBLAS_ROOT}/lib -lopenblas


Then modify the contents to reflect the compiler and library settings on your machine, for details see the [compiler and linker options](#compiler-and-linker-options) section below. Once done, the '''VASPml''' library can be built by executing this command in the top directory:
Finally, compile the LAMMPS source code with this command:


<code>
make mpi
make -j
</code>


This will automatically build the two _targets_ <code>libvaspml</code> and <code>applications</code>, and is equivalent to running two make commands explicitly in this order:
Optionally, add the <code>-j</code> flag to perform a parallel build (faster). If the build process succeeds the LAMMPS executable <code>lmp_mpi</code> will be located in the <code>lammps/src</code> directory.


<code>
= Setting up a LAMMPS MD run =
make libvaspml -j


make applications -j
LAMMPS comes with its own powerful script language which allows the user to specify all relevant MD simulation parameters in a single file. Please consult the [https://docs.lammps.org/Commands_input.html LAMMPS documentation] for details. Within the LAMMPS script language the commands <code>pair_style</code> and <code>pair_coeff</code> are responsible for selecting a force field. The <code>ML-VASP</code> package introduces a new <code>pair_style</code> called <code>vasp</code>. The <code>pair_style vasp</code> command does not have any additional arguments, all configurable settings are given as arguments to the <code>pair_coeff</code> command in this format:
</code>


The <code>libvaspml</code> target builds the library with the same name and places it in the <code>lib</code> folder. The <code>applications</code> target compiles and links standalone applications present in <code>src/applications</code>. At the moment there is only one application named <code>vaspml-predict</code> which predicts energy, forces, and stress for one {{FILE|POSCAR}} file with a given {{FILE|ML_FF}} force field file. The executable will be copied to the <code>bin</code> directory.
<pre>pair_style vasp
pair_coeff * * file types</pre>
The <code>pair_coeff</code> command must be followed by <code>* *</code>, then followed by the name of the {{VASP}} force field file, typically <code>ML_FF</code>. Finally, there comes a mapping from LAMMPS atom types to {{VASP}} force field types, e.g., <code>H O Na Cl</code> means that LAMMPS types <code>1</code>, <code>2</code>, <code>3</code> and <code>4</code> are mapped to {{VASP}} types <code>H</code>, <code>O</code>, <code>Na</code> and <code>Cl</code>, respectively. A valid example may look like this:


With the <code>-j</code> flag present <code>make</code> will run the build process in parallel, starting as many parallel jobs as possible. You can limit the maximum load the build process is allowed to cause with the <code>-l</code> flag, please review the documentation of GNU <code>make</code>.
<pre>pair_style vasp
pair_coeff * * ML_FF Pb Br Cs</pre>
This will map the LAMMPS atom types <code>1</code>, <code>2</code> and <code>3</code> in the [https://docs.lammps.org/read_data.html input data file] to the types <code>Pb</code>, <code>Br</code> and <code>Cs</code> for which a pre-trained machine-learned force field should be present in the <code>ML_FF</code> file in the execution directory. A summary of the type mapping is provided in the screen output and the <code>log.lammps</code> file, e.g. for the example above it looks like this:


==== Compiler and linker options ====
<pre>   LAMMPS      pair_coeff      VASP      |            VASP force field
 
The following compiler and linker options in the <code>makefile.include</code> should be reviewed and eventually modified before starting the build process:
 
- <code>CXX</code>: This should be a C++17-compatible C++ compiler with MPI support.
- <code>CXXFLAGS</code>: Specifies the flags for the C++ compiler.
- <code>INCLUDE</code>: Paths in which to look for headers of required libraries. Here the include directory of BLAS should be listed.
- <code>FC</code> (deprecated)
- <code>FFLAGS</code> (deprecated)
 
==== Compile-time options ====
 
- <code>-DVASPML_DEBUG_LEVEL</code>: If set to 1, 2 or 3 enables various sanity checks during runtime with low, medium and high impact on performance, respectively.
- <code>-DVASPML_USE_CBLAS</code>: Use CBLAS (C interface for BLAS routines) for linear algebra. This is the default and should always be used.
- <code>-DVASPML_USE_MKL</code>: Use Intel MKL for linear algebra.
- <code>-DVASPML_FORTRAN_MATH</code> (deprecated): Enable legacy Fortran math routines.
 
==== Makefile options ====
 
- <code>--no-color</code>: Disables colored output of makefiles.
- <code>--no-logo</code>: Disables the logo '''VASPml''' logo output.
 
==== Automatic patching and compilations of **LAMMPS** ====
 
<code>
make lammps -j
</code>
 
=== Technical details ===
 
From a technical standpoint **LAMMPS** and **VASPml** interact in the following way: on the **LAMMPS** side a new  class `PairVASP` (inheriting from `Pair`) is implemented in `pair_vasp.cpp/h`. Its purpose is to transfer the neighbor lists to **VASPml**, trigger processing, and receive back the energy and force contributions. **VASPml** enters the received neighbor list data into its own structures and computes energy and force predictions according to the pre-trained machine-learned force field. A typical build for the combination of the two codes requires to first compile the `libvaspml` library. Then, **LAMMPS** is patched with the additional `pair_vasp.cpp/h` files, which are automatically compiled during the **LAMMPS** build. In the final stage, **LAMMPS** is linked to the `libvaspml` library, resulting in a patched executable. This can be done manually but **VASPml** also offers a convenient automated way covering all steps (`make lammps`).
 
== Running LAMMPS with VASP machine-learned force field ==
 
=== LAMMPS input scripts ===
 
**LAMMPS** comes with its own powerful script language which allows the user to specify all relevant MD simulation parameters in a single file. Please consult the [LAMMPS documentation](https://docs.lammps.org/Commands_input.html) for details. Within the **LAMMPS** script language the commands `pair_style` and `pair_coeff` are responsible selecting a force field. The patch **VASPml** provides introduces a new `pair_style` called `vasp`. The `pair_style vasp` command does not have any additional arguments, all configurable settings are given as arguments to the `pair_coeff` command in this format:
 
<code>
pair_style vasp
 
pair_coeff * * file types
</code>
 
The `pair_coeff` command must be followed by `* *`, then followed by the name of the **VASP** force field file, typically `ML_FF`. Finally, there comes a mapping from **LAMMPS** atom types to **VASP** force fiel types, e.g., `H O Na Cl` means that **LAMMPS** types `1`, `2`, `3` and `4` are mapped to **VASP** types `H`, `O`, `Na` and `Cl`, respectively. A valid example may look like this:
 
<code>
pair_style vasp
 
pair_coeff * * ML_FF Pb Br Cs
</code>
 
This will map the **LAMMPS** atom types `1`, `2` and `3` in the [input data file](#LAMMPS input data file) to the types `Pb`, `Br` and `Cs` for which a pre-trained machine-learned force field should be present in the `ML_FF` file in the execution directory. A summary of the type mapping is provided in the screen output and the `log.lammps` file, e.g. for the example above it looks like this:
```
  LAMMPS      pair_coeff      VASP      |            VASP force field
     types      names          subtypes  |    types      names        subtypes
     types      names          subtypes  |    types      names        subtypes
----------------------------------------- | -------------------------------------
----------------------------------------- | -------------------------------------
         1 <---> Pb        <---> 0        |        0 <---> Pb    <---> 0         
         1 &lt;---&gt; Pb        &lt;---&gt; 0        |        0 &lt;---&gt; Pb    &lt;---&gt; 0         
         2 <---> Br        <---> 1        |        1 <---> Br    <---> 1         
         2 &lt;---&gt; Br        &lt;---&gt; 1        |        1 &lt;---&gt; Br    &lt;---&gt; 1         
         3 <---> Cs        <---> 2        |        2 <---> Cs    <---> 2   
         3 &lt;---&gt; Cs        &lt;---&gt; 2        |        2 &lt;---&gt; Cs    &lt;---&gt; </pre>
```
On the left side we find the mapping, the right side gives an overview of types present in the force field file. In this example, there is a one-to-one mapping, hence, the table looks pretty obvious and contains somewhat redundant information. However, it is also possible to leave out a mapping from specified LAMMPS types by supplying <code>NULL</code> instead of a valid {{VASP}} type name. This can be helpful when multiple force fields should be combined, see [https://docs.lammps.org/pair_hybrid.html <code>pair_style hybrid</code>]. Furthermore, multiple LAMMPS types may be mapped to the same {{VASP}} types. Finally, the force field file may contain types which are not used in the current MD simulation. Therefore, a more complicated example may look like this:
On the left side we find the mapping, the right side gives an overview of types present in the force field file. In this example, there is a one-to-one mapping, hence, the table looks pretty obvious and contains somewhat redundant information. However, it is also possible to leave out a mapping from specified **LAMMPS** types by supplying `NULL` instead of a valid **VASP** type name. This can be helpful when multiple force fields should be combined, see [`pair_style hybrid`](https://docs.lammps.org/pair_hybrid.html). Furthermore, multiple **LAMMPS** types may be mapped to the same **VASP** types. Finally, the force field file may contain types which are not used in the current MD simulation. Therefore, a more complicated example may look like this:


<code>
<pre>pair_coeff * * vasp ML_FF NULL Cs NULL Br Pb Br</pre>
pair_coeff * * vasp ML_FF NULL Cs NULL Br Pb Br
and the corresponding table could contain this information:
</code>


and the corresponding table could contain this information:
<pre>  LAMMPS      pair_coeff      VASP      |            VASP force field
```
  LAMMPS      pair_coeff      VASP      |            VASP force field
     types      names          subtypes  |    types      names        subtypes
     types      names          subtypes  |    types      names        subtypes
----------------------------------------- | -------------------------------------
----------------------------------------- | -------------------------------------
         1 <---> unmapped! <---> unmapped! |        0 <---> Ca    <---> unused!
         1 &lt;---&gt; unmapped! &lt;---&gt; unmapped! |        0 &lt;---&gt; Ca    &lt;---&gt; unused!
         2 <---> Cs        <---> 2        |        1 <---> Pb    <---> 0         
         2 &lt;---&gt; Cs        &lt;---&gt; 2        |        1 &lt;---&gt; Pb    &lt;---&gt; 0         
         3 <---> unmapped! <---> unmapped! |        2 <---> O      <---> unused!
         3 &lt;---&gt; unmapped! &lt;---&gt; unmapped! |        2 &lt;---&gt; O      &lt;---&gt; unused!
         4 <---> Br        <---> 1        |        3 <---> Br    <---> 1         
         4 &lt;---&gt; Br        &lt;---&gt; 1        |        3 &lt;---&gt; Br    &lt;---&gt; 1         
         5 <---> Pb        <---> 0        |        4 <---> Cs    <---> 2         
         5 &lt;---&gt; Pb        &lt;---&gt; 0        |        4 &lt;---&gt; Cs    &lt;---&gt; 2         
         6 <---> Br        <---> 1        |
         6 &lt;---&gt; Br        &lt;---&gt; 1        |</pre>
```
{{NB|mind|Always ensure that the type mapping is correctly set up because mixed-up types may not immediately result in errors. An MD simulation may still run and only post-processing may ultimately reveal inconsistencies which can be tedious to trace back to type-mapping mistakes.}}
It is important to always ensure that the type mapping is correctly set up because mixed-up types may not immediately result in errors. An MD simulation may still run and only post-processing may ultimately reveal inconsistencies which can be tedious to trace back to type-mapping mistakes.
 
The `pair_style vasp` expects input coordinates to be in the units of Ångström and returns energies and forces with the energy unit of eV. Hence, it is only compatible with the **LAMMPS** setting `units metal` in the input script, otherwise, an error will occur.
 
=== LAMMPS input data file ===
 
Where **VASP** uses POSCAR files to define the input structure (lattice and ion positions) **LAMMPS** uses [its own file format](https://docs.lammps.org/read_data.html) to start MD simulations from. For simple cubic or orthorhombic systems, the files can be manually converted with little effort. However, this becomes more cumbersome with triclinic simulation cells because **LAMMPS** originally only supported _restricted triclinic_ boxes. Here, the first lattice vector is _restricted_ to lie along the x-axis of the Cartesian coordinate system and the second vector must lie in the xy-plane. The third lattice vector can be arbitrary as long as it points out of the xy-plane and the three vectors form a right-hand system. Note that any set of lattice vectors can be transformed (rotated and/or mirrored) to fulfill these conditions without changing the physical situation. These restrictions do not apply to **VASP** POSCAR files and therefore _general_ triclinic lattices need to be [transformed](https://docs.lammps.org/Howto_triclinic.html) to create a valid **LAMMPS** input file. This task can be performed by the Python script `poscar2lammps_data.py` which is located in the `res` directory relative to the base folder. It takes two command-line arguments:
 
<code>
poscar2lammps_data.py <in> <out>
</code>
 
where `<in>` is the {{FILE|POSCAR}} input file and `out` is the resulting **LAMMPS** data file in restricted triclinic form. If `<out>` is omitted, the output file is written to `lammps.data`.
Please be aware that this script is not heavily tested and its results should be checked for consistency. Alternatively, the ase environment can be used to convert {{FILE|POSCAR}} to lammps input files. For this, a {{FILE|POSCAR}} can be read into an atoms environment of ase and then written to a file in lammps format. Also, recent versions of **LAMMPS** (e.g. `patch_17Apr2024`) do support general triclinic lattices for convenience, see remarks [here](https://docs.lammps.org/Howto_triclinic.html#general-triclinic-simulation-boxes-in-lammps).
 
=== Example directory ===
 
An example **LAMMPS** MD simulation of Cesium Lead Bromide can be found in the following directory relative to the **VASPml** base directory:
 
<code>
examples/lammps/CsPbBr3
</code>
 
To execute, first [compile the patched **LAMMPS** executable](#Automatic-patching-and-compilations-of-**LAMMPS**) change into the directory above and run a parallel MD simulation with this command:


<code>
The <code>pair_style vasp</code> expects input coordinates to be in the units of Ångström and returns energies and forces with the energy unit of eV. Hence, it is only compatible with the LAMMPS setting <code>units metal</code> in the input script, otherwise an error will occur.
mpirun -np 4 ../../../bin/lmp_mpi -in in.lmp
<code>


Here, `lmp_mpi` is the patched **LAMMPS** executable and `-in in.lmp` is one of its command line arguments specifying that the **LAMMPS** commands should be read from a script file called `in.lmp`. This file is present in the example directory and contains an already advanced MD setup for a simulation of 100 time steps sampling the NpT ensemble. `in.lmp` also specifies that the output trajectory should be written to `out.dump` and global thermodynamic properties (e.g. potential energy, pressure,...) are written to `out.prop`. The example **LAMMPS** script file can be easily altered to sample also NVE or NVT ensembles. Many other simulation parameters can also be modified by changing the variable values at the beginning of the file. Please have a look at the comments in `in.lmp` and visit the [**LAMMPS** documentation](https://docs.lammps.org/Manual.html) for more information.
[[Category:Machine-learned force fields]]
[[Category:Howto]]

Latest revision as of 08:36, 24 January 2025

LAMMPS is a very popular molecular dynamics (MD) package which implements lots of advanced simulation methods. Although VASP itself also offers MD simulations LAMMPS provides more flexibility and additional methods (e.g. thermostats/barostats, grouping atoms, etc.). This page describes how to make pre-trained VASP machine-learned force fields available within LAMMPS. On a technical level this is achieved by patching the LAMMPS source code in such way that a new pair_style named vasp is available in the LAMMPS script language. The patched LAMMPS source is compiled and then linked to the VASPml library. The first section describes in detail how to patch and compile LAMMPS. The second section explains how the VASP ML_FF file can be loaded in a LAMMPS script.

Warning: The VASPml library and therefore also the LAMMPS interface are experimental features. Please carefully check results and, if feasible, compare against similar VASP MD simulations.

Building LAMMPS with VASPml patch

Before starting the LAMMPS build please compile VASP with the VASPml library. To confirm that everything is ready we can check for the presence of the following files:

  • /path/to/vasp/build/VERSION/vaspml/lib/libvaspml.a
  • /path/to/vasp/build/VERSION/vaspml/include/InterfaceLAMMPS.hpp

where VERSION is any of std, gam or ncl. It does not matter which VASP build version is used because the VASPml library will be identical in all three cases.

Next, we need to obtain the LAMMPS source code with the patch for VASPml. Please clone the following repository to your hard disk and change into the LAMMPS root directory:

git clone https://github.com/vasp-dev/lammps
cd lammps

At this point looking around in the git repository will show the files from the develop branch (the main development branch of LAMMPS). However, the patch files are located in another branch, hence we need to switch with this command:

git checkout vasp-mlff

Then, while still in the LAMMPS root directory we need to create a symbolic link from lammps/lib/vasp/vaspml to the actual location of the VASPml folder:

ln -s /path/to/vasp/build/std/vaspml lib/vasp/

Again, it is not important which of the three VASP build directories (std, gam or ncl) is used because the VASPml library is the same. For the remaining steps we need to change into the src directory:

cd src

The source files for the pair_style vasp are part of the optional package ML-VASP which can be activated with this command:

make yes-ml-vasp

Before we can finally start the build process it is necessary to adapt the LAMMPS makefile in MAKE/Makefile.mpi. Modify the CC and LINK variables to match the compiler used during the VASPml build process (CXX_ML variable). Also match the compiler flags in CCFLAGS and LINKFLAGS to CXXFLAGS_ML. Flags do not need to be identical but at least compatible compiler features should be used. Since VASPml requires BLAS and LAPACK we may also need to complete the LIB variable with the required libraries and their paths. For the GNU compiler with openBLAS it may look like this:

...
CC =    mpic++
CCFLAGS = -g -O3 -std=c++17
...
LINK =    mpic++
LINKFLAGS = -g -O3 -std=c++17
LIB = -L${OPENBLAS_ROOT}/lib -lopenblas

Finally, compile the LAMMPS source code with this command:

make mpi

Optionally, add the -j flag to perform a parallel build (faster). If the build process succeeds the LAMMPS executable lmp_mpi will be located in the lammps/src directory.

Setting up a LAMMPS MD run

LAMMPS comes with its own powerful script language which allows the user to specify all relevant MD simulation parameters in a single file. Please consult the LAMMPS documentation for details. Within the LAMMPS script language the commands pair_style and pair_coeff are responsible for selecting a force field. The ML-VASP package introduces a new pair_style called vasp. The pair_style vasp command does not have any additional arguments, all configurable settings are given as arguments to the pair_coeff command in this format:

pair_style vasp
pair_coeff * * file types

The pair_coeff command must be followed by * *, then followed by the name of the VASP force field file, typically ML_FF. Finally, there comes a mapping from LAMMPS atom types to VASP force field types, e.g., H O Na Cl means that LAMMPS types 1, 2, 3 and 4 are mapped to VASP types H, O, Na and Cl, respectively. A valid example may look like this:

pair_style vasp
pair_coeff * * ML_FF Pb Br Cs

This will map the LAMMPS atom types 1, 2 and 3 in the input data file to the types Pb, Br and Cs for which a pre-trained machine-learned force field should be present in the ML_FF file in the execution directory. A summary of the type mapping is provided in the screen output and the log.lammps file, e.g. for the example above it looks like this:

   LAMMPS       pair_coeff      VASP      |             VASP force field
    types       names           subtypes  |     types       names        subtypes
----------------------------------------- | -------------------------------------
        1 <---> Pb        <---> 0         |         0 <---> Pb     <---> 0        
        2 <---> Br        <---> 1         |         1 <---> Br     <---> 1        
        3 <---> Cs        <---> 2         |         2 <---> Cs     <---> 2  

On the left side we find the mapping, the right side gives an overview of types present in the force field file. In this example, there is a one-to-one mapping, hence, the table looks pretty obvious and contains somewhat redundant information. However, it is also possible to leave out a mapping from specified LAMMPS types by supplying NULL instead of a valid VASP type name. This can be helpful when multiple force fields should be combined, see pair_style hybrid. Furthermore, multiple LAMMPS types may be mapped to the same VASP types. Finally, the force field file may contain types which are not used in the current MD simulation. Therefore, a more complicated example may look like this:

pair_coeff * * vasp ML_FF NULL Cs NULL Br Pb Br

and the corresponding table could contain this information:

   LAMMPS       pair_coeff      VASP      |             VASP force field
    types       names           subtypes  |     types       names        subtypes
----------------------------------------- | -------------------------------------
        1 <---> unmapped! <---> unmapped! |         0 <---> Ca     <---> unused!
        2 <---> Cs        <---> 2         |         1 <---> Pb     <---> 0        
        3 <---> unmapped! <---> unmapped! |         2 <---> O      <---> unused!
        4 <---> Br        <---> 1         |         3 <---> Br     <---> 1        
        5 <---> Pb        <---> 0         |         4 <---> Cs     <---> 2        
        6 <---> Br        <---> 1         |
Mind: Always ensure that the type mapping is correctly set up because mixed-up types may not immediately result in errors. An MD simulation may still run and only post-processing may ultimately reveal inconsistencies which can be tedious to trace back to type-mapping mistakes.

The pair_style vasp expects input coordinates to be in the units of Ångström and returns energies and forces with the energy unit of eV. Hence, it is only compatible with the LAMMPS setting units metal in the input script, otherwise an error will occur.