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

Merge pull request #3628 from lammps/fix-mdi-qmmm

Browse Source 
Add a fix mdi/qmmm command for running QMMM via MDI code coupling
This commit is contained in:
Axel Kohlmeyer
2023-03-23 12:33:00 -04:00
committed by GitHub
parent 12e0131abf 667ba0febb
commit ed8b06a756
171 changed files with 33006 additions and 47044 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/src/Commands_fix.rst
View File

@ -111,6 +111,7 @@ OPT.
* :doc:`lineforce <fix_lineforce>`
* :doc:`manifoldforce <fix_manifoldforce>`
* :doc:`mdi/qm <fix_mdi_qm>`
* :doc:`mdi/qmmm <fix_mdi_qmmm>`
* :doc:`meso/move <fix_meso_move>`
* :doc:`mol/swap <fix_mol_swap>`
* :doc:`momentum (k) <fix_momentum>`

68
doc/src/Howto_mdi.rst
View File

@ -76,9 +76,16 @@ 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 package also has a :doc:`fix mdi/qmmm <fix_mdi_qmmm>` command in
which LAMMPS operates as an MDI driver in conjunction with a quantum
mechanics code as an MDI engine to perform QM/MM simulations. The
LAMMPS input script partitions the system into QM and MM (molecular
mechanics) atoms. As described below the ``examples/QUANTUM`` directory
has examples for coupling to 3 different quantum codes in this manner.
----------
The examples/mdi directory contains Python scripts and LAMMPS input
The ``examples/mdi`` directory contains Python scripts and LAMMPS input
script which use LAMMPS as either an MDI driver or engine, or both.
Currently, 5 example use cases are provided:
@ -119,45 +126,26 @@ as a plugin library.
-------------
Currently, there are at least two quantum DFT codes which have direct MDI
As of March 2023, these are quantum codes with MDI support provided via
Python wrapper scripts included in the LAMMPS distribution. These can
be used with the fix mdi/qm and fix mdi/qmmm commands to perform QM
calculations of an entire system (e.g. AIMD) or QM/MM simulations. See
the ``examples/QUANTUM`` sub-directories for more details:
* LATTE - AIMD only
* PySCF - QM/MM only
* NWChem - AIMD or QM/MM
There are also at least two quantum 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
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
<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_.
Here is how to build QE as a stand-alone ``pw.x`` file which can be
used in stand-alone mode:
.. code-block:: bash
git clone --branch mdi_plugin https://github.com/MolSSI-MDI/q-e.git <base_path>/q-e
build the executable pw.x, following the `QE build guide <https://gitlab.com/QEF/q-e/-/wikis/Developers/CMake-build-system>`_
Here is how to build QE as a shared library which can be used in plugin mode,
which results in a ``libqemdi.so`` file in ``<base_path>/q-e/MDI/src``:
.. code-block:: bash
git clone --branch mdi_plugin https://github.com/MolSSI-MDI/q-e.git <base_path>/q-e
cd <base_path>/q-e
./configure --enable-parallel --enable-openmp --enable-shared FFLAGS="-fPIC" FCFLAGS="-fPIC" CFLAGS="-fPIC" foxflags="-fPIC" try_foxflags="-fPIC"
make -j 4 mdi
INQ cannot be built as a stand-alone code; it is by design a library.
Here is how to build INQ as a shared library which can be used in
plugin mode, which results in a ``libinqmdi.so`` file in
``<base_path>/inq/build/examples``:
.. code-block:: bash
git clone --branch mdi --recurse-submodules https://gitlab.com/taylor-a-barnes/inq.git <base_path>/inq
cd <base_path>/inq
mkdir -p build
cd build
../configure --prefix=<install_path>/install
make -j 4
make install
These direct- and indirect-support codes should be usable for full
system calculations (e.g. AIMD). Whether they support QM/MM models
depends on the individual QM code.

3
doc/src/fix.rst
View File

