complete documentation for LAMMPS plugin coupling example

doc/src/Howto_couple.rst

@@ -70,6 +70,8 @@ examples/COUPLE/README for more details:
 
 * simple: simple driver programs in C++ and C which invoke LAMMPS as a
   library
+* plugin: simple driver program in C which invokes LAMMPS as a plugin
+  from a shared library.
 * lammps\_quest: coupling of LAMMPS and `Quest <quest_>`_, to run classical
   MD with quantum forces calculated by a density functional code
 * lammps\_spparks: coupling of LAMMPS and `SPPARKS <spparks_>`_, to couple

examples/COUPLE/README

@@ -27,6 +27,7 @@ These are the sub-directories included in this directory:
 
 simple		    simple example of driver code calling LAMMPS as a lib
 multiple	    example of driver code calling multiple instances of LAMMPS
+plugin              example for loading LAMMPS at runtime from a shared library
 lammps_mc           client/server coupling of Monte Carlo client 
                       with LAMMPS server for energy evaluation
 lammps_nwchem       client/server coupling of LAMMPS client with 

examples/COUPLE/plugin/README

@@ -1,21 +1,22 @@
-This directory has a simple C code that shows how
+This directory has a simple C code that shows how LAMMPS can be included
-LAMMPS can be linked to a driver application as a library. The purpose
+in an application as a shared library loaded at runtime. The code is
-is to illustrate how another code could perform computations while
+essentially the same as in the "simple" example that links to LAMMPS
-using LAMMPS to perform MD on all or a subset of the processors, or
+either with a static or shared library. The purpose is to illustrate
-how an umbrella code or script could call both LAMMPS and some other
+how another code could be built without having a LAMMPS library present
-code to perform a coupled calculation.
+and then load the (separately compiled) shared library.
 
 simple.c           is the C driver
 liblammpsplugin.c  is the LAMMPS library plugin loader
 
-The 3 codes do the same thing, so you can compare them to see how to
+You can then build the driver executable codes with a compile line
-drive LAMMPS from each language.  See lammps/python/example/simple.py
+like below.
-to do something similar from Python.  The Fortran driver requires an
-additional wrapper library that interfaces the C interface of the
-LAMMPS library to Fortran and also translates the MPI communicator
-from Fortran to C.
 
-First build LAMMPS as a library (see examples/COUPLE/README), e.g. 
+mpicc -c -O -Wall -g -I$HOME/lammps/src liblammpsplugin.c
+mpicc -c -O -Wall -g simple.c
+mpicc simple.o liblammsplugin.o -ldl -o simpleC
+
+You also need to build LAMMPS as a shared library
+(see examples/COUPLE/README), e.g. 
 
 cd $HOME/lammps/src
 make mode=shlib mpi
@@ -28,15 +29,6 @@ cd build-shared
 cmake -D BUILD_LIB=on -D BUILD_SHARED_LIBS=on ../cmake
 make
 
-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).
-
-mpicc -c simple.c
-mpicc simple.o -llammps -lfftw -o simpleC
-
-
 You then run simpleC on a parallel machine
 on some number of processors Q with 3 arguments:
 
@@ -66,5 +58,6 @@ of LAMMPS through the function pointers in the liblammpsplugin_t struct.
 This has the benefit that your binary is not linked to liblammps.so directly
 and thus you can change the name of the shared library (e.g. to have 
 different variants compiled, or to load a different LAMMPS versions without
-having to update your executable).
+having to update your executable). The shared library still has to be
+compatible with the compilation settings the plugin code.