server md command¶
Examples¶
server md
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 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 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.
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 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 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_wrap.py or examples/COUPLE/lammps_nwchem/nwchem_wrap.py files for examples of how a quantum code (VASP or NWChem) 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
Client sends 2 kinds of messages:
# required fields: DIM, PERIODICTY, ORIGIN, BOX, NATOMS, NTYPES, TYPES, COORDS # optional fields: UNITS, CHARGE cs->send(SETUP,nfields) # msgID with nfields 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 # required fields: COORDS # optional fields: ORIGIN, BOX cs->send(STEP,nfields) # msgID with nfields 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
Server replies to either kind of message:
# required fields: FORCES, ENERGY, PRESSURE # optional fields: ERROR 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)
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 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
Note that these are metal units in LAMMPS.
If you wish to run LAMMPS in another its non-atomic units, e.g. lj units, 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.
Restrictions¶
This command is part of the MESSAGE package. It is only enabled if LAMMPS was built with that package. See the Build package page for more info.
Default¶
none