Merge pull request lammps#4431 from Becksteinlab/imd-v3-integration

Interactive Molecular Dynamics [IMD] Version 3 implementation

Author: akohlmey

cmake/CMakeLists.txt

@@ -605,6 +605,16 @@ foreach(PKG_WITH_INCL KSPACE PYTHON ML-IAP VORONOI COLVARS ML-HDNNP MDI MOLFILE
   endif()
 endforeach()
 
+# settings for misc packages and styles
+if(PKG_MISC)
+  option(LAMMPS_ASYNC_IMD "Asynchronous IMD processing" OFF)
+  mark_as_advanced(LAMMPS_ASYNC_IMD)
+  if(LAMMPS_ASYNC_IMD)
+    target_compile_definitions(lammps PRIVATE -DLAMMPS_ASYNC_IMD)
+    message(STATUS "Using IMD in asynchronous mode")
+  endif()
+endif()
+
 # optionally enable building script wrappers using swig
 option(WITH_SWIG "Build scripting language wrappers with SWIG" OFF)
 if(WITH_SWIG)

doc/src/Build_extras.rst

@@ -48,6 +48,7 @@ This is the list of packages that may require additional steps.
    * :ref:`LEPTON <lepton>`
    * :ref:`MACHDYN <machdyn>`
    * :ref:`MDI <mdi>`
+   * :ref:`MISC <misc>`
    * :ref:`ML-HDNNP <ml-hdnnp>`
    * :ref:`ML-IAP <mliap>`
    * :ref:`ML-PACE <ml-pace>`
@@ -2031,7 +2032,7 @@ TBB and MKL.
 .. _mdi:
 
 MDI package
------------------------------
+-----------
 
 .. tabs::
 
@@ -2058,6 +2059,37 @@ MDI package
 
 ----------
 
+.. _misc:
+
+MISC package
+------------
+
+The :doc:`fix imd <fix_imd>` style in this package can be run either
+synchronously (communication with IMD clients is done in the main
+process) or asynchronously (the fix spawns a separate thread that can
+communicate with IMD clients concurrently to the LAMMPS execution).
+
+.. tabs::
+
+   .. tab:: CMake build
+
+      .. code-block:: bash
+
+         -D LAMMPS_ASYNC_IMD=value  # Run IMD server asynchronously
+                                    # value = no (default) or yes
+
+   .. tab:: Traditional make
+
+      To enable asynchronous mode the ``-DLAMMPS_ASYNC_IMD`` define
+      needs to be added to the ``LMP_INC`` variable in the
+      ``Makefile.machine`` you are using.  For example:
+
+      .. code-block:: make
+
+         LMP_INC = -DLAMMPS_ASYNC_IMD -DLAMMPS_MEMALIGN=64
+
+----------
+
 .. _molfile:
 
 MOLFILE package

doc/src/Build_package.rst

@@ -49,6 +49,7 @@ packages:
    * :ref:`LEPTON <lepton>`
    * :ref:`MACHDYN <machdyn>`
    * :ref:`MDI <mdi>`
+   * :ref:`MISC <misc>`
    * :ref:`ML-HDNNP <ml-hdnnp>`
    * :ref:`ML-IAP <mliap>`
    * :ref:`ML-PACE <ml-pace>`

doc/src/fix_imd.rst

@@ -26,6 +26,29 @@ Syntax
        *nowait* arg = *on* or *off*
          off = LAMMPS waits to be connected to an IMD client before continuing (default)
          on = LAMMPS listens for an IMD client, but continues with the run
+       *version* arg = *2* or *3*
+         2 = use IMD protocol version 2 (default)
+         3 = use IMD protocol version 3.
+
+  The following keywords are only supported for IMD protocol version 3.
+
+  .. parsed-literal::
+
+       *time* arg = *on* or *off*
+          off = simulation time is not transmitted (default)
+          on = simulation time is transmitted.
+       *box* arg = *on* or *off*
+          off = simulation box data is not transmitted (default)
+          on = simulation box data is transmitted.
+       *coordinates* arg = *on* or *off*
+          off = atomic coordinates are not transmitted (default)
+          on = atomic coordinates are transmitted.
+       *velocities* arg = *on* or *off*
+          off = atomic velocities are not transmitted (default)
+          on = atomic velocities are transmitted.
+       *forces* arg = *on* or *off*
+          off = atomic forces are not transmitted (default)
+          on = atomic forces are transmitted.
 
 Examples
 """"""""
@@ -40,16 +63,19 @@ Description
 
 This fix implements the "Interactive MD" (IMD) protocol which allows
 realtime visualization and manipulation of MD simulations through the
-IMD protocol, as initially implemented in VMD and NAMD.  Specifically
-it allows LAMMPS to connect an IMD client, for example the `VMD visualization program <VMD_>`_, so that it can monitor the progress of the
-simulation and interactively apply forces to selected atoms.
-
-If LAMMPS is compiled with the pre-processor flag -DLAMMPS_ASYNC_IMD
-then fix imd will use POSIX threads to spawn a IMD communication
-thread on MPI rank 0 in order to offload data reading and writing
-from the main execution thread and potentially lower the inferred
-latencies for slow communication links. This feature has only been
-tested under linux.
+IMD protocol, as initially implemented in VMD and NAMD.  Specifically it
+allows LAMMPS to connect an IMD client, for example the `VMD
+visualization program <VMD_>`_ (currently only supports IMDv2) or the
+`Python IMDClient <IMDClient_>`_ (supports both IMDv2 and IMDv3), so
+that it can monitor the progress of the simulation and interactively
+apply forces to selected atoms.
+
+If LAMMPS is compiled with the pre-processor flag
+:ref:`-DLAMMPS_ASYNC_IMD <misc>` then fix imd will use POSIX threads to
+spawn an IMD communication thread on MPI rank 0 in order to offload data
+exchange with the IMD client from the main execution thread and
+potentially lower the inferred latencies for slow communication
+links. This feature has only been tested under linux.
 
 The source code for this fix includes code developed by the Theoretical
 and Computational Biophysics Group in the Beckman Institute for Advanced
@@ -94,6 +120,15 @@ with different units or as a measure to tweak the forces generated by
 the manipulation of the IMD client, this option allows to make
 adjustments.
 
+.. versionadded:: TBD
+
+In `IMDv3 <IMDv3_>`_, the IMD protocol has been extended to allow for
+the transmission of simulation time, box dimensions, atomic coordinates,
+velocities, and forces. The *version* keyword allows to select the
+version of the protocol to be used. The *time*, *box*, *coordinates*,
+*velocities*, and *forces* keywords allow to select which data is
+transmitted to the IMD client. The default is to transmit all data.
+
 To connect VMD to a listening LAMMPS simulation on the same machine
 with fix imd enabled, one needs to start VMD and load a coordinate or
 topology file that matches the fix group.  When the VMD command
@@ -129,6 +164,10 @@ screen output is active.
 
 .. _imdvmd: https://www.ks.uiuc.edu/Research/vmd/imd/
 
+.. _IMDClient: https://github.com/Becksteinlab/imdclient/tree/main/imdclient
+
+.. _IMDv3: https://imdclient.readthedocs.io/en/latest/protocol_v3.html
+
 Restart, fix_modify, output, run start/stop, minimize info
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
@@ -147,14 +186,14 @@ This fix is part of the MISC package.  It is only enabled if LAMMPS was
 built with that package.  See the :doc:`Build package <Build_package>`
 page for more info.
 
-When used in combination with VMD, a topology or coordinate file has
-to be loaded, which matches (in number and ordering of atoms) the
-group the fix is applied to. The fix internally sorts atom IDs by
-ascending integer value; in VMD (and thus the IMD protocol) those will
-be assigned 0-based consecutive index numbers.
+When used in combination with VMD, a topology or coordinate file has to
+be loaded, which matches (in number and ordering of atoms) the group the
+fix is applied to.  The fix internally sorts atom IDs by ascending
+integer value; in VMD (and thus the IMD protocol) those will be assigned
+0-based consecutive index numbers.
 
 When using multiple active IMD connections at the same time, each
-needs to use a different port number.
+fix instance needs to use a different port number.
 
 Related commands
 """"""""""""""""

examples/PACKAGES/imd/deca-ala-solv_imd_v3.py

@@ -0,0 +1,13 @@
+"""
+For use with 'in.deca-ala-solv_imd_v3'.
+
+Tested with imdclient v0.1.4 and MDAnalysis v2.8.0
+"""
+from imdclient.IMD import IMDReader
+import MDAnalysis as mda
+
+u = mda.Universe('data.deca-ala-solv', "imd://localhost:5678", topology_format='DATA')
+
+for ts in u.trajectory:
+    print(ts.time)
+    print(ts.velocities)

examples/PACKAGES/imd/in.deca-ala-solv_imd_v3

@@ -0,0 +1,31 @@
+# 
+units           real
+neighbor        2.5 bin
+neigh_modify    delay 1 every 1 
+
+atom_style      full
+bond_style      harmonic
+angle_style     charmm
+dihedral_style  charmm
+improper_style  harmonic
+
+pair_style      lj/charmm/coul/long 8 10
+pair_modify     mix arithmetic
+special_bonds   charmm
+read_data       data.deca-ala-solv
+
+
+group peptide   id <= 103
+fix             rigidh all shake 1e-6 100 1000 t 1 2 3 4 5 a 23
+
+thermo          100
+thermo_style    multi
+timestep        2.0
+kspace_style    pppm 1e-5
+
+fix             ensemble all npt temp 300.0 300.0 100.0 iso 1.0 1.0 1000.0 drag 0.2
+
+# IMD setup. Client code available in 'deca-ala-solv_imd_v3.py'
+fix  comm       all imd 5678 unwrap on trate 10 version 3 time on box on coordinates on velocities on forces off 
+
+run 5000000