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

Merge branch 'develop' into dielectric-updates

Browse Source
This commit is contained in:
Trung Nguyen
2022-04-12 16:33:02 -05:00
committed by GitHub
parent ef53298f7c 2ff8ac0cb2
commit 616349c27b
952 changed files with 23964 additions and 39343 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
doc/src/Build_extras.rst
View File

@ -45,7 +45,6 @@ This is the list of packages that may require additional steps.
* :ref:`MACHDYN <machdyn>`
* :ref:`MDI <mdi>`
* :ref:`MESONT <mesont>`
* :ref:`MESSAGE <message>`
* :ref:`ML-HDNNP <ml-hdnnp>`
* :ref:`ML-IAP <mliap>`
* :ref:`ML-PACE <ml-pace>`
@ -797,47 +796,6 @@ library.
----------
.. _message:
MESSAGE package
-----------------------------
This package can optionally include support for messaging via sockets,
using the open-source `ZeroMQ library <http://zeromq.org>`_, which must
be installed on your system.
.. tabs::
.. tab:: CMake build
.. code-block:: bash
-D MESSAGE_ZMQ=value # build with ZeroMQ support, value = no (default) or yes
-D ZMQ_LIBRARY=path # ZMQ library file (only needed if a custom location)
-D ZMQ_INCLUDE_DIR=path # ZMQ include directory (only needed if a custom location)
.. tab:: Traditional make
Before building LAMMPS, you must build the CSlib library in
``lib/message``\ . You can build the CSlib library manually if
you prefer; follow the instructions in ``lib/message/README``\ .
You can also do it in one step from the ``lammps/src`` dir, using
a command like these, which simply invoke the
``lib/message/Install.py`` script with the specified args:
.. code-block:: bash
$ make lib-message # print help message
$ make lib-message args="-m -z" # build with MPI and socket (ZMQ) support
$ make lib-message args="-s" # build as serial lib with no ZMQ support
The build should produce two files: ``lib/message/cslib/src/libmessage.a``
and ``lib/message/Makefile.lammps``. The latter is copied from an
existing ``Makefile.lammps.*`` and has settings to link with the ZeroMQ
library if requested in the build.
----------
.. _mliap:
ML-IAP package

1
doc/src/Build_package.rst
View File

@ -45,7 +45,6 @@ packages:
* :ref:`KOKKOS <kokkos>`
* :ref:`LATTE <latte>`
* :ref:`MACHDYN <machdyn>`
* :ref:`MESSAGE <message>`
* :ref:`ML-HDNNP <ml-hdnnp>`
* :ref:`ML-PACE <ml-pace>`
* :ref:`ML-QUIP <ml-quip>`

4
doc/src/Commands_all.rst
View File

