Revision as of 15:35, 23 January 2025

ToDo: Write introduction to LAMMPS!

Building LAMMPS with VASPml patch

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

cd lammps

git checkout vasp-mlff

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

cd src

make yes-ml-vasp

make mpi

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         |

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.

@@ Line 1: / Line 1: @@
 {{NB|warning|Write introduction to LAMMPS!||ToDo:}}
-== LAMMPS input scripts ==
+= Building LAMMPS with VASPml patch =
-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 patch VASPml provides 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:
+ git clone https://github.com/vasp-dev/lammps
+ cd lammps
+ git checkout vasp-mlff
+ ln -s /path/to/vasp/build/std/vaspml lib/vasp/
+ cd src
+ make yes-ml-vasp
+ make mpi
+= 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 [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:
 <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 fiel 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:
+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:
 <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 [[#LAMMPS%20input%20data%20file|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:
+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:
 <pre>   LAMMPS       pair_coeff      VASP      |             VASP force field
@@ Line 36: / Line 52: @@
 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.
-== LAMMPS input data file ==
-Where {{VASP}} uses POSCAR files to define the input structure (lattice and ion positions) LAMMPS uses [https://docs.lammps.org/read_data.html its own file format] 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 [https://docs.lammps.org/Howto_triclinic.html transformed] to create a valid LAMMPS input file. This task can be performed by the Python script <code>poscar2lammps_data.py</code> which is located in the <code>res</code> directory relative to the base folder. It takes two command-line arguments:
-<pre>poscar2lammps_data.py &lt;in&gt; &lt;out&gt;</pre>
-where <code>&lt;in&gt;</code> is the POSCAR input file and <code>out</code> is the resulting LAMMPS data file in restricted triclinic form. If <code>&lt;out&gt;</code> is omitted, the output file is written to <code>lammps.data</code>.
-Please be aware that this script is not heavily tested and its results should be checked for consistency. Also, recent versions of LAMMPS (e.g. <code>patch_17Apr2024</code>) do support general triclinic lattices for convenience, see remarks [https://docs.lammps.org/Howto_triclinic.html#general-triclinic-simulation-boxes-in-lammps here].
-== MD run in example directory ==
-An example LAMMPS MD simulation of Cesium Lead Bromide can be found in the following directory relative to the VASPml base directory:
-<pre>examples/lammps/CsPbBr3</pre>
-To execute, first [[#Automatic-patching-and-compilations-of-**LAMMPS**|compile the patched LAMMPS executable]] change into the directory above and run a parallel MD simulation with this command:
-<pre>mpirun -np 4 ../../../bin/lmp_mpi -in in.lmp</pre>
-Here, <code>lmp_mpi</code> is the patched LAMMPS executable and <code>-in in.lmp</code> is one of its command line arguments specifying that the LAMMPS commands should be read from a script file called <code>in.lmp</code>. 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. <code>in.lmp</code> also specifies that the output trajectory should be written to <code>out.dump</code> and global thermodynamic properties (e.g. potential energy, pressure,…) are written to <code>out.prop</code>. 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 <code>in.lmp</code> and visit the [https://docs.lammps.org/Manual.html LAMMPS documentation] for more information.
-= Quick How-To for experienced {{VASP}}/LAMMPS users =
-{{NB|warning|Connect this section to actual installation instructions||ToDo:}}
-# Just like in {{VASP}} pick a template from the <code>arch</code> directory and copy it to the base directory, e.g.
-<pre>cp arch/makefile.include.gnu makefile.include</pre>
-<ol start="2" style="list-style-type: decimal;">
-<li>Modify the build settings in <code>makefile.include</code> according to your system.</li>
-<li>Compile a patched version of LAMMPS with support for {{VASP}} machine-learned force fields:</li></ol>
-<pre>make lammps -j</pre>
-<ol start="4" style="list-style-type: decimal;">
-<li>Switch to the <code>examples/lammps/CsPbBr3</code> directory and try to run the example MD simulation, e.g. with</li></ol>
-<pre>mpirun -np 4 ../../../bin/lmp_mpi -in in.lmp</pre>
-<ol start="5" style="list-style-type: decimal;">
-<li>Inspect the LAMMPS input script <code>in.lmp</code> and modify to your needs.</li></ol>