Use "mdi/engine" consistenty, complete integration in manual, spelling

doc/src/Commands_all.rst

@@ -67,6 +67,7 @@ An alphabetic list of all general LAMMPS commands.
    * :doc:`lattice <lattice>`
    * :doc:`log <log>`
    * :doc:`mass <mass>`
+   * :doc:`mdi/engine <mdi_engine>`
    * :doc:`message <message>`
    * :doc:`minimize <minimize>`
    * :doc:`min_modify <min_modify>`

doc/src/Commands_fix.rst

@@ -101,6 +101,7 @@ OPT.
    * :doc:`lb/viscous <fix_lb_viscous>`
    * :doc:`lineforce <fix_lineforce>`
    * :doc:`manifoldforce <fix_manifoldforce>`
+   * :doc:`mdi/engine <fix_mdi_engine>`
    * :doc:`meso/move <fix_meso_move>`
    * :doc:`momentum (k) <fix_momentum>`
    * :doc:`momentum/chunk <fix_momentum>`

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 <Howto_couple>` doc page.
 
-Some advantages of client/server coupling are that the two codes can
+Some advantages of client/server coupling are that the two codes can run
-run as stand-alone executables; they need not be linked together.
+as stand-alone executables; they need not be linked together.  Thus
-Thus neither code needs to have a library interface.  This also makes
+neither code needs to have a library interface.  This also makes it easy
-it easy to run the two codes on different numbers of processors.  If a
+to run the two codes on different numbers of processors.  If a message
-message protocol (format and content) is defined for a particular kind
+protocol (format and content) is defined for a particular kind of
-of simulation, then in principle any code whcih implements the
+simulation, then in principle any code which implements the client-side
-client-side protocol can be used in tandem with any code which
+protocol can be used in tandem with any code which implements the
-implements the server-side protocol.  Neither code needs to know what
+server-side protocol.  Neither code needs to know what specific other
-specific other code it is working with.
+code it is working with.
 
-In MDI lingo, a client code is the "driver", and a server code is an
+In MDI nomenclature, a client code is the "driver", and a server code is
-"engine".  One driver code can communicate with one or more instances
+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
+of one or more engine codes.  Driver and engine codes can be written in
-in any language: C, C++, Fortran, Python, etc.
+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),
+As an example, LAMMPS and the ``pw.x`` command from Quantum Espresso (a
-can work together via the MDI library to perform an ab initio MD
+suite of quantum DFT codes), can work together via the MDI library to
-(AIMD) simulation, where LAMMPS runs an MD simulation and sends a
+perform an ab initio MD (AIMD) simulation, where LAMMPS runs an MD
-message each timestep to QE asking it to compute quantum forces on the
+simulation and sends a message each timestep to ``pw.x`` asking it to
-current configuration of atoms.  Here is how the 2 codes are launched
+compute quantum forces on the current configuration of atoms.  Here is
-to communicate by MPI:
+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 2 lmp_mpi -mdi "-role DRIVER -name d -method TCP -port 8021" -in in.aimd
-% mpirun -np 16 qe -mdi "-role ENGINE -name e -method TCP -port 8021 -hostname localhost"
+% 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
+After both codes initialize themselves to model the same system, this is
-is what occurs each timestep:
+what occurs each timestep:
 
-* LAMMPS send a ">COORDS" message to QE with a 3*N vector of current atom coords
+* LAMMPS send a ">COORDS" message to ``pw.x`` with a 3*N vector of current atom coords
-* QE receives the message/coords and computes quantum forces on all the atoms
+* ``pw.x`` receives the message/coords and computes quantum forces on all the atoms
-* LAMMPS send a "<FORCES" message to QE and waits for the result
+* LAMMPS send a "<FORCES" message to ``pw.x`` and waits for the result
-* QE receives the message (after its computation finishes) and sends a 3*N vector of forces
+* ``pw.x`` receives the message (after its computation finishes) and sends a 3*N vector of forces
 * LAMMPS receives the forces and time integrates to complete a single timestep
 
 -------------
@@ -107,7 +108,7 @@ instructions on how to run the examples.
 
 If LAMMPS is used as a stand-alone engine it should set up the system
 it will be modeling in its input script, then invoke the
-:doc:`mdi_engine <mdi_engine>` command.  This will put LAMMPS into
+:doc:`mdi/engine <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
+LAMMPS supports the full set of MD-appropriate engine commands defined
-defined by the MDI library.  See the :doc:`mdi_engine <mdi_engine>`
+by the MDI library.  See the :doc:`mdi/engine <mdi_engine>` doc page for
-doc page for a list of these.
+a list of these.
 
-If those commands are not sufficient for a user-developed driver to
+If those commands are not sufficient for a user-developed driver to use
-use LAMMPS as an engine, then new commands can easily be added.  See
+LAMMPS as an engine, then new commands can be easily added.  See these
-these two files which implement the definition of MDI commands and the
+two files which implement the definition of MDI commands and the logic
-logic for responding to them:
+for responding to them:
 
 * src/MDI/mdi_engine.cpp
 * src/MDI/fix_mdi_engine.cpp

