Merge pull request #1835 from lammps/message-iterate

coords.  It returns them as a message to LAMMPS, which completes the

timestep.

A more complex example is where LAMMPS is the client code and

processes a series of data files, sending each configuration to a

quantum code to compute energy and forces.  Or LAMMPS runs dynamics

with an atomistic force field, but pauses every N steps to ask the

quantum code to compute energy and forces.

Alternate methods for code coupling with LAMMPS are described on

the :doc:`Howto couple <Howto_couple>` doc page.

The protocol for using LAMMPS as a client is to use these 3 commands

in this order (other commands may come in between):

* :doc:`message client <message>`  # initiate client/server interaction

* :doc:`fix client/md <fix_client_md>`   # any client fix which makes specific requests to the server

* :doc:`message quit <message>`    # terminate client/server interaction

In between the two message commands, a client fix command and

:doc:`unfix <unfix>` command can be used multiple times.  Similarly,

this sequence of 3 commands can be repeated multiple times, assuming

the server program operates in a similar fashion, to initiate and

terminate client/server communication.

The protocol for using LAMMPS as a server is to use these 2 commands

in this order (other commands may come in between):

* :doc:`message server <message>`  # initiate client/server interaction

* :doc:`server md <server_md>`    # any server command which responds to specific requests from the client

This sequence of 2 commands can be repeated multiple times, assuming

the client program operates in a similar fashion, to initiate and

terminate client/server communication.

LAMMPS support for client/server coupling is in its :ref:`MESSAGE package <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

.. 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

   code, the other code also has to use the CSlib.  This can often be

   done without any modification 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

for the interacting particles to LAMMPS, so it can complete the

timestep.

The server code could be a quantum code, or another classical MD code

which encodes a force field (pair\_style in LAMMPS lingo) which LAMMPS

does not have.  In the quantum case, this fix is a mechanism for

running *ab initio* MD with quantum forces.

Note that the server code can be a quantum code, or another classical

MD code which encodes a force field (pair\_style in LAMMPS lingo) which

LAMMPS does not have.  In the quantum case, this fix is a mechanism

for running *ab initio* MD with quantum forces.

The group associated with this fix is ignored.

was built with that package.  See the :doc:`Build package <Build_package>` doc page for more info.

A script that uses this command must also use the

:doc:`message <message>` command to setup the messaging protocol with

the other server code.

:doc:`message <message>` command to setup and shut down the messaging

protocol with the server code.

Related commands

""""""""""""""""

   message which protocol mode arg

* which = *client* or *server*

* which = *client* or *server* or *quit*

* protocol = *md* or *mc*

* mode = *file* or *zmq* or *mpi/one* or *mpi/two*

   message client md mpi/two tmp.couple

   message server md mpi/two tmp.couple

   message quit

Description

"""""""""""

The *which* argument defines LAMMPS to be the client or the server.

As explained below the *quit* option should be used when LAMMPS is

finished as a client.  It sends a message to the server to tell it to

shut down.

----------

----------

Normally, the message command should be used at the top of a LAMMPS

input script.  It performs an initial handshake with the other code to

setup messaging and to verify that both codes are using the same

message protocol and mode.  Assuming both codes are launched at

(nearly) the same time, the other code should perform the same kind of

initialization.

Normally, the message client or message server command should be used

at the top of a LAMMPS input script.  It performs an initial handshake

with the other code to setup messaging and to verify that both codes

are using the same message protocol and mode.  Assuming both codes are

launched at (nearly) the same time, the other code should perform the

same kind of initialization.

If LAMMPS is the client code, it will begin sending messages when a

LAMMPS client command begins its operation.  E.g. for the :doc:`fix client/md <fix_client_md>` command, it is when a :doc:`run <run>`

If LAMMPS is the server code, it will begin receiving messages when

the :doc:`server <server>` command is invoked.

A fix client command will terminate its messaging with the server when

LAMMPS ends, or the fix is deleted via the :doc:`unfix <unfix>` command.

The server command will terminate its messaging with the client when the

client signals it.  Then the remainder of the LAMMPS input script will

be processed.

If both codes do something similar, this means a new round of

client/server messaging can be initiated after termination by re-using

a 2nd message command in your LAMMPS input script, followed by a new

fix client or server command.

If LAMMPS is being used as a client, the message quit command will

terminate its messaging with the server.  If you do not use this

command and just allow LAMMPS to exit, then the server will continue

to wait for further messages.  This may not be a problem, but if both

the client and server programs were launched in the same batch script,

then if the server runs indefinitely, it may consume the full allocation

of computer time, even if the calculation finishes sooner.

Note that if LAMMPS is the client or server, it will continue

processing the rest of its input script after client/server

communication terminates.

If both codes cooperate in this manner, a new round of client/server

messaging can be initiated after termination by re-using a 2nd message

command in your LAMMPS input script, followed by a new fix client or

server command, followed by another message quit command (if LAMMPS is

the client).  As an example, this can be performed in a loop to use a

quantum code as a server to compute quantum forces for multiple LAMMPS

data files or periodic snapshots while running dynamics.

----------

When this command is invoked, LAMMPS will run in server mode in an

endless loop, waiting for messages from the client code.  The client

signals when it is done sending messages to LAMMPS, at which point the

loop will exit, and the remainder of the LAMMPS script will be

loop will exit, and the remainder of the LAMMPS input script will be

processed.

The *protocol* argument defines the format and content of messages

"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 :h3

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 :ul

The server doc files give details of the message protocols

for data that is exchanged between 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, through 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 substituted 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 :pre

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.