Merge pull request #1835 from lammps/message-iterate

add quit option to message command
This commit is contained in:
Axel Kohlmeyer 2020-01-14 11:41:06 -05:00 committed by GitHub
commit 126bc01dd4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 115 additions and 511 deletions

View File

@ -24,9 +24,38 @@ atoms. The quantum code computes energy and forces based on the
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
@ -39,8 +68,8 @@ 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
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

View File

@ -41,10 +41,10 @@ computes their interaction, and returns the energy, forces, and virial
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.
@ -99,8 +99,8 @@ This fix is part of the MESSAGE package. It is only enabled if LAMMPS
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
""""""""""""""""

View File

@ -11,7 +11,7 @@ Syntax
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*
@ -46,6 +46,8 @@ Examples
message client md mpi/two tmp.couple
message server md mpi/two tmp.couple
message quit
Description
"""""""""""
@ -64,6 +66,10 @@ enables the two codes to work in tandem to perform a simulation.
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.
----------
@ -146,12 +152,12 @@ path/file in a common filesystem.
----------
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>`
@ -160,16 +166,25 @@ command is executed.
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 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.
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.
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.
----------

View File

@ -39,7 +39,7 @@ enables the two codes to work in tandem to perform a simulation.
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

View File

@ -1,131 +0,0 @@
"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.

View File

@ -1,106 +0,0 @@
"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
fix client/md command :h3
[Syntax:]
fix ID group-ID client/md :pre
ID, group-ID are documented in "fix"_fix.html command
client/md = style name of this fix command :ul
[Examples:]
fix 1 all client/md :pre
[Description:]
This fix style enables LAMMPS to run as a "client" code and
communicate each timestep with a separate "server" code to perform an
MD simulation together.
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.
When using this fix, LAMMPS (as the client code) passes the current
coordinates of all particles to the server code each timestep, which
computes their interaction, and returns the energy, forces, and virial
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.
The group associated with this fix is ignored.
The protocol and "units"_units.html for message format and content
that LAMMPS exchanges with the server code is defined on the "server
md"_server_md.html doc page.
Note that when using LAMMPS as an MD client, your LAMMPS input script
should not normally contain force field commands, like a
"pair_style"_pair_style.html, "bond_style"_bond_style.html, or
"kspace_style"_kspace_style.html command. However it is possible for
a server code to only compute a portion of the full force-field, while
LAMMPS computes the remaining part. Your LAMMPS script can also
specify boundary conditions or force constraints in the usual way,
which will be added to the per-atom forces returned by the server
code.
See the examples/message dir for example scripts where LAMMPS is both
the "client" and/or "server" code for this kind of client/server MD
simulation. The examples/message/README file explains how to launch
LAMMPS and another code in tandem to perform a coupled simulation.
:line
[Restart, fix_modify, output, run start/stop, minimize info:]
No information about this fix is written to "binary restart
files"_restart.html.
The "fix_modify"_fix_modify.html {energy} option is supported by this
fix to add the potential energy computed by the server application to
the system's potential energy as part of "thermodynamic
output"_thermo_style.html.
The "fix_modify"_fix_modify.html {virial} option is supported by this
fix to add the server application's contribution to the system's
virial as part of "thermodynamic output"_thermo_style.html. The
default is {virial yes}
This fix computes a global scalar which can be accessed by various
"output commands"_Howto_output.html. The scalar is the potential
energy discussed above. The scalar value calculated by this fix is
"extensive".
No parameter of this fix can be used with the {start/stop} keywords of
the "run"_run.html command. This fix is not invoked during "energy
minimization"_minimize.html.
[Restrictions:]
This fix 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.
A script that uses this command must also use the
"message"_message.html command to setup the messaging protocol with
the other server code.
[Related commands:]
"message"_message.html, "server"_server.html
[Default:] none

View File

@ -1,162 +0,0 @@
"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

View File

@ -1,71 +0,0 @@
"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
server command :h3
[Syntax:]
server protocol :pre
protocol = {md} or {mc} :ul
[Examples:]
server md :pre
[Description:]
This command starts LAMMPS running in "server" mode, where it receives
messages from a separate "client" code and responds by sending a reply
message back to the client. The specified {protocol} determines the
format and content of messages LAMMPS expects to receive and how it
responds.
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.
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
processed.
The {protocol} argument defines the format and content of messages
that will be exchanged between the two codes. The current options
are:
"md"_server_md.html = run dynamics with another code
"mc"_server_mc.html = perform Monte Carlo moves with another code :ul
For protocol {md}, LAMMPS can be either a client (via the "fix
client/md"_fix_client_md.html command) 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
[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.
A script that uses this command must also use the
"message"_message.html command to setup the messaging protocol with
the other client code.
[Related commands:]
"message"_message.html, "fix client/md"_fix_client_md.html
[Default:] none

View File

@ -32,3 +32,4 @@ fix_modify 2 energy yes
thermo 1
run 3
message quit

View File

@ -39,3 +39,5 @@ fix_modify 2 energy yes
thermo 10
run 50
message quit

View File

@ -40,3 +40,5 @@ thermo_style custom step temp epair etotal press xy
thermo 1000
run 50000
message quit

View File

@ -80,21 +80,6 @@ FixClientMD::FixClientMD(LAMMPS *lmp, int narg, char **arg) :
FixClientMD::~FixClientMD()
{
memory->destroy(xpbc);
CSlib *cs = (CSlib *) lmp->cslib;
// all-done message to server
cs->send(-1,0);
int nfield;
int *fieldID,*fieldtype,*fieldlen;
cs->recv(nfield,fieldID,fieldtype,fieldlen);
// clean-up
delete cs;
lmp->cslib = NULL;
}
/* ---------------------------------------------------------------------- */

View File

@ -26,16 +26,31 @@ using namespace CSLIB_NS;
void Message::command(int narg, char **arg)
{
if (narg < 3) error->all(FLERR,"Illegal message command");
if (narg < 1) error->all(FLERR,"Illegal message command");
int clientserver=0;
if (strcmp(arg[0],"client") == 0) clientserver = 1;
else if (strcmp(arg[0],"server") == 0) clientserver = 2;
else if (strcmp(arg[0],"quit") == 0) clientserver = 0;
else error->all(FLERR,"Illegal message command");
// shutdown current client mode
if (clientserver == 0) {
if (lmp->clientserver != 1)
error->all(FLERR,"Cannot message quit if not in client mode");
quit();
return;
}
// setup client or server mode
lmp->clientserver = clientserver;
// validate supported protocols
if (narg < 3) error->all(FLERR,"Illegal message command");
if ((strcmp(arg[1],"md") != 0) && (strcmp(arg[1],"mc") != 0))
error->all(FLERR,"Unknown message protocol");
@ -82,3 +97,25 @@ void Message::command(int narg, char **arg)
cs->send(0,0);
}
}
/* ---------------------------------------------------------------------- */
void Message::quit()
{
CSlib *cs = (CSlib *) lmp->cslib;
// send all-done message to server
// receive acknowledgement back
cs->send(-1,0);
int nfield;
int *fieldID,*fieldtype,*fieldlen;
cs->recv(nfield,fieldID,fieldtype,fieldlen);
// clean-up
delete cs;
lmp->cslib = NULL;
lmp->clientserver = 0;
}

View File

@ -28,6 +28,9 @@ class Message : protected Pointers {
public:
Message(class LAMMPS *lmp) : Pointers(lmp) {};
void command(int, char **);
private:
void quit();
};
}