doc/src/Packages_details.rst

@@ -82,6 +82,7 @@ page gives those details.
    * :ref:`USER-INTEL <PKG-USER-INTEL>`
    * :ref:`USER-LB <PKG-USER-LB>`
    * :ref:`USER-MANIFOLD <PKG-USER-MANIFOLD>`
+   * :ref:`USER-MDI <PKG-USER-MDI>`
    * :ref:`USER-MEAMC <PKG-USER-MEAMC>`
    * :ref:`USER-MESODPD <PKG-USER-MESODPD>`
    * :ref:`USER-MESONT <PKG-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 <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_. 
+
+**Author:** Taylor Barnes - MolSSI, taylor.a.barnes at gmail.com
+
+**Supporting info:**
+
+* src/USER-MDI/README
+* :doc:`mdi/engine <mdi_engine>`
+* :doc:`fix mdi/engine <fix_mdi_engine>`
+* examples/USER/mdi
+
+----------
+
 .. _PKG-USER-MEAMC:
 
 USER-MEAMC package

doc/src/Packages_user.rst

@@ -65,6 +65,8 @@ package:
 +------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
 | :ref:`USER-MANIFOLD <PKG-USER-MANIFOLD>`       | motion on 2d surfaces                                           | :doc:`fix manifoldforce <fix_manifoldforce>`                                  | USER/manifold                                        | no      |
 +------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
+| :ref:`USER-MDI <PKG-USER-MDI>`                 | client-server coupling                                          | :doc:`MDI Howto <Howto_mdi>`                                                  | USER/mdi                                             | ext     |
++------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
 | :ref:`USER-MEAMC <PKG-USER-MEAMC>`             | modified EAM potential (C++)                                    | :doc:`pair_style meam/c <pair_meamc>`                                         | meamc                                                | no      |
 +------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
 | :ref:`USER-MESODPD <PKG-USER-MESODPD>`         | mesoscale DPD models                                            | :doc:`pair_style edpd <pair_mesodpd>`                                         | USER/mesodpd                                         | no      |

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 <neighbor>`  and
 :doc:`neighbor multi/old <neighbor>` commands for
 neighbor list construction options that may also be beneficial for
-simulations of this kind. The *multi* communiction mode is only compatable
+simulations of this kind. The *multi* communication mode is only compatible
-with the *multi* neighbor style. The *multi/old* communication mode is compatble
+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
+communication mode *multi* instead. Since the communication cutoffs are
-cutoffs are determined per atom collections, a collection specifier is needed and
+determined per atom collections, a collection specifier is needed and
-cutoff for one or multiple collections can be extended. Also ranges of collections
+cutoff for one or multiple collections can be extended. Also ranges of
-using the usual asterisk notation can be given.
+collections using the usual asterisk notation can be given.  Collections
-Collections are indexed from 1 to N where N is the total number of 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.
+simulation to account for potential changes in the number of
-Custom cutoffs are preserved between runs but if collections are redefined,
+collections.  Custom cutoffs are preserved between runs but if
-one may want to respecify communication cutoffs.
+collections are redefined, one may want to re-specify the communication
-For granular pair styles,the default cutoff is set to the sum of the
+cutoffs.  For granular pair styles,the default cutoff is set to the sum
-current maximum atomic radii for each collection.
+of the current maximum atomic radii for each collection.  The
-The *cutoff/multi/old* option is similar to *cutoff/multi* except it
+*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 <fix>` or :doc:`compute <compute>` or
 :doc:`pairwise potential <pair_style>` 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.
 

doc/src/commands_list.rst

@@ -59,6 +59,7 @@ Commands
    lattice
    log
    mass
+   mdi_engine
    message
    min_modify
    min_spin

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 <mdi_engine>` command
+This fix is used along with the :doc:`mdi/engine <mdi_engine>` command
 to enable LAMMPS to use the `MDI Library
 <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_ 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 <mdi_engine>` command.  If the
+even when using the :doc:`mdi/engine <mdi_engine>` command.  If the
-:doc:`mdi_engine <mdi_engine>` command is executed and this fix is not
+:doc:`mdi/engine <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 <mdi_engine>` command and the :doc:`Howto mdi
+:doc:`mdi/engine <mdi_engine>` command and the :doc:`Howto mdi
 <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 <mdi_engine>`
+:doc:`mdi/engine <mdi_engine>`
 
 Default
 """""""

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
 <https://molssi-mdi.github.io/MDI_Library/html/mdi_standard.html>`_
-
+.. NOTE: Taylor - is this the best link for this info?  Can we flesh this
-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
-out with the full list of supported commands?  Maybe the distiniction
+.. of what "node" the commands refer to is not needed in this table?
-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
    * - <NATOMS
      - Driver requests the number of atoms in the system
    * - <COORDS

doc/src/neigh_modify.rst

@@ -221,14 +221,15 @@ from 1 to n (inclusive).  A trailing asterisk means all types from n to M
 (inclusive).  A middle asterisk means all types from m to n (inclusive).
 Note that all atom types must be included in exactly one of the N collections.
 