@ -262,7 +262,8 @@ accelerated styles exist.
* :doc:`lb/viscous <fix_lb_viscous>` - :doc:`fix viscous <fix_viscous>` replacement for use with a lattice-Boltzmann fluid
* :doc:`lineforce <fix_lineforce>` - constrain atoms to move in a line
* :doc:`manifoldforce <fix_manifoldforce>` - restrain atoms to a manifold during minimization
* :doc:`mdi/qm <fix_mdi_qm>` - LAMMPS operates as driver for a quantum code via the MolSSI Driver Interface (MDI)
* :doc:`mdi/qm <fix_mdi_qm>` - LAMMPS operates as a client for a quantum code via the MolSSI Driver Interface (MDI)
* :doc:`mdi/qmmm <fix_mdi_qmmm>` - LAMMPS operates as client for QM/MM simulation with 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

121
doc/src/fix_mdi_qm.rst
View File

@ -8,12 +8,12 @@ Syntax
.. parsed-literal::
fix ID group-ID mdi/qm keyword
fix ID group-ID mdi/qm keyword value(s) keyword value(s) ...
* 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*
* keyword = *virial* or *add* or *every* or *connect* or *elements* or *mc*
.. parsed-literal::
@ -29,7 +29,9 @@ Syntax
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
N_1,N_2,...N_ntypes = chemical symbol for each of ntypes LAMMPS atom types
*mc* args = mcfixID
mcfixID = ID of a Monte Carlo fix designed to work with this fix
Examples
""""""""
@ -38,7 +40,7 @@ Examples
fix 1 all mdi/qm
fix 1 all mdi/qm virial yes
fix 1 all mdi/qm add no every 100 elements 13 29
fix 1 all mdi/qm add no every 100 elements C C H O
Description
"""""""""""
@ -57,12 +59,27 @@ The server code must support use of the `MDI Library
<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_ as
explained below.
Typically, to use this fix, the input script should not define any
other classical force field components, e.g. a pair style, bond style,
etc.
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
* perform a QM calculation for a series of independent systems which
LAMMPS reads or generates once
* run a classical MD simulation and calculate QM energy/forces once
every N steps on the current configuration
More generally any command which calculates per-atom forces can instead
use quantum forces by defining this fix. Examples are the Monte Carlo
commands :doc:`fix gcmc <fix_gcmc>` and :doc:`fix atom/swap
<fix_atom_swap>`, as well as the :doc:`compute born/matrix
<compute_born_matrix>` command. The only requirement is that internally
the command invokes the post_force() method of fixes such as this one,
which will trigger the quantum calculation.
The code coupling performed by this command is done via the `MDI
Library <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_.
@ -72,27 +89,32 @@ 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 ``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.
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. The
``examples/QUANTUM`` directory has examples for coupling LAMMPS to 3 QM
codes either via this fix or the :doc:`fix mdi/qmmm <fix_mdi_qmmm>`
command.
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.
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 and
``examples/QUANTUM/QM-code/README`` files explain 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 *virial* keyword setting of yes or no determines whether LAMMPS
will request the QM code to also compute and return the QM
contribution to a stress tensor for the system which LAMMPS will
convert to a 6-element symmetric virial tensor.
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
@ -109,25 +131,27 @@ 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.
*Nevery* timesteps. By default *Nevery* = 1.
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.
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
and the MDI coupling is between two stand-alone codes (not plugin mode).
E.g. if it used inside a loop which also uses the :doc:`clear <clear>`
command to destroy the system (including this fix). 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.
LAMMPS atom type corresponds to. This is specified by the chemical
symbol of the element, e.g. C or Al or Si. A symbol must be specified
for each of the ntypes LAMMPS atom types. Multiple LAMMPS types can
represent the same element. Ntypes is typically specified via the
:doc:`create_box <create_box>` command or in the data file read by the
:doc:`read_data <read_data>` command.
If this keyword is specified, then this fix will send the MDI
">ELEMENTS" command to the engine, to ensure the two codes are
@ -136,10 +160,18 @@ not specified, then this fix will send the MDI >TYPES command to the
engine. This is fine if both the LAMMPS driver and the MDI engine are
initialized so that the atom type values are consistent in both codes.
The *mc* keyword enables this fix to be used with a Monte Carlo (MC)
fix to calculate before/after quantum energies as part of the MC
accept/reject criterion. The :doc:`fix gcmc <fix_gcmc>` and :doc:`fix
atom/swap <fix_atom_swap>` commands can be used in this manner.
Specify the ID of the MC fix following the *mc* keyword. This allows
the two fixes to coordinate when MC events are being calculated versus
MD timesteps between the MC events.
----------
The following 3 example use cases are illustrated in the examples/mdi
directory. See its README file for more details.
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
@ -252,12 +284,6 @@ 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
@ -265,12 +291,15 @@ 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.
supports, e.g. *lj*, but then no unit conversion to MDI units is
performed.
Related commands
""""""""""""""""
:doc:`mdi plugin <mdi>`, :doc:`mdi engine <mdi>`
:doc:`mdi plugin <mdi>`,
:doc:`mdi engine <mdi>`,
:doc:`fix mdi/qmmm <fix_mdi_qmmm>`
Default
"""""""

