From bc62002b1ca3f5fea860e95bab48346dc9f12ee4 Mon Sep 17 00:00:00 2001 From: Steve Plimpton Date: Fri, 31 Aug 2018 16:05:24 -0600 Subject: [PATCH] units and doc changes --- doc/src/fix_client_md.txt | 7 ++--- doc/src/server_mc.txt | 1 + doc/src/server_md.txt | 43 +++++++++++++++++++++++------- examples/COUPLE/README | 6 +++-- examples/COUPLE/lammps_mc/Makefile | 5 ++-- examples/COUPLE/lammps_mc/README | 34 +++++++++++++++++------ examples/COUPLE/lammps_vasp/README | 38 +++++++++++++++++++++++--- src/MESSAGE/fix_client_md.cpp | 19 ++++++++----- src/MESSAGE/server_md.cpp | 23 +++++++++------- 9 files changed, 132 insertions(+), 44 deletions(-) diff --git a/doc/src/fix_client_md.txt b/doc/src/fix_client_md.txt index 1712e1615e..5b62d5617d 100644 --- a/doc/src/fix_client_md.txt +++ b/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 diff --git a/doc/src/server_mc.txt b/doc/src/server_mc.txt index 3f7b3b8893..53ccfc8ecd 100644 --- a/doc/src/server_mc.txt +++ b/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. diff --git a/doc/src/server_md.txt b/doc/src/server_md.txt index 58dfa7f762..0db7bbe16b 100644 --- a/doc/src/server_md.txt +++ b/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 diff --git a/examples/COUPLE/README b/examples/COUPLE/README index 2d09ed7d4b..0e611befbd 100644 --- a/examples/COUPLE/README +++ b/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 diff --git a/examples/COUPLE/lammps_mc/Makefile b/examples/COUPLE/lammps_mc/Makefile index 821eb58134..c75bd08c73 100644 --- a/examples/COUPLE/lammps_mc/Makefile +++ b/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: diff --git a/examples/COUPLE/lammps_mc/README b/examples/COUPLE/lammps_mc/README index af4d86f92f..c201a6351c 100644 --- a/examples/COUPLE/lammps_mc/README +++ b/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 diff --git a/examples/COUPLE/lammps_vasp/README b/examples/COUPLE/lammps_vasp/README index b301bd779f..e942d52535 100644 --- a/examples/COUPLE/lammps_vasp/README +++ b/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 diff --git a/src/MESSAGE/fix_client_md.cpp b/src/MESSAGE/fix_client_md.cpp index bfcca4841b..dbaada9b50 100644 --- a/src/MESSAGE/fix_client_md.cpp +++ b/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 diff --git a/src/MESSAGE/server_md.cpp b/src/MESSAGE/server_md.cpp index e51571e972..aa771b7d46 100644 --- a/src/MESSAGE/server_md.cpp +++ b/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); }