Streaming trajectories from a simulation engine with IMDv3 ========================================================== Configuring the simulation engine for IMDv3 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To stream a trajectory from a simulation engine that supports IMDv3, first use the appropriate input options on the simulation engine to prepare it for the IMDClient receiver. Below, we have provided brief instructions on how to setup the various simulation engines to output stream data using IMDv3. GROMACS ------- The IMDv3 protocol is currently not available as part of the official GROMACS release or source code repository. However, the feature is currently available for use in the *imd-v3* branch of the forked repository: https://gitlab.com/heydenlabasu/streaming-md/gromacs/-/tree/imd-v3. In GROMACS, you can use ``gmx mdrun`` with the ``-imdwait`` flag to ensure that GROMACS will wait for a client before starting the simulation. Specific IMDv3 options were added to GROMACS, as documented in the GROMACS User Guide `Molecular dynamics parameters (.mdp options)`_ under *Interactive Molecular Dynamics (IMD)*. GROMACS does *not* support multiple concurrent connections to the same IMD port. In GROMACS, you will know that the simulation is ready and waiting for the IMDClient when this line is printed to the terminal: .. code-block:: none IMD: Will wait until I have a connection and IMD_GO orders. You are now ready to connect to the simulation engine with a client. .. TODO: update to official GROMACS docs (issue #79) .. _`Molecular dynamics parameters (.mdp options)`: https://gitlab.com/heydenlabasu/streaming-md/gromacs/-/blob/imd-v3/docs/user-guide/mdp-options.rst?ref_type=heads&plain=1 LAMMPS ------ The IMDv3 protocol implementation is part of the official LAMMPS distribution since **patch_4Feb2025**. It is available in the LAMMPS source code repository: https://github.com/lammps/lammps. However, the above version lacks kokkos support for IMDv3. The latest version with kokkos compatible optimization for IMDv3 is available here: https://github.com/Becksteinlab/lammps/tree/fix-imdv3-kokkos Information on using IMDv3 with LAMMPS can be found in the LAMMPS documentation for `fix imd`_. LAMMPS does *not* support multiple concurrent connections to the same IMD port. To use IMDv3 with LAMMPS, add the following lines to your LAMMPS input script: .. code-block:: none fix ID group-ID imd trate version 3 unwrap time box coordinates velocities forces Once the simulation is ready for a client connection, it will print following terminal message: .. code-block:: none Waiting for IMD connection on port You are now ready to connect to the simulation engine with a client. .. _`fix imd`: https://docs.lammps.org/fix_imd.html .. _`raise an issue`: https://github.com/Becksteinlab/imdclient/issues NAMD ---- The IMDv3 protocol has been implemented in NAMD and will be made available through the official NAMD release in the near future. It is currently available as a part of the official NAMD GitLab repository: https://gitlab.com/tcbgUIUC/namd. However, the above version lacks complete GPU Resident mode support for IMDv3. The latest version with GPU Resident mode compatible optimization for IMDv3 is available in a branch of the official NAMD repository: https://gitlab.com/tcbgUIUC/namd/-/tree/fix-imdv3-gpures. NAMD *does* in principle support multiple concurrent connections to the same IMD port, however, this behavior has not been tested with IMDv3 and therefore should not be relied upon. Instead, we suggest rewriting a singular client's trajectory processing code to perform all tasks that multiple clients would have performed. This method will likely also reduce the TCP latency overhead of maintaining multiple client connections. If you have a use-case that this method doesn't cover, please `raise an issue`_. To use IMDv3 with NAMD, add the following lines to your NAMD configuration file: .. code-block:: none IMDon yes IMDport IMDwait IMDfreq IMDsendPositions IMDsendEnergies IMDsendTime IMDsendBoxDimensions IMDsendVelocities IMDsendForces IMDwrapPositions Once the simulation is ready for a client connection, it will print following terminal message: .. code-block:: none Info: INTERACTIVE MD AWAITING CONNECTION You are now ready to connect to the simulation engine with the IMDClient. Using IMDClient ^^^^^^^^^^^^^^^ Once the simulation is ready for a client connection, one can setup the client using the :class:`~imdclient.IMDClient` class: :: from imdclient.utils import parse_host_port from imdclient.IMDClient import IMDClient host, port = parse_host_port("imd://localhost:8888") # `n_atoms` is the number of atoms in the simulation # Adjust this value according to your simulation setup # This forms the connection and starts the simulation # by sending the `IMD_GO` client = IMDClient(host, port, n_atoms=1000) # Read trajectory data from the IMDBuffer which stores # data received from the socket i = 0 while True: try: frame = client.get_imdframe() except EOFError: break else: i += 1 # Process and analyze the frame data as needed # For example, print frame number, simulation time, and positions of atom 0 print(f"Frame {i}: time={frame.time}, atom 0 position={frame.positions[0]}") The :meth:`~imdclient.IMDClient.get_imdframe` method returns an :class:`~imdclient.IMDFrame` object containing the frame data read from the buffer and received from the socket. The above example can be used as a starting point to implement your own reader class that utilizes :class:`~imdclient.IMDClient` to read trajectory data from the socket and generate on-the-fly simulation analysis. .. SeeAlso:: `MDAnalysis `_ (from release 2.10.0 onwards) can directly read IMDv3 streams.