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

Merge branch 'develop' into remove-message-package

Browse Source
This commit is contained in:
Axel Kohlmeyer
2022-04-09 00:25:11 -04:00
parent 521d45dcc6 8b53ff9383
commit 674d2a6788
213 changed files with 21808 additions and 8033 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/src/Commands_compute.rst
View File

@ -63,6 +63,7 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`event/displace <compute_event_displace>`
* :doc:`fabric <compute_fabric>`
* :doc:`fep <compute_fep>`
* :doc:`fep/ta <compute_fep_ta>`
* :doc:`force/tally <compute_tally>`
* :doc:`fragment/atom <compute_cluster_atom>`
* :doc:`global/atom <compute_global_atom>`

2
doc/src/Commands_fix.rst
View File

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

8
doc/src/Commands_pair.rst
View File

@ -88,12 +88,12 @@ OPT.
* :doc:`coul/tt <pair_coul_tt>`
* :doc:`coul/wolf (ko) <pair_coul>`
* :doc:`coul/wolf/cs <pair_cs>`
* :doc:`dpd (gio) <pair_dpd>`
* :doc:`dpd (giko) <pair_dpd>`
* :doc:`dpd/fdt <pair_dpd_fdt>`
* :doc:`dpd/ext <pair_dpd_ext>`
* :doc:`dpd/ext/tstat <pair_dpd_ext>`
* :doc:`dpd/ext (k) <pair_dpd_ext>`
* :doc:`dpd/ext/tstat (k) <pair_dpd_ext>`
* :doc:`dpd/fdt/energy (k) <pair_dpd_fdt>`
* :doc:`dpd/tstat (go) <pair_dpd>`
* :doc:`dpd/tstat (gko) <pair_dpd>`
* :doc:`dsmc <pair_dsmc>`
* :doc:`e3b <pair_e3b>`
* :doc:`drip <pair_drip>`

21
doc/src/Developer_plugins.rst
View File

