units and doc changes

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