@ -67,8 +67,7 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`lattice <lattice>`
* :doc:`log <log>`
* :doc:`mass <mass>`
* :doc:`mdi/engine <mdi_engine>`
* :doc:`message <message>`
* :doc:`mdi <mdi>`
* :doc:`minimize <minimize>`
* :doc:`min_modify <min_modify>`
* :doc:`min_style <min_style>`
@ -105,7 +104,6 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`restart <restart>`
* :doc:`run <run>`
* :doc:`run_style <run_style>`
* :doc:`server <server>`
* :doc:`set <set>`
* :doc:`shell <shell>`
* :doc:`special_bonds <special_bonds>`

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>`

3
doc/src/Commands_fix.rst
View File

@ -51,7 +51,6 @@ OPT.
* :doc:`bond/swap <fix_bond_swap>`
* :doc:`box/relax <fix_box_relax>`
* :doc:`charge/regulation <fix_charge_regulation>`
* :doc:`client/md <fix_client_md>`
* :doc:`cmap <fix_cmap>`
* :doc:`colvars <fix_colvars>`
* :doc:`controller <fix_controller>`
@ -101,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.

4
doc/src/Examples.rst
View File

@ -94,12 +94,12 @@ 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 |
+-------------+------------------------------------------------------------------+
| message | demos for LAMMPS client/server coupling with the MESSAGE package |
+-------------+------------------------------------------------------------------+
| micelle | self-assembly of small lipid-like molecules into 2d bilayers |
+-------------+------------------------------------------------------------------+
| min | energy minimization of 2d LJ melt |

1
doc/src/Howto.rst
View File

@ -22,7 +22,6 @@ General howto
Howto_replica
Howto_library
Howto_couple
Howto_client_server
Howto_mdi
Settings howto

163
doc/src/Howto_client_server.rst
View File

@ -1,163 +0,0 @@
Using LAMMPS in client/server mode
==================================
Client/server coupling of two codes is where one code is the "client"
and sends request messages 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.
Some advantages of client/server coupling are that the two codes run
as stand-alone executables; they are not linked together. Thus
neither code needs to have a library interface. This often makes it
easier 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 that implements the
client-side protocol can be used in tandem with any code that
implements the server-side protocol, without the two codes needing to
know anything more specific about each other.
A simple example of client/server coupling is where LAMMPS is the
client code performing MD timestepping. Each timestep it sends a
message to a server quantum code containing current coords of all the
atoms. The quantum code computes energy and forces based on the
coords. It returns them as a message to LAMMPS, which completes the
timestep.
A more complex example is where LAMMPS is the client code and
processes a series of data files, sending each configuration to a
quantum code to compute energy and forces. Or LAMMPS runs dynamics
with an atomistic force field, but pauses every N steps to ask the
quantum code to compute energy and forces.
Alternate methods for code coupling with LAMMPS are described on
the :doc:`Howto couple <Howto_couple>` doc page.
The protocol for using LAMMPS as a client is to use these 3 commands
in this order (other commands may come in between):
* :doc:`message client <message>` # initiate client/server interaction
* :doc:`fix client/md <fix_client_md>` # any client fix which makes specific requests to the server
* :doc:`message quit <message>` # terminate client/server interaction
In between the two message commands, a client fix command and
:doc:`unfix <unfix>` command can be used multiple times. Similarly,
this sequence of 3 commands can be repeated multiple times, assuming
the server program operates in a similar fashion, to initiate and
terminate client/server communication.
The protocol for using LAMMPS as a server is to use these 2 commands
in this order (other commands may come in between):
* :doc:`message server <message>` # initiate client/server interaction
* :doc:`server md <server_md>` # any server command which responds to specific requests from the client
This sequence of 2 commands can be repeated multiple times, assuming
the client program operates in a similar fashion, to initiate and
terminate client/server communication.
LAMMPS support for client/server coupling is in its :ref:`MESSAGE package <PKG-MESSAGE>` which implements several
commands that enable LAMMPS to act as a client or server, as discussed
below. The MESSAGE package also wraps a client/server library called
CSlib which enables two codes to exchange messages in different ways,
either via files, sockets, or MPI. The CSlib is provided with LAMMPS
in the lib/message dir. The CSlib has its own
`website <https://cslib.sandia.gov>`_ with documentation and test
programs.
.. note::
For client/server coupling to work between LAMMPS and another
code, the other code also has to use the CSlib. This can sometimes be
done without any modifications to the other code by simply wrapping it
with a Python script that exchanges CSlib messages with LAMMPS and
prepares input for or processes output from the other code. The other
code also has to implement a matching protocol for the format and
content of messages that LAMMPS exchanges with it.
These are the commands currently in the MESSAGE package for two
protocols, MD and MC (Monte Carlo). New protocols can easily be
defined and added to this directory, where LAMMPS acts as either the
client or server.
* :doc:`message <message>`
* :doc:`fix client md <fix_client_md>` = LAMMPS is a client for running MD
* :doc:`server md <server_md>` = LAMMPS is a server for computing MD forces
* :doc:`server mc <server_mc>` = LAMMPS is a server for computing a Monte Carlo energy
The server doc files give details of the message protocols
for data that is exchanged between the client and server.
These example directories illustrate how to use LAMMPS as either a
client or server code:
* examples/message
* examples/COUPLE/README
* examples/COUPLE/lammps_mc
* examples/COUPLE/lammps_nwchem
* examples/COUPLE/lammps_vasp
The examples/message directory couples a client instance of LAMMPS to a
server instance of LAMMPS.
The files in the *lammps_mc* folder show how to couple LAMMPS as
a server to a simple Monte Carlo client code as the driver.
The files in the *lammps_nwchem* folder show how to couple LAMMPS
as a client code running MD timestepping to NWChem acting as a
server providing quantum DFT forces, through a Python wrapper script
on NWChem.
The files in the *lammps_vasp* folder show how to couple LAMMPS as
a client code running MD timestepping to VASP acting as a server
providing quantum DFT forces, through a Python wrapper script on VASP.
Here is how to launch a client and server code together for any of the
4 modes of message exchange that the :doc:`message <message>` command
and the CSlib support. Here LAMMPS is used as both the client and
server code. Another code could be substituted for either.
The examples below show launching both codes from the same window (or
batch script), using the "&" character to launch the first code in the
background. For all modes except *mpi/one*, you could also launch the
codes in separate windows on your desktop machine. It does not
matter whether you launch the client or server first.
In these examples either code can be run on one or more processors.
If running in a non-MPI mode (file or zmq) you can launch a code on a
single processor without using mpirun.
IMPORTANT: If you run in mpi/two mode, you must launch both codes via
mpirun, even if one or both of them runs on a single processor. This
is so that MPI can figure out how to connect both MPI processes
together to exchange MPI messages between them.
For message exchange in *file*, *zmq*, or *mpi/two* modes:
.. code-block:: bash
% mpirun -np 1 lmp_mpi -log log.client < in.client &
% mpirun -np 2 lmp_mpi -log log.server < in.server
% mpirun -np 4 lmp_mpi -log log.client < in.client &
% mpirun -np 1 lmp_mpi -log log.server < in.server
% mpirun -np 2 lmp_mpi -log log.client < in.client &
% mpirun -np 4 lmp_mpi -log log.server < in.server
For message exchange in *mpi/one* mode:
Launch both codes in a single mpirun command:
.. code-block:: bash
mpirun -np 2 lmp_mpi -mpicolor 0 -in in.message.client -log log.client : -np 4 lmp_mpi -mpicolor 1 -in in.message.server -log log.server
The two -np values determine how many procs the client and the server
run on.
A LAMMPS executable run in this manner must use the -mpicolor color
command-line option as their its option, where color is an integer
label that will be used to distinguish one executable from another in
the multiple executables that the mpirun command launches. In this
example the client was colored with a 0, and the server with a 1.

