ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #3307 from lammps/fix-mdi-aimd-enhance

Browse Source 
MDI package enhancements
This commit is contained in:
Axel Kohlmeyer
2022-07-01 20:48:40 -04:00
committed by GitHub
parent f245a4313e e34e9aca48
commit 146b00c395
150 changed files with 35538 additions and 2429 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/src/Commands_fix.rst
View File

@ -103,7 +103,7 @@ OPT.
* :doc:`lb/viscous <fix_lb_viscous>`
* :doc:`lineforce <fix_lineforce>`
* :doc:`manifoldforce <fix_manifoldforce>`
* :doc:`mdi/aimd <fix_mdi_aimd>`
* :doc:`mdi/qm <fix_mdi_qm>`
* :doc:`meso/move <fix_meso_move>`
* :doc:`mol/swap <fix_mol_swap>`
* :doc:`momentum (k) <fix_momentum>`

63
doc/src/Howto_mdi.rst
View File

@ -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.
@ -63,22 +63,39 @@ The package also provides a :doc:`mdi plugin <mdi>` command which
enables LAMMPS to operate as an MDI driver and load an MDI engine as a
plugin library.
The package also has a `fix mdi/aimd <fix_mdi_aimd>` command in which
LAMMPS operates as an MDI driver to perform *ab initio* MD simulations
in conjunction with a quantum mechanics code. Its post_force() method
illustrates how a driver issues MDI commands to another code. This
command can be used to couple to an MDI engine which is either a
stand-alone code or a plugin library.
The package also has a `fix mdi/qm <fix_mdi_qm>` command in which
LAMMPS operates as an MDI driver in conjunction with a quantum
mechanics code as an MDI engine. The post_force() method of the
fix_mdi_qm.cpp file shows how a driver issues MDI commands to another
code. This command can be used to couple to an MDI engine which is
either a stand-alone code or a plugin library.
As explained on the `fix mdi/qm <fix_mdi_qm>` command doc page, it can
be used to perform *ab initio* MD simulations or energy minimizations,
or to evaluate the quantum energy and forces for a series of
independent systems. The examples/mdi directory has example input
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
@ -91,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

2
doc/src/Packages_details.rst
View File

@ -1479,7 +1479,7 @@ the :doc:`Build extras <Build_extras>` page.
* lib/mdi/README
* :doc:`Howto MDI <Howto_mdi>`
* :doc:`mdi <mdi>`
* :doc:`fix mdi/aimd <fix_mdi_aimd>`
* :doc:`fix mdi/qm <fix_mdi_qm>`
* examples/PACKAGES/mdi
----------

2
doc/src/fix.rst
View File

@ -246,7 +246,7 @@ accelerated styles exist.
* :doc:`lb/viscous <fix_lb_viscous>` -
* :doc:`lineforce <fix_lineforce>` - constrain atoms to move in a line
* :doc:`manifoldforce <fix_manifoldforce>` - restrain atoms to a manifold during minimization
* :doc:`mdi/aimd <fix_mdi_aimd>` - LAMMPS operates as driver for ab initio MD (AIMD) via the MolSSI Driver Interface (MDI)
* :doc:`mdi/qm <fix_mdi_qm>` - LAMMPS operates as driver for a quantum code via the MolSSI Driver Interface (MDI)
* :doc:`meso/move <fix_meso_move>` - move mesoscopic SPH/SDPD particles in a prescribed fashion
* :doc:`mol/swap <fix_mol_swap>` - Monte Carlo atom type swapping with a molecule
* :doc:`momentum <fix_momentum>` - zero the linear and/or angular momentum of a group of atoms

9
doc/src/fix_latte.rst
View File

