lammps/examples/couple/README

This directory has a C and C++ code that shows how LAMMPS can be
linked to a driver application as a library.  The purpose is to
illustrate how another code could perform computations while using
LAMMPS to perform MD, or how an umbrella code or script could call
both LAMMPS and some other code to perform a coupled calculation.

c_driver.c     is the C driver
c++_driver.c   is the C++ driver

The 2 codes do the same thing, so you can compare them to see how to
drive LAMMPS in this manner.  The C driver is similar in spirit to
what one could use from a Fortran program or scripting language.

LAMMPS must first be built as a library.  See the "Making LAMMPS"
section of Section_start.html in the documentation for info on how to
do this.  Basically, you type something like

make makelib
make -f Makefile.lib g++

in the LAMMPS src directory to create liblmp_g++.a

You can then build either driver code with a compile line something
like this, which includes paths to the LAMMPS library interface, MPI,
and FFTW.

This builds the C driver with the LAMMPS library using a C compiler:

gcc -I/home/sjplimp/tools/mpich/include -I/home/sjplimp/lammps/new2 \
    -L/home/sjplimp/lammps/new2 -L/home/sjplimp/tools/mpich/lib \
    -L/home/sjplimp/tools/fftw/lib c_driver.c \
    -llmp_g++ -lfftw -lmpich -lstdc++ -o c_driver

This builds the C++ driver with the LAMMPS library using a C++ compiler:

g++ -I/home/sjplimp/tools/mpich/include -I/home/sjplimp/lammps/new2 \
    -L/home/sjplimp/lammps/new2 -L/home/sjplimp/tools/mpich/lib \
    -L/home/sjplimp/tools/fftw/lib c++_driver.cpp \
    -llmp_g++ -lfftw -lmpich -o c++_driver

You then run c_driver or c++_driver on a parallel machine on some
number of processors Q with 2 arguments:

mpirun -np Q c_driver P in.lj

P is the number of procs you want LAMMPS to run on (must be <= Q).
In.lj is a LAMMPS input script.

The driver will launch LAMMPS on P procs, read the input script a line
at a time, and pass each command line to LAMMPS.  The final line of
the script is a "run" command, so LAMMPS will run the problem.

The driver then requests all the atom coordinates from LAMMPS, moves
one of the atoms a small amount "epsilon", passes the coordinates back
to LAMMPS, and runs LAMMPS again.  If you look at the output, you
should see a small energy change between runs, due to the moved atom.

The C driver is calling C-style routines in the src/library.cpp file
of LAMMPS.  You could add any functions you wish to this file to
manipulate LAMMPS data however you wish.

The C++ driver does the same thing, except that it instantiates LAMMPS
as an object first.  Some of the functions in src/library.cpp can be
invoked directly as methods within appropriate LAMMPS classes, which
is what the driver does.  Any public LAMMPS class method could be
called from the driver this way.  However the get/put functions are
only implemented in src/library.cpp, so the C++ driver calls them as
C-style functions.