-The *collection/interval* option provides a similar capability.
+The *collection/interval* option provides a similar capability.  This
-This command allows a user to define collections by specifying a
+command allows a user to define collections by specifying a series of
-series of cutoff intervals. LAMMPS will automatically sort atoms into these intervals
+cutoff intervals. LAMMPS will automatically sort atoms into these
-based on their type-dependent cutoffs or their finite size.
+intervals based on their type-dependent cutoffs or their finite size.
-You must first specify the number of collections N to be
+You must first specify the number of collections N to be defined
-defined followed by N values representing the upper cutoff of each interval.
+followed by N values representing the upper cutoff of each interval.
-This command is particularly useful for granular pairstyles where the interaction distance
+This command is particularly useful for granular pair styles where the
-of particles depends on their radius and may not depend on their atom type.
+interaction distance of particles depends on their radius and may not
+depend on their atom type.
 
 Restrictions
 """"""""""""

doc/utils/sphinx-config/false_positives.txt

@@ -47,6 +47,7 @@ Agnolin
 Ai
 Aidan
 aij
+aimd
 airebo
 Aj
 ajs
@@ -196,6 +197,7 @@ Ballenegger
 Bammann
 Banna
 Barashev
+barnes
 barostat
 Barostats
 barostatted
@@ -1207,6 +1209,7 @@ Halver
 Hamaker
 Hamel
 Hammerschmidt
+Hanley
 haptic
 Hara
 Harpertown
@@ -1269,6 +1272,7 @@ holonomic
 Homebrew
 hooke
 Hookean
+hostname
 hotpink
 Houlle
 howto
@@ -1728,6 +1732,7 @@ Lmpsdata
 lmptype
 LMT
 ln
+localhost
 localTemp
 localvectors
 Loewen
@@ -1858,6 +1863,8 @@ mc
 McLachlan
 md
 mdf
+MDI
+mdi
 mdpd
 mDPD
 meam
@@ -3143,6 +3150,7 @@ Tanmoy
 Tartakovsky
 taskset
 taubi
+taylor
 tb
 tchain
 Tchain

src/USER-MDI/README

@@ -1,4 +1,4 @@
-The USRE-MDI package adds an mdi_engine command which enables LAMMPS
+The USER-MDI package adds an mdi/engine command which enables LAMMPS
 to operate as a MolSSI Driver Interface (MDI) engine, responding to
 commands from an external MDI driver.
 
@@ -8,7 +8,7 @@ developed and maintained by Taylor Barnes (tbarnes1@vt.edu) at the
 Molecular Sciences Software Institute (MolSSI).
 
 For more information about using MDI with LAMMPS, see the LAMMPS
-documentation for the mdi_engine command and the mdi/engine fix.
+documentation for the mdi/engine command and the mdi/engine fix.
 For general purpose information about MDI, see the MDI Library
 documentation:
 https://molssi-mdi.github.io/MDI_Library/html/index.html
@@ -18,3 +18,7 @@ built using the Install.py file in lib/mdi.  For example:
 
 python Install.py -m gcc
 python Install.py -m icc
+
+When using CMake to build LAMMPS the CMake configuration can use
+either a preinstalled MDI library or download and compile a
+private copy.

src/USER-MDI/fix_mdi_engine.cpp

@@ -311,7 +311,7 @@ int FixMDIEngine::execute_command(const char *command, MDI_Comm mdicomm)
     receive_forces(error, 1);
 
   // initialize new MD simulation or minimization
-  // return control to return to mdi_engine
+  // return control to return to mdi/engine
 
   } else if (strcmp(command,"@INIT_MD") == 0 ) {
     if (most_recent_init != 0)
@@ -320,7 +320,7 @@ int FixMDIEngine::execute_command(const char *command, MDI_Comm mdicomm)
     local_exit_flag = true;
 
   // initialize new energy minimization
-  // return control to return to mdi_engine
+  // return control to return to mdi/engine
 
   } else if (strcmp(command,"@INIT_OPTG") == 0 ) {
     if ( most_recent_init != 0 )

src/USER-MDI/mdi_engine.cpp

@@ -40,7 +40,7 @@ using namespace LAMMPS_NS;
    trigger LAMMPS to start acting as an MDI engine
    endlessly loop over receiving commands from driver and responding
    much of the logic for this is in FixMDIEngine
-   when EXIT command is received, mdi_engine command exits
+   when EXIT command is received, mdi/engine command exits
 ---------------------------------------------------------------------- */
 
 void MDIEngine::command(int narg, char **arg)
@@ -176,7 +176,7 @@ void MDIEngine::command(int narg, char **arg)
   MDI_Register_command("@COORDS", "@FORCES");
   MDI_Register_command("@COORDS", "EXIT");
 
-  // if the mdi_engine fix is not already present, add it now
+  // if the mdi/engine fix is not already present, add it now
 
   int ifix = modify->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");
 }

src/USER-MDI/mdi_engine.h

@@ -13,7 +13,7 @@
 
 #ifdef COMMAND_CLASS
 
-CommandStyle(mdi_engine,MDIEngine)
+CommandStyle(mdi/engine,MDIEngine)
 
 #else
 

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.