From 02a8a9d706cf7675d507f99814340e9775d03bc6 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 8 Jan 2025 20:30:48 -0500 Subject: [PATCH 1/4] 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 ` * :ref:`MACHDYN ` * :ref:`MDI ` + * :ref:`MISC ` * :ref:`ML-HDNNP ` * :ref:`ML-IAP ` * :ref:`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 ` 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 ` * :ref:`MACHDYN ` * :ref:`MDI ` + * :ref:`MISC ` * :ref:`ML-HDNNP ` * :ref:`ML-IAP ` * :ref:`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 `_ -(currently only supports IMDv2) or the -`Python 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 `_ (currently only supports IMDv2) or the +`Python 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 From 6a363d441b9f6ed4fef39268719a459a01f15fd1 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 8 Jan 2025 20:35:08 -0500 Subject: [PATCH 2/4] small formatting tweaks, add versionadded tag --- doc/src/fix_imd.rst | 35 +++++++++++++++++++++-------------- 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/doc/src/fix_imd.rst b/doc/src/fix_imd.rst index 158b44bdc6..fd0fd2dc00 100644 --- a/doc/src/fix_imd.rst +++ b/doc/src/fix_imd.rst @@ -27,8 +27,13 @@ Syntax 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 version 2 (default) - 3 = use IMD version 3. The subsequent keywords are only supported for version 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. @@ -115,12 +120,14 @@ 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. -In `IMDv3 `_, the 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. +.. versionadded:: TBD + +In `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 @@ -179,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 ` 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 """""""""""""""" From 1032c94c9f5c9e256dacf2ae73d7a33317d01179 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 8 Jan 2025 20:52:57 -0500 Subject: [PATCH 3/4] apply some more of LAMMPS' programming style guidelines and improve errors --- src/MISC/fix_imd.cpp | 38 ++++++++++++++++---------------------- 1 file changed, 16 insertions(+), 22 deletions(-) diff --git a/src/MISC/fix_imd.cpp b/src/MISC/fix_imd.cpp index 5be6de2c2c..493c3a4e0f 100644 --- a/src/MISC/fix_imd.cpp +++ b/src/MISC/fix_imd.cpp @@ -454,29 +454,31 @@ struct commdata { MPI_Datatype MPI_CommData; /*************************************************************** - * create class and parse arguments in LAMMPS script. Syntax: - * fix ID group-ID imd [trate ] [version (2|3)] [unwrap (on|off)] [fscale ] [time (on|off)] [box (on|off)] [coordinates (on|off)] [velocities (on|off)] [forces (on|off)] + * create class and parse arguments in LAMMPS script. ***************************************************************/ + FixIMD::FixIMD(LAMMPS *lmp, int narg, char **arg) : - Fix(lmp, narg, arg) + Fix(lmp, narg, arg), localsock(nullptr), clientsock(nullptr), coord_data(nullptr), + vel_data(nullptr), force_data(nullptr), idmap(nullptr), rev_idmap(nullptr), + recv_force_buf(nullptr), imdsinfo(nullptr), msgdata(nullptr) { - if (narg < 4) - error->all(FLERR,"Illegal fix imd command"); + if (narg < 4) utils::missing_cmd_args(FLERR, "fix imd", error); imd_port = utils::inumeric(FLERR,arg[3],false,lmp); - if (imd_port < 1024) - error->all(FLERR,"Illegal fix imd parameter: port < 1024"); + if (imd_port < 1024) error->all(FLERR,"Illegal fix imd parameter: port < 1024"); /* default values for optional flags */ - imd_version = 2; + imd_version = 2; unwrap_flag = 0; nowait_flag = 0; connect_msg = 1; imd_fscale = 1.0; imd_trate = 1; - /* IMDv3-only flags. Aren't stored as class attributes since they're converted into IMDSessionInfo */ + // IMDv3-only flags. + // Aren't stored as class attributes since they're converted into IMDSessionInfo + int time_flag = 1; int box_flag = 1; int coord_flag = 1; @@ -507,17 +509,17 @@ FixIMD::FixIMD(LAMMPS *lmp, int narg, char **arg) : } else if (0 == strcmp(arg[iarg], "forces")) { force_flag = utils::logical(FLERR, arg[iarg+1], false, lmp); } else { - error->all(FLERR,"Unknown fix imd parameter"); + error->all(FLERR,"Unknown fix imd parameter: {}", arg[iarg]); } ++iarg; ++iarg; } /* sanity check on parameters */ if (imd_trate < 1) - error->all(FLERR,"Illegal fix imd parameter. trate < 1."); + error->all(FLERR,"Illegal fix imd trate parameter. trate < 1."); if (imd_version != 2 && imd_version != 3) - error->all(FLERR,"Illegal fix imd parameter. version != 2 or 3."); + error->all(FLERR,"Illegal fix imd version parameter: version != 2 or 3."); imdsinfo = new IMDSessionInfo; @@ -553,19 +555,11 @@ FixIMD::FixIMD(LAMMPS *lmp, int narg, char **arg) : MPI_Comm_rank(world,&me); /* initialize various imd state variables. */ - clientsock = nullptr; - localsock = nullptr; nlevels_respa = 0; imd_inactive = 0; imd_terminate = 0; imd_forces = 0; - recv_force_buf = nullptr; maxbuf = 0; - coord_data = nullptr; - vel_data = nullptr; - force_data = nullptr; - idmap = nullptr; - rev_idmap = nullptr; if (imd_version == 3) { msglen = 0; @@ -673,8 +667,8 @@ FixIMD::~FixIMD() imdsock_destroy(clientsock); imdsock_shutdown(localsock); imdsock_destroy(localsock); - clientsock=nullptr; - localsock=nullptr; + clientsock = nullptr; + localsock = nullptr; } /* ---------------------------------------------------------------------- */ From 494f58904cb0622fe05527b80e41fb17a5c87121 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 8 Jan 2025 20:54:04 -0500 Subject: [PATCH 4/4] correct reference --- doc/src/fix_imd.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/fix_imd.rst b/doc/src/fix_imd.rst index fd0fd2dc00..a4d7d9d387 100644 --- a/doc/src/fix_imd.rst +++ b/doc/src/fix_imd.rst @@ -71,7 +71,7 @@ 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 +:ref:`-DLAMMPS_ASYNC_IMD ` 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