lammps/examples/COUPLE/lammps_vasp

Sample LAMMPS MD wrapper on VASP quantum DFT via client/server
coupling

See the MESSAGE package (doc/Section_messages.html#MESSAGE) and
Section_howto.html#howto10 for more details on how client/server
coupling works in LAMMPS.

In this dir, the vasp_wrap.py is a wrapper on the VASP quantum DFT
code so it can work as a "server" code which LAMMPS drives as a
"client" code to perform ab initio MD.  LAMMPS performs the MD
timestepping, sends VASP a current set of coordinates each timestep,
VASP computes forces and energy and virial and returns that info to
LAMMPS.

Messages are exchanged between MC and LAMMPS via a client/server
library (CSlib), which is included in the LAMMPS distribution in
lib/message.  As explained below you can choose to exchange data
between the two programs either via files or sockets (ZMQ).  If the
vasp_wrap.py program became parallel, or the CSlib library calls were
integrated into VASP directly, then data could also be exchanged via
MPI.

----------------

Build LAMMPS with its MESSAGE package installed:

See the Build extras doc page and its MESSAGE package
section for details.

CMake:

-D PKG_MESSAGE=yes      # include the MESSAGE package
-D MESSAGE_ZMQ=value    # build with ZeroMQ support, value = no (default) or yes

Traditional make:

cd lammps/lib/message
python Install.py -m -z       # build CSlib with MPI and ZMQ support
cd lammps/src
make yes-message
make mpi

You can leave off the -z if you do not have ZMQ on your system.

----------------

Build the CSlib in a form usable by the vasp_wrapper.py script:

% cd lammps/lib/message/cslib/src
% make shlib            # build serial and parallel shared lib with ZMQ support
% make shlib zmq=no     # build serial and parallel shared lib w/out ZMQ support

This will make a shared library versions of the CSlib, which Python
requires.  Python must be able to find both the cslib.py script and
the libcsnompi.so library in your lammps/lib/message/cslib/src
directory.  If it is not able to do this, you will get an error when
you run vasp_wrapper.py.

You can do this by augmenting two environment variables, either
from the command line, or in your shell start-up script.
Here is the sample syntax for the csh or tcsh shells:

setenv PYTHONPATH ${PYTHONPATH}:/home/sjplimp/lammps/lib/message/cslib/src
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/lib/message/cslib/src

----------------

Prepare to use VASP and the vasp_wrapper.py script

You can run the vasp_wrap.py script as-is to test that the coupling
between it and LAMMPS is functional.  This will use the included
vasprun.xml file output by a previous VASP run.

But note that the as-is version of vasp_wrap.py will not attempt to
run VASP.

To do this, you must edit the 1st vaspcmd line at the top of
vasp_wrapper.py to be the launch command needed to run VASP on your
system.  It can be a command to run VASP in serial or in parallel,
e.g. an mpirun command.  Then comment out the 2nd vaspcmd line
immediately following it.

Insure you have the necessary VASP input files in this
directory, suitable for the VASP calculation you want to perform:

INCAR
KPOINTS
POSCAR_template
POTCAR

Examples of all but the POTCAR file are provided.  As explained below,
POSCAR_W is an input file for a 2-atom unit cell of tungsten and can
be used to test the LAMMPS/VASP coupling.  The POTCAR file is a
proprietary VASP file, so use one from your VASP installation.

Note that the POSCAR_template file should be matched to the LAMMPS
input script (# of atoms and atom types, box size, etc).  The provided
POSCAR_W matches in.client.W.

Once you run VASP yourself, the vasprun.xml file will be overwritten.

----------------

To run in client/server mode:

NOTE: The vasp_wrap.py script must be run with Python version 2, not
3.  This is because it used the CSlib python wrapper, which only
supports version 2.  We plan to upgrade CSlib to support Python 3.

Both the client (LAMMPS) and server (vasp_wrap.py) must use the same
messaging mode, namely file or zmq.  This is an argument to the
vasp_wrap.py code; it can be selected by setting the "mode" variable
when you run LAMMPS.  The default mode = file.

Here we assume LAMMPS was built to run in parallel, and the MESSAGE
package was installed with socket (ZMQ) support.  This means either of
the messaging modes can be used and LAMMPS can be run in serial or
parallel.  The vasp_wrap.py code is always run in serial, but it
launches VASP from Python via an mpirun command which can run VASP
itself in parallel.

When you run, the server should print out thermodynamic info every
timestep which corresponds to the forces and virial computed by VASP.
VASP will also generate output files each timestep.  The vasp_wrapper.py
script could be generalized to archive these.

The examples below are commands you should use in two different
terminal windows.  The order of the two commands (client or server
launch) does not matter.  You can run them both in the same window if
you append a "&" character to the first one to run it in the
background.

--------------

File mode of messaging:

% mpirun -np 1 lmp_mpi -v mode file < in.client.W
% python vasp_wrap.py file POSCAR_W

% mpirun -np 2 lmp_mpi -v mode file < in.client.W
% python vasp_wrap.py file POSCAR_W

ZMQ mode of messaging:

% mpirun -np 1 lmp_mpi -v mode zmq < in.client.W
% python vasp_wrap.py zmq POSCAR_W

% mpirun -np 2 lmp_mpi -v mode zmq < in.client.W
% python vasp_wrap.py zmq POSCAR_W