units and doc changes

doc/src/fix_client_md.txt

@@ -44,10 +44,11 @@ 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.
+The protocol and "units"_units.html 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
+Note that when using LAMMPS as an MD client, 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

doc/src/server_mc.txt

@@ -37,6 +37,7 @@ 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
 See an example of how this command is used in
 examples/COUPLE/lammps_mc/in.server.
 

doc/src/server_md.txt

@@ -37,7 +37,8 @@ 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.
 
-See an example of how this command is used in
+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
@@ -45,13 +46,13 @@ 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 virial 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.
+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 virial
+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
@@ -70,7 +71,7 @@ The following pseudo-code uses these values, defined as enums.
 
 enum{SETUP=1,STEP};
 enum{DIM=1,PERIODICITY,ORIGIN,BOX,NATOMS,NTYPES,TYPES,COORDS,UNITS,CHARGE};
-enum{FORCES=1,ENERGY,VIRIAL,ERROR}; :pre
+enum{FORCES=1,ENERGY,PRESSURE,ERROR}; :pre
 
 [Client sends 2 kinds of messages]:
 
@@ -101,11 +102,35 @@ 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 :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(VIRIAL,6,virial)    # global virial tensor (6-vector)
-cs->pack(ERROR,6,virial)     # server had an error (e.g. DFT non-convergence) :pre
+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 meesaging.
+
+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
 

examples/COUPLE/README

@@ -34,11 +34,13 @@ These are the sub-directories included in this directory:
 
 simple		    simple example of driver code calling LAMMPS as a lib
 multiple	    example of driver code calling multiple instances of LAMMPS
-lammps_mc           client/server coupling Monte Carlo with LAMMPS MD
+lammps_mc           client/server coupling of Monte Carlo client 
+                      with LAMMPS server for energy evaluation
 lammps_quest	    MD with quantum forces, coupling to Quest DFT code
 lammps_spparks	    grain-growth Monte Carlo with strain via MD,
 		    coupling to SPPARKS kinetic MC code
-lammps_vasp         client/server coupling LAMMPS MD with VASP quantum DFT
+lammps_vasp         client/server coupling of LAMMPS client  with 
+                      VASP quantum DFT as server for quantum forces
 library		    collection of useful inter-code communication routines
 fortran             a simple wrapper on the LAMMPS library API that
  		      can be called from Fortran

examples/COUPLE/lammps_mc/Makefile

@@ -19,10 +19,9 @@ LINKFLAGS =	-g -O -L$(CSLIB)
 # targets
 
 mc:	$(OBJ)
-#	this line if built the CSlib within lib/message with ZMQ support
-#       note this is using the serial (no-mpi) version of the CSlib
+#	first line if built the CSlib within lib/message with ZMQ support
+#	second line if built the CSlib without ZMQ support
 	$(LINK) $(LINKFLAGS) $(OBJ) -lcsnompi -lzmq -o mc
-#	this line if built the CSlib without ZMQ support
 #	$(LINK) $(LINKFLAGS) $(OBJ) -lcsnompi -o mc
 
 clean:

examples/COUPLE/lammps_mc/README

@@ -22,25 +22,43 @@ change, and to run dynamics between MC moves.
 
 ----------------
 
-Build LAMMPS and the MC client code
+Build LAMMPS with its MESSAGE package installed:
 
-First, build LAMMPS with its MESSAGE package installed:
+See the Build extras doc page and its MESSAGE package
+section for details.
+
+CMake:
+
+-D PKG_MESSAGE=yes      # include the MESSAGE package
+-D MESSAGE_ZMQ=value    # build with ZeroMQ support, value = no (default) or yes
+
+Traditional make:
 
 % cd lammps/lib/message
 % python Install.py -m -z       # build CSlib with MPI and ZMQ support
-% python Install.py -s -z       # also build serial lib and ZMQ support
 % cd lammps/src
 % make yes-message
 % make mpi
 
 You can leave off the -z if you do not have ZMQ on your system.
 
-Next build the MC client code, which will link with the serial CSlib.
+----------------
 
