update doc pages

doc/src/Howto_mdi.rst

@@ -5,9 +5,9 @@ Client/server coupling of two (or more) codes is where one code is the
 "client" and sends request messages (data) to one (or more) "server"
 code(s).  A server responds to each request with a reply message
 (data).  This enables two (or more) codes to work in tandem to perform
-a simulation.  LAMMPS can act as either a client or server code; it
+a simulation.  In this context, LAMMPS can act as either a client or
-does this by using the `MolSSI Driver Interface (MDI) library
+server code.  It does this by using the `MolSSI Driver Interface (MDI)
-<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_,
+library <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_,
 developed by the `Molecular Sciences Software Institute (MolSSI)
 <https://molssi.org>`_, which is supported by the :ref:`MDI <PKG-MDI>`
 package.
@@ -80,11 +80,22 @@ scripts for all of these use cases.
 
 The examples/mdi directory contains Python scripts and LAMMPS input
 script which use LAMMPS as either an MDI driver or engine or both.
-Three example use cases are provided:
+Currently, 5 example use cases are provided:
 
-* Run ab initio MD (AIMD) using 2 instances of LAMMPS, one as driver
+* Run ab initio MD (AIMD) using 2 instances of LAMMPS.  As a driver
-  and one as an engine.  As an engine, LAMMPS is a surrogate for a
+  LAMMPS performs the timestepping in either NVE or NPT mode.  As an
-  quantum code.
+  engine, LAMMPS computes forces and is a surrogate for a quantum
+  code.
+
+* As a driver, LAMMPS runs an MD simulation.  Every N steps it passes
+  the current snapshot to an MDI engine to evaluate the energy,
+  virial, and peratom forces.  As the engine LAMMPS is a surrogate for
+  a quantum code.
+
+* As a driver, LAMMPS loops over a series of data files and passes the
+  configuration to an MDI engine to evaluate the energy, virial, and
+  peratom forces.  As the engine LAMMPS is a surrogate for a quantum
+  code.
 
 * A Python script driver invokes a sequence of unrelated LAMMPS
   calculations.  Calculations can be single-point energy/force
@@ -97,20 +108,22 @@ Three example use cases are provided:
 
 Note that in any of these example where LAMMPS is used as an engine,
 an actual QM code (which supports MDI) could be used in its place,
-without modifying other code or scripts, except to specify the name of
+without modifying the input scripts or launch commands, except to
-the QM code.
+specify the name of the QM code.
 
-The examples/mdi/README file explains how to launch both driver and
+The examples/mdi/Run.sh file illustrates how to launch both driver and
 engine codes so that they communicate using the MDI library via either
-MPI or sockets.
+MPI or sockets.  Or using the engine as a stand-alone code or plugin
+library.
 
 -------------
 
-Currently there are two quantum DFT codes which have direct MDI
+Currently there are at least two quantum DFT codes which have direct
-support, `Quantum ESPRESSO (QE) <https://www.quantum-espresso.org/>`_
+MDI support, `Quantum ESPRESSO (QE)
-and `INQ <https://qsg.llnl.gov/node/101.html>`_.  There are also
+<https://www.quantum-espresso.org/>`_ and `INQ
-several QM codes which have indirect support through QCEngine or i-PI.
+<https://qsg.llnl.gov/node/101.html>`_.  There are also several QM
-The former means they require a wrapper program (QCEngine) with MDI
+codes which have indirect support through QCEngine or i-PI.  The
+former means they require a wrapper program (QCEngine) with MDI
 support which writes/read files to pass data to the quantum code
 itself.  The list of QCEngine-supported and i-PI-supported quantum
 codes is on the `MDI webpage

doc/src/fix_mdi_qm.rst

@@ -13,7 +13,7 @@ Syntax
 * ID, group-ID are documented in :doc:`fix <fix>` command
 * mdi/qm = style name of this fix command
 * zero or more keyword/value pairs may be appended
-* keyword = *virial* or *add* or *every*
+* keyword = *virial* or *add* or *every* or *connect*
 
   .. parsed-literal::
 
@@ -25,6 +25,9 @@ Syntax
          no = do not add returned values to LAMMPS quantities
        *every* args = Nevery
          Nevery = request values from server code once every Nevery steps
+       *connect* args = *yes* or *no*
+         yes = perform a one-time connection to the MDI engine code
+         no = do not perform the connection operation
 
 Examples
 """"""""
@@ -66,7 +69,7 @@ information about how LAMMPS can operate as either an MDI driver or
 engine.
 
 The examples/mdi directory contains input scripts using this fix in
-the various use cases listed above.  In each case, two instances of
+the various use cases dicussed below.  In each case, two instances of
 LAMMPS are used, once as an MDI driver, once as an MDI engine
 (surrogate for a QM code).  The examples/mdi/README file explains how
 to launch two codes so that they communicate via the MDI library using
@@ -104,9 +107,21 @@ during a dynamics run with the current LAMMPS simulation box and
 configuration of atoms.  The QM code will be called once every
 *Nevery* timesteps.
 
+The *connect* keyword determines whether this fix performs a one-time
+connection to the QM code.  The default is *yes*.  The only time a
+*no* is needed is if this command is used multiple times in an input
+script.  E.g. if it used inside a loop which also uses the :doc:`clear
+<clear>` command to destroy the system (including any defined fixes).
+See the examples/mdi/in.series.driver script as an example of this,
+where LAMMPS is using the QM code to compute energy and forces for a
+series of system configurations.  In this use case *connect no*
+is used along with the :doc:`mdi connect and exit <mdi>` command
+to one-time initiate/terminate the connection outside the loop.
+
 ----------
 
-3 example use cases:
+The following 3 example use cases are illustrated in the examples/mdi
+directory.  See its README file for more details.
 
 (1) To run an ab initio MD (AIMD) dynamics simulation, or an energy
 minimization with QM forces, or a multi-replica NEB calculation, use
@@ -243,4 +258,4 @@ Default
 """""""
 
 The default for the optional keywords are virial = no, add = yes,
-every = 1.
+every = 1, connect = yes.

doc/src/mdi.rst

@@ -8,9 +8,9 @@ Syntax
 
 .. parsed-literal::
 
-   mdi mode args
+   mdi option args
 
-* mode = *engine* or *plugin*
+* option = *engine* or *plugin* or *connect* or *exit*
 
   .. parsed-literal::
 
@@ -22,7 +22,8 @@ Syntax
          *infile* value = filename the engine will read at start-up
          *extra* value = aditional command-line args to pass to engine library when loaded
          *command* value = a LAMMPS input script command to execute
-
+     *connect* args = none
+     *exit* args = none
 
 Examples
 """"""""
@@ -33,23 +34,15 @@ Examples
    mdi plugin lammps mdi "-role ENGINE -name lammps -method LINK" &
               infile in.aimd.engine extra "-log log.aimd.engine.plugin" &
               command "run 5"
+   mdi connect
+   mdi exit
 
 Description
 """""""""""
 
-This command implements two high-level operations within LAMMPS to use
+This command implements operations within LAMMPS to use the `MDI
-the `MDI Library
+Library <https://molssi-mdi.github.io/MDI_Library/html/index.html>`
-<https://molssi-mdi.github.io/MDI_Library/html/index.html>` for
+for coupling to other codes in a client/server protocol.
-coupling to other codes in a client/server protocol.
-
-The *engine* mode enables LAMMPS to act as an MDI engine (server),
-responding to requests from an MDI driver (client) code.
-
-The *plugin* mode enables LAMMPS to act as an MDI driver (client), and
-load the MDI engine (server) code as a library plugin.  In this case
-the MDI engine is a library plugin.  It can also be a stand-alone
-code, launched separately from LAMMPS, in which case the mdi plugin
-command is not used.
 
 See the Howto MDI doc page for a discussion of all the different ways
 2 or more codes can interact via MDI.
