ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

additions/changes to MDI doc pages

Browse Source
This commit is contained in:
Steve Plimpton
2021-05-05 17:15:39 -06:00
committed by taylor-a-barnes
parent eacfe05e0f
commit 2d12d04545
4 changed files with 202 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/src/Howto.rst
View File

@ -23,6 +23,7 @@ General howto
Howto_library
Howto_couple
Howto_client_server
Howto_mdi
Settings howto
==============

131
doc/src/Howto_mdi.rst Normal file
View File

@ -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 <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
<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_,
developed by the `Molecular Sciences Software Institute (MolSSI)
<https://molssi.org>`_.
Alternate methods for code coupling with LAMMPS are described on the
:doc:`Howto couple <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 "<FORCES" message to QE and waits for the result
* QE receives the message (after its computation finishes) and sends a 3*N vector of forces
* LAMMPS receives the forces and time integrates to complete a single timestep
-------------
Examples scripts for using LAMMPS as an MDI engine are in the
examples/mdi directory. See the README file in that directory for
instructions on how to run the examples.
..note::
Work is underway to add commands that allow LAMMPS to be used as an
MDI driver, e.g. for the AIMD example discussed above. Example
scripts for this usage mode will be added the same directory when
available.
If LAMMPS is used as a stand-alone engine it should set up the system
it will be modeling in its input script, then invoke the
:doc:`mdi_engine <mdi_engine>` 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 <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

29
doc/src/fix_mdi_engine.rst
View File

@ -23,29 +23,30 @@ Examples
Description
"""""""""""
This fix is used alongside the :doc:`mdi_engine <mdi_engine>` command
to enable LAMMPS to use the
`MDI Library <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_
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 <mdi_engine>` command
to enable LAMMPS to use the `MDI Library
<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_ 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 <mdi_engine>` command; if the
even when using the :doc:`mdi_engine <mdi_engine>` command. If the
:doc:`mdi_engine <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 <mdi_engine>` command.
:doc:`mdi_engine <mdi_engine>` command and the :doc:`Howto mdi
<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 <Build_package>` doc page for more info.
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` doc page for more info.
Related commands
""""""""""""""""

66
doc/src/mdi_engine.rst
View File

@ -13,26 +13,70 @@ Syntax
Description
"""""""""""
This command causes LAMMPS to use the
`MDI Library <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_
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 <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_
to run as an MDI engine (server), responding to commands made by an
external MDI driver code (client). See the :doc:`Howto mdi
<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 <https://molssi-mdi.github.io/MDI_Library/html/library_page.html#library_launching_sec>`_
MDI Library can be found in the `corresponding page
<https://molssi-mdi.github.io/MDI_Library/html/library_page.html#library_launching_sec>`_
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
<https://molssi-mdi.github.io/MDI_Library/html/mdi_8c.html#a7bebce6d5fa91ee99a34fdcc5dcaedea>`_
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
* - <NATOMS
- Driver requests the number of atoms in the system
* - <COORDS
- Driver requests 3*N double-precision atom coordinates
* - >FORCES
- Driver sends 3*N double-precision atom forces
* - <COORDS
- Driver requests 3*N double-precision atom forces
* - EXIT
- Driver tells the engine (LAMMPS) to exit engine mode
If these commands are not sufficient to support what a driver which
you write needs, additional commands can be defined by simply using a
new command name not in this list. Code to support the new command
needs to be added to the USER-MDI package within LAMMPS; see its
src/USER-MDI/mdi_engine.cpp and fix_mdi_engine.cpp files.
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 <Build_package>` doc page for more info.
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` doc page for more info.
Related commands
""""""""""""""""
@ -42,4 +86,4 @@ Related commands
Default
"""""""
none
None