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..a4d7d9d387 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. @@ -58,19 +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 `_ -(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 ` 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 @@ -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 """""""""""""""" 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; } /* ---------------------------------------------------------------------- */