"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Command_all.html)

:line

message command :h3

[Syntax:]

message which protocol mode arg :pre

which = {client} or {server} :ulb,l
protocol = {md} or {mc} :l
mode = {file} or {zmq} or {mpi/one} or {mpi/two} :l
  {file} arg = filename
    filename = file used for message exchanges
  {zmq} arg = socket-ID
    socket-ID for client = localhost:5555, see description below
    socket-ID for server = *:5555, see description below
  {mpi/one} arg = none
  {mpi/two} arg = filename
    filename = file used to establish communication between 2 MPI jobs :pre
:ule

[Examples:]

message client md file tmp.couple
message server md file tmp.couple :pre

message client md zmq localhost:5555
message server md zmq *:5555 :pre

message client md mpi/one
message server md mpi/one :pre

message client md mpi/two tmp.couple
message server md mpi/two tmp.couple :pre

[Description:]

Establish a messaging protocol between LAMMPS and another code for the
purpose of client/server coupling.

The "Howto client/server"_Howto_client_server.html doc page gives an
overview of client/server coupling of LAMMPS with another code 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.

:line

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

:line

The {protocol} argument defines the format and content of messages
that will be exchanged between the two codes.  The current options
are:

md = run dynamics with another code
mc = perform Monte Carlo moves with another code :ul

For protocol {md}, LAMMPS can be either a client or server.  See the
"server md"_server_md.html doc page for details on the protocol.

For protocol {mc}, LAMMPS can be the server.  See the "server
mc"_server_mc.html doc page for details on the protocol.

:line

The {mode} argument specifies how messages are exchanged between the
client and server codes.  Both codes must use the same mode and use
consistent parameters.

For mode {file}, the 2 codes communicate via binary files.  They must
use the same filename, which is actually a file prefix.  Several files
with that prefix will be created and deleted as a simulation runs.
The filename can include a path.  Both codes must be able to access
the path/file in a common filesystem.

For mode {zmq}, the 2 codes communicate via a socket on the server
code's machine.  Support for socket messaging is provided by the
open-source "ZeroMQ library"_http://zeromq.org, which must be
installed on your system.  The client specifies an IP address (IPv4
format) or the DNS name of the machine the server code is running on,
followed by a 4-digit port ID for the socket, separated by a colon.
E.g.

localhost:5555        # client and server running on same machine
192.168.1.1:5555      # server is 192.168.1.1
deptbox.uni.edu:5555  # server is deptbox.uni.edu :pre

The server specifies "*:5555" where "*" represents all available
interfaces on the server's machine, and the port ID must match
what the client specifies.

NOTE: What are allowed port IDs?

NOTE: Additional explanation is needed here about how to use the {zmq}
mode on a parallel machine, e.g. a cluster with many nodes.

For mode {mpi/one}, the 2 codes communicate via MPI and are launched
by the same mpirun command, e.g. with this syntax for OpenMPI:

mpirun -np 2 lmp_mpi -mpicolor 0 -in in.client -log log.client : -np 4 othercode args  # LAMMPS is client
mpirun -np 2 othercode args : -np 4 lmp_mpi -mpicolor 1 -in in.server  # LAMMPS is server :pre

Note the use of the "-mpicolor color" command-line argument with
LAMMPS.  See the "command-line args"_Run_options.html doc page for
further explanation.

For mode {mpi/two}, the 2 codes communicate via MPI, but are launched
be 2 separate mpirun commands.  The specified {filename} argument is a
file the 2 MPI processes will use to exchange info so that an MPI
inter-communicator can be established to enable the 2 codes to send
MPI messages to each other.  Both codes must be able to access the
path/file in a common filesystem.

:line

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.

If LAMMPS is the client code, it will begin sending messages when a
LAMMPS client command begins its operation.  E.g. for the "fix
client/md"_fix_client_md.html command, it is when a "run"_run.html
command is executed.

If LAMMPS is the server code, it will begin receiving messages when
the "server"_server.html command is invoked.

A fix client command will terminate its messaging with the server when
LAMMPS ends, or the fix is deleted via the "unfix"_unfix.html 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.

:line

[Restrictions:]

This command is part of the MESSAGE package.  It is only enabled if
LAMMPS was built with that package.  See the "Build
package"_Build_package.html doc page for more info.

[Related commands:]

"server"_server.html, "fix client/md"_fix_client_md.html

[Default:] none
