From 02a8a9d706cf7675d507f99814340e9775d03bc6 Mon Sep 17 00:00:00 2001
From: Axel Kohlmeyer <akohlmey@gmail.com>
Date: Wed, 8 Jan 2025 20:30:48 -0500
Subject: [PATCH] make LAMMPS_ASYNC_IMD a CMake variable, too, and document it
 properly

---
 cmake/CMakeLists.txt      | 10 ++++++++++
 doc/src/Build_extras.rst  | 34 +++++++++++++++++++++++++++++++++-
 doc/src/Build_package.rst |  1 +
 doc/src/fix_imd.rst       | 24 ++++++++++++------------
 4 files changed, 56 insertions(+), 13 deletions(-)

diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
index 38431e3bb5..e89a2a3a77 100644
--- a/cmake/CMakeLists.txt
+++ b/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)
diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst
index 08e4cdbb7a..80b9da1bd5 100644
--- a/doc/src/Build_extras.rst
+++ b/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
diff --git a/doc/src/Build_package.rst b/doc/src/Build_package.rst
index 8b2da8ad30..c4c4889806 100644
--- a/doc/src/Build_package.rst
+++ b/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>`
diff --git a/doc/src/fix_imd.rst b/doc/src/fix_imd.rst
index 1ec279a91b..158b44bdc6 100644
--- a/doc/src/fix_imd.rst
+++ b/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
-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.
+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 -DLAMMPS_ASYNC_IMD (-DCMAKE_CXX_FLAGS="-DLAMMPS_ASYNC_IMD" in CMake),
-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.
+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