28
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,6 +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 client/server <Howto_client_server>` doc
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.

216
doc/src/Howto_mdi.rst
View File

@ -1,132 +1,144 @@
Using LAMMPS with the MDI library for code coupling
===================================================
.. note::
This Howto page will eventually replace the
:doc:`Howto client/server <Howto_client_server>` doc page.
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])

2
doc/src/Install_mac.rst
View File

@ -5,7 +5,7 @@ LAMMPS can be downloaded, built, and configured for OS X on a Mac with
`Homebrew <homebrew_>`_. (Alternatively, see the install instructions for
:doc:`Download an executable via Conda <Install_conda>`.) The following LAMMPS
packages are unavailable at this time because of additional needs not yet met:
GPU, KOKKOS, LATTE, MSCG, MESSAGE, MPIIO POEMS VORONOI.
GPU, KOKKOS, LATTE, MSCG, MPIIO, POEMS, VORONOI.
After installing Homebrew, you can install LAMMPS on your system with
the following commands:

43
doc/src/Packages_details.rst
View File

@ -72,7 +72,6 @@ page gives those details.
* :ref:`MDI <PKG-MDI>`
* :ref:`MEAM <PKG-MEAM>`
* :ref:`MESONT <PKG-MESONT>`
* :ref:`MESSAGE <PKG-MESSAGE>`
* :ref:`MGPT <PKG-MGPT>`
* :ref:`MISC <PKG-MISC>`
* :ref:`ML-HDNNP <PKG-ML-HDNNP>`
@ -1408,17 +1407,25 @@ 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 <mdi>` 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
----------
@ -1495,32 +1502,6 @@ Philipp Kloza (U Cambridge)
----------
.. _PKG-MESSAGE:
MESSAGE package
---------------
**Contents:**
Commands to use LAMMPS as either a client or server and couple it to
another application.
**Install:**
This package has :ref:`specific installation instructions <message>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
* src/MESSAGE: filenames -> commands
* lib/message/README
* :doc:`message <message>`
* :doc:`fix client/md <fix_client_md>`
* :doc:`server md <server_md>`
* :doc:`server mc <server_mc>`
* examples/message
----------
.. _PKG-MGPT:
MGPT package

7
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
@ -258,11 +258,6 @@ whether an extra library is needed to build and use the package:
- pair styles :doc:`mesont/tpm <pair_mesont_tpm>`, :doc:`mesocnt <pair_mesocnt>`
- PACKAGES/mesont
- int
* - :ref:`MESSAGE <PKG-MESSAGE>`
- client/server messaging
- :doc:`message <message>`
- message
- int
* - :ref:`MGPT <PKG-MGPT>`
- fast MGPT multi-ion potentials
- :doc:`pair_style mgpt <pair_mgpt>`

9
doc/src/Run_options.rst
View File

@ -226,15 +226,6 @@ other executable(s) perform an MPI_Comm_split() with their own colors
to shrink the MPI_COMM_WORLD communication to be the subset of
processors they are actually running on.
Currently, this is only used in LAMMPS to perform client/server
messaging with another application. LAMMPS can act as either a client
or server (or both). More details are given on the :doc:`Howto client/server <Howto_client_server>` doc page.
Specifically, this refers to the "mpi/one" mode of messaging provided
by the :doc:`message <message>` command and the CSlib library LAMMPS
links with from the lib/message directory. See the
:doc:`message <message>` command for more details.
----------
.. _cite:

6
doc/src/commands_list.rst
View File

@ -59,8 +59,7 @@ Commands
lattice
log
mass
mdi_engine
message
mdi
min_modify
min_spin
min_style
@ -96,9 +95,6 @@ Commands
restart
run
run_style
server
server_mc
server_md
set
shell
special_bonds

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>`.

