From 0bc648e23e3a495be12eeaaebc6f779ee2abb56f Mon Sep 17 00:00:00 2001 From: Steve Plimpton Date: Tue, 18 Jun 2019 14:30:30 -0600 Subject: [PATCH] add message quit protocol, to allow for non-quantum MD steps --- doc/src/Howto_client_server.txt | 33 +++++++++++++++-- doc/src/fix_client_md.txt | 12 +++---- doc/src/message.txt | 47 ++++++++++++++++--------- doc/src/server.txt | 2 +- examples/COUPLE/lammps_vasp/in.client.W | 1 + examples/message/in.message.client | 2 ++ examples/message/in.message.tilt.client | 2 ++ src/MESSAGE/fix_client_md.cpp | 15 -------- src/MESSAGE/message.cpp | 39 +++++++++++++++++++- src/MESSAGE/message.h | 3 ++ 10 files changed, 115 insertions(+), 41 deletions(-) diff --git a/doc/src/Howto_client_server.txt b/doc/src/Howto_client_server.txt index 96939809dc..37b622151c 100644 --- a/doc/src/Howto_client_server.txt +++ b/doc/src/Howto_client_server.txt @@ -32,9 +32,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 "Howto couple"_Howto_couple.html 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): + +"message client"_message.html # initiate client/server interaction +"fix client/md"_fix_client_md.html # any client fix which makes specific requests to the server +"message quit"_message.html # terminate client/server interaction :ul + +In between the two message commands, a client fix command and +"unfix"_unfix.html 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): + +"message server"_message.html # initiate client/server interaction +"server md"_server__md.html # any server command which responds to specific requests from the client :ul + +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 "MESSAGE package"_Packages_details.html#PKG-MESSAGE which implements several commands that enable LAMMPS to act as a client or server, as discussed @@ -46,8 +75,8 @@ in the lib/message dir. The CSlib has its own 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 diff --git a/doc/src/fix_client_md.txt b/doc/src/fix_client_md.txt index 5fee8511fe..d43da450af 100644 --- a/doc/src/fix_client_md.txt +++ b/doc/src/fix_client_md.txt @@ -37,10 +37,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. @@ -96,8 +96,8 @@ 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. +"message"_message.html command to setup and shut down the messaging +protocol with the server code. [Related commands:] diff --git a/doc/src/message.txt b/doc/src/message.txt index 0c10af4ac6..71e3550b42 100644 --- a/doc/src/message.txt +++ b/doc/src/message.txt @@ -12,7 +12,7 @@ message command :h3 message which protocol mode arg :pre -which = {client} or {server} :ulb,l +which = {client} or {server} or {quit} :ulb,l protocol = {md} or {mc} :l mode = {file} or {zmq} or {mpi/one} or {mpi/two} :l {file} arg = filename @@ -39,6 +39,8 @@ message server md mpi/one :pre message client md mpi/two tmp.couple message server md mpi/two tmp.couple :pre +message quit :pre + [Description:] Establish a messaging protocol between LAMMPS and another code for the @@ -54,6 +56,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. + :line The {protocol} argument defines the format and content of messages @@ -121,12 +127,12 @@ 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. +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 "fix @@ -136,16 +142,25 @@ 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 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. :line diff --git a/doc/src/server.txt b/doc/src/server.txt index 8f87b5c76b..d30d398598 100644 --- a/doc/src/server.txt +++ b/doc/src/server.txt @@ -35,7 +35,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 diff --git a/examples/COUPLE/lammps_vasp/in.client.W b/examples/COUPLE/lammps_vasp/in.client.W index 3eaf99dcbb..1af1c312e4 100644 --- a/examples/COUPLE/lammps_vasp/in.client.W +++ b/examples/COUPLE/lammps_vasp/in.client.W @@ -32,3 +32,4 @@ fix_modify 2 energy yes thermo 1 run 3 +message quit diff --git a/examples/message/in.message.client b/examples/message/in.message.client index f1ec644a80..cd0a40367a 100644 --- a/examples/message/in.message.client +++ b/examples/message/in.message.client @@ -39,3 +39,5 @@ fix_modify 2 energy yes thermo 10 run 50 + +message quit diff --git a/examples/message/in.message.tilt.client b/examples/message/in.message.tilt.client index b55bc6585b..d178c801f5 100644 --- a/examples/message/in.message.tilt.client +++ b/examples/message/in.message.tilt.client @@ -40,3 +40,5 @@ thermo_style custom step temp epair etotal press xy thermo 1000 run 50000 + +message quit diff --git a/src/MESSAGE/fix_client_md.cpp b/src/MESSAGE/fix_client_md.cpp index 727481dcc0..82a1b78d03 100644 --- a/src/MESSAGE/fix_client_md.cpp +++ b/src/MESSAGE/fix_client_md.cpp @@ -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; } /* ---------------------------------------------------------------------- */ diff --git a/src/MESSAGE/message.cpp b/src/MESSAGE/message.cpp index 61221ca26e..fa48b19d1d 100644 --- a/src/MESSAGE/message.cpp +++ b/src/MESSAGE/message.cpp @@ -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; 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; +} diff --git a/src/MESSAGE/message.h b/src/MESSAGE/message.h index c384a5a7b7..f8b2d47a21 100644 --- a/src/MESSAGE/message.h +++ b/src/MESSAGE/message.h @@ -28,6 +28,9 @@ class Message : protected Pointers { public: Message(class LAMMPS *lmp) : Pointers(lmp) {}; void command(int, char **); + + private: + void quit(); }; }