From 06ffed196560ede27b9a730dac29a82b04d93d2f Mon Sep 17 00:00:00 2001 From: Steve Plimpton Date: Fri, 17 Jun 2022 12:11:13 -0600 Subject: [PATCH] update doc pages --- doc/src/Howto_mdi.rst | 45 ++++++++++++++++++---------- doc/src/fix_mdi_qm.rst | 23 +++++++++++--- doc/src/mdi.rst | 68 +++++++++++++++++++++++++++++++----------- 3 files changed, 99 insertions(+), 37 deletions(-) diff --git a/doc/src/Howto_mdi.rst b/doc/src/Howto_mdi.rst index f9147f44d9..578f98e61e 100644 --- a/doc/src/Howto_mdi.rst +++ b/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 -does this by using the `MolSSI Driver Interface (MDI) library -`_, +a simulation. In this context, LAMMPS can act as either a client or +server code. It does this by using the `MolSSI Driver Interface (MDI) +library `_, developed by the `Molecular Sciences Software Institute (MolSSI) `_, which is supported by the :ref:`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 - and one as an engine. As an engine, LAMMPS is a surrogate for a - quantum code. +* Run ab initio MD (AIMD) using 2 instances of LAMMPS. As a driver + LAMMPS performs the timestepping in either NVE or NPT mode. As an + 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 -the QM code. +without modifying the input scripts or launch commands, except to +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 -support, `Quantum ESPRESSO (QE) `_ -and `INQ `_. There are also -several QM codes which have indirect support through QCEngine or i-PI. -The former means they require a wrapper program (QCEngine) with MDI +Currently there are at least two quantum DFT codes which have direct +MDI support, `Quantum ESPRESSO (QE) +`_ and `INQ +`_. There are also several QM +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 diff --git a/doc/src/fix_mdi_qm.rst b/doc/src/fix_mdi_qm.rst index 5c66ac2639..8ecb6ed488 100644 --- a/doc/src/fix_mdi_qm.rst +++ b/doc/src/fix_mdi_qm.rst @@ -13,7 +13,7 @@ Syntax * ID, group-ID are documented in :doc:`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 +` 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 ` 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. diff --git a/doc/src/mdi.rst b/doc/src/mdi.rst index 73e245697e..0d647bbd4e 100644 --- a/doc/src/mdi.rst +++ b/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 -the `MDI Library -` for -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. +This command implements operations within LAMMPS to use the `MDI +Library ` +for coupling to other codes in a client/server protocol. 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. * - TOLERANCE - Send 4 tolerance parameters for next MD minimization via OPTG command * - >TYPES or ` 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 +` 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 +` 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 """"""""""""