-First edit the Makefile in this dir.  The CSLIB variable should be the
-path to where the LAMMPS lib/message dir is on your system.  If you
-built the CSlib without ZMQ support you will also need to
-comment/uncomment two lines.  Then you can just type 
+Build the MC client code
+
+The source files for the MC code are in this dir.  It links with the
+CSlib library in lib/message/cslib.
+
+You must first build the CSlib in serial mode, e.g.
+
+% cd lammps/lib/message/cslib/src
+% make lib            # build serial and parallel lib with ZMQ support
+% make lib zmq=no     # build serial and parallel lib without ZMQ support
+
+Then edit the Makefile in this dir.  The CSLIB variable should be the
+path to where the LAMMPS lib/message/cslib/src dir is on your system.
+If you built the CSlib without ZMQ support you will also need to
+comment/uncomment one line.  Then you can just type
 
 % make
 

examples/COUPLE/lammps_vasp/README

@@ -24,6 +24,16 @@ MPI.
 
 Build LAMMPS with its MESSAGE package installed:
 
+See the Build extras doc page and its MESSAGE package
+section for details.
+
+CMake:
+
+-D PKG_MESSAGE=yes      # include the MESSAGE package
+-D MESSAGE_ZMQ=value    # build with ZeroMQ support, value = no (default) or yes
+
+Traditional make:
+
 cd lammps/lib/message
 python Install.py -m -z       # build CSlib with MPI and ZMQ support
 cd lammps/src
@@ -34,6 +44,27 @@ You can leave off the -z if you do not have ZMQ on your system.
 
 ----------------
 
+Build the CSlib in a form usable by the vasp_wrapper.py script:
+
+% cd lammps/lib/message/cslib/src
+% make shlib            # build serial and parallel shared lib with ZMQ support
+% make shlib zmq=no     # build serial and parallel shared lib w/out ZMQ support
+
+This will make a shared library versions of the CSlib, which Python
+requires.  Python must be able to find both the cslib.py script and
+the libcsnompi.so library in your lammps/lib/message/cslib/src
+directory.  If it is not able to do this, you will get an error when
+you run vasp_wrapper.py.
+
+You can do this by augmenting two environment variables, either
+from the command line, or in your shell start-up script.
+Here is the sample syntax for the csh or tcsh shells:
+
+setenv PYTHONPATH ${PYTHONPATH}:/home/sjplimp/lammps/lib/message/cslib/src
+setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/lib/message/cslib/src
+
+----------------
+
 Prepare to use VASP and the vasp_wrapper.py script
 
 You can run the vasp_wrap.py script as-is to test that the coupling
@@ -68,13 +99,14 @@ POSCAR_W matches in.client.W.
 
 Once you run VASP yourself, the vasprun.xml file will be overwritten.
 
-NOTE: explain how vasp_wrapper.py finds the cslib.py wrapper on the
-CSlib to import.
-
 ----------------
 
 To run in client/server mode:
 
+NOTE: The vasp_wrap.py script must be run with Python version 2, not
+3.  This is because it used the CSlib python wrapper, which only
+supports version 2.  We plan to upgrade CSlib to support Python 3.
+
 Both the client (LAMMPS) and server (vasp_wrap.py) must use the same
 messaging mode, namely file or zmq.  This is an argument to the
 vasp_wrap.py code; it can be selected by setting the "mode" variable

src/MESSAGE/fix_client_md.cpp

@@ -32,7 +32,7 @@ using namespace FixConst;
 enum{OTHER,REAL,METAL};
 enum{SETUP=1,STEP};
 enum{DIM=1,PERIODICITY,ORIGIN,BOX,NATOMS,NTYPES,TYPES,COORDS,UNITS,CHARGE};
-enum{FORCES=1,ENERGY,VIRIAL,ERROR};
+enum{FORCES=1,ENERGY,PRESSURE,ERROR};
 
 /* ---------------------------------------------------------------------- */
 
@@ -67,10 +67,10 @@ FixClientMD::FixClientMD(LAMMPS *lmp, int narg, char **arg) :
   // otherwise not needed
   // message received in METAL units, convert to local REAL units
 
