164 lines
7.3 KiB
ReStructuredText
164 lines
7.3 KiB
ReStructuredText
Using LAMMPS in client/server mode
|
|
==================================
|
|
|
|
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.
|
|
|
|
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
|
|
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 <https://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.
|
|
|
|
* :doc:`message <message>`
|
|
* :doc:`fix client md <fix_client_md>` = LAMMPS is a client for running MD
|
|
* :doc:`server md <server_md>` = LAMMPS is a server for computing MD forces
|
|
* :doc:`server mc <server_mc>` = LAMMPS is a server for computing a Monte Carlo energy
|
|
|
|
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_nwchem
|
|
* examples/COUPLE/lammps_vasp
|
|
|
|
The examples/message directory couples a client instance of LAMMPS to a
|
|
server instance of LAMMPS.
|
|
|
|
The files in the *lammps_mc* folder show how to couple LAMMPS as
|
|
a server to a simple Monte Carlo client code as the driver.
|
|
|
|
The files in the *lammps_nwchem* folder show how to couple LAMMPS
|
|
as a client code running MD timestepping to NWChem acting as a
|
|
server providing quantum DFT forces, through a Python wrapper script
|
|
on NWChem.
|
|
|
|
The files in the *lammps_vasp* folder show 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 :doc:`message <message>` 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:
|
|
|
|
.. code-block:: bash
|
|
|
|
% mpirun -np 1 lmp_mpi -log log.client < in.client &
|
|
% mpirun -np 2 lmp_mpi -log log.server < in.server
|
|
|
|
% mpirun -np 4 lmp_mpi -log log.client < in.client &
|
|
% mpirun -np 1 lmp_mpi -log log.server < in.server
|
|
|
|
% mpirun -np 2 lmp_mpi -log log.client < in.client &
|
|
% mpirun -np 4 lmp_mpi -log log.server < in.server
|
|
|
|
For message exchange in *mpi/one* mode:
|
|
|
|
Launch both codes in a single mpirun command:
|
|
|
|
.. code-block:: bash
|
|
|
|
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
|
|
|
|
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.
|