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

Use "mdi/engine" consistenty, complete integration in manual, spelling

Browse Source
This commit is contained in:
Axel Kohlmeyer
2021-05-13 09:57:08 -04:00
parent f86f182cd3
commit 33205ed91f
16 changed files with 129 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/src/Commands_all.rst
View File

@ -67,6 +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:`minimize <minimize>`
* :doc:`min_modify <min_modify>`

1
doc/src/Commands_fix.rst
View File

@ -101,6 +101,7 @@ OPT.
* :doc:`lb/viscous <fix_lb_viscous>`
* :doc:`lineforce <fix_lineforce>`
* :doc:`manifoldforce <fix_manifoldforce>`
* :doc:`mdi/engine <fix_mdi_engine>`
* :doc:`meso/move <fix_meso_move>`
* :doc:`momentum (k) <fix_momentum>`
* :doc:`momentum/chunk <fix_momentum>`

81
doc/src/Howto_mdi.rst
View File

@ -19,20 +19,20 @@ developed by the `Molecular Sciences Software Institute (MolSSI)
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 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 whcih 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.
Some advantages of client/server coupling are that the two 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.
In MDI lingo, 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 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
@ -49,47 +49,48 @@ engine instances and re-instantiate them.
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 optinally some data, which can
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 bewteen the driver and engine via MPI
MDI library, data is exchanged between the driver and engine via MPI
calls or sockets. This a run-time choice by the user.
-------------
As an example, LAMMPS and Quantum Espresso (QE, a quantum DFT code),
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 QE asking it to compute quantum forces on the
current configuration of atoms. Here is how the 2 codes are launched
to communicate by MPI:
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:
.. code-block:: bash
% mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method MPI" < in.aimd : -np 16 qe -mdi "-role ENGINE -name e -method MPI"
% 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"
In this case LAMMPS runs on 2 processors (MPI tasks), QE runs on 16
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:
.. code-block:: bash
% mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method TCP -port 8021" < in.aimd
% mpirun -np 16 qe -mdi "-role ENGINE -name e -method TCP -port 8021 -hostname localhost"
% 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"
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, QE could be run on another machine on the same network, or
IP address, ``pw.x`` could be run on another machine on the same network, or
even on another machine across the country.
After both codes initialize themselves to model the same system, this
is what occurs each timestep:
After both codes initialize themselves to model the same system, this is
what occurs each timestep:
* LAMMPS send a ">COORDS" message to QE with a 3*N vector of current atom coords
* QE receives the message/coords and computes quantum forces on all the atoms
* LAMMPS send a "<FORCES" message to QE and waits for the result
* QE receives the message (after its computation finishes) and sends a 3*N vector of forces
* 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
-------------
@ -107,7 +108,7 @@ instructions on how to run the examples.
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
: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.
@ -118,14 +119,14 @@ 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>`
doc page for a list of these.
LAMMPS supports the full set of MD-appropriate engine commands defined
by the MDI library. See the :doc:`mdi/engine <mdi_engine>` doc 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 easily be added. See
these two files which implement the definition of MDI commands and the
logic for responding to them:
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

23
doc/src/Packages_details.rst
View File

@ -82,6 +82,7 @@ page gives those details.
* :ref:`USER-INTEL <PKG-USER-INTEL>`
* :ref:`USER-LB <PKG-USER-LB>`
* :ref:`USER-MANIFOLD <PKG-USER-MANIFOLD>`
* :ref:`USER-MDI <PKG-USER-MDI>`
* :ref:`USER-MEAMC <PKG-USER-MEAMC>`
* :ref:`USER-MESODPD <PKG-USER-MESODPD>`
* :ref:`USER-MESONT <PKG-USER-MESONT>`
@ -1791,6 +1792,28 @@ Waltham, MA, USA)
----------
.. _PKG-USER-MDI:
USER-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
(MDI) library <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_.
**Author:** Taylor Barnes - MolSSI, taylor.a.barnes at gmail.com
**Supporting info:**
* src/USER-MDI/README
* :doc:`mdi/engine <mdi_engine>`
* :doc:`fix mdi/engine <fix_mdi_engine>`
* examples/USER/mdi
----------
.. _PKG-USER-MEAMC:
USER-MEAMC package

