update doc pages
This commit is contained in:
Steve Plimpton
@ -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
|
||||
<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_,
|
||||
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 <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
|
||||
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) <https://www.quantum-espresso.org/>`_
|
||||
and `INQ <https://qsg.llnl.gov/node/101.html>`_. 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)
|
||||
<https://www.quantum-espresso.org/>`_ and `INQ
|
||||
<https://qsg.llnl.gov/node/101.html>`_. 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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
<https://molssi-mdi.github.io/MDI_Library/html/index.html>` 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 <https://molssi-mdi.github.io/MDI_Library/html/index.html>`
|
||||
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.
|
||||
* - <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
|
||||
""""""""""""
|
||||
|
||||
Reference in New Issue
Block a user