new MESSAGE package for client/server/coupling

cmake/CMakeLists.txt

@@ -211,7 +211,7 @@ if(ENABLE_TESTING)
 endif(ENABLE_TESTING)
 
 set(DEFAULT_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS DIPOLE GRANULAR
-  KSPACE MANYBODY MC MEAM MISC MOLECULE PERI REAX REPLICA RIGID SHOCK SPIN SNAP
+  KSPACE MANYBODY MC MEAM MESSAGE MISC MOLECULE PERI REAX REPLICA RIGID SHOCK SPIN SNAP
   SRD KIM PYTHON MSCG MPIIO VORONOI POEMS LATTE USER-ATC USER-AWPMD USER-BOCS
   USER-CGDNA USER-MESO USER-CGSDK USER-COLVARS USER-DIFFRACTION USER-DPD USER-DRUDE
   USER-EFF USER-FEP USER-H5MD USER-LB USER-MANIFOLD USER-MEAMC USER-MGPT USER-MISC
@@ -504,6 +504,39 @@ if(PKG_KIM)
   include_directories(${KIM_INCLUDE_DIRS})
 endif()
 
+if(PKG_MESSAGE)
+  option(MESSAGE_ZMQ "Use ZeroMQ in MESSAGE package" OFF)
+  file(GLOB_RECURSE cslib_SOURCES ${LAMMPS_LIB_SOURCE_DIR}/message/cslib/*.F
+      ${LAMMPS_LIB_SOURCE_DIR}/message/cslib/*.c ${LAMMPS_LIB_SOURCE_DIR}/message/cslib/*.cpp)
+
+  if(BUILD_SHARED_LIBS)
+      add_library(cslib SHARED ${cslib_SOURCES})
+  else()
+      add_library(cslib STATIC ${cslib_SOURCES})
+  endif()
+
+  if(BUILD_MPI)
+    target_compile_definitions(cslib PRIVATE -DMPI_YES)
+    set_target_properties(cslib PROPERTIES OUTPUT_NAME "csmpi")
+  else()
+    target_compile_definitions(cslib PRIVATE -DMPI_NO)
+    set_target_properties(cslib PROPERTIES OUTPUT_NAME "csnompi")
+  endif()
+
+  if(MESSAGE_ZMQ)
+    target_compile_definitions(cslib PRIVATE -DZMQ_YES)
+    find_package(ZMQ REQUIRED)
+    target_include_directories(cslib PRIVATE ${ZMQ_INCLUDE_DIRS})
+    target_link_libraries(cslib PUBLIC ${ZMQ_LIBRARIES})
+  else()
+    target_compile_definitions(cslib PRIVATE -DZMQ_NO)
+    target_include_directories(cslib PRIVATE ${LAMMPS_LIB_SOURCE_DIR}/message/cslib/src/STUBS_ZMQ)
+  endif()
+
+  list(APPEND LAMMPS_LINK_LIBS cslib)
+  include_directories(${LAMMPS_LIB_SOURCE_DIR}/message/cslib/src)
+endif()
+
 if(PKG_MSCG)
   find_package(GSL REQUIRED)
   option(DOWNLOAD_MSCG "Download latte (instead of using the system's one)" OFF)
@@ -1200,7 +1233,7 @@ endif()
 ###############################################################################
 # Print package summary
 ###############################################################################
-foreach(PKG ${DEFAULT_PACKAGES} ${ACCEL_PACKAGES})
+foreach(PKG ${DEFAULT_PACKAGES} ${ACCEL_PACKAGES} ${OTHER_PACKAGES})
   if(PKG_${PKG})
     message(STATUS "Building package: ${PKG}")
   endif()

cmake/Modules/FindZMQ.cmake

@@ -0,0 +1,8 @@
+find_path(ZMQ_INCLUDE_DIR zmq.h)
+find_library(ZMQ_LIBRARY NAMES zmq)
+
+set(ZMQ_LIBRARIES ${ZMQ_LIBRARY})
+set(ZMQ_INCLUDE_DIRS ${ZMQ_INCLUDE_DIR})
+
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(ZMQ DEFAULT_MSG ZMQ_LIBRARY ZMQ_INCLUDE_DIR)

doc/src/Build_extras.txt

@@ -31,6 +31,7 @@ This is the list of packages that may require additional steps.
 "KOKKOS"_#kokkos,
 "LATTE"_#latte,
 "MEAM"_#meam,
+"MESSAGE"_#message,
 "MSCG"_#mscg,
 "OPT"_#opt,
 "POEMS"_#poems,
@@ -361,6 +362,10 @@ make lib-meam args="-m mpi"    # build with default Fortran compiler compatible
 make lib-meam args="-m serial" # build with compiler compatible with "make serial" (GNU Fortran)
 make lib-meam args="-m ifort"  # build with Intel Fortran compiler using Makefile.ifort :pre
 
+NOTE: You should test building the MEAM library with both the Intel
+and GNU compilers to see if a simulation runs faster with one versus
+the other on your system.
+
 The build should produce two files: lib/meam/libmeam.a and
 lib/meam/Makefile.lammps.  The latter is copied from an existing
 Makefile.lammps.* and has settings needed to link C++ (LAMMPS) with
@@ -373,6 +378,35 @@ file.
 
 :line
 
+MESSAGE package :h4,link(message)
+
+This package can optionally include support for messaging via sockets,
+using the open-source "ZeroMQ library"_http://zeromq.org, which must
+be installed on your system.
+
+[CMake build]:
+
+-D MESSAGE_ZMQ=value    # build with ZeroMQ support, value = no (default) or yes
+
+[Traditional make]:
+
+Before building LAMMPS, you must build the CSlib library in
+lib/message.  You can build the CSlib library manually if you prefer;
+follow the instructions in lib/message/README.  You can also do it in
+one step from the lammps/src dir, using a command like these, which
+simply invoke the lib/message/Install.py script with the specified args:
+
+make lib-message               # print help message
+make lib-message args="-m -z"  # build with MPI and socket (ZMQ) support
+make lib-message args="-s"     # build as serial lib with no ZMQ support
+
+The build should produce two files: lib/message/cslib/src/libmessage.a
+and lib/message/Makefile.lammps.  The latter is copied from an
+existing Makefile.lammps.* and has settings to link with the ZeroMQ
+library if requested in the build.
+
+:line
+
 MSCG package :h4,link(mscg)
 
 To build with this package, you must download and build the MS-CG

doc/src/Build_package.txt

@@ -42,6 +42,7 @@ packages:
 "KOKKOS"_Build_extras.html#kokkos,
 "LATTE"_Build_extras.html#latte,
 "MEAM"_Build_extras.html#meam,
+"MESSAGE"_#Build_extras.html#message,
 "MSCG"_Build_extras.html#mscg,
 "OPT"_Build_extras.html#opt,
 "POEMS"_Build_extras.html#poems,

doc/src/Commands_all.txt

@@ -71,6 +71,7 @@ An alphabetic list of all LAMMPS commands.
 "lattice"_lattice.html,
 "log"_log.html,
 "mass"_mass.html,
+"message"_message.html,
 "minimize"_minimize.html,
 "min_modify"_min_modify.html,
 "min_style"_min_style.html,
@@ -103,6 +104,7 @@ An alphabetic list of all LAMMPS commands.
 "restart"_restart.html,
 "run"_run.html,
 "run_style"_run_style.html,
+"server"_server.html,
 "set"_set.html,
 "shell"_shell.html,
 "special_bonds"_special_bonds.html,

doc/src/Howto.txt

@@ -54,6 +54,7 @@ General howto :h3
    Howto_replica
    Howto_library
    Howto_couple
+   Howto_client_server
 
 END_RST -->
 
@@ -64,7 +65,8 @@ END_RST -->
 "Run multiple simulations from one input script"_Howto_multiple.html
 "Multi-replica simulations"_Howto_replica.html
 "Library interface to LAMMPS"_Howto_library.html
-"Couple LAMMPS to other codes"_Howto_couple.html :all(b)
+"Couple LAMMPS to other codes"_Howto_couple.html
+"Using LAMMPS in client/server mode"_Howto_client_server.html :all(b)
 
 <!-- END_HTML_ONLY -->
 

doc/src/Howto_client_server.txt

@@ -0,0 +1,131 @@
+"Higher level section"_Howto.html - "LAMMPS WWW Site"_lws - "LAMMPS
+Documentation"_ld - "LAMMPS Commands"_lc :c
+
+:link(lws,http://lammps.sandia.gov)
+:link(ld,Manual.html)
+:link(lc,Commands_all.html)
+
+:line
+
+Using LAMMPS in client/server mode
+
+Client/server coupling of two codes is where one code is the "client"
+and sends request messages to a "server" code.  The server responds to
+each request with a reply message.  This enables the two codes to work
+in tandem to perform a simulation.  LAMMPS can act as either a client
+or server code.
+
+Some advantages of client/server coupling are that the two codes run
+as stand-alone executables; they are not linked together.  Thus
+neither code needs to have a library interface.  This often makes it
+easier to run the two codes on different numbers of processors.  If a
+message protocol (format and content) is defined for a particular kind
+of simulation, then in principle any code that implements the
+client-side protocol can be used in tandem with any code that
+implements the server-side protocol, without the two codes needing to
+know anything more specific about each other.
+
+A simple example of client/server coupling is where LAMMPS is the
+client code performing MD timestepping.  Each timestep it sends a
+message to a server quantum code containing current coords of all the
+atoms.  The quantum code computes energy and forces based on the
+coords.  It returns them as a message to LAMMPS, which completes the
+timestep.
+
+Alternate methods for code coupling with LAMMPS are described on
+the "Howto couple"_Howto_couple.html doc page.
+
+LAMMPS support for client/server coupling is in its "MESSAGE
+package"_Packages_details.html#PKG-MESSAGE which implements several
+commands that enable LAMMPS to act as a client or server, as discussed
+below.  The MESSAGE package also wraps a client/server library called
+CSlib which enables two codes to exchange messages in different ways,
+either via files, sockets, or MPI.  The CSlib is provided with LAMMPS
+in the lib/message dir.  The CSlib has its own
+"website"_http://cslib.sandia.gov with documentation and test
+programs.
+
+NOTE: For client/server coupling to work between LAMMPS and another
+code, the other code also has to use the CSlib.  This can sometimes be
+done without any modifications to the other code by simply wrapping it
+with a Python script that exchanges CSlib messages with LAMMPS and
+prepares input for or processes output from the other code.  The other
+code also has to implement a matching protocol for the format and
+content of messages that LAMMPS exchanges with it.
+
+These are the commands currently in the MESSAGE package for two
+protocols, MD and MC (Monte Carlo).  New protocols can easily be
+defined and added to this directory, where LAMMPS acts as either the
+client or server.
+
+"message"_message.html
+"fix client md"_fix_client_md.html = LAMMPS is a client for running MD
+"server md"_server_md.html = LAMMPS is a server for computing MD forces
+"server mc"_server_mc.html = LAMMPS is a server for computing a Monte Carlo energy
+
+The server doc files give details of the message protocols
+for data that is exchanged bewteen the client and server.
+
+These example directories illustrate how to use LAMMPS as either a
+client or server code:
+
+examples/message
+examples/COUPLE/README
+examples/COUPLE/lammps_mc
+examples/COUPLE/lammps_vasp :ul
+
+The examples/message dir couples a client instance of LAMMPS to a
+server instance of LAMMPS.  
+
+The lammps_mc dir shows how to couple LAMMPS as a server to a simple
+Monte Carlo client code as the driver.
+
+The lammps_vasp dir shows how to couple LAMMPS as a client code
+running MD timestepping to VASP acting as a server providing quantum
+DFT forces, thru a Python wrapper script on VASP.
+
+Here is how to launch a client and server code together for any of the
+4 modes of message exchange that the "message"_message.html command
+and the CSlib support.  Here LAMMPS is used as both the client and
+server code.  Another code could be subsitituted for either.
+
+The examples below show launching both codes from the same window (or
+batch script), using the "&" character to launch the first code in the
+background.  For all modes except {mpi/one}, you could also launch the
+codes in separate windows on your desktop machine.  It does not
+matter whether you launch the client or server first.
+
+In these examples either code can be run on one or more processors.
+If running in a non-MPI mode (file or zmq) you can launch a code on a
+single processor without using mpirun.
+
+IMPORTANT: If you run in mpi/two mode, you must launch both codes via
+mpirun, even if one or both of them runs on a single processor.  This
+is so that MPI can figure out how to connect both MPI processes
+together to exchange MPI messages between them.
+
+For message exchange in {file}, {zmq}, or {mpi/two} modes:
+
+% mpirun -np 1 lmp_mpi -log log.client < in.client & 
+% mpirun -np 2 lmp_mpi -log log.server < in.server :pre
+
+% mpirun -np 4 lmp_mpi -log log.client < in.client & 
+% mpirun -np 1 lmp_mpi -log log.server < in.server :pre
+
+% mpirun -np 2 lmp_mpi -log log.client < in.client & 
+% mpirun -np 4 lmp_mpi -log log.server < in.server :pre
+
+For message exchange in {mpi/one} mode:
+
+Launch both codes in a single mpirun command:
+
+mpirun -np 2 lmp_mpi -mpicolor 0 -in in.message.client -log log.client : -np 4 lmp_mpi -mpicolor 1 -in in.message.server -log log.server
+
+The two -np values determine how many procs the client and the server
+run on.
+
+A LAMMPS executable run in this manner must use the -mpicolor color
+command-line option as their its option, where color is an integer
+label that will be used to distinguish one executable from another in
+the multiple executables that the mpirun command launches.  In this
+example the client was colored with a 0, and the server with a 1.

doc/src/Howto_couple.txt

@@ -16,10 +16,12 @@ atoms and pass those forces to LAMMPS.  Or a continuum finite element
 nodal points, compute a FE solution, and return interpolated forces on
 MD atoms.
 
-LAMMPS can be coupled to other codes in at least 3 ways.  Each has
+LAMMPS can be coupled to other codes in at least 4 ways.  Each has
 advantages and disadvantages, which you'll have to think about in the
 context of your application.
 
+:line
+
 (1) Define a new "fix"_fix.html command that calls the other code.  In
 this scenario, LAMMPS is the driver code.  During its timestepping,
 the fix is invoked, and can make library calls to the other code,
@@ -32,6 +34,8 @@ LAMMPS.
 
 :link(poems,http://www.rpi.edu/~anderk5/lab)
 
+:line
+
 (2) Define a new LAMMPS command that calls the other code.  This is
 conceptually similar to method (1), but in this case LAMMPS and the
 other code are on a more equal footing.  Note that now the other code
@@ -52,6 +56,8 @@ command writes and reads.
 See the "Modify command"_Modify_command.html doc page for info on how
 to add a new command to LAMMPS.
 
+:line
+
 (3) Use LAMMPS as a library called by another code.  In this case the
 other code is the driver and calls LAMMPS as needed.  Or a wrapper
 code could link and call both LAMMPS and another code as libraries.
@@ -102,3 +108,9 @@ on all the processors.  Or it might allocate half the processors to
 LAMMPS and half to the other code and run both codes simultaneously
 before syncing them up periodically.  Or it might instantiate multiple
 instances of LAMMPS to perform different calculations.
+
+:line
+
+(4) Couple LAMMPS with another code in a client/server mode.  This is
+described on the "Howto client/server"_Howto_client_server.html doc
+page.

doc/src/Packages_details.txt

@@ -549,10 +549,6 @@ This package has "specific installation
 instructions"_Build_extras.html#gpu on the "Build
 extras"_Build_extras.html doc page.
 
-NOTE: You should test building the MEAM library with both the Intel
-and GNU compilers to see if a simulation runs faster with one versus
-the other on your system.
-
 [Supporting info:]
 
 src/MEAM: filenames -> commands
@@ -563,6 +559,31 @@ examples/meam :ul
 
 :line
 
+MESSAGE package :link(PKG-MESSAGE),h4
+
+[Contents:]
+
+Commands to use LAMMPS as either a client or server and couple it to
+another application.
+
+[Install:]
+
+This package has "specific installation
+instructions"_Build_extras.html#message on the "Build
+extras"_Build_extras.html doc page.
+
+[Supporting info:]
+
+src/MESSAGE: filenames -> commands
+lib/message/README
+"message"_message.html
+"fix client/md"_fix_client_md.html
+"server md"_server_md.html
+"server mc"_server_mc.html
+examples/message :ul
+
+:line
+
 MISC package :link(PKG-MISC),h4
 
 [Contents:]

doc/src/Packages_standard.txt

@@ -47,6 +47,7 @@ Package, Description, Doc page, Example, Library
 "MANYBODY"_Packages_details.html#PKG-MANYBODY, many-body potentials, "pair_style tersoff"_pair_tersoff.html, shear, no
 "MC"_Packages_details.html#PKG-MC, Monte Carlo options, "fix gcmc"_fix_gcmc.html, n/a, no
 "MEAM"_Packages_details.html#PKG-MEAM, modified EAM potential, "pair_style meam"_pair_meam.html, meam, int
+"MESSAGE"_Packages_details.html#PKG-MESSAGE, client/server messaging, "message"_message.html, message, int
 "MISC"_Packages_details.html#PKG-MISC, miscellaneous single-file commands, n/a, no, no
 "MOLECULE"_Packages_details.html#PKG-MOLECULE, molecular system force fields, "Howto bioFF"_Howto_bioFF.html, peptide, no
 "MPIIO"_Packages_details.html#PKG-MPIIO, MPI parallel I/O dump and restart, "dump"_dump.html, n/a, no