2
doc/src/Packages_user.rst
View File

@ -65,6 +65,8 @@ package:
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-MANIFOLD <PKG-USER-MANIFOLD>` | motion on 2d surfaces | :doc:`fix manifoldforce <fix_manifoldforce>` | USER/manifold | no |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-MDI <PKG-USER-MDI>` | client-server coupling | :doc:`MDI Howto <Howto_mdi>` | USER/mdi | ext |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-MEAMC <PKG-USER-MEAMC>` | modified EAM potential (C++) | :doc:`pair_style meam/c <pair_meamc>` | meamc | no |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-MESODPD <PKG-USER-MESODPD>` | mesoscale DPD models | :doc:`pair_style edpd <pair_mesodpd>` | USER/mesodpd | no |

30
doc/src/comm_modify.rst
View File

@ -34,7 +34,7 @@ Examples
comm_modify mode multi reduce/multi
comm_modify mode multi group solvent
comm_modift mode multi cutoff/multi 1 10.0 cutoff/multi 2*4 15.0
comm_modify mode multi cutoff/multi 1 10.0 cutoff/multi 2*4 15.0
comm_modify vel yes
comm_modify mode single cutoff 5.0 vel yes
comm_modify cutoff/multi * 0.0
@ -75,8 +75,8 @@ communicated. in *multi/old*, a similar technique is used but atoms
are grouped by atom type. See the :doc:`neighbor multi <neighbor>` and
:doc:`neighbor multi/old <neighbor>` commands for
neighbor list construction options that may also be beneficial for
simulations of this kind. The *multi* communiction mode is only compatable
with the *multi* neighbor style. The *multi/old* communication mode is compatble
simulations of this kind. The *multi* communication mode is only compatible
with the *multi* neighbor style. The *multi/old* communication mode is comparable
with both the *multi* and *multi/old* neighbor styles.
The *cutoff* keyword allows you to extend the ghost cutoff distance
@ -97,18 +97,18 @@ warning is printed, if this bond based estimate is larger than the
communication cutoff used.
The *cutoff/multi* option is equivalent to *cutoff*\ , but applies to
communication mode *multi* instead. Since the communication
cutoffs are determined per atom collections, a collection specifier is needed and
cutoff for one or multiple collections can be extended. Also ranges of collections
using the usual asterisk notation can be given.
Collections are indexed from 1 to N where N is the total number of collections.
communication mode *multi* instead. Since the communication cutoffs are
determined per atom collections, a collection specifier is needed and
cutoff for one or multiple collections can be extended. Also ranges of
collections using the usual asterisk notation can be given. Collections
are indexed from 1 to N where N is the total number of collections.
Note that the arguments for *cutoff/multi* are parsed right before each
simulation to account for potential changes in the number of collections.
Custom cutoffs are preserved between runs but if collections are redefined,
one may want to respecify communication cutoffs.
For granular pair styles,the default cutoff is set to the sum of the
current maximum atomic radii for each collection.
The *cutoff/multi/old* option is similar to *cutoff/multi* except it
simulation to account for potential changes in the number of
collections. Custom cutoffs are preserved between runs but if
collections are redefined, one may want to re-specify the communication
cutoffs. For granular pair styles,the default cutoff is set to the sum
of the current maximum atomic radii for each collection. The
*cutoff/multi/old* option is similar to *cutoff/multi* except it
operates on atom types as opposed to collections.
The *reduce/multi* option applies to *multi* and sets the communication
@ -147,7 +147,7 @@ ghost cutoff should be set.
In the last scenario, a :doc:`fix <fix>` or :doc:`compute <compute>` or
:doc:`pairwise potential <pair_style>` needs to calculate with ghost
atoms beyond the normal pairwise cutoff for some computation it
performs (e.g. locate neighbors of ghost atoms in a multibody pair
performs (e.g. locate neighbors of ghost atoms in a manybody pair
potential). Setting the ghost cutoff appropriately can insure it will
find the needed atoms.

1
doc/src/commands_list.rst
View File

@ -59,6 +59,7 @@ Commands
lattice
log
mass
mdi_engine
message
min_modify
min_spin

12
doc/src/fix_mdi_engine.rst
View File

@ -1,7 +1,7 @@
.. index:: fix move
fix mdi/engine command
================
======================
Syntax
""""""
@ -23,22 +23,22 @@ Examples
Description
"""""""""""
This fix is used along with the :doc:`mdi_engine <mdi_engine>` command
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
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
:doc:`mdi/engine <mdi_engine>` command and the :doc:`Howto mdi
<Howto_mdi>` doc page.
Restrictions
@ -51,7 +51,7 @@ LAMMPS was built with that package. See the :doc:`Build package
Related commands
""""""""""""""""
:doc:`mdi_engine <mdi_engine>`
:doc:`mdi/engine <mdi_engine>`
Default
"""""""

11
doc/src/mdi_engine.rst
View File

@ -1,7 +1,7 @@
.. index:: mdi_engine
mdi_engine command
===============
==================
Syntax
""""""
@ -41,10 +41,9 @@ 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 distiniction
of what "node" the commands refer to is not needed in this table?
.. 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
@ -53,7 +52,7 @@ of what "node" the commands refer to is not needed in this table?
* - Command name
- Action
* - >NATOMS
- Driver sends the number of atoms in the ststem
- Driver sends the number of atoms in the system
* - <NATOMS
- Driver requests the number of atoms in the system
* - <COORDS

17
doc/src/neigh_modify.rst
View File

@ -221,14 +221,15 @@ from 1 to n (inclusive). A trailing asterisk means all types from n to M
(inclusive). A middle asterisk means all types from m to n (inclusive).
Note that all atom types must be included in exactly one of the N collections.
The *collection/interval* option provides a similar capability.
This command allows a user to define collections by specifying a
series of cutoff intervals. LAMMPS will automatically sort atoms into these intervals
based on their type-dependent cutoffs or their finite size.
You must first specify the number of collections N to be
defined followed by N values representing the upper cutoff of each interval.
This command is particularly useful for granular pairstyles where the interaction distance
of particles depends on their radius and may not depend on their atom type.
The *collection/interval* option provides a similar capability. This
command allows a user to define collections by specifying a series of
cutoff intervals. LAMMPS will automatically sort atoms into these
intervals based on their type-dependent cutoffs or their finite size.
You must first specify the number of collections N to be defined
followed by N values representing the upper cutoff of each interval.
This command is particularly useful for granular pair styles where the
interaction distance of particles depends on their radius and may not
depend on their atom type.
Restrictions
""""""""""""

8
doc/utils/sphinx-config/false_positives.txt
View File

@ -47,6 +47,7 @@ Agnolin
Ai
Aidan
aij
aimd
airebo
Aj
ajs
@ -196,6 +197,7 @@ Ballenegger
Bammann
Banna
Barashev
barnes
barostat
Barostats
barostatted
@ -1207,6 +1209,7 @@ Halver
Hamaker
Hamel
Hammerschmidt
Hanley
haptic
Hara
Harpertown
@ -1269,6 +1272,7 @@ holonomic
Homebrew
hooke
Hookean
hostname
hotpink
Houlle
howto
@ -1728,6 +1732,7 @@ Lmpsdata
lmptype
LMT
ln
localhost
localTemp
localvectors
Loewen
@ -1858,6 +1863,8 @@ mc
McLachlan
md
mdf
MDI
mdi
mdpd
mDPD
meam
@ -3143,6 +3150,7 @@ Tanmoy
Tartakovsky
taskset
taubi
taylor
tb
tchain
Tchain

8
src/USER-MDI/README
View File

@ -1,4 +1,4 @@
The USRE-MDI package adds an mdi_engine command which enables LAMMPS
The USER-MDI package adds an mdi/engine command which enables LAMMPS
to operate as a MolSSI Driver Interface (MDI) engine, responding to
commands from an external MDI driver.
@ -8,7 +8,7 @@ developed and maintained by Taylor Barnes (tbarnes1@vt.edu) at the
Molecular Sciences Software Institute (MolSSI).
For more information about using MDI with LAMMPS, see the LAMMPS
documentation for the mdi_engine command and the mdi/engine fix.
documentation for the mdi/engine command and the mdi/engine fix.
For general purpose information about MDI, see the MDI Library
documentation:
https://molssi-mdi.github.io/MDI_Library/html/index.html
@ -18,3 +18,7 @@ built using the Install.py file in lib/mdi. For example:
python Install.py -m gcc
python Install.py -m icc
When using CMake to build LAMMPS the CMake configuration can use
either a preinstalled MDI library or download and compile a
private copy.

4
src/USER-MDI/fix_mdi_engine.cpp
View File

@ -311,7 +311,7 @@ int FixMDIEngine::execute_command(const char *command, MDI_Comm mdicomm)
receive_forces(error, 1);
// initialize new MD simulation or minimization
// return control to return to mdi_engine
// return control to return to mdi/engine
} else if (strcmp(command,"@INIT_MD") == 0 ) {
if (most_recent_init != 0)
@ -320,7 +320,7 @@ int FixMDIEngine::execute_command(const char *command, MDI_Comm mdicomm)
local_exit_flag = true;
// initialize new energy minimization
// return control to return to mdi_engine
// return control to return to mdi/engine
} else if (strcmp(command,"@INIT_OPTG") == 0 ) {
if ( most_recent_init != 0 )

14
src/USER-MDI/mdi_engine.cpp
View File

@ -40,7 +40,7 @@ using namespace LAMMPS_NS;
trigger LAMMPS to start acting as an MDI engine
endlessly loop over receiving commands from driver and responding
much of the logic for this is in FixMDIEngine
when EXIT command is received, mdi_engine command exits
when EXIT command is received, mdi/engine command exits
---------------------------------------------------------------------- */
void MDIEngine::command(int narg, char **arg)
@ -176,7 +176,7 @@ void MDIEngine::command(int narg, char **arg)
MDI_Register_command("@COORDS", "@FORCES");
MDI_Register_command("@COORDS", "EXIT");
// if the mdi_engine fix is not already present, add it now
// if the mdi/engine fix is not already present, add it now
int ifix = modify->find_fix_by_style("mdi/engine");
bool added_mdi_engine_fix = false;
@ -192,13 +192,13 @@ void MDIEngine::command(int narg, char **arg)
// check that LAMMPS is setup as a compatible MDI engine
if (narg > 0) error->all(FLERR,"Illegal mdi_engine command");
if (narg > 0) error->all(FLERR,"Illegal mdi/engine command");
if (atom->tag_enable == 0)
error->all(FLERR,"Cannot use mdi_engine without atom IDs");
error->all(FLERR,"Cannot use mdi/engine without atom IDs");
if (atom->tag_consecutive() == 0)
error->all(FLERR,"mdi_engine requires consecutive atom IDs");
error->all(FLERR,"mdi/engine requires consecutive atom IDs");
// endless engine loop, responding to driver commands
@ -206,7 +206,7 @@ void MDIEngine::command(int narg, char **arg)
while (1) {
// mdi_engine command only recognizes three nodes
// mdi/engine command only recognizes three nodes
// DEFAULT, INIT_MD, INIT_OPTG
command = mdi_fix->engine_mode("@DEFAULT");
@ -230,7 +230,7 @@ void MDIEngine::command(int narg, char **arg)
"invalid command: {}",command));
}
// remove mdi/engine fix that mdi_engine instantiated
// remove mdi/engine fix that mdi/engine instantiated
if (added_mdi_engine_fix) modify->delete_fix("MDI_ENGINE_INTERNAL");
}

2
src/USER-MDI/mdi_engine.h
View File

@ -13,7 +13,7 @@
#ifdef COMMAND_CLASS
CommandStyle(mdi_engine,MDIEngine)
CommandStyle(mdi/engine,MDIEngine)
#else

2
src/library.cpp
View File

@ -4991,7 +4991,7 @@ when LAMMPS is run as a plugin, and should not otherwise be used.
The function initializes MDI, then creates and initializes an instance
of LAMMPS. The command-line arguments ``argc`` and ``argv`` used to
initialize LAMMPS are recieved from MDI. The LAMMPS instance runs an
input file, which must include the ``mdi_engine`` command; when LAMMPS
input file, which must include the ``mdi/engine`` command; when LAMMPS
executes this command, it will begin listening for commands from the
driver. The name of the input file is obtained from the ``-in``
command-line argument, which must be provided by the MDI driver.