lammps/examples/message

This dir contains scripts that demonstrate how to use LAMMPS as both a
client and server code to run a simple MD simulation.  LAMMPS as a
client performs the MD timestepping.  LAMMPS as a server provides the
energy and forces between interacting particles.  Every timestep the
LAMMPS client sends a message to the LAMMPS server and receives a
response message in return.

Another code could replace LAMMPS as the client, e.g. another MD code
which wants to use a LAMMPS potential.  Another code could replace
LAMMPS as the server, e.g. a quantum code computing quantum forces, so
that ab initio MD could be performed.  See an example of the latter in
examples/COUPLE/lammps_vasp.

See the doc pages for the "MESSAGE package"
(Package_details.html#PKG-MESSAGE) and "Howto client/server"
(Howto_client_server.html) for more details on how client/server
coupling works in LAMMPS.

--------------

Note that you can adjust the problem size run by these scripts by
setting "x,y,z" variables when you run LAMMPS.  The default problem size
is x = y = z = 5, which is 500 particles.

lmp_mpi -v x 10 -v y 10 -v z 20    # 8000 particles

This applies to either in.message or in.message.client

You can also run the in.message scripts with an NPT integrator
instead of NVE, if you comment/uncomment the correct lines.

The client and server script define a "mode" variable
which can be set to file, zmq, mpi/one, or mpi/two, 
as illustrated below.

--------------

To run this problem in the traditional way (no client/server coupling)
do one of these:

% lmp_serial < in.message
% mpirun -np 4 lmp_mpi < in.message

Or run with in.message.tilt.

--------------

To run in client/server mode:

Both the client and server script must use the same messaging mode.
This can be selected by setting the "mode" variable when you run
LAMMPS.  The default mode = file.  The other options for the mode
variable are zmq, mpione, mpitwo.

Here we assume LAMMPS was built to run in parallel, and the MESSAGE
package was installed with socket (ZMQ) support.  This means any of
the 4 messaging modes can be used.

The next sections illustrate how to launch LAMMPS twice, once as a
client, once as a server, for each of the messaging modes.

In all cases, the client should print out thermodynamic info for 50
steps.  The server should print out setup info, print nothing until
the client exits, at which point the server should also exit.

The examples below show launching LAMMPS twice from the same window
(or batch script), using the "&" character to launch the first time in
the background.  For all modes except {mpi/one}, you could also launch
twice in separate windows on your desktop machine.  It does not matter
whether you launch the client or server first.

In these examples either the client or server can be run on one or
more processors.  If running in a non-MPI mode (file or zmq) you can
launch LAMMPS on a single processor without using mpirun.

IMPORTANT: If you run in mpi/two mode, you must launch LAMMPS both
times 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.

--------------

NOTE: the Script.sh file has comands to perform all the
runs listed below.

--------------

File or ZMQ or mpi/two modes of messaging:

% mpirun -np 1 lmp_mpi -v mode file -log log.client < in.message.client & 
% mpirun -np 2 lmp_mpi -v mode file -log log.server < in.message.server

% mpirun -np 4 lmp_mpi -v mode zmq -log log.client < in.message.client & 
% mpirun -np 1 lmp_mpi -v mode zmq -log log.server < in.message.server

% mpirun -np 2 lmp_mpi -v mode mpitwo -log log.client < in.message.client & 
% mpirun -np 4 lmp_mpi -v mode mpitwo -log log.server < in.message.server

Or run with in.message.tilt.client/server.
Don't run the tilt files with the "file" mode; they run too slow.

--------------

Mpi/one mode of messaging:

Launch LAMMPS twice in a single mpirun command:

% mpirun -np 2 lmp_mpi -mpicolor 0 -in in.message.client -v mode mpione -log log.client : -np 4 lmp_mpi -mpicolor 1 -in in.message.server -v mode mpione -log log.server

Or run with in.message.tilt.client/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 its first option, where color is set to one
integer value for the 1st app, and another value for the 2nd app.