-  fconvert = econvert = vconvert = 1.0;
+  fconvert = econvert = pconvert = 1.0;
   if (units == REAL) {
-    fconvert = econvert = 23.06035;
-    vconvert = 0.986923;
+    fconvert = econvert = 23.06035;    // eV -> Kcal/mole
+    pconvert = 0.986923;               // bars -> atmospheres
   }
 }
 
@@ -274,7 +274,7 @@ void FixClientMD::pack_box()
 
 /* ----------------------------------------------------------------------
    receive message from server
-   required fields: FORCES, ENERGY, VIRIAL
+   required fields: FORCES, ENERGY, PRESSURE
    optional field: ERROR
 ------------------------------------------------------------------------- */
 
@@ -307,9 +307,14 @@ void FixClientMD::receive_fev(int vflag)
   eng = econvert * cs->unpack_double(ENERGY);
   
   if (vflag) {
-    double *v = (double *) cs->unpack(VIRIAL);
+    double *v = (double *) cs->unpack(PRESSURE);
+
+    double nktv2p = force->nktv2p;
+    double volume = domain->xprd * domain->yprd * domain->zprd;
+    double factor = inv_nprocs * pconvert * volume / nktv2p;
+
     for (int i = 0; i < 6; i++)
-      virial[i] = inv_nprocs * vconvert * v[i];
+      virial[i] = factor * v[i];
   }
 
   // error return

src/MESSAGE/server_md.cpp

@@ -37,7 +37,7 @@ using namespace CSLIB_NS;
 enum{OTHER,REAL,METAL};
 enum{SETUP=1,STEP};
 enum{DIM=1,PERIODICITY,ORIGIN,BOX,NATOMS,NTYPES,TYPES,COORDS,UNITS,CHARGE};
-enum{FORCES=1,ENERGY,VIRIAL,ERROR};
+enum{FORCES=1,ENERGY,PRESSURE,ERROR};
 
 /* ---------------------------------------------------------------------- */
 
@@ -58,10 +58,10 @@ ServerMD::ServerMD(LAMMPS *lmp) : Pointers(lmp)
   // otherwise not needed
   // local computation in REAL units, send message in METAL units
 
-  fconvert = econvert = vconvert = 1.0;
+  fconvert = econvert = pconvert = 1.0;
   if (units == REAL) {
-    fconvert = econvert = 1.0 / 23.06035;
-    vconvert = 1.0 / 0.986923;
+    fconvert = econvert = 1.0 / 23.06035;    // Kcal/mole -> eV
+    pconvert = 1.0 / 0.986923;               // atmospheres -> bars
   }
 
   fcopy = NULL;
@@ -339,7 +339,7 @@ void ServerMD::box_change(double *origin, double *box)
 /* ----------------------------------------------------------------------
    return message with forces, energy, pressure tensor
    pressure tensor should be just pair and KSpace contributions
-   required fields: FORCES, ENERGY, VIRIAL
+   required fields: FORCES, ENERGY, PRESSURE
    optional field: ERROR (not ever sending)
 ------------------------------------------------------------------------- */
 
@@ -374,11 +374,16 @@ void ServerMD::send_fev(int msgID)
   double v[6],vall[6];
   for (int i = 0; i < 6; i++)
     v[i] = force->pair->virial[i];
+  MPI_Allreduce(&v,&vall,6,MPI_DOUBLE,MPI_SUM,world);
+
   if (force->kspace)
     for (int i = 0; i < 6; i++)
-      v[i] += force->kspace->virial[i];
+      vall[i] += force->kspace->virial[i];
 
-  for (int i = 0; i < 6; i++) v[i] *= vconvert;
-  MPI_Allreduce(&v,&vall,6,MPI_DOUBLE,MPI_SUM,world);
-  cs->pack(VIRIAL,4,6,vall);
+  double nktv2p = force->nktv2p;
+  double volume = domain->xprd * domain->yprd * domain->zprd;
+  double factor = pconvert / volume * nktv2p;
+  for (int i = 0; i < 6; i++) vall[i] *= factor;
+
+  cs->pack(PRESSURE,4,6,vall);
 }