diff --git a/doc/src/Commands_fix.rst b/doc/src/Commands_fix.rst index 89cf3e880a..0f5ac0d461 100644 --- a/doc/src/Commands_fix.rst +++ b/doc/src/Commands_fix.rst @@ -109,6 +109,7 @@ OPT. * :doc:`lineforce ` * :doc:`manifoldforce ` * :doc:`mdi/qm ` + * :doc:`mdi/qmmm ` * :doc:`meso/move ` * :doc:`mol/swap ` * :doc:`momentum (k) ` diff --git a/doc/src/Howto_mdi.rst b/doc/src/Howto_mdi.rst index f138d5aa11..ec8027b942 100644 --- a/doc/src/Howto_mdi.rst +++ b/doc/src/Howto_mdi.rst @@ -76,16 +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 `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 QMMM simulations. The +The package also has a :doc:`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 +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: @@ -129,12 +129,12 @@ as a plugin library. As of Feb 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 QMMM simulations. -See the examples/QUANTUM sub-directories for more details: +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 - QMMM only -* NWChem - AIMD or QMMM +* 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) `_ @@ -147,5 +147,5 @@ codes is on the `MDI webpage `_. These direct- and indirect-support codes should be usable for full -system calculations (e.g. AIMD). Whether they support QMMM models +system calculations (e.g. AIMD). Whether they support QM/MM models depends on the individual QM code. diff --git a/doc/src/fix.rst b/doc/src/fix.rst index 7d505fec63..6977584a33 100644 --- a/doc/src/fix.rst +++ b/doc/src/fix.rst @@ -260,7 +260,8 @@ accelerated styles exist. * :doc:`lb/viscous ` - :doc:`fix viscous ` replacement for use with a lattice-Boltzmann fluid * :doc:`lineforce ` - constrain atoms to move in a line * :doc:`manifoldforce ` - restrain atoms to a manifold during minimization -* :doc:`mdi/qm ` - LAMMPS operates as driver for a quantum code via the MolSSI Driver Interface (MDI) +* :doc:`mdi/qm ` - LAMMPS operates as a client for a quantum code via the MolSSI Driver Interface (MDI) +* :doc:`mdi/qmmm ` - LAMMPS operates as client for QM/MM simulation with a quantum code via the MolSSI Driver Interface (MDI) * :doc:`meso/move ` - move mesoscopic SPH/SDPD particles in a prescribed fashion * :doc:`mol/swap ` - Monte Carlo atom type swapping with a molecule * :doc:`momentum ` - zero the linear and/or angular momentum of a group of atoms diff --git a/doc/src/fix_mdi_qm.rst b/doc/src/fix_mdi_qm.rst index 08fc07aa4e..46b62fe8db 100644 --- a/doc/src/fix_mdi_qm.rst +++ b/doc/src/fix_mdi_qm.rst @@ -68,16 +68,18 @@ 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 once -* run a classical MD simulation and calculate QM energy/forces once every N steps on the current configuration +* 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 calulates per-atom forces can instead -use quantum forces be defining this fix. Examples are the Monte Carlo +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 ` and :doc:`fix atom/swap -`, as well as the :doc:`compute born ` -command. The only requirement is that internally the commmand invokes -the post_force() method of fixes such as this one, which will trigger -the quantum calculation. +`, as well as the :doc:`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 `_. @@ -87,24 +89,24 @@ for MDI. See the :doc:`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 -` 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 ` +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 ` +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 ` 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 ` 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 +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 ` 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. ---------- @@ -132,16 +134,16 @@ configuration of atoms. The QM code will be called once every *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 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 ` 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 ` 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 ` +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 ` 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 @@ -168,8 +170,8 @@ 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 @@ -295,8 +297,9 @@ performed. Related commands """""""""""""""" -:doc:`mdi plugin `, :doc:`mdi engine `, :doc:`fix mdi/qmmm - ` +:doc:`mdi plugin `, +:doc:`mdi engine `, +:doc:`fix mdi/qmmm ` Default """"""" diff --git a/doc/src/fix_mdi_qmmm.rst b/doc/src/fix_mdi_qmmm.rst index d9bcd9e6a7..58be173930 100644 --- a/doc/src/fix_mdi_qmmm.rst +++ b/doc/src/fix_mdi_qmmm.rst @@ -1,7 +1,7 @@ .. index:: fix mdi/qmmm fix mdi/qmmm command -====================== +==================== Syntax """""" @@ -39,14 +39,14 @@ Examples Description """"""""""" -This command enables LAMMPS to act as a client with another server -code to perform a coupled QMMM (quantum-mechanics/molecular-mechanics) -simulation. LAMMPS will perform classical MD (molecular mechnanics +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 +energy and forces due to the cross interactions between QM and MM atoms. +The QM server code must support use of the `MDI Library `_ as explained below. @@ -54,7 +54,7 @@ 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 QMMM simulation. +script to use this fix and perform a QM/MM simulation. The code coupling performed by this command is done via the `MDI Library `_. @@ -64,31 +64,31 @@ support for MDI. See the :doc:`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 +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 ` 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 ` 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. +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 ` 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 QMMM coupling algorithm is used. +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*, +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 QMMM simulations using this fix. +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. @@ -96,12 +96,12 @@ 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 QMMM simulation should +The input script for performing a *direct* mode QM/MM simulation should do the following: -* delete all bonds (angles, dihedrals, etc) bewteen QM atoms +* delete all bonds (angles, dihedrals, etc) between QM atoms * set the charge on each QM atom to zero -* define no bonds (angles, dihederals, etc) which involve both QM and MM atoms +* 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 @@ -114,8 +114,8 @@ 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 QMMM simulations using the *direct* mode. +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 @@ -129,34 +129,34 @@ 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 QMMM simulation +The input script for performing a *potential* mode QM/MM simulation should do the following: -* delete all bonds (angles, dihedrals, etc) bewteen QM atoms +* 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, dihederals, etc) which involve both QM and MM atoms +* 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 -` command. See the examples/QUANTUM/NWChem/in.* files +` 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 -potentail for the QM atoms. +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 thoes interactions need -to be turned off, which typically requires the atom types for the QM atoms -be different than those for the MM atoms. +(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 QMMM simulations using the *potential* mode. Those scripts +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. ---------- @@ -171,7 +171,7 @@ 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 this fix). As -example would be a script which loop over a series of independent QMMM +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 ` command to one-time initiate/terminate the connection outside @@ -262,11 +262,11 @@ also perform similar unit conversions into its preferred units. Related commands """""""""""""""" -:doc:`mdi plugin `, :doc:`mdi engine `, :doc:`fix mdi/qm - ` +:doc:`mdi plugin `, +:doc:`mdi engine `, +:doc:`fix mdi/qm ` Default """"""" -The default for the optional keywords are virial = no and connect = -yes. +The default for the optional keywords are virial = no and connect = yes. diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index 0f18e6822f..cffc87d3e3 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/doc/utils/sphinx-config/false_positives.txt @@ -2572,7 +2572,7 @@ nvidia nvk nvt Nwait -nwchem +NWChem nx Nx nxlo @@ -2906,6 +2906,7 @@ PyLammps pymbar pymodule pymol +PySCF pythonic pytorch pyy