@ -262,3 +262,24 @@ A plugin may be registered under an existing style name. In that case
the plugin will override the existing code. This can be used to modify
the behavior of existing styles or to debug new versions of them without
having to re-compile or re-install all of LAMMPS.
Compiling plugins
^^^^^^^^^^^^^^^^^
Plugins need to be compiled with the same compilers and libraries
(e.g. MPI) and compilation settings (MPI on/off, OpenMP, integer sizes)
as the LAMMPS executable and library. Otherwise the plugin will likely
not load due to mismatches in the function signatures (LAMMPS is C++ so
scope, type, and number of arguments are encoded into the symbol names
and thus differences in them will lead to failed plugin load commands.
Compilation of the plugin can be managed via both, CMake or traditional
GNU makefiles. Some examples that can be used as a template are in the
``examples/plugins`` folder. The CMake script code has some small
adjustments to allow building the plugins for running unit tests with
them. Another example that converts the KIM package into a plugin can be
found in the ``examples/kim/plugin`` folder. No changes to the sources
of the KIM package themselves are needed; only the plugin interface and
loader code needs to be added. This example only supports building with
CMake, but is probably a more typical example. To compile you need to
run CMake with -DLAMMPS_SOURCE_DIR=<path/to/lammps/src/folder>. Other
configuration setting are identical to those for compiling LAMMPS.

2
doc/src/Examples.rst
View File

@ -94,6 +94,8 @@ Lowercase directories
+-------------+------------------------------------------------------------------+
| latte | examples for using fix latte for DFTB via the LATTE library |
+-------------+------------------------------------------------------------------+
| mdi | use of the MDI package and MolSSI MDI code coupling library |
+-------------+------------------------------------------------------------------+
| meam | MEAM test for SiC and shear (same as shear examples) |
+-------------+------------------------------------------------------------------+
| melt | rapid melt of 3d LJ system |

27
doc/src/Howto_couple.rst
View File

@ -12,16 +12,16 @@ LAMMPS can be coupled to other codes in at least 4 ways. Each has
advantages and disadvantages, which you will have to think about in the
context of your application.
1. Define a new :doc:`fix <fix>` command that calls the other code. In
this scenario, LAMMPS is the driver code. During timestepping,
1. Define a new :doc:`fix <fix>` command that calls the other code.
In this scenario, LAMMPS is the driver code. During timestepping,
the fix is invoked, and can make library calls to the other code,
which has been linked to LAMMPS as a library. This is the way how the
which has been linked to LAMMPS as a library. This is the way the
:ref:`LATTE <PKG-LATTE>` package, which performs density-functional
tight-binding calculations using the `LATTE software <https://github.com/lanl/LATTE>`_
to compute forces, is hooked to LAMMPS.
See the :doc:`fix latte <fix_latte>` command for more details.
Also see the :doc:`Modify <Modify>` doc pages for info on how to
add a new fix to LAMMPS.
tight-binding calculations using the `LATTE software
<https://github.com/lanl/LATTE>`_ to compute forces, is hooked to
LAMMPS. See the :doc:`fix latte <fix_latte>` command for more
details. Also see the :doc:`Modify <Modify>` doc pages for info on
how to add a new fix to LAMMPS.
.. spacer
@ -58,5 +58,12 @@ context of your application.
.. spacer
4. Couple LAMMPS with another code in a client/server mode. This is
described on the :doc:`Howto MDI library coupling <Howto_mdi>` page.
4. Couple LAMMPS with another code in a client/server fashion, using
using the `MDI Library
<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_
developed by the `Molecular Sciences Software Institute (MolSSI)
<https://molssi.org>`_ to run LAMMPS as either an MDI driver
(client) or an MDI engine (server). The MDI driver issues commands
to the MDI server to exchange data between them. See the
:doc:`Howto mdi <Howto_mdi>` page for more information about how
LAMMPS can operate in either of these modes.

211
doc/src/Howto_mdi.rst
View File

@ -1,127 +1,144 @@
Using LAMMPS with the MDI library for code coupling
===================================================
Client/server coupling of two codes is where one code is the "client"
and sends request messages (data) to a "server" code. The server
responds to each request with a reply message. This enables the two
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
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>`_,
developed by the `Molecular Sciences Software Institute (MolSSI)
<https://molssi.org>`_.
<https://molssi.org>`_, which is supported by the :ref:`MDI <PKG-MDI>`
package.
Alternate methods for code coupling with LAMMPS are described on the
:doc:`Howto couple <Howto_couple>` doc page.
Some advantages of client/server coupling are that the two codes can run
Some advantages of client/server coupling are that the codes can run
as stand-alone executables; they need not be linked together. Thus
neither code needs to have a library interface. This also makes it easy
to run the two codes on different numbers of processors. If a message
protocol (format and content) is defined for a particular kind of
simulation, then in principle any code which implements the client-side
protocol can be used in tandem with any code which implements the
server-side protocol. Neither code needs to know what specific other
code it is working with.
neither code needs to have a library interface. This also makes it
easy to run the two codes on different numbers of processors. If a
message protocol (format and content) is defined for a particular kind
of simulation, then in principle any code which implements the
client-side protocol can be used in tandem with any code which
implements the server-side protocol. Neither code needs to know what
specific other code it is working with.
In MDI nomenclature, a client code is the "driver", and a server code is
an "engine". One driver code can communicate with one or more instances
of one or more engine codes. Driver and engine codes can be written in
any language: C, C++, Fortran, Python, etc.
In addition to allowing driver and engine(s) running to run as
stand-alone executables, MDI also enables a server code to be a
"plugin" to the client code. In this scenario, server code(s) are
compiled as shared libraries, and one (or more) instances of the
server are instantiated by the driver code. If the driver code runs
in parallel, it can split its MPI communicator into multiple
sub-communicators, and launch each plugin engine instance on a
sub-communicator. Driver processors in that sub-communicator exchange
messages with that engine instance, and can also send MPI messages to
other processors in the driver. The driver code can also destroy
engine instances and re-instantiate them.
In addition to allowing driver and engine(s) to run as stand-alone
executables, MDI also enables an engine to be a *plugin* to the client
code. In this scenario, server code(s) are compiled as shared
libraries, and one (or more) instances of the server are instantiated
by the driver code. If the driver code runs in parallel, it can split
its MPI communicator into multiple sub-communicators, and launch each
plugin engine instance on a sub-communicator. Driver processors
within that sub-communicator exchange messages with the corresponding
engine instance, and can also send MPI messages to other processors in
the driver. The driver code can also destroy engine instances and
re-instantiate them. LAMMPS can operate as either a stand-alone or
plugin MDI engine. When it operates as a driver, if can use either
stand-alone or plugin MDI engines.
The way that a driver communicates with an engine is by making
MDI_Send() and MDI_Recv() calls, which are conceptually similar to
MPI_Send() and MPI_Recv() calls. Each send or receive has a string
which identifies the command name, and optionally some data, which can
be a single value or vector of values of any data type. Inside the
MDI library, data is exchanged between the driver and engine via MPI
calls or sockets. This a run-time choice by the user.
The way in which an MDI driver communicates with an MDI engine is by
making MDI_Send() and MDI_Recv() calls, which are conceptually similar
to MPI_Send() and MPI_Recv() calls. Each send or receive operation
uses a string to identify the command name, and optionally some data,
which can be a single value or vector of values of any data type.
Inside the MDI library, data is exchanged between the driver and
engine via MPI calls or sockets. This a run-time choice by the user.
----------
The :ref:`MDI <PKG-MDI>` package provides a :doc:`mdi engine <mdi>`
command which enables LAMMPS to operate as an MDI engine. Its doc
page explains the variety of standard and custom MDI commands which
the LAMMPS engine recognizes and can respond to.
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 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:
* 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.
* A Python script driver invokes a sequence of unrelated LAMMPS
calculations. Calculations can be single-point energy/force
evaluations, MD runs, or energy minimizations.
* Run AIMD with a Python driver code and 2 LAMMPS instances as
engines. The first LAMMPS instance performs MD timestepping. The
second LAMMPS instance acts as a surrogate QM code to compute
forces.
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.
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.
-------------
As an example, LAMMPS and the ``pw.x`` command from Quantum Espresso (a
suite of quantum DFT codes), can work together via the MDI library to
perform an ab initio MD (AIMD) simulation, where LAMMPS runs an MD
simulation and sends a message each timestep to ``pw.x`` asking it to
compute quantum forces on the current configuration of atoms. Here is
how the 2 codes are launched to communicate by MPI:
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
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
% mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method MPI" \
-in in.aimd : -np 16 pw.x -in qe.in -mdi "-role ENGINE -name e -method MPI"
% 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>`_
In this case LAMMPS runs on 2 processors (MPI tasks), ``pw.x`` runs on 16
processors.
Here is how the 2 codes are launched to communicate by sockets:
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
% mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method TCP -port 8021" -in in.aimd
% mpirun -np 16 pw.x -in qe.in -mdi "-role ENGINE -name e -method TCP -port 8021 -hostname localhost"
% 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
These commands could be issued in different windows on a desktop
machine. Or in the same window, if the first command is ended with
"&" so as to run in the background. If "localhost" is replaced by an
IP address, ``pw.x`` could be run on another machine on the same network, or
even on another machine across the country.
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:
After both codes initialize themselves to model the same system, this is
what occurs each timestep:
.. code-block:: bash
* LAMMPS send a ">COORDS" message to ``pw.x`` with a 3*N vector of current atom coords
* ``pw.x`` receives the message/coords and computes quantum forces on all the atoms
* LAMMPS send a "<FORCES" message to ``pw.x`` and waits for the result
* ``pw.x`` receives the message (after its computation finishes) and sends a 3*N vector of forces
* LAMMPS receives the forces and time integrates to complete a single timestep
-------------
Examples scripts for using LAMMPS as an MDI engine are in the
examples/mdi directory. See the README file in that directory for
instructions on how to run the examples.
.. note::
Work is underway to add commands that allow LAMMPS to be used as an
MDI driver, e.g. for the AIMD example discussed above. Example
scripts for this usage mode will be added the same directory when
available.
If LAMMPS is used as a stand-alone engine it should set up the system
it will be modeling in its input script, then invoke the
:doc:`mdi/engine <mdi_engine>` command. This will put LAMMPS into
"engine mode" where it waits for messages and data from the driver.
When the driver sends an "EXIT" command, LAMMPS will exit engine mode
and the input script will continue.
If LAMMPS is used as a plugin engine it operates the same way, except
that the driver will pass LAMMPS an input script to initialize itself.
Upon receiving the "EXIT" command, LAMMPS will exit engine mode and the
input script will continue. After finishing execution of the input
script, the instance of LAMMPS will be destroyed.
LAMMPS supports the full set of MD-appropriate engine commands defined
by the MDI library. See the :doc:`mdi/engine <mdi_engine>` page for
a list of these.
If those commands are not sufficient for a user-developed driver to use
LAMMPS as an engine, then new commands can be easily added. See these
two files which implement the definition of MDI commands and the logic
for responding to them:
* src/MDI/mdi_engine.cpp
* src/MDI/fix_mdi_engine.cpp
% 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

6
doc/src/Howto_structured_data.rst
View File

@ -79,6 +79,10 @@ This data can be extracted and parsed from a log file using python with:
.. code-block:: python
import re, yaml
try:
from yaml import CSafeLoader as Loader, CSafeDumper as Dumper
except ImportError:
from yaml import SafeLoader as Loader, SafeDumper as Dumper
docs = ""
with open("log.lammps") as f:
@ -86,7 +90,7 @@ This data can be extracted and parsed from a log file using python with:
m = re.search(r"^(keywords:.*$|data:$|---$|\.\.\.$| - \[.*\]$)", line)
if m: docs += m.group(0) + '\n'
thermo = list(yaml.load_all(docs, Loader=yaml.SafeLoader))
thermo = list(yaml.load_all(docs, Loader=Loader))
print("Number of runs: ", len(thermo))
print(thermo[1]['keywords'][4], ' = ', thermo[1]['data'][2][4])

15
doc/src/Packages_details.rst
View File

@ -1395,17 +1395,24 @@ MDI package
**Contents:**
A LAMMPS command and fix to allow client-server coupling of LAMMPS to
other atomic or molecular simulation codes via the `MolSSI Driver Interface
A LAMMPS command and fixes to allow client-server coupling of LAMMPS
to other atomic or molecular simulation codes or materials modeling
workflows via the `MolSSI Driver Interface
(MDI) library <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_.
**Author:** Taylor Barnes - MolSSI, taylor.a.barnes at gmail.com
**Install:**
This package has :ref:`specific installation instructions <message>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
* src/MDI/README
* :doc:`mdi/engine <mdi_engine>`
* :doc:`fix mdi/engine <fix_mdi_engine>`
* lib/mdi/README
* :doc:`Howto MDI <Howto_mdi>`
* :doc:`mdi <mdi>`
* :doc:`fix mdi/aimd <fix_mdi_aimd>`
* examples/PACKAGES/mdi
----------

2
doc/src/Packages_list.rst
View File

@ -244,7 +244,7 @@ whether an extra library is needed to build and use the package:
- n/a
- no
* - :ref:`MDI <PKG-MDI>`
- client-server coupling
- client-server code coupling
- :doc:`MDI Howto <Howto_mdi>`
- PACKAGES/mdi
- ext

3
doc/src/compute.rst
View File

@ -208,7 +208,8 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` pag
* :doc:`erotate/sphere/atom <compute_erotate_sphere_atom>` - rotational energy for each spherical particle
* :doc:`event/displace <compute_event_displace>` - detect event on atom displacement
* :doc:`fabric <compute_fabric>` - calculates fabric tensors from pair interactions
* :doc:`fep <compute_fep>` -
* :doc:`fep <compute_fep>` - compute free energies for alchemical transformation from perturbation theory
* :doc:`fep/ta <compute_fep_ta>` - compute free energies for a test area perturbation
* :doc:`force/tally <compute_tally>` - force between two groups of atoms via the tally callback mechanism
* :doc:`fragment/atom <compute_cluster_atom>` - fragment ID for each atom
* :doc:`global/atom <compute_global_atom>` -

99
doc/src/compute_fep_ta.rst Normal file
View File

@ -0,0 +1,99 @@
.. index:: compute fep/ta
compute fep/ta command
======================
Syntax
""""""
.. parsed-literal::
compute ID group-ID fep/ta temp plane scale_factor keyword value ...
* ID, group-ID are documented in the :doc:`compute <compute>` command
* fep/ta = name of this compute command
* temp = external temperature (as specified for constant-temperature run)
* plane = *xy* or *xz* or *yz*
* scale_factor = multiplicative factor for change in plane area
* zero or more keyword/value pairs may be appended
* keyword = *tail*
.. parsed-literal::
*tail* value = *no* or *yes*
*no* = ignore tail correction to pair energies (usually small in fep)
*yes* = include tail correction to pair energies
Examples
""""""""
.. code-block:: LAMMPS
compute 1 all fep/ta 298 xy 1.0005
Description
"""""""""""
Define a computation that calculates the change in the free energy due
to a test-area (TA) perturbation :ref:`(Gloor) <Gloor>`. The test-area
approach can be used to determine the interfacial tension of the system
in a single simulation:
.. math::
\gamma = \lim_{\Delta \mathcal{A} \to 0} \left( \frac{\Delta A_{0 \to 1 }}{\Delta \mathcal{A}}\right)_{N,V,T}
= - \frac{kT}{\Delta \mathcal{A}} \ln \left< \exp(-(U_1 - U_0)/kT) \right>_0
During the perturbation, both axes of *plane* are scaled by multiplying
:math:`\sqrt{scale\_factor}`, while the other axis divided by
*scale_factor* such that the overall volume of the system is maintained.
The *tail* keyword controls the calculation of the tail correction to
"van der Waals" pair energies beyond the cutoff, if this has been
activated via the :doc:`pair_modify <pair_modify>` command. If the
perturbation is small, the tail contribution to the energy difference
between the reference and perturbed systems should be negligible.
----------
Output info
"""""""""""
This compute calculates a global vector of length 3 which contains the
energy difference ( :math:`U_1-U_0` ) as c_ID[1], the Boltzmann factor
:math:`\exp(-(U_1-U_0)/kT)`, as c_ID[2] and the change in the *plane*
area :math:`\Delta \mathcal{A}` as c_ID[3]. :math:`U_1` is the potential
energy of the perturbed state and :math:`U_0` is the potential energy of
the reference state. The energies include kspace terms if these are
used in the simulation.
These output results can be used by any command that uses a global
scalar or vector from a compute as input. See the :doc:`Howto output
<Howto_output>` page for an overview of LAMMPS output options. For
example, the computed values can be averaged using :doc:`fix ave/time
<fix_ave_time>`.
Restrictions
""""""""""""
Constraints, like fix shake, may lead to incorrect values for energy difference.
This compute is distributed as the FEP package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`compute fep <compute_fep>`
Default
"""""""
The option defaults are *tail* = *no*\ .
----------
.. _Gloor:
**(Gloor)** Gloor, J Chem Phys, 123, 134703 (2005)

79
doc/src/dump.rst
View File

@ -36,7 +36,7 @@ Syntax
* ID = user-assigned name for the dump
* group-ID = ID of the group of atoms to be dumped
* style = *atom* or *atom/gz* or *atom/zstd or *atom/mpiio* or *cfg* or *cfg/gz* or *cfg/zstd* or *cfg/mpiio* or *custom* or *custom/gz* or *custom/zstd* or *custom/mpiio* or *dcd* or *h5md* or *image* or *local* or *local/gz* or *local/zstd* or *molfile* or *movie* or *netcdf* or *netcdf/mpiio* or *vtk* or *xtc* or *xyz* or *xyz/gz* or *xyz/zstd* or *xyz/mpiio*
* style = *atom* or *atom/gz* or *atom/zstd or *atom/mpiio* or *cfg* or *cfg/gz* or *cfg/zstd* or *cfg/mpiio* or *custom* or *custom/gz* or *custom/zstd* or *custom/mpiio* or *dcd* or *h5md* or *image* or *local* or *local/gz* or *local/zstd* or *molfile* or *movie* or *netcdf* or *netcdf/mpiio* or *vtk* or *xtc* or *xyz* or *xyz/gz* or *xyz/zstd* or *xyz/mpiio* or *yaml*
* N = dump every this many timesteps
* file = name of file to write dump info to
* args = list of arguments for a particular style
@ -68,8 +68,9 @@ Syntax
*xyz/gz* args = none
*xyz/zstd* args = none
*xyz/mpiio* args = none
*yaml* args = same as *custom* args, see below
* *custom* or *custom/gz* or *custom/zstd* or *custom/mpiio* or *netcdf* or *netcdf/mpiio* args = list of atom attributes
* *custom* or *custom/gz* or *custom/zstd* or *custom/mpiio* or *netcdf* or *netcdf/mpiio* or *yaml* args = list of atom attributes
.. parsed-literal::
@ -386,6 +387,70 @@ from using the (numerical) atom type to an element name (or some
other label). This will help many visualization programs to guess
bonds and colors.
Dump style *yaml* has the same command syntax as style *custom* and
writes YAML format files that can be easily parsed by a variety of data
processing tools and programming languages. Each timestep will be
written as a YAML "document" (i.e. starts with "---" and ends with
"..."). The style supports writing one file per timestep through the
"\*" wildcard but not multi-processor outputs with the "%" token in the
filename. In addition to per-atom data, :doc:`thermo <thermo>` data can
be included in the *yaml* style dump file using the :doc:`dump_modify
thermo yes <dump_modify>`. The data included in the dump file uses the
"thermo" tag and is otherwise identical to data specified by the
:doc:`thermo_style <thermo_style>` command.
Below is an example for a YAML format dump created by the following commands.
.. code-block:: LAMMPS
dump out all yaml 100 dump.yaml id type x y z vx vy vz ix iy iz
dump_modify out time yes units yes thermo yes format 1 %5d format "% 10.6e"
The tags "time", "units", and "thermo" are optional and enabled by the
dump_modify command. The list under the "box" tag has 3 lines for
orthogonal boxes and 4 lines with triclinic boxes, where the first 3 are
the box boundaries and the 4th the three tilt factors (xy, xz, yz). The
"thermo" data follows the format of the *yaml* thermo style. The
"keywords" tag lists the per-atom properties contained in the "data"
columns, which contain a list with one line per atom. The keywords may
be renamed using the dump_modify command same as for the *custom* dump
style.
.. code-block:: yaml
---
timestep: 0
units: lj
time: 0
natoms: 4000
boundary: [ p, p, p, p, p, p, ]
thermo:
- keywords: [ Step, Temp, E_pair, E_mol, TotEng, Press, ]
- data: [ 0, 0, -27093.472213010766, 0, 0, 0, ]
box:
- [ 0, 16.795961913825074 ]
- [ 0, 16.795961913825074 ]
- [ 0, 16.795961913825074 ]
- [ 0, 0, 0 ]
keywords: [ id, type, x, y, z, vx, vy, vz, ix, iy, iz, ]
data:
- [ 1 , 1 , 0.000000e+00 , 0.000000e+00 , 0.000000e+00 , -1.841579e-01 , -9.710036e-01 , -2.934617e+00 , 0 , 0 , 0, ]
- [ 2 , 1 , 8.397981e-01 , 8.397981e-01 , 0.000000e+00 , -1.799591e+00 , 2.127197e+00 , 2.298572e+00 , 0 , 0 , 0, ]
- [ 3 , 1 , 8.397981e-01 , 0.000000e+00 , 8.397981e-01 , -1.807682e+00 , -9.585130e-01 , 1.605884e+00 , 0 , 0 , 0, ]
[...]
...
---
timestep: 100
units: lj
time: 0.5
[...]
...
----------
Note that *atom*, *custom*, *dcd*, *xtc*, and *xyz* style dump files
can be read directly by `VMD <http://www.ks.uiuc.edu/Research/vmd>`_, a
popular molecular viewing program.
@ -427,9 +492,9 @@ If a "%" character appears in the filename, then each of P processors
writes a portion of the dump file, and the "%" character is replaced
with the processor ID from 0 to P-1. For example, tmp.dump.% becomes
tmp.dump.0, tmp.dump.1, ... tmp.dump.P-1, etc. This creates smaller
files and can be a fast mode of output on parallel machines that
support parallel I/O for output. This option is not available for the
*dcd*, *xtc*, and *xyz* styles.
files and can be a fast mode of output on parallel machines that support
parallel I/O for output. This option is **not** available for the *dcd*,
*xtc*, *xyz*, and *yaml* styles.
By default, P = the number of processors meaning one file per
processor, but P can be set to a smaller value via the *nfile* or
@ -722,8 +787,8 @@ are part of the MPIIO package. They are only enabled if LAMMPS was
built with that package. See the :doc:`Build package <Build_package>`
doc page for more info.
The *xtc* and *dcd* styles are part of the EXTRA-DUMP package. They
are only enabled if LAMMPS was built with that package. See the
The *xtc*, *dcd* and *yaml* styles are part of the EXTRA-DUMP package.
They are only enabled if LAMMPS was built with that package. See the
:doc:`Build package <Build_package>` page for more info.
Related commands

36
doc/src/dump_modify.rst
View File

@ -26,6 +26,10 @@ Syntax
N = index of frame written upon first dump
*balance* arg = *yes* or *no*
*buffer* arg = *yes* or *no*
*colname* values = ID string, or *default*
string = new column header name
ID = integer from 1 to N, or integer from -1 to -N, where N = # of quantities being output
*or* a custom dump keyword or reference to compute, fix, property or variable.
*delay* arg = Dstep
Dstep = delay output until this timestep
*element* args = E1 E2 ... EN, where N = # of atom types
@ -40,9 +44,10 @@ Syntax
Np = write one file for every this many processors
*first* arg = *yes* or *no*
*flush* arg = *yes* or *no*
*format* args = *line* string, *int* string, *float* string, M string, or *none*
*format* args = *line* string, *int* string, *float* string, ID string, or *none*
string = C-style format string
M = integer from 1 to N, where N = # of per-atom quantities being output
ID = integer from 1 to N, or integer from -1 to -N, where N = # of quantities being output
*or* a custom dump keyword or reference to compute, fix, property or variable.
*header* arg = *yes* or *no*
*yes* to write the header
*no* to not write the header
@ -375,6 +380,29 @@ performed with dump style *xtc*\ .
----------
The *colname* keyword can be used to change the default header keyword
for dump styles: *atom*, *custom*, and *cfg* and their compressed, ADIOS,
and MPIIO variants. The setting for *ID string* replaces the default
text with the provided string. *ID* can be a positive integer when it
represents the column number counting from the left, a negative integer
when it represents the column number from the right (i.e. -1 is the last
column/keyword), or a custom dump keyword (or compute, fix, property, or
variable reference) and then it replaces the string for that specific
keyword. For *atom* dump styles only the keywords "id", "type", "x",
"y", "z", "ix", "iy", "iz" can be accessed via string regardless of
whether scaled or unwrapped coordinates were enabled or disabled, and
it always assumes 8 columns for indexing regardless of whether image
flags are enabled or not. For dump style *cfg* only the "auxiliary"
keywords (6th or later keyword) may be changed and the column indexing
considers only them (i.e. the 6th keyword is the the 1st column).
The *colname* keyword can be used multiple times. If multiple *colname*
settings refer to the same keyword, the last setting has precedence. A
setting of *default* clears all previous settings, reverting all values
to their default names.
----------
The *format* keyword can be used to change the default numeric format output
by the text-based dump styles: *atom*, *local*, *custom*, *cfg*, and
*xyz* styles, and their MPIIO variants. Only the *line* or *none*
@ -684,8 +712,8 @@ run, this option is ignored since the output is already balanced.
----------
The *thermo* keyword only applies the dump *netcdf* style. It
triggers writing of :doc:`thermo <thermo>` information to the dump file
The *thermo* keyword only applies the dump styles *netcdf* and *yaml*.
It triggers writing of :doc:`thermo <thermo>` information to the dump file
alongside per-atom data. The values included in the dump file are
identical to the values specified by :doc:`thermo_style <thermo_style>`.

2
doc/src/fix.rst
View File

@ -243,7 +243,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/engine <fix_mdi_engine>` - connect LAMMPS to external programs via the MolSSI Driver Interface (MDI)
* :doc:`mdi/aimd <fix_mdi_aimd>` - LAMMPS operates as driver for ab initio MD (AIMD) 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

103
doc/src/fix_mdi_aimd.rst Normal file
View File

@ -0,0 +1,103 @@
.. 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
* optional keyword = *plugin*
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all mdi/aimd
fix 1 all mdi/aimd plugin
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.
To use this fix with a plugin engine, you must specify the
*plugin* keyword as the last argument, as illustrated above.
.. note::
As of April 2022, the *plugin* keyword is needed. In a future
version of the MDI library it will no longer be necessary.
----------
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

59
doc/src/fix_mdi_engine.rst
View File

@ -1,59 +0,0 @@
.. index:: fix mdi/engine
fix mdi/engine command
======================
Syntax
""""""
.. parsed-literal::
fix ID group-ID mdi/engine
* ID, group-ID are documented in :doc:`fix <fix>` command
* mdi/engine = style name of this fix command
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all mdi/engine
Description
"""""""""""
This fix is used along with the :doc:`mdi/engine <mdi_engine>` command
to enable LAMMPS to use the `MDI Library
<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_ to run as
an MDI engine. The fix provides hooks that enable MDI driver codes to
communicate with LAMMPS at various points within a LAMMPS timestep.
It is not generally necessary to add this fix to a LAMMPS input file,
even when using the :doc:`mdi/engine <mdi_engine>` command. If the
:doc:`mdi/engine <mdi_engine>` command is executed and this fix is not
present, it will automatically be added and applied as a new fix for
all atoms for the duration of the command. Thus it is only necessary
to add this fix to an input file when you want to modify the group-ID
or the ordering of this fix relative to other fixes in the input script.
For more information about running LAMMPS as an MDI engine, see the
:doc:`mdi/engine <mdi_engine>` command and the :doc:`Howto mdi
<Howto_mdi>` doc page.
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.
Related commands
""""""""""""""""
:doc:`mdi/engine <mdi_engine>`
Default
"""""""
none

19
doc/src/fix_tmd.rst
View File

@ -29,10 +29,10 @@ Description
"""""""""""
Perform targeted molecular dynamics (TMD) on a group of atoms. A
holonomic constraint is used to force the atoms to move towards (or
away from) the target configuration. The parameter "rho" is
monotonically decreased (or increased) from its initial value to
rho_final at the end of the run.
holonomic constraint is used to force the atoms to move towards (or away
from) the target configuration. The parameter "rho" is monotonically
decreased (or increased) from its initial value to rho_final at the end
of the run.
Rho has distance units and is a measure of the root-mean-squared
distance (RMSD) between the current configuration of the atoms in the
@ -55,22 +55,25 @@ a .gz suffix). The format of the target file1 is as follows:
The first 3 lines may or may not be needed, depending on the format of
the atoms to follow. If image flags are included with the atoms, the
first 3 lo/hi lines must appear in the file. If image flags are not
included, the first 3 lines should not appear. The 3 lines contain the
first 3 lo/hi lines **must** appear in the file. If image flags are not
included, the first 3 lines **must not** appear. The 3 lines contain the
simulation box dimensions for the atom coordinates, in the same format
as in a LAMMPS data file (see the :doc:`read_data <read_data>` command).
The remaining lines each contain an atom ID and its target x,y,z
coordinates. The atom lines (all or none of them) can optionally be
followed by 3 integer values: nx,ny,nz. For periodic dimensions, they
followed by 3 integer values: nx,ny,nz.For periodic dimensions, they
specify which image of the box the atom is considered to be in, i.e. a
value of N (positive or negative) means add N times the box length to
the coordinate to get the true value.
the coordinate to get the true value. Those 3 integers either must
be given for all atoms or none.
The atom lines can be listed in any order, but every atom in the group
must be listed in the file. Atoms not in the fix group may also be
listed; they will be ignored.
Comments starting with '#' and empty lines may be included as well.
TMD statistics are written to file2 every N timesteps, unless N is
specified as 0, which means no statistics.