@@ -61,6 +54,22 @@ stand-alone code or as a plugin.  The README file in that directory
 shows how to launch and couple codes for all the 4 usage modes, and so
 they communicate via the MDI library using either MPI or sockets.
 
+The scripts in that directory illustrate the use of all the options
+for this command.
+
+The *engine* option enables LAMMPS to act as an MDI engine (server),
+responding to requests from an MDI driver (client) code.
+
+The *plugin* option enables LAMMPS to act as an MDI driver (client),
+and load the MDI engine (server) code as a library plugin.  In this
+case the MDI engine is a library plugin.  An MDI engine can also be a
+stand-alone code, launched separately from LAMMPS, in which case the
+mdi plugin command is not used.
+
+The *connect* and *exit* options are only used when LAMMPS is acting
+as an MDI driver.  As explained below, these options are normally not
+needed, except for a specific kind of use case.
+
 ----------
 
 The *mdi engine* command is used to make LAMMPS operate as an MDI
@@ -121,7 +130,7 @@ commands, which are described further below.
    * - <PE
      - Request potential energy of the system (1 value)
    * - <STRESS
-     - Request stress tensor (virial) of the system (6 values)
+     - Request symmetric stress tensor (virial) of the system (9 values)
    * - >TOLERANCE
      - Send 4 tolerance parameters for next MD minimization via OPTG command
    * - >TYPES or <TYPES
@@ -284,6 +293,31 @@ could specify a filename with multiple LAMMPS commands.
    "mdi plugin" command could then load the same library plugin or
    a different one if desired.
 
+----------
+
+The *mdi connect* and *mdi exit* commands are only used when LAMMPS is
+operating as an MDI driver.  And when other LAMMPS command(s) which
+send MDI commands and associated data to/from the MDI engine are not
+able to initiate and terminate the connection to the engine code.
+
+The only current MDI driver command in LAMMPS is the :doc:`fix mdi/qm
+<fix_mdi_qm>` command.  If it is only used once in an input script
+then it can initiate and terminate the connection.  But if it is being
+issuedd multiple times, e.g. in a loop that issues a :doc:`clear
+<clear>` command, then it cannot initiate/terminate the connection
+multiple times.  Instead, the *mdi connect* and *mdi exit* commands
+should be used outside the loop to intiate/terminate the connection.
+
+See the examples/mdi/in.series.driver script for an example of how
+this is done.  The LOOP in that script is reading a series of data
+file configurations and passing them to an MDI engine (e.g. quantum
+code) for enery and force evaluation.  A *clear* command inside the
+loop wipes out the current system so a new one can be defined.  This
+operation also destroys all fixes.  So the :doc:`fix mdi/qm
+<fix_mdi_qm>` command is issued once per loop iteration.  Note that it
+includes a "connect no" option which disables the initiate/terminate
+logic within that fix.
+
 
 Restrictions
 """"""""""""