3
doc/src/fix.rst
View File

@ -194,7 +194,6 @@ accelerated styles exist.
* :doc:`bond/swap <fix_bond_swap>` - Monte Carlo bond swapping
* :doc:`box/relax <fix_box_relax>` - relax box size during energy minimization
* :doc:`charge/regulation <fix_charge_regulation>` - Monte Carlo sampling of charge regulation
* :doc:`client/md <fix_client_md>` - MD client for client/server simulations
* :doc:`cmap <fix_cmap>` - enables CMAP cross-terms of the CHARMM force field
* :doc:`colvars <fix_colvars>` - interface to the collective variables "Colvars" library
* :doc:`controller <fix_controller>` - apply control loop feedback mechanism
@ -244,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

118
doc/src/fix_client_md.rst
View File

@ -1,118 +0,0 @@
.. index:: fix client/md
fix client/md command
=====================
Syntax
""""""
.. parsed-literal::
fix ID group-ID client/md
* ID, group-ID are documented in :doc:`fix <fix>` command
* client/md = style name of this fix command
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all client/md
Description
"""""""""""
This fix style enables LAMMPS to run as a "client" code and
communicate each timestep with a separate "server" code to perform an
MD simulation together.
The :doc:`Howto client/server <Howto_client_server>` page gives an
overview of client/server coupling of LAMMPS with another code where
one code is the "client" and sends request messages 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.
When using this fix, LAMMPS (as the client code) passes the current
coordinates of all particles to the server code each timestep, which
computes their interaction, and returns the energy, forces, and virial
for the interacting particles to LAMMPS, so it can complete the
timestep.
Note that the server code can be a quantum code, or another classical
MD code which encodes a force field (pair_style in LAMMPS lingo) which
LAMMPS does not have. In the quantum case, this fix is a mechanism
for running *ab initio* MD with quantum forces.
The group associated with this fix is ignored.
The protocol and :doc:`units <units>` for message format and content
that LAMMPS exchanges with the server code is defined on the
:doc:`server md <server_md>` doc page.
Note that when using LAMMPS as an MD client, your LAMMPS input script
should not normally contain force field commands, like a
:doc:`pair_style <pair_style>`, :doc:`bond_style <bond_style>`, or
:doc:`kspace_style <kspace_style>` command. However it is possible
for a server code to only compute a portion of the full force-field,
while LAMMPS computes the remaining part. Your LAMMPS script can also
specify boundary conditions or force constraints in the usual way,
which will be added to the per-atom forces returned by the server
code.
See the examples/message directory for example scripts where LAMMPS is both
the "client" and/or "server" code for this kind of client/server MD
simulation. The examples/message/README file explains how to launch
LAMMPS and another code in tandem to perform a coupled simulation.
----------
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 set by the server application 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 server application to
the global pressure of the system via the :doc:`compute pressure
<compute_pressure>` command. This can be accessed by
:doc:`thermodynamic output <thermo_style>`. The default setting for
this fix is :doc:`fix_modify virial yes <fix_modify>`.
This fix computes a global scalar which can be accessed by various
:doc:`output commands <Howto_output>`. The scalar is the potential
energy discussed above. The scalar value calculated by this fix is
"extensive".
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command.
This fix is not invoked during :doc:`energy minimization <minimize>`.
Restrictions
""""""""""""
This fix is part of the MESSAGE package. It is only enabled if LAMMPS
was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
A script that uses this command must also use the
:doc:`message <message>` command to setup and shut down the messaging
protocol with the server code.
Related commands
""""""""""""""""
:doc:`message <message>`, :doc:`server <server>`
Default
"""""""
none

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