@ -116,13 +116,6 @@ potential energy of the system as part of :doc:`thermodynamic output
<thermo_style>`. The default setting for this fix is :doc:`fix_modify
energy yes <fix_modify>`.
The :doc:`fix_modify <fix_modify>` *virial* option is supported by
this fix to add the contribution compute by LATTE to the global
pressure of the system via the :doc:`compute pressure
<compute_pressure>` command. This can be accessed by
:doc:`thermodynamic output <thermo_style>`. The default setting for
this fix is :doc:`fix_modify virial yes <fix_modify>`.
The :doc:`fix_modify <fix_modify>` *virial* option is supported by
this fix to add the contribution computed by LATTE to the global
pressure of the system as part of :doc:`thermodynamic output
@ -137,7 +130,7 @@ energy discussed above. The scalar value calculated by this fix is
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command.
The DFTB forces computed by LATTE via this fix are imposed during an
The DFTB forces computed by LATTE via this fix are used during an
energy minimization, invoked by the :doc:`minimize <minimize>`
command.

93
doc/src/fix_mdi_aimd.rst
View File

@ -1,93 +0,0 @@
.. index:: fix mdi/aimd
fix mdi/aimd command
======================
Syntax
""""""
.. parsed-literal::
fix ID group-ID mdi/aimd keyword
* ID, group-ID are documented in :doc:`fix <fix>` command
* mdi/aimd = style name of this fix command
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all mdi/aimd
Description
"""""""""""
This command enables LAMMPS to act as a client with another server
code to couple the two codes together to perform ab initio MD (AIMD)
simulations.
More specifically, this command causes LAMMPS to begin using the `MDI
Library <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_
to run as an MDI driver (client), which sends MDI commands to an
external MDI engine code (server) which in the case of AIMD is a
quantum mechanics (QM) code, or could be LAMMPS itself, acting as a
surrogate for a QM code. See the :doc:`Howto mdi <Howto_mdi>` page
for more information about how LAMMPS can operate as either an MDI
driver or engine.
The examples/mdi directory contains input scripts performing AIMD in
this manner with LAMMPS acting as both a driver and an engine
(surrogate for a QM code). The examples/mdi/README file explains how
to launch both driver and engine codes so that they communicate using
the MDI library via either MPI or sockets. Any QM code that supports
MDI could be used in place of LAMMPS acting as a QM surrogate. See
the :doc:`Howto mdi <Howto_mdi>` page for a current list (March 2022)
of such QM codes.
The engine code can run either as a stand-alone code, launched at the
same time as LAMMPS, or as a plugin library. See the :doc:`mdi plugin
<mdi>` command for how to trigger LAMMPS to load the plugin library.
Again, the examples/mdi/README file explains how to launch both driver
and engine codes so that engine is used in plugin mode.
----------
This fix performs the timestepping portion of an AIMD simulation.
Both LAMMPS and the engine code (QM or LAMMPS) should define the same
system (simulation box, atoms and their types) in their respective
input scripts. LAMMPS then begins its timestepping.
At the point in each timestep when LAMMPS needs the force on each
atom, it communicates with the engine code. It sends the current
simulation box size and shape (if they change dynamically, e.g. during
an NPT simulation), and the current atom coordinates. The engine code
computes quantum forces on each atom and returns them to LAMMPS. If
LAMMPS also needs the system energy and/or virial, it requests those
values from the engine code as well.
Restrictions
""""""""""""
This command is part of the MDI package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
To use LAMMPS as an MDI driver in conjunction with other MDI-enabled
atomistic codes, the :doc:`units <units>` command should be used to
specify *real* or *metal* units. This will ensure the correct unit
conversions between LAMMPS and MDI units, which the other codes will
also perform in their preferred units.
LAMMPS can also be used as an MDI driver in other unit choices it
supports, e.g. *lj*, but then no unit conversion is performed.
Related commands
""""""""""""""""
:doc:`mdi engine <mdi>`
Default
"""""""
none

276
doc/src/fix_mdi_qm.rst Normal file
View File

@ -0,0 +1,276 @@
.. index:: fix mdi/qm
fix mdi/qm command
======================
Syntax
""""""
.. parsed-literal::
fix ID group-ID mdi/qm keyword
* 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* or *connect* or *elements*
.. parsed-literal::
*virial* args = *yes* or *no*
yes = request virial tensor from server code
no = do not request virial tensor from server code
*add* args = *yes* or *no*
yes = add returned value from server code to LAMMPS quantities
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
*elements* args = N_1 N_2 ... N_ntypes
N_1,N_2,...N_ntypes = atomic number for each of ntypes LAMMPS atom types
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all mdi/qm
fix 1 all mdi/qm virial yes
fix 1 all mdi/qm add no every 100 elements 13 29
Description
"""""""""""
This command enables LAMMPS to act as a client with another server
code that will compute the total energy, per-atom forces, and total
virial for atom conformations and simulation box size/shapes that
LAMMPS sends it.
Typically the server code will be a quantum mechanics (QM) code, hence
the name of the fix. However this is not required, the server code
could be another classical molecular dynamics code or LAMMPS itself.
The server code must support use of the `MDI Library
<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_ as
explained below.
These are example use cases for this fix, discussed further below:
* perform an ab initio MD (AIMD) simulation with quantum forces
* perform an energy minimization with quantum forces
* perform a nudged elastic band (NEB) calculation with quantum forces
* perform a QM calculation for a series of independent systems which LAMMPS reads or generates
The code coupling performed by this command is done via the `MDI
Library <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_.
LAMMPS runs as an MDI driver (client), and sends MDI commands to an
external MDI engine code (server), e.g. a QM code which has support
for MDI. See the :doc:`Howto mdi <Howto_mdi>` page for more
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 discussed 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
either MPI or sockets. Any QM code that supports MDI could be used in
place of LAMMPS acting as a QM surrogate. See the :doc:`Howto mdi
<Howto_mdi>` page for a current list (March 2022) of such QM codes.
Note that an engine code can support MDI in either or both of two
modes. It can be used as a stand-alone code, launched at the same
time as LAMMPS. Or it can be used as a plugin library, which LAMMPS
loads. See the :doc:`mdi plugin <mdi>` command for how to trigger
LAMMPS to load a plugin library. The examples/mdi/README file
explains how to launch the two codes in either mode.
----------
The *virial* keyword setting of yes or no determines whether
LAMMPS will request the QM code to also compute and return
a 6-element symmetric virial tensor for the system.
The *add* keyword setting of *yes* or *no* determines whether the
energy and forces and virial returned by the QM code will be added to
the LAMMPS internal energy and forces and virial or not. If the
setting is *no* then the default :doc:`fix_modify energy <fix_modify>`
and :doc:`fix_modify virial <fix_modify>` settings are also set to
*no* and your input scripts should not set them to yes. See more
details on these fix_modify settings below.
Whatever the setting for the *add* keyword, the QM energy, forces, and
virial will be stored by the fix, so they can be accessed by other
commands. See details below.
The *every* keyword determines how often the QM code will be invoked
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.
The *elements* keyword allows specification of what element each
LAMMPS atom type corresponds to. This is specified by the atomic
number of the element, e.g. 13 for Al. An atomic number must be
specified for each of the ntypes LAMMPS atom types. Ntypes is
typically specified via the create_box command or in the data file
read by the read_data command. If this keyword is not specified, then
this fix will send the LAMMPS atom type for each atom to the MDI
engine. If both the LAMMPS driver and the MDI engine are initialized
so that atom type values are consistent in both codes, then the
*elements* keyword is not needed. Otherwise the keyword can be used
to insure the two codes are consistent in their definition of atomic
species.
----------
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
*add yes* and *every 1* (the defaults). This is so that every time
LAMMPS needs energy and forces, the QM code will be invoked.
Both LAMMPS and the QM code should define the same system (simulation
box, atoms and their types) in their respective input scripts. Note
that on this scenario, it may not be necessary for LAMMPS to define a
pair style or use a neighbor list.
LAMMPS will then perform the timestepping or minimization iterations
for the simulation. At the point in each timestep or iteration when
LAMMPS needs the force on each atom, it communicates with the engine
code. It sends the current simulation box size and shape (if they
change dynamically, e.g. during an NPT simulation), and the current
atom coordinates. The engine code computes quantum forces on each
atom and the total energy of the system and returns them to LAMMPS.
Note that if the AIMD simulation is an NPT or NPH model, or the energy
minimization includes :doc:`fix box relax <fix_box_relax>` to
equilibrate the box size/shape, then LAMMPS computes a pressure. This
means the *virial* keyword should be set to *yes* so that the QM
contribution to the pressure can be included.
(2) To run dynamics with a LAMMPS interatomic potential, and evaluate
the QM energy and forces once every 1000 steps, use *add no* and
*every 1000*. This could be useful for using an MD run to generate
randomized configurations which are then passed to the QM code to
produce training data for a machine learning potential. A :doc:`dump
custom <dump>` command could be invoked every 1000 steps to dump the
atom coordinates and QM forces to a file. Likewise the QM energy and
virial could be output with the :doc:`thermo_style custom
<thermo_style>` command.
(3) To do a QM evaluation of energy and forces for a series of *N*
independent systems (simulation box and atoms), use *add no* and
*every 1*. Write a LAMMPS input script which loops over the *N*
systems. See the :doc:`Howto multiple <Howto_multiple>` doc page for
details on looping and removing old systems. The series of systems
could be initialized by reading them from data files with
:doc:`read_data <read_data>` commands. Or, for example, by using the
:doc:`lattice <lattice>` , :doc:`create_atoms <create_atoms>`,
:doc:`delete_atoms <delete_atoms>`, and/or :doc:`displace_atoms
random <displace_atoms>` commands to generate a series of different
systems. At the end of the loop perform :doc:`run 0 <run>` and
:doc:`write_dump <write_dump>` commands to invoke the QM code and
output the QM energy and forces. As in (2) this be useful to produce
QM data for training a machine learning potential.
----------
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
No information about this fix is written to :doc:`binary restart files
<restart>`.
The :doc:`fix_modify <fix_modify>` *energy* option is supported by
this fix to add the potential energy computed by the QM code to the
global potential energy of the system as part of :doc:`thermodynamic
output <thermo_style>`. The default setting for this fix is
:doc:`fix_modify energy yes <fix_modify>`, unless the *add* keyword is
set to *no*, in which case the default setting is *no*.
The :doc:`fix_modify <fix_modify>` *virial* option is supported by
this fix to add the contribution computed by the QM code to the global
pressure of the system as part of :doc:`thermodynamic output
<thermo_style>`. The default setting for this fix is :doc:`fix_modify
virial yes <fix_modify>`, unless the *add* keyword is set to *no*, in
which case the default setting is *no*.
This fix computes a global scalar which can be accessed by various
:doc:`output commands <Howto_output>`. The scalar is the energy
returned by the QM code. The scalar value calculated by this fix is
"extensive".
This fix also computes a global vector with of length 6 which contains
the symmetric virial tensor values returned by the QM code. It can
likewise be accessed by various :doc:`output commands <Howto_output>`.
The ordering of values in the symmetric virial tensor is as follows:
vxx, vyy, vzz, vxy, vxz, vyz. The values will be in pressure
:doc:`units <units>`.
This fix also computes a peratom array with 3 columns which contains
the peratom forces returned by the QM code. It can likewise be
accessed by various :doc:`output commands <Howto_output>`.
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command.
Assuming the *add* keyword is set to *yes* (the default), the forces
computed by the QM code are used during an energy minimization,
invoked by the :doc:`minimize <minimize>` command.
.. note::
If you want the potential energy associated with the QM forces to
be included in the total potential energy of the system (the
quantity being minimized), you MUST not disable the
:doc:`fix_modify <fix_modify>` *energy* option for this fix, which
means the *add* keyword should also be set to *yes* (the default).
Restrictions
""""""""""""
This command is part of the MDI package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
The QM code does not currently compute and return per-atom energy or
per-atom virial contributions. So they will not show up as part of
the calculations performed by the :doc:`compute pe/atom
<compute_pe_atom>` or :doc:`compute stress/atom <compute_stress_atom>`
commands.
To use LAMMPS as an MDI driver in conjunction with other MDI-enabled
codes (MD or QM codes), the :doc:`units <units>` command should be
used to specify *real* or *metal* units. This will ensure the correct
unit conversions between LAMMPS and MDI units. The other code will
also perform similar unit conversions into its preferred units.
LAMMPS can also be used as an MDI driver in other unit choices it
supports, e.g. *lj*, but then no unit conversion is performed.
Related commands
""""""""""""""""
:doc:`mdi plugin <mdi>`, :doc:`mdi engine <mdi>`
Default
"""""""
The default for the optional keywords are virial = no, add = yes,
every = 1, connect = yes.

113
doc/src/mdi.rst
View File

@ -8,21 +8,26 @@ Syntax
.. parsed-literal::
mdi mode args
mdi option args
* mode = *engine* or *plugin*
* option = *engine* or *plugin* or *connect* or *exit*
.. parsed-literal::
*engine* args = none
*plugin* args = name keyword value keyword value
*engine* args = zero or more keyword arg pairs
keywords = *elements*
*elements* args = N_1 N_2 ... N_ntypes
N_1,N_2,...N_ntypes = atomic number for each of ntypes LAMMPS atom types
*plugin* args = name keyword value keyword value ...
name = name of plugin library, e.g. lammps means a liblammps.so library will be loaded
keyword/value pairs in any order, some are required, some are optional
keywords = *mdi* or *infile* or *extra* or *command*
*mdi* value = args passed to MDI for driver to operate with plugins
*infile* value = filename the engine will read at start-up
*mdi* value = args passed to MDI for driver to operate with plugins (required)
*infile* value = filename the engine will read at start-up (optional)
*extra* value = aditional command-line args to pass to engine library when loaded
*command* value = a LAMMPS input script command to execute
*command* value = a LAMMPS input script command to execute (required)
*connect* args = none
*exit* args = none
Examples
""""""""
@ -30,26 +35,19 @@ Examples
.. code-block:: LAMMPS
mdi engine
mdi engine elements 13 29
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 +59,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
@ -100,6 +114,8 @@ commands, which are described further below.
- Send/request charge on each atom (N values)
* - >COORDS or <COORDS
- Send/request coordinates of each atom (3N values)
* - >ELEMENTS
- Send elements (atomic numbers) for each atom (N values)
* - <ENERGY
- Request total energy (potential + kinetic) of the system (1 value)
* - >FORCES or <FORCES
@ -121,11 +137,11 @@ 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
- Send/request the numeric type of each atom (N values)
- Send/request the LAMMPS atom type for each atom (N values)
* - >VELOCITIES or <VELOCITIES
- Send/request the velocity of each atom (3N values)
* - @INIT_MD or @INIT_OPTG
@ -145,9 +161,25 @@ commands, which are described further below.
builds. If the change in atom positions is large (since the
previous >COORDS command), then LAMMPS will do a more expensive
operation to migrate atoms to new processors as needed and
re-neighbor. If the >NATOMS or >TYPES commands have been sent
(since the previous >COORDS command), then LAMMPS assumes the
system is new and re-initializes an entirely new simulation.
re-neighbor. If the >NATOMS or >TYPES or >ELEMENTS commands have
been sent (since the previous >COORDS command), then LAMMPS assumes
the system is new and re-initializes an entirely new simulation.
.. note::
The >TYPES or >ELEMENTS commands are how the MDI driver tells the
LAMMPS engine which LAMMPS atom type to assign to each atom. If
both the MDI driver and the LAMMPS engine are initialized so that
atom type values are consistent in both codes, then the >TYPES
command can be used. If not, the optional *elements* keyword can
be used to specify what element each LAMMPS atom type corresponds
to. This is specified by the atomic number of the element, e.g. 13
for Al. An atomic number must be specified for each of the ntypes
LAMMPS atom types. Ntypes is typically specified via the
create_box command or in the data file read by the read_data
command. In this has been done, the MDI driver can send an
>ELEMENTS command to the LAMMPS driver with the atomic number of
each atom.
The MD and OPTG commands perform an entire MD simulation or energy
minimization (to convergence) with no communication from the driver
@ -270,7 +302,7 @@ The *command* keyword is required. It specifies a LAMMPS input script
command (as a single argument in quotes if it is multiple words).
Once the plugin library is launched, LAMMPS will execute this command.
Other previously-defined commands in the input script, such as the
:doc:`fix mdi/aimd <fix_mdi_aimd>` command, should perform MDI
:doc:`fix mdi/qm <fix_mdi_qm>` command, should perform MDI
communication with the engine, while the specified *command* executes.
Note that if *command* is an :doc:`include <include>` command, then it
could specify a filename with multiple LAMMPS commands.
@ -284,6 +316,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
issued multiple times, e.g. in a loop that issues a :doc:`clear
<clear>` command, then it cannot initiate or terminate the connection
multiple times. Instead, the *mdi connect* and *mdi exit* commands
should be used outside the loop to initiate or 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 energy 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
""""""""""""
@ -304,7 +361,7 @@ supports, e.g. *lj*, but then no unit conversion is performed.
Related commands
""""""""""""""""
:doc:`fix mdi/aimd <fix_mdi_aimd>`
:doc:`fix mdi/qm <fix_mdi_qm>`
Default
"""""""