8
doc/src/fix_ttm.rst
View File

@ -154,7 +154,7 @@ of the electronic specific heat, but ignored temperature dependencies
of any of the other parameters. See more discussion below for fix
ttm/mod.
..note::
.. note::
These fixes do not perform time integration of the atoms in the fix
group, they only rescale their velocities. Thus a time integration
@ -164,7 +164,7 @@ ttm/mod.
fix, e.g. :doc:`fix nvt <fix_nh>` or :doc:`fix langevin
<fix_langevin>`.
..note::
.. note::
These fixes require use of an orthogonal 3d simulation box with
periodic boundary conditions in all dimensions. They also require
@ -305,8 +305,8 @@ is calculated as
where lambda is the electron mean free path (see :ref:`(Norman) <Norman>`,
:ref:`(Pisarev) <Pisarev>`)
The fix ttm/mod parameter file *init_file* has the following syntax/
Every line with the odd number is considered as a comment and
The fix ttm/mod parameter file *init_file* has the following syntax.
Every line with an odd number is considered as a comment and
ignored. The lines with the even numbers are treated as follows:
.. parsed-literal::

312
doc/src/mdi.rst Normal file
View File

@ -0,0 +1,312 @@
.. index:: mdi
mdi command
==================
Syntax
""""""
.. parsed-literal::
mdi mode args
* mode = *engine* or *plugin*
.. parsed-literal::
*engine* args = none
*plugin* args = name keyword value keyword value
name = name of plugin library, e.g. lammps means a liblammps.so library will be loaded
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
*extra* value = aditional command-line args to pass to engine library when loaded
*command* value = a LAMMPS input script command to execute
Examples
""""""""
.. code-block:: LAMMPS
mdi engine
mdi plugin lammps mdi "-role ENGINE -name lammps -method LINK" &
infile in.aimd.engine extra "-log log.aimd.engine.plugin" &
command "run 5"
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.
See the Howto MDI doc page for a discussion of all the different ways
2 or more codes can interact via MDI.
The examples/mdi directory has examples which use LAMMPS in 4
different modes: as a driver using an engine as either a stand-alone
code or as a plugin, and as an engine operating as either a
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 *mdi engine* command is used to make LAMMPS operate as an MDI
engine. It is typically used in an input script after LAMMPS has
setup the system it is going to model consistent with what the driver
code expects. Depending on when the driver code tells the LAMMPS
engine to exit, other commands can be executed after this command, but
typically it is used at the end of a LAMMPS input script.
To act as an MDI engine operating as an MD code (or surrogate QM
code), this is the list of standard MDI commands issued by a driver
code which LAMMPS currently recognizes. Using standard commands
defined by the MDI library means that a driver code can work
interchangeably with LAMMPS or other MD codes or with QM codes which
support the MDI standard. See more details about these commands in
the `MDI library documentation
<https://molssi-mdi.github.io/MDI_Library/html/mdi_standard.html>`_
These commands are valid at the @DEFAULT node defined by MDI.
Commands that start with ">" mean the driver is sending information to
LAMMPS. Commands that start with "<" are requests by the driver for
LAMMPS to send it information. Commands that start with an alphabetic
letter perform actions. Commands that start with "@" are MDI "node"
commands, which are described further below.
.. list-table::
:widths: 20 80
:header-rows: 1
* - Command name
- Action
* - >CELL or <CELL
- Send/request 3 simulation box edge vectors (9 values)
* - >CELL_DISPL or <CELL_DISPL
- Send/request displacement of the simulation box from the origin (3 values)
* - >CHARGES or <CHARGES
- Send/request charge on each atom (N values)
* - >COORDS or <COORDS
- Send/request coordinates of each atom (3N values)
* - <ENERGY
- Request total energy (potential + kinetic) of the system (1 value)
* - >FORCES or <FORCES
- Send/request forces on each atom (3N values)
* - >+FORCES
- Send forces to add to each atom (3N values)
* - <LABELS
- Request string label of each atom (N values)
* - <MASSES
- Request mass of each atom (N values)
* - MD
- Perform an MD simulation for N timesteps (most recent >NSTEPS value)
* - OPTG
- Perform an energy minimization to convergence (most recent >TOLERANCE values)
* - >NATOMS or <NATOMS
- Sends/request number of atoms in the system (1 value)
* - >NSTEPS
- Send number of timesteps for next MD dynamics run via MD command
* - <PE
- Request potential energy of the system (1 value)
* - <STRESS
- Request stress tensor (virial) of the system (6 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)
* - >VELOCITIES or <VELOCITIES
- Send/request the velocity of each atom (3N values)
* - @INIT_MD or @INIT_OPTG
- Driver tells LAMMPS to start single-step dynamics or minimization (see below)
* - EXIT
- Driver tells LAMMPS to exit engine mode
.. note::
The <ENERGY, <FORCES, <PE, and <STRESS commands trigger LAMMPS to
compute atomic interactions for the current configuration of atoms
and size/shape of the simulation box. I.e. LAMMPS invokes its
pair, bond, angle, ..., kspace styles. If the driver is updating
the atom coordinates and/or box incrementally (as in an MD
simulation which the driver is managing), then the LAMMPS engine
will do the same, and only occasionally trigger neighbor list
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.
The MD and OPTG commands perform an entire MD simulation or energy
minimization (to convergence) with no communication from the driver
until the simulation is complete. By contrast, the @INIT_MD and
@INIT_OPTG commands allow the driver to communicate with the engine at
each timestep of a dynamics run or iteration of a minimization; see
more info below.
The MD command performs a simulation using the most recent >NSTEPS
value. The OPTG command performs a minimization using the 4
convergence parameters from the most recent >TOLERANCE command. The 4
parameters sent are those used by the :doc:`minimize <minimize>`
command in LAMMPS: etol, ftol, maxiter, and maxeval.
The mdi engine command also implements the following custom MDI
commands which are LAMMPS-specific. These commands are also valid at
the @DEFAULT node defined by MDI:
* - Command name
- Action
* - >NBYTES
- Send # of datums in a subsequent command (1 value)
* - >COMMAND
- Send a LAMMPS input script command as a string (Nbytes in length)
* - >COMMANDS
- Send multiple LAMMPS input script commands as a newline-separated string (Nbytes in length)
* - >INFILE
- Send filename of an input script to execute (filename Nbytes in length)
* - <KE
- Request kinetic energy of the system (1 value)
Note that other custom commands can easily be added if these are not
sufficient to support what a user-written driver code needs. Code to
support new commands can be added to the MDI package within LAMMPS,
specifically to the src/MDI/mdi_engine.cpp file.
MDI also defines a standard mechanism for the driver to request that
an MD engine (LAMMPS) perform a dynamics simulation one step at a time
or an energy minimization one iteration at a time. This is so that
the driver can (optionally) communicate with LAMMPS at intermediate
points of the timestep or iteration by issuing MDI node commands which
start with "@".
To tell LAMMPS to run dynamics in single-step mode, the driver sends
as @INIT_MD command followed by the these commands. The driver
can interact with LAMMPS at 3 node locations within each
timestep: @COORDS, @FORCES, @ENDSTEP:
* - Command name
- Action
* - @COORDS
- Proceed to next @COORDS node = post-integrate location in LAMMPS timestep
* - @FORCES
- Proceed to next @FORCES node = post-force location in LAMMPS timestep
* - @ENDSTEP
- Proceed to next @ENDSTEP node = end-of-step location in LAMMPS timestep
* - @DEFAULT
- Exit MD simulation, return to @DEFAULT node
* - EXIT
- Driver tells LAMMPS to exit the MD simulation and engine mode
To tell LAMMPS to run an energy minimization in single-iteration mode.
The driver can interact with LAMMPS at 2 node locations within each
iteration of the minimizer: @COORDS, @FORCES:
* - Command name
- Action
* - @COORDS
- Proceed to next @COORDS node = min-pre-force location in LAMMPS min iteration
* - @FORCES
- Proceed to next @FORCES node = min-post-force location in LAMMPS min iteration
* - @DEFAULT
- Exit minimization, return to @DEFAULT node
* - EXIT
- Driver tells LAMMPS to exit the minimization and engine mode
While LAMMPS is at its @COORDS node, the following standard MDI
commands are supported, as documented above: >COORDS or <COORDS,
@COORDS, @FORCES, @ENDSTEP, @DEFAULT, EXIT.
While LAMMPS is at its @FORCES node, the following standard MDI
commands are supported, as documented above: <COORDS, <ENERGY, >FORCES
or >+FORCES or <FORCES, <KE, <PE, <STRESS, @COORDS, @FORCES, @ENDSTEP,
@DEFAULT, EXIT.
While LAMMPS is at its @ENDSTEP node, the following standard MDI
commands are supported, as documented above: <ENERGY, <FORCES, <KE,
<PE, <STRESS, @COORDS, @FORCES, @ENDSTEP, @DEFAULT, EXIT.
----------
The *mdi plugin* command is used to make LAMMPS operate as an MDI
driver which loads an MDI engine as a plugin library. It is typically
used in an input script after LAMMPS has setup the system it is going
to model consistent with the engine code.
The *name* argument specifies which plugin library to load. A name
like "lammps" is converted to a filename liblammps.so. The path for
where this file is located is specified by the -plugin_path switch
within the -mdi command-line switch, which is specified when LAMMPS is
launched. See the examples/mdi/README files for examples of how this
is done.
The *mdi* keyword is required and is used as the -mdi argument passed
to the library when it is launched. The -role and -method settings
are required. The -name setting can be anything you choose. MDI
drivers and engines can query their names to verify they are values
they expect.
The *infile* keyword is also required. It is the name of an input
script which the engine will open and process. MDI will pass it as a
command-line argument to the library when it is launched. The file
typically contains settings that an MD or QM code will use for its
subsequent calculations.
The *extra* keyword is optional. It contains additional command-line
arguments which MDI will pass to the library when it is launched.
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
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.
.. note::
When the single *command* is complete, LAMMPS will send an MDI
EXIT command to the plugin engine and the plugin will be removed.
The "mdi plugin" command will then exit and the next command
(if any) in the LAMMPS input script will be processed. A subsequent
"mdi plugin" command could then load the same library plugin or
a different one if desired.
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 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 engine in other unit choices it
supports, e.g. *lj*, but then no unit conversion is performed.
Related commands
""""""""""""""""
:doc:`fix mdi/aimd <fix_mdi_aimd>`
Default
"""""""
None

88
doc/src/mdi_engine.rst
View File

@ -1,88 +0,0 @@
.. index:: mdi/engine
mdi_engine command
==================
Syntax
""""""
.. parsed-literal::
mdi_engine
Description
"""""""""""
This command is used to have LAMMPS act as a server with another
client code to effectively couple the two codes together in
client/server mode.
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 engine (server), responding to commands made by an
external MDI driver code (client). See the :doc:`Howto mdi
<Howto_mdi>` page for more information about how LAMMPS can work
as both an MDI driver or engine.
General information about launching codes that communicate using the
MDI Library can be found in the `corresponding page
<https://molssi-mdi.github.io/MDI_Library/html/library_page.html#library_launching_sec>`_
of the MDI Library's documentation.
----------
This command should typically be used in an input script after LAMMPS
has setup the system it is going to model in collaboration with the
driver code. Depending on how the driver code tells the LAMMPS engine
to exit, other commands can be executed after this command, but
typically it should be used at the end of the LAMMPS input script.
To act as a MD-based MDI engine, this is the list of MDI commands from
a driver code which LAMMPS currently recognizes. See more details
about these commands in the `MDI library documentation
<https://molssi-mdi.github.io/MDI_Library/html/mdi_standard.html>`_
.. NOTE: Taylor - is this the best link for this info? Can we flesh this
.. out with the full list of supported commands? Maybe the distinction
.. of what "node" the commands refer to is not needed in this table?
.. list-table::
:widths: 20 80
:header-rows: 1
* - Command name
- Action
* - >NATOMS
- Driver sends the number of atoms in the system
* - <NATOMS
- Driver requests the number of atoms in the system
* - <COORDS
- Driver requests 3*N double-precision atom coordinates
* - >FORCES
- Driver sends 3*N double-precision atom forces
* - <COORDS
- Driver requests 3*N double-precision atom forces
* - EXIT
- Driver tells the engine (LAMMPS) to exit engine mode
If these commands are not sufficient to support what a driver which
you write needs, additional commands can be defined by simply using a
new command name not in this list. Code to support the new command
needs to be added to the MDI package within LAMMPS; see its
src/MDI/mdi_engine.cpp and fix_mdi_engine.cpp files.
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.
Related commands
""""""""""""""""
:doc:`fix mdi/engine <fix_mdi_engine>`
Default
"""""""
None

19
doc/src/package.rst
View File

@ -467,14 +467,14 @@ simple pairwise potentials such as Lennard-Jones do support threading
over both atoms and neighbors.
If the *neigh/transpose* keyword is set to *off*, then the KOKKOS
package will use the same memory layout for building the neigh list on
package will use the same memory layout for building the neighbor list on
GPUs as used for the pair style. When this keyword is set to *on* it
will use a different (transposed) memory layout to build the neigh
will use a different (transposed) memory layout to build the neighbor
list on GPUs. This can be faster in some cases (e.g. ReaxFF HNS
benchmark) but slower in others (e.g. Lennard Jones benchmark). The
copy between different memory layouts is done out of place and
therefore doubles the memory overhead of the neigh list, which can be
signicant.
therefore doubles the memory overhead of the neighbor list, which can
be significant.
The *newton* keyword sets the Newton flags for pairwise and bonded
interactions to *off* or *on*, the same as the :doc:`newton <newton>`
@ -484,11 +484,12 @@ computation is done, but less communication. However, when running on
CPUs a value of *on* is the default since it can often be faster, just
as it is for non-accelerated pair styles
The *binsize* keyword sets the size of bins used to bin atoms in
neighbor list builds. The same value can be set by the :doc:`neigh_modify binsize <neigh_modify>` command. Making it an option in the package
kokkos command allows it to be set from the command line. The default
value for CPUs is 0.0, which means the LAMMPS default will be used,
which is bins = 1/2 the size of the pairwise cutoff + neighbor skin
The *binsize* keyword sets the size of bins used to bin atoms during
neighbor list builds. The same value can be set by the
:doc:`neigh_modify binsize <neigh_modify>` command. Making it an option
in the package kokkos command allows it to be set from the command line.
The default value for CPUs is 0.0, which means the LAMMPS default will be
used, which is bins = 1/2 the size of the pairwise cutoff + neighbor skin
distance. This is fine when neighbor lists are built on the CPU. For GPU
builds, a 2x larger binsize equal to the pairwise cutoff + neighbor skin
is often faster, which is the default. Note that if you use a

6
doc/src/pair_dpd.rst
View File

@ -1,20 +1,22 @@
.. index:: pair_style dpd
.. index:: pair_style dpd/gpu
.. index:: pair_style dpd/intel
.. index:: pair_style dpd/kk
.. index:: pair_style dpd/omp
.. index:: pair_style dpd/tstat
.. index:: pair_style dpd/tstat/gpu
.. index:: pair_style dpd/tstat/kk
.. index:: pair_style dpd/tstat/omp
pair_style dpd command
======================
Accelerator Variants: *dpd/gpu*, *dpd/intel*, *dpd/omp*
Accelerator Variants: *dpd/gpu*, *dpd/intel*, *dpd/kk*, *dpd/omp*
pair_style dpd/tstat command
============================
Accelerator Variants: *dpd/tstat/gpu*, *dpd/tstat/omp*
Accelerator Variants: *dpd/tstat/gpu*, *dpd/tstat/kk*, *dpd/tstat/omp*
Syntax
""""""

10
doc/src/pair_dpd_ext.rst
View File

@ -1,12 +1,18 @@
.. index:: pair_style dpd/ext
.. index:: pair_style dpd/ext/kk
.. index:: pair_style dpd/ext/tstat
.. index:: pair_style dpd/ext/tstat/kk
pair_style dpd/ext command
==========================
Accelerator Variants: dpd/ext/kk
pair_style dpd/ext/tstat command
================================
Accelerator Variants: dpd/ext/tstat/kk
Syntax
""""""
@ -137,6 +143,10 @@ except that A is not included.
----------
.. include:: accel_styles.rst
----------
**Mixing, shift, table, tail correction, restart, rRESPA info**\ :

9
doc/src/plugin.rst
View File

@ -70,12 +70,11 @@ Restrictions
""""""""""""
The *plugin* command is part of the PLUGIN package. It is
only enabled if LAMMPS was built with that package.
See the :doc:`Build package <Build_package>` page for
more info. Plugins are not available on Windows.
only enabled if LAMMPS was built with that package. See
the :doc:`Build package <Build_package>` page for more info.
If plugins access functions or classes from a package, LAMMPS must
have been compiled with that package included.
If plugins access functions or classes from a package,
LAMMPS must have been compiled with that package included.
Plugins are dependent on the LAMMPS binary interface (ABI)
and particularly the MPI library used. So they are not guaranteed

43
doc/src/thermo_modify.rst
View File

@ -21,9 +21,14 @@ Syntax
*norm* value = *yes* or *no*
*flush* value = *yes* or *no*
*line* value = *one* or *multi* or *yaml*
*format* values = *line* string, *int* string, *float* string, M string, or *none*
*colname* values = ID string, or *default*
string = new column header name
ID = integer from 1 to N, or integer from -1 to -N, where N = # of quantities being output
*or* a thermo keyword or reference to compute, fix, property or variable.
*format* values = *line* string, *int* string, *float* string, ID string, or *none*
string = C-style format string
M = integer from 1 to N, where N = # of quantities being output
ID = integer from 1 to N, or integer from -1 to -N, where N = # of quantities being output
*or* a thermo keyword or reference to compute, fix, property or variable.
*temp* value = compute ID that calculates a temperature
*press* value = compute ID that calculates a pressure
@ -36,7 +41,8 @@ Examples
thermo_modify temp myTemp format 3 %15.8g
thermo_modify temp myTemp format line "%ld %g %g %15.8g"
thermo_modify line multi format float %g
themos_modify line yaml format none
thermo_modify line yaml format none
thermo_modify colname 1 Timestep colname -2 Pressure colname f_1[1] AvgDensity
Description
"""""""""""
@ -147,6 +153,20 @@ containing the timestep and CPU time ("multi"), or in a YAML format
block ("yaml"). This modify option overrides the *one*, *multi*, or
*yaml* thermo_style settings.
The *colname* keyword can be used to change the default header keyword
for a column or field of thermodynamic output. The setting for *ID
string* replaces the default text with the provided string. *ID* can be
a positive integer when it represents the column number counting from
the left, a negative integer when it represents the column number from
the right (i.e. -1 is the last column/keyword), or a thermo keyword (or
compute, fix, property, or variable reference) and then it replaces the
string for that specific thermo keyword.
The *colname* keyword can be used multiple times. If multiple *colname*
settings refer to the same keyword, the last setting has precedence. A
setting of *default* clears all previous settings, reverting all values
to their default values.
The *format* keyword can be used to change the default numeric format of
any of quantities the :doc:`thermo_style <thermo_style>` command
outputs. All the specified format strings are C-style formats, e.g. as
@ -155,12 +175,16 @@ argument which is the format string for the entire line of thermo
output, with N fields, which you must enclose in quotes if it is more
than one field. The *int* and *float* keywords take a single format
argument and are applied to all integer or floating-point quantities
output. The setting for *M string* also takes a single format argument
which is used for the Mth value output in each line, e.g. the fifth
column is output in high precision for "format 5 %20.15g".
output. The setting for *ID string* also takes a single format argument
which is used for the indexed value in each line. The interpretation is
the same as for *colname*, i.e. a positive integer is the n-th value
corresponding to the n-th thermo keyword, a negative integer is counting
backwards, and a string matches the entry with the thermo keyword.,
e.g. the fifth column is output in high precision for "format 5 %20.15g"
and the pair energy for "format epair %20.15g".
The *format* keyword can be used multiple times. The precedence is
that for each value in a line of output, the *M* format (if specified)
that for each value in a line of output, the *ID* format (if specified)
is used, else the *int* or *float* setting (if specified) is used,
else the *line* setting (if specified) for that value is used, else
the default setting is used. A setting of *none* clears all previous
@ -173,9 +197,10 @@ settings, reverting all values to their default format.
When specifying the *format int* option you can use a "%d"-style
format identifier in the format string and LAMMPS will convert this
to the corresponding 8-byte form when it is applied to those
keywords. However, when specifying the *line* option or *format M
keywords. However, when specifying the *line* option or *format ID
string* option for *step* and *natoms*, you should specify a format
string appropriate for an 8-byte signed integer, e.g. one with "%ld".
string appropriate for an 8-byte signed integer, e.g. one with "%ld"
or "%lld" depending on the platform.
The *temp* keyword is used to determine how thermodynamic temperature is
calculated, which is used by all thermo quantities that require a