204
doc/src/message.rst
View File

@ -1,204 +0,0 @@
.. index:: message
message command
===============
Syntax
""""""
.. parsed-literal::
message which protocol mode arg
* which = *client* or *server* or *quit*
* protocol = *md* or *mc*
* mode = *file* or *zmq* or *mpi/one* or *mpi/two*
.. parsed-literal::
*file* arg = filename
filename = file used for message exchanges
*zmq* arg = socket-ID
socket-ID for client = localhost:5555, see description below
socket-ID for server = \*:5555, see description below
*mpi/one* arg = none
*mpi/two* arg = filename
filename = file used to establish communication between 2 MPI jobs
Examples
""""""""
.. code-block:: LAMMPS
message client md file tmp.couple
message server md file tmp.couple
message client md zmq localhost:5555
message server md zmq *:5555
message client md mpi/one
message server md mpi/one
message client md mpi/two tmp.couple
message server md mpi/two tmp.couple
message quit
Description
"""""""""""
Establish a messaging protocol between LAMMPS and another code for the
purpose of client/server coupling.
The :doc:`Howto client/server <Howto_client_server>` page gives an
overview of client/server coupling of LAMMPS with another code where
one code is the "client" and sends request messages 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.
----------
The *which* argument defines LAMMPS to be the client or the server.
As explained below the *quit* option should be used when LAMMPS is
finished as a client. It sends a message to the server to tell it to
shut down.
----------
The *protocol* argument defines the format and content of messages
that will be exchanged between the two codes. The current options
are:
* md = run dynamics with another code
* mc = perform Monte Carlo moves with another code
For protocol *md*, LAMMPS can be either a client or server. See the
:doc:`server md <server_md>` page for details on the protocol.
For protocol *mc*, LAMMPS can be the server. See the :doc:`server mc <server_mc>` page for details on the protocol.
----------
The *mode* argument specifies how messages are exchanged between the
client and server codes. Both codes must use the same mode and use
consistent parameters.
For mode *file*, the 2 codes communicate via binary files. They must
use the same filename, which is actually a file prefix. Several files
with that prefix will be created and deleted as a simulation runs.
The filename can include a path. Both codes must be able to access
the path/file in a common filesystem.
For mode *zmq*, the 2 codes communicate via a socket on the server
code's machine. Support for socket messaging is provided by the
open-source `ZeroMQ library <http://zeromq.org>`_, which must be
installed on your system. The client specifies an IP address (IPv4
format) or the DNS name of the machine the server code is running on,
followed by a 4 or 5 digit port ID for the socket, separated by a colon.
E.g.
.. parsed-literal::
localhost:5555 # client and server running on same machine
192.168.1.1:5555 # server is 192.168.1.1
deptbox.uni.edu:5555 # server is deptbox.uni.edu
The server specifies "\*:5555" where "\*" represents all available
interfaces on the server's machine, and the port ID must match
what the client specifies.
.. note::
On Linux or Unix machines port IDs below 1024 are reserved to the
superuser and thus not available. Other ports may already be in
use and cannot be opened by a second process. On a Linux machine
the commands "netstat -t4an" or "ss -t4an" will list all locally
used port IDs for IPv4 addresses.
.. note::
On many machines (and sometimes on local networks) also ports IDs
may be blocked by default through firewalls. In that case either
access to the required port (or a desired range of ports) has to
be selectively enabled to the firewall disabled (the latter is
usually not a good idea unless you are on a (small) local network
that is already protected from outside access.
.. note::
Additional explanation is needed here about how to use the *zmq*
mode on a parallel machine, e.g. a cluster with many nodes.
For mode *mpi/one*, the 2 codes communicate via MPI and are launched
by the same mpirun command, e.g. with this syntax for OpenMPI:
.. code-block:: bash
mpirun -np 2 lmp_mpi -mpicolor 0 -in in.client -log log.client : -np 4 othercode args # LAMMPS is client
mpirun -np 2 othercode args : -np 4 lmp_mpi -mpicolor 1 -in in.server # LAMMPS is server
Note the use of the "-mpicolor color" command-line argument with
LAMMPS. See the :doc:`command-line args <Run_options>` page for
further explanation.
For mode *mpi/two*, the 2 codes communicate via MPI, but are launched
be 2 separate mpirun commands. The specified *filename* argument is a
file the 2 MPI processes will use to exchange info so that an MPI
inter-communicator can be established to enable the 2 codes to send
MPI messages to each other. Both codes must be able to access the
path/file in a common filesystem.
----------
Normally, the message client or message server command should be used
at the top of a LAMMPS input script. It performs an initial handshake
with the other code to setup messaging and to verify that both codes
are using the same message protocol and mode. Assuming both codes are
launched at (nearly) the same time, the other code should perform the
same kind of initialization.
If LAMMPS is the client code, it will begin sending messages when a
LAMMPS client command begins its operation. E.g. for the :doc:`fix client/md <fix_client_md>` command, it is when a :doc:`run <run>`
command is executed.
If LAMMPS is the server code, it will begin receiving messages when
the :doc:`server <server>` command is invoked.
If LAMMPS is being used as a client, the message quit command will
terminate its messaging with the server. If you do not use this
command and just allow LAMMPS to exit, then the server will continue
to wait for further messages. This may not be a problem, but if both
the client and server programs were launched in the same batch script,
then if the server runs indefinitely, it may consume the full allocation
of computer time, even if the calculation finishes sooner.
Note that if LAMMPS is the client or server, it will continue
processing the rest of its input script after client/server
communication terminates.
If both codes cooperate in this manner, a new round of client/server
messaging can be initiated after termination by re-using a second message
command in your LAMMPS input script, followed by a new fix client or
server command, followed by another message quit command (if LAMMPS is
the client). As an example, this can be performed in a loop to use a
quantum code as a server to compute quantum forces for multiple LAMMPS
data files or periodic snapshots while running dynamics.
----------
Restrictions
""""""""""""
This command is part of the MESSAGE 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:`server <server>`, :doc:`fix client/md <fix_client_md>`
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

74
doc/src/server.rst
View File

@ -1,74 +0,0 @@
.. index:: server
server command
==============
Syntax
""""""
.. parsed-literal::
server protocol
* protocol = *md* or *mc*
Examples
""""""""
.. code-block:: LAMMPS
server md
Description
"""""""""""
This command starts LAMMPS running in "server" mode, where it receives
messages from a separate "client" code and responds by sending a reply
message back to the client. The specified *protocol* determines the
format and content of messages LAMMPS expects to receive and how it
responds.
The :doc:`Howto client/server <Howto_client_server>` page gives an
overview of client/server coupling of LAMMPS with another code where
one code is the "client" and sends request messages 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.
When this command is invoked, LAMMPS will run in server mode in an
endless loop, waiting for messages from the client code. The client
signals when it is done sending messages to LAMMPS, at which point the
loop will exit, and the remainder of the LAMMPS input script will be
processed.
The *protocol* argument defines the format and content of messages
that will be exchanged between the two codes. The current options
are:
* :doc:`md <server_md>` = run dynamics with another code
* :doc:`mc <server_mc>` = perform Monte Carlo moves with another code
For protocol *md*, LAMMPS can be either a client (via the :doc:`fix client/md <fix_client_md>` command) or server. See the :doc:`server md <server_md>` page for details on the protocol.
For protocol *mc*, LAMMPS can be the server. See the :doc:`server mc <server_mc>` page for details on the protocol.
----------
Restrictions
""""""""""""
This command is part of the MESSAGE package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` page for more info.
A script that uses this command must also use the
:doc:`message <message>` command to setup the messaging protocol with
the other client code.
Related commands
""""""""""""""""
:doc:`message <message>`, :doc:`fix client/md <fix_client_md>`
Default
"""""""
none

126
doc/src/server_mc.rst
View File

@ -1,126 +0,0 @@
.. index:: server mc
server mc command
=================
Syntax
""""""
.. parsed-literal::
server mc
mc = the protocol argument to the :doc:`server <server>` command
Examples
""""""""
.. code-block:: LAMMPS
server mc
Description
"""""""""""
This command starts LAMMPS running in "server" mode, where it will
expect messages from a separate "client" code that match the *mc*
protocol for format and content explained below. For each message
LAMMPS receives it will send a message back to the client.
The :doc:`Howto client/server <Howto_client_server>` page gives an
overview of client/server coupling of LAMMPS with another code where
one code is the "client" and sends request messages 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.
When this command is invoked, LAMMPS will run in server mode in an
endless loop, waiting for messages from the client code. The client
signals when it is done sending messages to LAMMPS, at which point the
loop will exit, and the remainder of the LAMMPS script will be
processed.
The :doc:`server <server>` page gives other options for using LAMMPS
See an example of how this command is used in
examples/COUPLE/lammps_mc/in.server.
----------
When using this command, LAMMPS (as the server code) receives
instructions from a Monte Carlo (MC) driver to displace random atoms,
compute the energy before and after displacement, and run dynamics to
equilibrate the system.
The MC driver performs the random displacements on random atoms,
accepts or rejects the move in an MC sense, and orchestrates the MD
runs.
The format and content of the exchanged messages are explained here in
a conceptual sense. Python-style pseudo code for the library calls to
the CSlib is shown, which performs the actual message exchange between
the two codes. See the `CSlib website <https://cslib.sandia.gov>`_ doc
pages for more details on the actual library syntax. The "cs" object
in this pseudo code is a pointer to an instance of the CSlib.
See the src/MESSAGE/server_mc.cpp file for details on how LAMMPS uses
these messages. See the examples/COUPLE/lammps_mc/mc.cpp file for an
example of how an MC driver code can use these messages.
Define NATOMS=1, EINIT=2, DISPLACE=3, ACCEPT=4, RUN=5.
**Client sends one of these kinds of message**\ :
.. parsed-literal::
cs->send(NATOMS,0) # msgID = 1 with no fields
cs->send(EINIT,0) # msgID = 2 with no fields
cs->send(DISPLACE,2) # msgID = 3 with 2 fields
cs->pack_int(1,ID) # 1st field = ID of atom to displace
cs->pack(2,3,xnew) # 2nd field = new xyz coords of displaced atom
cs->send(ACCEPT,1) # msgID = 4 with 1 field
cs->pack_int(1,flag) # 1st field = accept/reject flag
cs->send(RUN,1) # msgID = 5 with 1 field
cs->pack_int(1,nsteps) # 1st field = # of timesteps to run MD
**Server replies**\ :
.. parsed-literal::
cs->send(NATOMS,1) # msgID = 1 with 1 field
cs->pack_int(1,natoms) # 1st field = number of atoms
cs->send(EINIT,2) # msgID = 2 with 2 fields
cs->pack_double(1,poteng) # 1st field = potential energy of system
cs->pack(2,3\*natoms,x) # 2nd field = 3N coords of Natoms
cs->send(DISPLACE,1) # msgID = 3 with 1 field
cs->pack_double(1,poteng) # 1st field = new potential energy of system
cs->send(ACCEPT,0) # msgID = 4 with no fields
cs->send(RUN,0) # msgID = 5 with no fields
----------
Restrictions
""""""""""""
This command is part of the MESSAGE package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` page for more info.
A script that uses this command must also use the
:doc:`message <message>` command to setup the messaging protocol with
the other client code.
Related commands
""""""""""""""""
:doc:`message <message>`
Default
"""""""
none

161
doc/src/server_md.rst
View File

@ -1,161 +0,0 @@
.. index:: server md
server md command
=================
Syntax
""""""
.. parsed-literal::
server md
md = the protocol argument to the :doc:`server <server>` command
Examples
""""""""
.. code-block:: LAMMPS
server md
Description
"""""""""""
This command starts LAMMPS running in "server" mode, where it will
expect messages from a separate "client" code that match the *md*
protocol for format and content explained below. For each message
LAMMPS receives it will send a message back to the client.
The :doc:`Howto client/server <Howto_client_server>` page gives an
overview of client/server coupling of LAMMPS with another code where
one code is the "client" and sends request messages 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.
When this command is invoked, LAMMPS will run in server mode in an
endless loop, waiting for messages from the client code. The client
signals when it is done sending messages to LAMMPS, at which point the
loop will exit, and the remainder of the LAMMPS script will be
processed.
The :doc:`server <server>` page gives other options for using LAMMPS
in server mode. See an example of how this command is used in
examples/message/in.message.server.
----------
When using this command, LAMMPS (as the server code) receives the
current coordinates of all particles from the client code each
timestep, computes their interaction, and returns the energy, forces,
and pressure for the interacting particles to the client code, so it
can complete the timestep. This command could also be used with a
client code that performs energy minimization, using the server to
compute forces and energy each iteration of its minimizer.
When using the :doc:`fix client/md <fix_client_md>` command, LAMMPS (as
the client code) does the timestepping and receives needed energy,
forces, and pressure values from the server code.
The format and content of the exchanged messages are explained here in
a conceptual sense. Python-style pseudo code for the library calls to
the CSlib is shown, which performs the actual message exchange between
the two codes. See the `CSlib website <https://cslib.sandia.gov>`_ doc
pages for more details on the actual library syntax. The "cs" object
in this pseudo code is a pointer to an instance of the CSlib.
See the src/MESSAGE/server_md.cpp and src/MESSAGE/fix_client_md.cpp
files for details on how LAMMPS uses these messages. See the
examples/COUPLE/lammps_vasp/vasp_wrap.py or
examples/COUPLE/lammps_nwchem/nwchem_wrap.py files for examples of how
a quantum code (VASP or NWChem) can use these messages.
The following pseudo-code uses these values, defined as enums.
Define:
.. parsed-literal::
SETUP=1, STEP=2
DIM=1, PERIODICITY=2, ORIGIN=3, BOX=4, NATOMS=5, NTYPES=6, TYPES=7, COORDS=8, UNITS-9, CHARGE=10
FORCES=1, ENERGY=2, PRESSURE=3, ERROR=4
**Client sends 2 kinds of messages**\ :
.. parsed-literal::
# required fields: DIM, PERIODICTY, ORIGIN, BOX, NATOMS, NTYPES, TYPES, COORDS
# optional fields: UNITS, CHARGE
cs->send(SETUP,nfields) # msgID with nfields
cs->pack_int(DIM,dim) # dimension (2,3) of simulation
cs->pack(PERIODICITY,3,xyz) # periodicity flags in 3 dims
cs->pack(ORIGIN,3,origin) # lower-left corner of simulation box
cs->pack(BOX,9,box) # 3 edge vectors of simulation box
cs->pack_int(NATOMS,natoms) # total number of atoms
cs->pack_int(NTYPES,ntypes) # number of atom types
cs->pack(TYPES,natoms,type) # vector of per-atom types
cs->pack(COORDS,3\*natoms,x) # vector of 3N atom coords
cs->pack_string(UNITS,units) # units = "lj", "real", "metal", etc
cs->pack(CHARGE,natoms,q) # vector of per-atom charge
# required fields: COORDS
# optional fields: ORIGIN, BOX
cs->send(STEP,nfields) # msgID with nfields
cs->pack(COORDS,3\*natoms,x) # vector of 3N atom coords
cs->pack(ORIGIN,3,origin) # lower-left corner of simulation box
cs->pack(BOX,9,box) # 3 edge vectors of simulation box
**Server replies to either kind of message**\ :
.. parsed-literal::
# required fields: FORCES, ENERGY, PRESSURE
# optional fields: ERROR
cs->send(msgID,nfields) # msgID with nfields
cs->pack(FORCES,3\*Natoms,f) # vector of 3N forces on atoms
cs->pack(ENERGY,1,poteng) # total potential energy of system
cs->pack(PRESSURE,6,press) # global pressure tensor (6-vector)
cs->pack_int(ERROR,flag) # server had an error (e.g. DFT non-convergence)
----------
The units for various quantities that are sent and received iva
messages are defined for atomic-scale simulations in the table below.
The client and server codes (including LAMMPS) can use internal units
different than these (e.g. :doc:`real units <units>` in LAMMPS), so long
as they convert to these units for messaging.
* COORDS, ORIGIN, BOX = Angstroms
* CHARGE = multiple of electron charge (1.0 is a proton)
* ENERGY = eV
* FORCES = eV/Angstrom
* PRESSURE = bars
Note that these are :doc:`metal units <units>` in LAMMPS.
If you wish to run LAMMPS in another its non-atomic units, e.g. :doc:`lj units <units>`, then the client and server should exchange a UNITS
message as indicated above, and both the client and server should
agree on the units for the data they exchange.
----------
Restrictions
""""""""""""
This command is part of the MESSAGE 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:`message <message>`, :doc:`fix client/md <fix_client_md>`
Default
"""""""
none

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