make LAMMPS_ASYNC_IMD a CMake variable, too, and document it properly

cmake/CMakeLists.txt

@@ -579,6 +579,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>`
@@ -2019,7 +2020,7 @@ TBB and MKL.
 .. _mdi:
 
 MDI package
------------------------------
+-----------
 
 .. tabs::
 
@@ -2046,6 +2047,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

@@ -58,19 +58,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
+IMD protocol, as initially implemented in VMD and NAMD.  Specifically it
-it allows LAMMPS to connect an IMD client, for example the `VMD visualization program <VMD_>`_
+allows LAMMPS to connect an IMD client, for example the `VMD
-(currently only supports IMDv2) or the
+visualization program <VMD_>`_ (currently only supports IMDv2) or the
-`Python IMDClient <IMDClient_>`_ (supports both IMDv2 and IMDv3),
+`Python IMDClient <IMDClient_>`_ (supports both IMDv2 and IMDv3), so
-so that it can monitor the progress of the
+that it can monitor the progress of the simulation and interactively
-simulation and interactively apply forces to selected atoms.
+apply forces to selected atoms.
 
-If LAMMPS is compiled with the pre-processor flag -DLAMMPS_ASYNC_IMD (-DCMAKE_CXX_FLAGS="-DLAMMPS_ASYNC_IMD" in CMake),
+If LAMMPS is compiled with the pre-processor flag
-then fix imd will use POSIX threads to spawn a IMD communication
+:ref:`-DLAMMPS_ASYNC_IMD <_misc>` then fix imd will use POSIX threads to
-thread on MPI rank 0 in order to offload data reading and writing
+spawn an IMD communication thread on MPI rank 0 in order to offload data
-from the main execution thread and potentially lower the inferred
+exchange with the IMD client from the main execution thread and
-latencies for slow communication links. This feature has only been
+potentially lower the inferred latencies for slow communication
-tested under linux.
+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