From e87b3a21c2a4704ac69e3628bf028f8deb34c0c7 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 25 Feb 2020 14:10:55 -0500 Subject: [PATCH] complete documentation for LAMMPS plugin coupling example --- doc/src/Howto_couple.rst | 2 ++ examples/COUPLE/README | 1 + examples/COUPLE/plugin/README | 39 ++++++++++++++--------------------- 3 files changed, 19 insertions(+), 23 deletions(-) diff --git a/doc/src/Howto_couple.rst b/doc/src/Howto_couple.rst index 849415a0e3..a46bb3f2f2 100644 --- a/doc/src/Howto_couple.rst +++ b/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 `_, to run classical MD with quantum forces calculated by a density functional code * lammps\_spparks: coupling of LAMMPS and `SPPARKS `_, to couple diff --git a/examples/COUPLE/README b/examples/COUPLE/README index 05b38335fb..5a9f297b0f 100644 --- a/examples/COUPLE/README +++ b/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 diff --git a/examples/COUPLE/plugin/README b/examples/COUPLE/plugin/README index 7075689d6f..b035ed3c0e 100644 --- a/examples/COUPLE/plugin/README +++ b/examples/COUPLE/plugin/README @@ -1,21 +1,22 @@ -This directory has a simple 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 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. +This directory has a simple C code that shows how LAMMPS can be included +in an application as a shared library loaded at runtime. The code is +essentially the same as in the "simple" example that links to LAMMPS +either with a static or shared library. The purpose is to illustrate +how another code could be built without having a LAMMPS library present +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 -drive LAMMPS from each language. See lammps/python/example/simple.py -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. +You can then build the driver executable codes with a compile line +like below. -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.