lammps/examples/COUPLE/simple

This directory has a simple C, C++, and Fortran 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 on all or a subset of the processors, or
how an umbrella code or script could call both LAMMPS and some other
code to perform a coupled calculation.

simple.cpp     is the C++ driver
simple.c       is the C driver
simple.f90     is the Fortran driver
libfwrapper.c  is the Fortran-to-C wrapper

The 3 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 to write a scripting language interface.  See
python/examples/simple.py for an example of using Python as a wrapper
in that way.  The Fortran driver in addition requires a wrapper
library that interfaces the C interface of the LAMMPS library to
Fortran and also translates the MPI communicator from Fortran to C.

First, you must build LAMMPS as a library, either static or shared.
See http://lammps.sandia.gov/doc/Section_start.html#start_5 for
details.  To build it as a static library type this from
the src directory:

make makelib
make -f Makefile.lib g++

You can then build either driver code with a compile lines like these,
which include paths to the LAMMPS library interface, MPI, and FFTW
(assuming you built LAMMPS as a library with its PPPM solver).

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

g++ -I/home/sjplimp/lammps/src -c simple.cpp
g++ -L/home/sjplimp/lammps/src simple.o \
    -llammps_g++ -lfftw -lmpich -lmpl -lpthread -o simpleCC

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

gcc -I/home/sjplimp/lammps/src -c simple.c
gcc -L/home/sjplimp/lammps/src simple.o \
    -llammps_g++ -lfftw -lmpich -lmpl -lpthread -lstdc++ -o simpleC

This builds the Fortran wrapper and driver with the LAMMPS library
using a Fortran and C compiler, using the wrapper in the fortran
directory:

cp ../fortran/libfwrapper.c .
gcc -I/home/sjplimp/lammps/src -c libfwrapper.c
gfortran -I/home/sjplimp/lammps/src -c simple.f90
gfortran -L/home/sjplimp/lammps/src simple.o libfwrapper.o \
    -llammps_g++ -lfftw -lfmpich -lmpich -lpthread -lstdc++ -o simpleF

You then run simpleCC, simpleC, or simpleF on a parallel machine
on some number of processors Q with 2 arguments:

mpirun -np Q simpleCC P in.lj

P is the number of procs you want LAMMPS to run on (must be <= Q) and
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 Fortran driver is using the same C-style routines, but requires an
additional wrapper to make them Fortran callable. Only a subset of the
library functions are currently wrapped, but it should be clear how to
extend the wrapper if desired.

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.