274
doc/src/fix_mdi_qmmm.rst Normal file
View File

@ -0,0 +1,274 @@
.. index:: fix mdi/qmmm
fix mdi/qmmm command
====================
Syntax
""""""
.. parsed-literal::
fix ID group-ID mdi/qmmm mode keyword value(s) keyword value(s) ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* mdi/qmmm = style name of this fix command
* mode = *direct* or *potential*
* 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
*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 = chemical symbol for each of ntypes LAMMPS atom types
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all mdi/qmmm direct
fix 1 all mdi/qmmm potential virial yes
fix 1 all mdi/qmmm potential virial yes elements 13 29
Description
"""""""""""
.. versionadded:: TBD
This command enables LAMMPS to act as a client with another server code
to perform a coupled QM/MM (quantum-mechanics/molecular-mechanics)
simulation. LAMMPS will perform classical MD (molecular mechanics
or MM) for the (typically larger) MM portion of the system. A quantum
mechanics code will calculate quantum energy and forces for the QM
portion of the system. The two codes work together to calculate the
energy and forces due to the cross interactions between QM and MM atoms.
The QM server code must support use of the `MDI Library
<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_ as
explained below.
The partitioning of the system between QM and MM atoms is as follows.
Atoms in the specified group are QM atoms; the remaining atoms are MM
atoms. The input script should thus define this partitioning.
See additional information below about other requirements for an input
script to use this fix and perform a QM/MM simulation.
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), in this case 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/QUANTUM`` directory has sub-directories with example
input scripts using this fix in tandem with different QM codes. The
README files in the sub-directories explain how to download and build
the various QM codes. They also explain how to launch LAMMPS and the QM
code so that they communicate via the MDI library using either MPI or
sockets. Any QM code that supports MDI could be used in addition to
those discussed in the sub-directories. 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/QUANTUM`` sub-directory README files
explains how to launch the two codes in either mode.
----------
The *mode* setting determines which QM/MM coupling algorithm is used.
LAMMPS currently supports *direct* and *potential* algorithms, based
on the *mode* setting. Both algorithms should give reasonably
accurate results, but some QM codes support only one of the two modes.
E.g. in the ``examples/QUANTUM`` directory, PySCF supports only *direct*,
NWChem supports only *potential*, and LATTE currently supports
neither, so it cannot be used for QM/MM simulations using this fix.
The *direct* option passes the coordinates and charges of each MM atom
to the quantum code, in addition to the coordinates of each QM atom.
The quantum code returns forces on each QM atom as well as forces on
each MM atom. The latter is effectively the force on MM atoms due to
the QM atoms.
The input script for performing a *direct* mode QM/MM simulation should
do the following:
* delete all bonds (angles, dihedrals, etc) between QM atoms
* set the charge on each QM atom to zero
* define no bonds (angles, dihedrals, etc) which involve both QM and MM atoms
* define a force field (pair, bonds, angles, optional kspace) for the entire system
The first two bullet can be performed using the :doc:`delete_bonds
<delete_bonds>` and :doc:`set <set>` commands.
The third bullet is required to have a consistent model, but is not
checked by LAMMPS.
The fourth bullet implies that non-bonded non-Coulombic interactions
(e.g. van der Waals) between QM/QM and QM/MM pairs of atoms are
computed by LAMMPS.
See the ``examples/QUANTUM/PySCF/in.*`` files for examples of input
scripts for QM/MM simulations using the *direct* mode.
The *potential* option passes the coordinates of each QM atom and a
Coulomb potential for each QM atom to the quantum code. The latter is
calculated by performing a Coulombics-only calculation for the entire
system, subtracting all QM/QM pairwise Coulombic terms, and dividing
the Coulomb energy on each QM atom by the charge of the QM atom. The
potential value represents the Coulombic influence of all the MM atoms
on each QM atom.
The quantum code returns forces and charge on each QM atom. The new
charges on the QM atom are used to re-calculate the MM force field,
resulting in altered forces on the MM atoms.
The input script for performing a *potential* mode QM/MM simulation
should do the following:
* delete all bonds (angles, dihedrals, etc) between QM atoms
* define a hybrid pair style which includes a Coulomb-only pair sub-style
* define no bonds (angles, dihedrals, etc) which involve both QM and MM atoms
* define a force field (pair, bonds, angles, optional kspace) for the entire system
The first operation can be performed using the :doc:`delete_bonds
<delete_bonds>` command. See the ``examples/QUANTUM/NWChem/in.*`` files
for examples of how to do this.
The second operation is necessary so that this fix can calculate the
Coulomb potential for the QM atoms.
The third bullet is required to have a consistent model, but is not
checked by LAMMPS.
The fourth bullet implies that non-bonded non-Coulombic interactions
(e.g. van der Waals) between QM/QM and QM/MM pairs of atoms are computed
by LAMMPS. However, some QM codes do not want the MM code (LAMMPS) to
compute QM/QM van der Waals interactions. NWChem is an example. In
this case, the coefficients for those interactions need to be turned
off, which typically requires the atom types for the QM atoms be
different than those for the MM atoms.
See the ``examples/QUANTUM/NWChem/in.*`` files for examples of input
scripts for QM/MM simulations using the *potential* mode. Those scripts
also illustrate how to turn off QM/QM van der Waals interactions.
----------
The *virial* keyword setting of yes or no determines whether LAMMPS
will request the QM code to also compute and return the QM
contribution to a stress tensor for the system which LAMMPS will
convert to a 6-element symmetric virial tensor.
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 this fix). As
example would be a script which loop over a series of independent QM/MM
simulations, e.g. each with their own data file. In this use case
*connect no* could be 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 chemical
symbol of the element, e.g. C or Al or Si. A symbol must be specified
for each of the ntypes LAMMPS atom types. Multiple LAMMPS types can
represent the same element. Ntypes is typically specified via the
:doc:`create_box <create_box>` command or in the data file read by the
:doc:`read_data <read_data>` command.
If this keyword is specified, then this fix will send the MDI
">ELEMENTS" command to the engine, to insure the two codes are
consistent in their definition of atomic species. If this keyword is
not specified, then this fix will send the MDI >TYPES command to the
engine. This is fine if both the LAMMPS driver and the MDI engine are
initialized so that the atom type values are consistent in both codes.
----------
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>`.
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>`.
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>`. Note that
for *direct* mode this will be quantum forces on both QM and MM atoms.
For *potential* mode it will only be quantum forces on QM atoms; the
forces for MM atoms will be zero.
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command.
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.
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
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.
Related commands
""""""""""""""""
:doc:`mdi plugin <mdi>`,
:doc:`mdi engine <mdi>`,
:doc:`fix mdi/qm <fix_mdi_qm>`
Default
"""""""
The default for the optional keywords are virial = no and connect = yes.

21
doc/src/mdi.rst
View File

@ -17,7 +17,7 @@ Syntax
*engine* args = zero or more keyword/args 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
N_1,N_2,...N_ntypes = chemical symbol 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
@ -35,7 +35,7 @@ Examples
.. code-block:: LAMMPS
mdi engine
mdi engine elements 13 29
mdi engine elements Al Cu
mdi plugin lammps mdi "-role ENGINE -name lammps -method LINK" &
infile in.aimd.engine extra "-log log.aimd.engine.plugin" &
command "run 5"
@ -173,13 +173,16 @@ commands, which are described further below.
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.
to. This is specified by the chemical symbol of the element,
e.g. C or Al or Si. A symbol must be specified for each of the
ntypes LAMMPS atom types. Each LAMMPS type must map to a unique
element; two or more types cannot map to the same element. Ntypes
is typically specified via the :doc:`create_box <create_box>`
command or in the data file read by the :doc:`read_data
<read_data>` command. Once this has been done, the MDI driver can
send an >ELEMENTS command to the LAMMPS driver with the atomic
number of each atom and the LAMMPS engine will be able to map it to
a LAMMPS atom type.
The MD and OPTG commands perform an entire MD simulation or energy
minimization (to convergence) with no communication from the driver