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

:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Commands_all.html)

:line

server md command :h3

[Syntax:]

server md :pre

md = the protocol argument to the "server"_server.html command

[Examples:]

server md :pre

[Description:]

This command starts LAMMPS running in "server" mode, where it will
expect messages from a separate "client" code that match the {md}
protocol for format and content explained below.  For each message
LAMMPS receives it will send a message back to the client.

The "Howto client/server"_Howto_client_server.html doc page 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 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
processed.

The "server"_server.html doc page gives other options for using LAMMPS
in server mode.  See an example of how this command is used in
examples/message/in.message.server.

:line

When using this command, LAMMPS (as the server code) receives the
current coordinates of all particles from the client code each
timestep, computes their interaction, and returns the energy, forces,
and pressure for the interacting particles to the client code, so it
can complete the timestep.  This command could also be used with a
client code that performs energy minimization, using the server to
compute forces and energy each iteration of its minimizer.

When using the "fix client/md"_fix_client_md.html command, LAMMPS (as
the client code) does the timestepping and receives needed energy,
forces, and pressure values from the server code.

The format and content of the exchanged messages are explained here in
a conceptual sense.  Python-style pseudo code for the library calls to
the CSlib is shown, which performs the actual message exchange between
the two codes.  See the "CSlib website"_http://cslib.sandia.gov doc
pages for more details on the actual library syntax.  The "cs" object
in this pseudo code is a pointer to an instance of the CSlib.

See the src/MESSAGE/server_md.cpp and src/MESSAGE/fix_client_md.cpp
files for details on how LAMMPS uses these messages.  See the
examples/COUPLE/lammps_vasp/vasp_wrapper.py file for an example of how
a quantum code (VASP) can use these messages.

The following pseudo-code uses these values, defined as enums.

Define:

SETUP=1, STEP=2
DIM=1, PERIODICITY=2, ORIGIN=3, BOX=4, NATOMS=5, NTYPES=6, TYPES=7, COORDS=8, UNITS-9, CHARGE=10
FORCES=1, ENERGY=2, PRESSURE=3, ERROR=4 :pre

[Client sends 2 kinds of messages]:

# required fields: DIM, PERIODICTY, ORIGIN, BOX, NATOMS, NTYPES, TYPES, COORDS
# optional fields: UNITS, CHARGE :pre

cs->send(SETUP,nfields)        # msgID with nfields :pre

cs->pack_int(DIM,dim)          # dimension (2,3) of simulation
cs->pack(PERIODICITY,3,xyz)    # periodicity flags in 3 dims
cs->pack(ORIGIN,3,origin)      # lower-left corner of simulation box
cs->pack(BOX,9,box)            # 3 edge vectors of simulation box
cs->pack_int(NATOMS,natoms)    # total number of atoms
cs->pack_int(NTYPES,ntypes)    # number of atom types
cs->pack(TYPES,natoms,type)    # vector of per-atom types
cs->pack(COORDS,3*natoms,x)    # vector of 3N atom coords
cs->pack_string(UNITS,units)   # units = "lj", "real", "metal", etc
cs->pack(CHARGE,natoms,q)      # vector of per-atom charge :pre

# required fields: COORDS
# optional fields: ORIGIN, BOX :pre

cs->send(STEP,nfields)         # msgID with nfields :pre

cs->pack(COORDS,3*natoms,x)    # vector of 3N atom coords
cs->pack(ORIGIN,3,origin)      # lower-left corner of simulation box
cs->pack(BOX,9,box)            # 3 edge vectors of simulation box :pre

[Server replies to either kind of message]:

# required fields: FORCES, ENERGY, PRESSURE
# optional fields: ERROR :pre

cs->send(msgID,nfields)      # msgID with nfields
cs->pack(FORCES,3*Natoms,f)  # vector of 3N forces on atoms
cs->pack(ENERGY,1,poteng)    # total potential energy of system
cs->pack(PRESSURE,6,press)   # global pressure tensor (6-vector)
cs->pack_int(ERROR,flag)     # server had an error (e.g. DFT non-convergence) :pre

:line

The units for various quantities that are sent and received iva
messages are defined for atomic-scale simulations in the table below.
The client and server codes (including LAMMPS) can use internal units
different than these (e.g. "real units"_units.html in LAMMPS), so long
as they convert to these units for messaging.

COORDS, ORIGIN, BOX = Angstroms
CHARGE = multiple of electron charge (1.0 is a proton)
ENERGY = eV
FORCES = eV/Angstrom
PRESSURE = bars :ul

Note that these are "metal units"_units.html in LAMMPS.

If you wish to run LAMMPS in another its non-atomic units, e.g. "lj
units"_units.html, then the client and server should exchange a UNITS
message as indicated above, and both the client and server should
agree on the units for the data they exchange.

:line

[Restrictions:]

This command is part of the MESSAGE package.  It is only enabled if
LAMMPS was built with that package.  See the "Build
package"_Build_package.html doc page for more info.

[Related commands:]

"message"_message.html, "fix client/md"_fix_client_md.html

[Default:] none
