From 2d12d045456ac16d42bf8069e5c2cc8f9db8a56d Mon Sep 17 00:00:00 2001 From: Steve Plimpton Date: Wed, 5 May 2021 17:15:39 -0600 Subject: [PATCH] additions/changes to MDI doc pages --- doc/src/Howto.rst | 1 + doc/src/Howto_mdi.rst | 131 +++++++++++++++++++++++++++++++++++++ doc/src/fix_mdi_engine.rst | 29 ++++---- doc/src/mdi_engine.rst | 66 +++++++++++++++---- 4 files changed, 202 insertions(+), 25 deletions(-) create mode 100644 doc/src/Howto_mdi.rst diff --git a/doc/src/Howto.rst b/doc/src/Howto.rst index ff75b751b1..99a9fae4da 100644 --- a/doc/src/Howto.rst +++ b/doc/src/Howto.rst @@ -23,6 +23,7 @@ General howto Howto_library Howto_couple Howto_client_server + Howto_mdi Settings howto ============== diff --git a/doc/src/Howto_mdi.rst b/doc/src/Howto_mdi.rst new file mode 100644 index 0000000000..ddf52ea0f3 --- /dev/null +++ b/doc/src/Howto_mdi.rst @@ -0,0 +1,131 @@ +Using LAMMPS with the MDI library for code coupling +=================================================== + +..note:: + + This Howto doc page will eventually replace the + :doc:`Howto client/server ` doc page. + +Client/server coupling of two codes is where one code is the "client" +and sends request messages (data) 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; it does this by using the `MolSSI +Driver Interface (MDI) library +`_, +developed by the `Molecular Sciences Software Institute (MolSSI) +`_. + +Alternate methods for code coupling with LAMMPS are described on the +:doc:`Howto couple ` doc page. + +Some advantages of client/server coupling are that the two codes can +run as stand-alone executables; they need not be linked together. +Thus neither code needs to have a library interface. This also makes +it easy 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 whcih implements the +client-side protocol can be used in tandem with any code which +implements the server-side protocol. Neither code needs to know what +specific other code it is working with. + +In MDI lingo, a client code is the "driver", and a server code is an +"engine". One driver code can communicate with one or more instances +of one or more engine codes. Driver and engine codes can be written +in any language: C, C++, Fortran, Python, etc. + +In addition to allowing driver and engine(s) running to run as +stand-alone executables, MDI also enables a server code to be a +"plugin" to the client code. In this scenario, server code(s) are +compiled as shared libraries, and one (or more) instances of the +server are instantiated by the driver code. If the driver code runs +in parallel, it can split its MPI communicator into multiple +sub-communicators, and launch each plugin engine instance on a +sub-communicator. Driver processors in that sub-communicator exchange +messages with that engine instance, and can also send MPI messages to +other processors in the driver. The driver code can also destroy +engine instances and re-instantiate them. + +The way that a driver communicates with an engine is by making +MDI_Send() and MDI_Receive() calls, which are conceptually similar to +MPI_Send() and MPI_Receive() calls. Each send or receive has a string +which identifies the command name, and optinally some data, which can +be a single value or vector of values of any data type. Inside the +MDI library, data is exchanged bewteen the driver and engine via MPI +calls or sockets. This a run-time choice by the user. + +------------- + +As an example, LAMMPS and Quantum Espresso (QE, a quantum DFT code), +can work together via the MDI library to perform an ab initio MD +(AIMD) simulation, where LAMMPS runs an MD simulation and sends a +message each timestep to QE asking it to compute quantum forces on the +current configuration of atoms. Here is how the 2 codes are launched +to communicate by MPI: + +.. code-block:: bash + +% mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method MPI" < in.aimd: -np 16 qe -mdi "-role ENGINE -name e -method MPI" + +In this case LAMMPS runs on 2 processors (MPI tasks), QE runs on 16 +processors. + +Here is how the 2 codes are launched to communicate by sockets: + +.. code-block:: bash + +% mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method TCP -port 8021" < in.aimd +% mpirun -np 16 qe -mdi "-role ENGINE -name e -method TCP -port 8021 -hostname localhost" + +These commands could be issued in different windows on a desktop +machine. Or in the same window, if the first command is ended with +"&" so as to run in the background. If "localhost" is replaced by an +IP address, QE could be run on another machine on the same network, or +even on another machine across the country. + +After both codes initialize themselves to model the same system, this +is what occurs each timestep: + +* LAMMPS send a ">COORDS" message to QE with a 3*N vector of current atom coords +* QE receives the message/coords and computes quantum forces on all the atoms +* LAMMPS send a "` command. This will put LAMMPS into +engine mode where it waits for messages and data from the driver. +When the driver sends an "EXIT" command, LAMMPS will exit engine mode +and the input script will continue. + +If LAMMPS is used as a plugin engine it operates the same way, except +that the driver will pass LAMMPS an input script to initialize itself, +and after the "EXIT" command, the driver will typically destroy the +instance of LAMMPS, so the mdi_engine command should be the final +command in the LAMMPS script. + +LAMMPS supports the full set of MD-appropriate engine commands +defined by the MDI library. See the :doc:`mdi_engine ` +doc page for a list of these. + +If those commands are not sufficient for a user-developed driver to +use LAMMPS as an engine, then new commands can easily be added. See +these two files which implement the definition of MDI commands and the +logic for responding to them: + +* src/MDI/mdi_engine.cpp +* src/MDI/fix_mdi_engine.cpp diff --git a/doc/src/fix_mdi_engine.rst b/doc/src/fix_mdi_engine.rst index f4d717b2f2..431abfa737 100644 --- a/doc/src/fix_mdi_engine.rst +++ b/doc/src/fix_mdi_engine.rst @@ -23,29 +23,30 @@ Examples Description """"""""""" -This fix is used alongside the :doc:`mdi_engine ` command -to enable LAMMPS to use the -`MDI Library `_ -to run as an MDI engine. -The fix provides hooks that are enable external drivers to communicate -with LAMMPS at various points within LAMMPS timesteps. +This fix is used along with the :doc:`mdi_engine ` command +to enable LAMMPS to use the `MDI Library +`_ to run as +an MDI engine. The fix provides hooks that enable MDI driver codes to +communicate with LAMMPS at various points within a LAMMPS timestep. It is not generally necessary to add this fix to a LAMMPS input file, -even when using the :doc:`mdi_engine ` command; if the +even when using the :doc:`mdi_engine ` command. If the :doc:`mdi_engine ` command is executed and this fix is not -present, it will automatically be added to the end of the fix list and -applied to all atoms for the duration of the command. It is only -necessary to add this fix to an input file for cases in which the user -would like to modify order or group-ID of the fix. +present, it will automatically be added and applied as a new fix for +all atoms for the duration of the command. Thus it is only necessary +to add this fix to an input file when you want to modify the group-ID +or the ordering of this fix relative to other fixes in the input script. For more information about running LAMMPS as an MDI engine, see the -:doc:`mdi_engine ` command. - +:doc:`mdi_engine ` command and the :doc:`Howto mdi +` doc page. Restrictions """""""""""" + This command is part of the USER-MDI package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` doc page for more info. +LAMMPS was built with that package. See the :doc:`Build package +` doc page for more info. Related commands """""""""""""""" diff --git a/doc/src/mdi_engine.rst b/doc/src/mdi_engine.rst index 248c7b0622..300e0b7904 100644 --- a/doc/src/mdi_engine.rst +++ b/doc/src/mdi_engine.rst @@ -13,26 +13,70 @@ Syntax Description """"""""""" -This command causes LAMMPS to use the -`MDI Library `_ -to run as an MDI Engine, responding to commands from an external -MDI Driver. +This command is used to have LAMMPS act as a server with another +client code to effectively couple the two codes together in +client/server mode. + +More specifically, this command causes LAMMPS to begin using the `MDI +Library `_ +to run as an MDI engine (server), responding to commands made by an +external MDI driver code (client). See the :doc:`Howto mdi +` doc page for more information about how LAMMPS can work +as both an MDI driver or engine. + General information about launching codes that communicate using the -MDI Library can be found in the -`corresponding page `_ +MDI Library can be found in the `corresponding page +`_ of the MDI Library's documentation. ---------- -Other commands can be executed both before and after this command, -but typically this command should be used at the end of a LAMMPS -input script. +This command should typically be used in an input script after LAMMPS +has setup the system is is going to model in collaboration with the +driver code. Depending on how the driver code tells the LAMMPS engine +to exit, other commands can be executed after this command, but +typically it should be used at the end of the LAMMPS input script. + +To act as a MD-based MDI engine, this is the list of MDI commands from +a driver code which LAMMPS currently recognizes. See more details +about these commands in the `MDI library documentation +`_ + +NOTE: Taylor - is this the best link for this info? Can we flesh this +out with the full list of supported commands? Maybe the distiniction +of what "node" the commands refer to is not needed in this table? + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Command name + - Action + * - >NATOMS + - Driver sends the number of atoms in the ststem + * - FORCES + - Driver sends 3*N double-precision atom forces + * - ` doc page for more info. +LAMMPS was built with that package. See the :doc:`Build package +` doc page for more info. Related commands """""""""""""""" @@ -42,4 +86,4 @@ Related commands Default """"""" -none +None