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 using the new Fortran module
simple_f77.f90 is the Fortran driver using the legacy Fortran wrapper

The 4 codes do the same thing, so you can compare them to see how to
drive LAMMPS from each language.  See python/example/simple.py
to do something similar from Python.  The new Fortran driver requires
a Fortran module that uses the Fortran 03 ISO_C_BINDING module to
interface the LAMMPS C library functions to Fortran.

First build LAMMPS as a library (see examples/COUPLE/README), e.g.

make mode=shlib mpi

or via CMake through settings -DBUILD_SHARED_LIBS=on

You can then build any of the driver codes with compile lines like
these, which include paths to the LAMMPS library interface, and
linking with FFTW (only needed if you built LAMMPS as a library with
its PPPM solver).

This builds the C++ driver with the LAMMPS library using the mpicxx
(C++) compiler:

mpicxx -I${HOME}/lammps/src -c simple.cpp
mpicxx -L${HOME}/lammps/src simple.o -llammps -o simpleCC

This builds the C driver with the LAMMPS library using the mpicc (C)
compiler:

mpicc -I${HOME}/lammps/src -c simple.c
mpicc -L${HOME}/lammps/src simple.o -llammps -o simpleC

This builds the Fortran module and driver with the LAMMPS library
using the mpifort (Fortran) compilers, using the Fortran module from
the fortran directory:

mpifort -L${HOME}/lammps/src ../../../fortran/lammps.f90 simple.f90 -llammps -o simpleF

This builds the legacy Fortran wrapper and driver with the LAMMPS library
using the mpifort (Fortran) MPI compiler wrapper (assuming GNU gfortran).

mpifort -std=legacy -L${HOME}/lammps/src ../fortran/libfwrapper.c simple.f90 -llammps -o simpleF77

You then run simpleCC, simpleC, simpleF, or simpleF77 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 Fortran 03 module which uses a derived
type with type bound subroutines. Only a small subset of the C library
functions are currently accessible through the Fortran module.

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
by-passed and 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.
