new MESSAGE package for client/server/coupling

"lattice"_lattice.html,

"log"_log.html,

"mass"_mass.html,

"message"_message.html,

"minimize"_minimize.html,

"min_modify"_min_modify.html,

"min_style"_min_style.html,

"restart"_restart.html,

"run"_run.html,

"run_style"_run_style.html,

"server"_server.html,

"set"_set.html,

"shell"_shell.html,

"special_bonds"_special_bonds.html,

"bond/create"_fix_bond_create.html,

"bond/swap"_fix_bond_swap.html,

"box/relax"_fix_box_relax.html,

"client/md"_fix_client_md.html,

"cmap"_fix_cmap.html,

"controller"_fix_controller.html,

"deform (k)"_fix_deform.html,

"vector"_fix_vector.html,

"viscosity"_fix_viscosity.html,

"viscous"_fix_viscous.html,

"wall/body/polygon"_fix_wall_body_polygon.html,

"wall/body/polyhedron"_fix_wall_body_polyhedron.html,

"wall/colloid"_fix_wall.html,

"wall/gran"_fix_wall_gran.html,

"wall/gran/region"_fix_wall_gran_region.html,

"airebo (oi)"_pair_airebo.html,

"airebo/morse (oi)"_pair_airebo.html,

"beck (go)"_pair_beck.html,

"body/nparticle"_pair_body_nparticle.html,

"body/rounded/polygon"_pair_body_rounded/polygon.html,

"body/rounded/polyhedron"_pair_body_rounded/polyhedron.html,

"body"_pair_body.html,

"bop"_pair_bop.html,

"born (go)"_pair_born.html,

"born/coul/dsf"_pair_born.html,

6.25 "Polarizable models"_#howto_25

6.26 "Adiabatic core/shell model"_#howto_26

6.27 "Drude induced dipoles"_#howto_27

6.28 "Magnetic spins"_#howto_28 :all(b)

6.28 "Magnetic spins"_#howto_28

6.29 "Using LAMMPS in client/server mode"_#howto_29 :all(b)

The example input scripts included in the LAMMPS distribution and

highlighted in "Section 7"_Section_example.html also show how to

nodal points, compute a FE solution, and return interpolated forces on

MD atoms.

LAMMPS can be coupled to other codes in at least 3 ways.  Each has

LAMMPS can be coupled to other codes in at least 4 ways.  Each has

advantages and disadvantages, which you'll have to think about in the

context of your application.

before syncing them up periodically.  Or it might instantiate multiple

instances of LAMMPS to perform different calculations.

:line

(4) Couple LAMMPS with another code in a client/server mode.  This is

described in a separate "howto section"_#howto_29.

6.11 Visualizing LAMMPS snapshots :link(howto_11),h4

per atom magnetic quantities. Typically, the orientation of a given 

magnetic spin, or the magnetic force acting on this spin.

:line

6.29 Using LAMMPS in client/server mode :link(howto_29),h4

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 in "this

section"_#howto10.

LAMMPS support for client/server coupling is in its "MESSAGE

package"_Section_package.html#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, a socket, or MPI.  The CSlib is provided with LAMMPS

in the lib/message dir.  It has its own

"website"_http://cslib.sandia.gov (as of Aug 2018) 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

The server doc files give details of the message protocols

for data that is exchanged bewteen 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, thru 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 subsitituted 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 -mpi 2 -in in.message.client -log log.client : -np 4 lmp_mpi -mpi 2 -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 -mpi P

command-line option as their first option, where P is the number of

processors the first code in the mpirun command (client or server) is

running on.

:line

:line

"MANYBODY"_#MANYBODY, many-body potentials, "pair_style tersoff"_pair_tersoff.html, shear, -

"MC"_#MC, Monte Carlo options, "fix gcmc"_fix_gcmc.html, -, -

"MEAM"_#MEAM, modified EAM potential, "pair_style meam"_pair_meam.html, meam, int

"MESSAGE"_#MESSAGE, client/server messaging, "message"_message.html, message, int

"MISC"_#MISC, miscellanous single-file commands, -, -, -

"MOLECULE"_#MOLECULE, molecular system force fields, "Section 6.6.3"_Section_howto.html#howto_3, peptide, -

"MPIIO"_#MPIIO, MPI parallel I/O dump and restart, "dump"_dump.html, -, -

:line

MESSAGE package :link(MESSAGE),h4

[Contents:]

Commands to use LAMMPS as either a client or server

and couple it to another application.

[Install or un-install:]

Before building LAMMPS with this package, you must first build the

CSlib library in lib/message.  You can do this manually if you prefer;

follow the instructions in lib/message/README.  You can also do it in

one step from the lammps/src dir, using a command like these, which

simply invoke the lib/message/Install.py script with the specified

args:

make lib-message               # print help message

make lib-message args="-m -z"  # build with MPI and socket (ZMQ) support

make lib-message args="-s"     # build as serial lib with no ZMQ support

The build should produce two files: lib/message/cslib/src/libmessage.a

and lib/message/Makefile.lammps.  The latter is copied from an

existing Makefile.lammps.* and has settings to link with the

open-source ZMQ library if requested in the build.

You can then install/un-install the package and build LAMMPS in the

usual manner:

make yes-message

make machine :pre

make no-message

make machine :pre

[Supporting info:]

src/MESSAGE: filenames -> commands

lib/message/README

"message"_message.html

"fix client/md"_fix_client_md.html

"server md"_server_md.html

"server mc"_server_mc.html

examples/message :ul

:line

MISC package :link(MISC),h4

[Contents:]

-i or -in

-k or -kokkos

-l or -log

-m or -mpi

-nc or -nocite

-pk or -package

-p or -partition

"log"_log.html command in the input script will override this setting.

Option -plog will override the name of the partition log files file.N.

-mpi P :pre

If used, this must be the first command-line argument after the LAMMPS

executable name.  It is only used when running LAMMPS in client/server

mode with the "mpi/one" mode of messaging provided by the

"message"_message.html command and the CSlib library LAMMPS links with

from the lib/message directory.  See the "message"_message.html

command for more details

In the mpi/one mode of messaging, both executables (the client and the

server) are launched by one mpirun command.  P should be specified as

the number of processors (MPI tasks) the first executable is running

on (could be the client or the server code).

This information is required so that both codes can shrink the

MPI_COMM_WORLD communicator they are part of to the subset of

processors they are actually running on.

-nocite :pre

Disable writing the log.cite file which is normally written to list

"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Section_commands.html#comm)

: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.

"This section"_Section_howto.html#howto_29 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 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 in this mode, your LAMMPS input script

should not normally contain force field commands, like a

"pair_style"_doc/pair_style.html, "bond_style"_doc/bond_style.html, or

"kspace_style"_kspace_style.html commmand.  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"_Section_howto.html#howto_15.  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 "Making

LAMMPS"_Section_start.html#start_3 section 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