diff --git a/doc/src/Commands_all.rst b/doc/src/Commands_all.rst index b43fd0ed56..c708228be7 100644 --- a/doc/src/Commands_all.rst +++ b/doc/src/Commands_all.rst @@ -67,6 +67,7 @@ An alphabetic list of all general LAMMPS commands. * :doc:`lattice ` * :doc:`log ` * :doc:`mass ` + * :doc:`mdi/engine ` * :doc:`message ` * :doc:`minimize ` * :doc:`min_modify ` diff --git a/doc/src/Commands_fix.rst b/doc/src/Commands_fix.rst index 65f4f542cd..0dbe8f5bec 100644 --- a/doc/src/Commands_fix.rst +++ b/doc/src/Commands_fix.rst @@ -101,6 +101,7 @@ OPT. * :doc:`lb/viscous ` * :doc:`lineforce ` * :doc:`manifoldforce ` + * :doc:`mdi/engine ` * :doc:`meso/move ` * :doc:`momentum (k) ` * :doc:`momentum/chunk ` diff --git a/doc/src/Howto_mdi.rst b/doc/src/Howto_mdi.rst index c21d10c2e1..8e13563b37 100644 --- a/doc/src/Howto_mdi.rst +++ b/doc/src/Howto_mdi.rst @@ -19,20 +19,20 @@ developed by the `Molecular Sciences Software Institute (MolSSI) Alternate methods for code coupling with LAMMPS are described on the :doc:`Howto couple ` doc page. -Some advantages of client/server coupling are that the two codes can -run as stand-alone executables; they need not be linked together. -Thus neither code needs to have a library interface. This also makes -it easy to run the two codes on different numbers of processors. If a -message protocol (format and content) is defined for a particular kind -of simulation, then in principle any code whcih implements the -client-side protocol can be used in tandem with any code which -implements the server-side protocol. Neither code needs to know what -specific other code it is working with. +Some advantages of client/server coupling are that the two codes can run +as stand-alone executables; they need not be linked together. Thus +neither code needs to have a library interface. This also makes it easy +to run the two codes on different numbers of processors. If a message +protocol (format and content) is defined for a particular kind of +simulation, then in principle any code which implements the client-side +protocol can be used in tandem with any code which implements the +server-side protocol. Neither code needs to know what specific other +code it is working with. -In MDI lingo, a client code is the "driver", and a server code is an -"engine". One driver code can communicate with one or more instances -of one or more engine codes. Driver and engine codes can be written -in any language: C, C++, Fortran, Python, etc. +In MDI nomenclature, a client code is the "driver", and a server code is +an "engine". One driver code can communicate with one or more instances +of one or more engine codes. Driver and engine codes can be written in +any language: C, C++, Fortran, Python, etc. In addition to allowing driver and engine(s) running to run as stand-alone executables, MDI also enables a server code to be a @@ -49,47 +49,48 @@ engine instances and re-instantiate them. The way that a driver communicates with an engine is by making MDI_Send() and MDI_Recv() calls, which are conceptually similar to MPI_Send() and MPI_Recv() calls. Each send or receive has a string -which identifies the command name, and optinally some data, which can +which identifies the command name, and optionally some data, which can be a single value or vector of values of any data type. Inside the -MDI library, data is exchanged bewteen the driver and engine via MPI +MDI library, data is exchanged between the driver and engine via MPI calls or sockets. This a run-time choice by the user. ------------- -As an example, LAMMPS and Quantum Espresso (QE, a quantum DFT code), -can work together via the MDI library to perform an ab initio MD -(AIMD) simulation, where LAMMPS runs an MD simulation and sends a -message each timestep to QE asking it to compute quantum forces on the -current configuration of atoms. Here is how the 2 codes are launched -to communicate by MPI: +As an example, LAMMPS and the ``pw.x`` command from Quantum Espresso (a +suite of quantum DFT codes), can work together via the MDI library to +perform an ab initio MD (AIMD) simulation, where LAMMPS runs an MD +simulation and sends a message each timestep to ``pw.x`` asking it to +compute quantum forces on the current configuration of atoms. Here is +how the 2 codes are launched to communicate by MPI: .. code-block:: bash -% mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method MPI" < in.aimd : -np 16 qe -mdi "-role ENGINE -name e -method MPI" +% mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method MPI" \ + -in in.aimd : -np 16 pw.x -in qe.in -mdi "-role ENGINE -name e -method MPI" -In this case LAMMPS runs on 2 processors (MPI tasks), QE runs on 16 +In this case LAMMPS runs on 2 processors (MPI tasks), ``pw.x`` runs on 16 processors. Here is how the 2 codes are launched to communicate by sockets: .. code-block:: bash -% mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method TCP -port 8021" < in.aimd -% mpirun -np 16 qe -mdi "-role ENGINE -name e -method TCP -port 8021 -hostname localhost" +% mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method TCP -port 8021" -in in.aimd +% mpirun -np 16 pw.x -in qe.in -mdi "-role ENGINE -name e -method TCP -port 8021 -hostname localhost" These commands could be issued in different windows on a desktop machine. Or in the same window, if the first command is ended with "&" so as to run in the background. If "localhost" is replaced by an -IP address, QE could be run on another machine on the same network, or +IP address, ``pw.x`` could be run on another machine on the same network, or even on another machine across the country. -After both codes initialize themselves to model the same system, this -is what occurs each timestep: +After both codes initialize themselves to model the same system, this is +what occurs each timestep: -* LAMMPS send a ">COORDS" message to QE with a 3*N vector of current atom coords -* QE receives the message/coords and computes quantum forces on all the atoms -* LAMMPS send a "COORDS" message to ``pw.x`` with a 3*N vector of current atom coords +* ``pw.x`` receives the message/coords and computes quantum forces on all the atoms +* LAMMPS send a "` command. This will put LAMMPS into +:doc:`mdi/engine ` command. This will put LAMMPS into engine mode where it waits for messages and data from the driver. When the driver sends an "EXIT" command, LAMMPS will exit engine mode and the input script will continue. @@ -118,14 +119,14 @@ Upon receiving the "EXIT" command, LAMMPS will exit engine mode and the input script will continue. After finishing execution of the input script, the instance of LAMMPS will be destroyed. -LAMMPS supports the full set of MD-appropriate engine commands -defined by the MDI library. See the :doc:`mdi_engine ` -doc page for a list of these. +LAMMPS supports the full set of MD-appropriate engine commands defined +by the MDI library. See the :doc:`mdi/engine ` doc page for +a list of these. -If those commands are not sufficient for a user-developed driver to -use LAMMPS as an engine, then new commands can easily be added. See -these two files which implement the definition of MDI commands and the -logic for responding to them: +If those commands are not sufficient for a user-developed driver to use +LAMMPS as an engine, then new commands can be easily added. See these +two files which implement the definition of MDI commands and the logic +for responding to them: * src/MDI/mdi_engine.cpp * src/MDI/fix_mdi_engine.cpp diff --git a/doc/src/Packages_details.rst b/doc/src/Packages_details.rst index d6f40b3228..8a3602674f 100644 --- a/doc/src/Packages_details.rst +++ b/doc/src/Packages_details.rst @@ -82,6 +82,7 @@ page gives those details. * :ref:`USER-INTEL ` * :ref:`USER-LB ` * :ref:`USER-MANIFOLD ` + * :ref:`USER-MDI ` * :ref:`USER-MEAMC ` * :ref:`USER-MESODPD ` * :ref:`USER-MESONT ` @@ -1791,6 +1792,28 @@ Waltham, MA, USA) ---------- +.. _PKG-USER-MDI: + +USER-MDI package +---------------- + +**Contents:** + +A LAMMPS command and fix to allow client-server coupling of LAMMPS to +other atomic or molecular simulation codes via the `MolSSI Driver Interface +(MDI) library `_. + +**Author:** Taylor Barnes - MolSSI, taylor.a.barnes at gmail.com + +**Supporting info:** + +* src/USER-MDI/README +* :doc:`mdi/engine ` +* :doc:`fix mdi/engine ` +* examples/USER/mdi + +---------- + .. _PKG-USER-MEAMC: USER-MEAMC package diff --git a/doc/src/Packages_user.rst b/doc/src/Packages_user.rst index 23325e8357..f14d449dfd 100644 --- a/doc/src/Packages_user.rst +++ b/doc/src/Packages_user.rst @@ -65,6 +65,8 @@ package: +------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+ | :ref:`USER-MANIFOLD ` | motion on 2d surfaces | :doc:`fix manifoldforce ` | USER/manifold | no | +------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+ +| :ref:`USER-MDI ` | client-server coupling | :doc:`MDI Howto ` | USER/mdi | ext | ++------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+ | :ref:`USER-MEAMC ` | modified EAM potential (C++) | :doc:`pair_style meam/c ` | meamc | no | +------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+ | :ref:`USER-MESODPD ` | mesoscale DPD models | :doc:`pair_style edpd ` | USER/mesodpd | no | diff --git a/doc/src/comm_modify.rst b/doc/src/comm_modify.rst index 4e9e6325c1..27b370c941 100644 --- a/doc/src/comm_modify.rst +++ b/doc/src/comm_modify.rst @@ -34,7 +34,7 @@ Examples comm_modify mode multi reduce/multi comm_modify mode multi group solvent - comm_modift mode multi cutoff/multi 1 10.0 cutoff/multi 2*4 15.0 + comm_modify mode multi cutoff/multi 1 10.0 cutoff/multi 2*4 15.0 comm_modify vel yes comm_modify mode single cutoff 5.0 vel yes comm_modify cutoff/multi * 0.0 @@ -75,8 +75,8 @@ communicated. in *multi/old*, a similar technique is used but atoms are grouped by atom type. See the :doc:`neighbor multi ` and :doc:`neighbor multi/old ` commands for neighbor list construction options that may also be beneficial for -simulations of this kind. The *multi* communiction mode is only compatable -with the *multi* neighbor style. The *multi/old* communication mode is compatble +simulations of this kind. The *multi* communication mode is only compatible +with the *multi* neighbor style. The *multi/old* communication mode is comparable with both the *multi* and *multi/old* neighbor styles. The *cutoff* keyword allows you to extend the ghost cutoff distance @@ -97,18 +97,18 @@ warning is printed, if this bond based estimate is larger than the communication cutoff used. The *cutoff/multi* option is equivalent to *cutoff*\ , but applies to -communication mode *multi* instead. Since the communication -cutoffs are determined per atom collections, a collection specifier is needed and -cutoff for one or multiple collections can be extended. Also ranges of collections -using the usual asterisk notation can be given. -Collections are indexed from 1 to N where N is the total number of collections. +communication mode *multi* instead. Since the communication cutoffs are +determined per atom collections, a collection specifier is needed and +cutoff for one or multiple collections can be extended. Also ranges of +collections using the usual asterisk notation can be given. Collections +are indexed from 1 to N where N is the total number of collections. Note that the arguments for *cutoff/multi* are parsed right before each -simulation to account for potential changes in the number of collections. -Custom cutoffs are preserved between runs but if collections are redefined, -one may want to respecify communication cutoffs. -For granular pair styles,the default cutoff is set to the sum of the -current maximum atomic radii for each collection. -The *cutoff/multi/old* option is similar to *cutoff/multi* except it +simulation to account for potential changes in the number of +collections. Custom cutoffs are preserved between runs but if +collections are redefined, one may want to re-specify the communication +cutoffs. For granular pair styles,the default cutoff is set to the sum +of the current maximum atomic radii for each collection. The +*cutoff/multi/old* option is similar to *cutoff/multi* except it operates on atom types as opposed to collections. The *reduce/multi* option applies to *multi* and sets the communication @@ -147,7 +147,7 @@ ghost cutoff should be set. In the last scenario, a :doc:`fix ` or :doc:`compute ` or :doc:`pairwise potential ` needs to calculate with ghost atoms beyond the normal pairwise cutoff for some computation it -performs (e.g. locate neighbors of ghost atoms in a multibody pair +performs (e.g. locate neighbors of ghost atoms in a manybody pair potential). Setting the ghost cutoff appropriately can insure it will find the needed atoms. diff --git a/doc/src/commands_list.rst b/doc/src/commands_list.rst index e30d5c52dc..75affe7ce6 100644 --- a/doc/src/commands_list.rst +++ b/doc/src/commands_list.rst @@ -59,6 +59,7 @@ Commands lattice log mass + mdi_engine message min_modify min_spin diff --git a/doc/src/fix_mdi_engine.rst b/doc/src/fix_mdi_engine.rst index 431abfa737..a2f25780f5 100644 --- a/doc/src/fix_mdi_engine.rst +++ b/doc/src/fix_mdi_engine.rst @@ -1,7 +1,7 @@ .. index:: fix move fix mdi/engine command -================ +====================== Syntax """""" @@ -23,22 +23,22 @@ Examples Description """"""""""" -This fix is used along with the :doc:`mdi_engine ` command +This fix is used along with the :doc:`mdi/engine ` command to enable LAMMPS to use the `MDI Library `_ to run as an MDI engine. The fix provides hooks that enable MDI driver codes to communicate with LAMMPS at various points within a LAMMPS timestep. It is not generally necessary to add this fix to a LAMMPS input file, -even when using the :doc:`mdi_engine ` command. If the -:doc:`mdi_engine ` command is executed and this fix is not +even when using the :doc:`mdi/engine ` command. If the +:doc:`mdi/engine ` command is executed and this fix is not present, it will automatically be added and applied as a new fix for all atoms for the duration of the command. Thus it is only necessary to add this fix to an input file when you want to modify the group-ID or the ordering of this fix relative to other fixes in the input script. For more information about running LAMMPS as an MDI engine, see the -:doc:`mdi_engine ` command and the :doc:`Howto mdi +:doc:`mdi/engine ` command and the :doc:`Howto mdi ` doc page. Restrictions @@ -51,7 +51,7 @@ LAMMPS was built with that package. See the :doc:`Build package Related commands """""""""""""""" -:doc:`mdi_engine ` +:doc:`mdi/engine ` Default """"""" diff --git a/doc/src/mdi_engine.rst b/doc/src/mdi_engine.rst index 195165e62b..927a518f4e 100644 --- a/doc/src/mdi_engine.rst +++ b/doc/src/mdi_engine.rst @@ -1,7 +1,7 @@ .. index:: mdi_engine mdi_engine command -=============== +================== Syntax """""" @@ -41,10 +41,9 @@ To act as a MD-based MDI engine, this is the list of MDI commands from a driver code which LAMMPS currently recognizes. See more details about these commands in the `MDI library documentation `_ - -NOTE: Taylor - is this the best link for this info? Can we flesh this -out with the full list of supported commands? Maybe the distiniction -of what "node" the commands refer to is not needed in this table? +.. NOTE: Taylor - is this the best link for this info? Can we flesh this +.. out with the full list of supported commands? Maybe the distinction +.. of what "node" the commands refer to is not needed in this table? .. list-table:: :widths: 20 80 @@ -53,7 +52,7 @@ of what "node" the commands refer to is not needed in this table? * - Command name - Action * - >NATOMS - - Driver sends the number of atoms in the ststem + - Driver sends the number of atoms in the system * - find_fix_by_style("mdi/engine"); bool added_mdi_engine_fix = false; @@ -192,13 +192,13 @@ void MDIEngine::command(int narg, char **arg) // check that LAMMPS is setup as a compatible MDI engine - if (narg > 0) error->all(FLERR,"Illegal mdi_engine command"); + if (narg > 0) error->all(FLERR,"Illegal mdi/engine command"); if (atom->tag_enable == 0) - error->all(FLERR,"Cannot use mdi_engine without atom IDs"); + error->all(FLERR,"Cannot use mdi/engine without atom IDs"); if (atom->tag_consecutive() == 0) - error->all(FLERR,"mdi_engine requires consecutive atom IDs"); + error->all(FLERR,"mdi/engine requires consecutive atom IDs"); // endless engine loop, responding to driver commands @@ -206,7 +206,7 @@ void MDIEngine::command(int narg, char **arg) while (1) { - // mdi_engine command only recognizes three nodes + // mdi/engine command only recognizes three nodes // DEFAULT, INIT_MD, INIT_OPTG command = mdi_fix->engine_mode("@DEFAULT"); @@ -230,7 +230,7 @@ void MDIEngine::command(int narg, char **arg) "invalid command: {}",command)); } - // remove mdi/engine fix that mdi_engine instantiated + // remove mdi/engine fix that mdi/engine instantiated if (added_mdi_engine_fix) modify->delete_fix("MDI_ENGINE_INTERNAL"); } diff --git a/src/USER-MDI/mdi_engine.h b/src/USER-MDI/mdi_engine.h index fb0216b667..370e1070a6 100644 --- a/src/USER-MDI/mdi_engine.h +++ b/src/USER-MDI/mdi_engine.h @@ -13,7 +13,7 @@ #ifdef COMMAND_CLASS -CommandStyle(mdi_engine,MDIEngine) +CommandStyle(mdi/engine,MDIEngine) #else diff --git a/src/library.cpp b/src/library.cpp index 857883c0d9..e588bc676d 100644 --- a/src/library.cpp +++ b/src/library.cpp @@ -4991,7 +4991,7 @@ when LAMMPS is run as a plugin, and should not otherwise be used. The function initializes MDI, then creates and initializes an instance of LAMMPS. The command-line arguments ``argc`` and ``argv`` used to initialize LAMMPS are recieved from MDI. The LAMMPS instance runs an -input file, which must include the ``mdi_engine`` command; when LAMMPS +input file, which must include the ``mdi/engine`` command; when LAMMPS executes this command, it will begin listening for commands from the driver. The name of the input file is obtained from the ``-in`` command-line argument, which must be provided by the MDI driver.