Merge branch 'main' into copilot/fix-84

Author: orbeckst

.github/workflows/gh-ci.yaml

@@ -48,7 +48,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [macOS-latest, ubuntu-latest]
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
     - uses: actions/checkout@v4
@@ -171,7 +171,16 @@ jobs:
   
       - name: Run simulation engine tests
         run: |
-          pytest -v --color=yes ${{ matrix.script }}
+          pytest -v --cov=imdclient --cov-report=xml --color=yes ${{ matrix.script }}
+
+      - name: codecov
+        if: github.event_name != 'schedule'
+        uses: codecov/codecov-action@v5.4.3
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+          name: codecov-${{ matrix.name }}
+          verbose: True
 
   pylint_check:
     if: github.repository == 'Becksteinlab/imdclient'

AUTHORS.md

@@ -19,8 +19,14 @@ The rules for this file:
   * Don't ever delete anything
 -->
 
+**2024**
+- Lawson Woods <@ljwoods2>
+- Heekun Cho <@hcho38>
+- Oliver Beckstein <@orbeckst>
+
 **2025**
 - Amruthesh Thirumalaiswamy <@amruthesht>
-
-**2024**
-- Lawson <@ljwoods2>
+- Jennifer A. Clark <@jaclark5>
+- Hugo MacDermott-Opeskin <@hmacdope>
+- Matthias Heyden <@HeydenLabASU>
+- GitHub co-pilot <@copilot>

CHANGELOG.md

@@ -16,24 +16,32 @@ The rules for this file:
   * accompany each entry with github issue/PR number (Issue #xyz)
 -->
 
-## [v0.2.0] - 2025-??-??
+## [v0.2.0] - 2025-07-18
+
+**Breaking change**: The removal of the IMDReader and the associated
+streaming analysis functionality will *break code* (see issue
+#53). The IMDReader is being integrated into MDAnalysis and should be
+available in MDAnalysis release 2.10.0.
 
 ### Authors
 <!-- GitHub usernames of contributors to this release -->
-@amruthesht @ljwoods2
+@amruthesht @ljwoods2 @hmacdope @jaclark5 @orbeckst
+
+### Changed
+<!-- Changes in existing functionality -->
+* IMDReader removed from imdclient by @amruthesht in https://github.com/Becksteinlab/imdclient/pull/54 (issue #53)
+* added support for Python 3.13 (issue #90)
 
 ### Added
 <!-- New added features -->
 * Updated installation instructions by @amruthesht in https://github.com/Becksteinlab/imdclient/pull/74
-* MD engine links updated in IMDClient documnetation by @amruthesht in https://github.com/Becksteinlab/imdclient/pull/73
-* Parse input files for DT when not in traj by @ljwoods2 in https://github.com/Becksteinlab/imdclient/pull/71
+* MD engine links updated in IMDClient documentation by @amruthesht in https://github.com/Becksteinlab/imdclient/pull/73
+* Testing: Parse input files for DT when not in traj by @ljwoods2 in https://github.com/Becksteinlab/imdclient/pull/71
 
 ### Fixed
 <!-- Bug fixes -->
+* updated deployment workflow to use latest pypa/gh-action-pypi-publish@v1.12.4 action (PR #78)
 
-### Changed
-<!-- Changes in existing functionality -->
-* IMDReader removed from imdclient by @amruthesht in https://github.com/Becksteinlab/imdclient/pull/54
 
 ### Deprecated
 <!-- Soon-to-be removed features -->

README.md

@@ -25,6 +25,8 @@ IMDClient is bound by a [Code of Conduct](https://github.com/becksteinlab/imdcli
 
 ### Installation
 
+IMDClient requires Python 3.10 or higher.
+
 #### Install via mamba (recommended)
 To install the latest release of IMDClient from conda-forge:
 

docs/source/getting_started.rst

@@ -4,6 +4,8 @@ Getting Started
 Installation
 ############
 
+IMDClient requires Python 3.10 or higher.
+
 Install via mamba (recommended)
 -------------------------------
 

docs/source/usage.rst

@@ -13,8 +13,18 @@ simulation engine 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 ; clone the 
+repository and build GROMACS from source.
+
 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)*.
+
 In GROMACS, you will know that the simulation is ready and waiting for the
 IMDClient when this line is printed to the terminal:
 
@@ -24,8 +34,18 @@ IMDClient when this line is printed to the terminal:
 
 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
+
+
+
 NAMD
 ----
+The IMDv3 protocol has been implementaed 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.
+
 To use IMDv3 with NAMD, add the following lines to your NAMD configuration file:
 
 .. code-block:: none
@@ -55,6 +75,11 @@ You are now ready to connect to the simulation engine with the IMDClient.
 
 LAMMPS
 ------
+The IMDv3 protocol is part of the official LAMMPS distribution since ``patch_4Feb2025``.
+It is available in the LAMMPS source code repository - https://github.com/lammps/lammps.
+Information on using IMDv3 with LAMMPS can be found in the LAMMPS documentation
+- https://docs.lammps.org/fix_imd.html
+
 To use IMDv3 with LAMMPS, add the following lines to your LAMMPS input script:
 
 .. code-block:: none

imdclient/tests/server.py

@@ -29,14 +29,25 @@ def __init__(self, traj):
         self.listen_socket = None
         self.conn = None
         self.accept_thread = None
+        self._bound_port = None
 
     def set_imdsessioninfo(self, imdsinfo):
         self.imdsinfo = imdsinfo
 
-    def handshake_sequence(self, host, port, first_frame=True):
+    @property
+    def port(self):
+        """Get the port the server is bound to.
+        
+        Returns:
+            int: The port number, or None if not bound yet.
+        """
+        return self._bound_port
+
+    def handshake_sequence(self, host, first_frame=True):
         s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-        s.bind((host, port))
-        logger.debug(f"InThreadIMDServer: Listening on {host}:{port}")
+        s.bind((host, 0))  # Bind to port 0 to get a free port
+        self._bound_port = s.getsockname()[1]  # Store the actual bound port
+        logger.debug(f"InThreadIMDServer: Listening on {host}:{self._bound_port}")
         s.listen(60)
         self.listen_socket = s
 

imdclient/tests/test_imdclient.py

@@ -15,7 +15,6 @@
 from imdclient.IMDClient import imdframe_memsize, IMDClient
 from imdclient.IMDProtocol import IMDHeaderType
 from .utils import (
-    get_free_port,
     create_default_imdsinfo_v3,
 )
 from .server import InThreadIMDServer
@@ -46,10 +45,6 @@
 
 class TestIMDClientV3:
 
-    @pytest.fixture
-    def port(self):
-        return get_free_port()
-
     @pytest.fixture
     def universe(self):
         return mda.Universe(COORDINATES_TOPOLOGY, COORDINATES_H5MD)
@@ -59,13 +54,13 @@ def imdsinfo(self):
         return create_default_imdsinfo_v3()
 
     @pytest.fixture
-    def server_client_two_frame_buf(self, universe, imdsinfo, port):
+    def server_client_two_frame_buf(self, universe, imdsinfo):
         server = InThreadIMDServer(universe.trajectory)
         server.set_imdsessioninfo(imdsinfo)
-        server.handshake_sequence("localhost", port, first_frame=False)
+        server.handshake_sequence("localhost", first_frame=False)
         client = IMDClient(
             f"localhost",
-            port,
+            server.port,
             universe.trajectory.n_atoms,
             buffer_size=imdframe_memsize(universe.trajectory.n_atoms, imdsinfo)
             * 2,
@@ -76,14 +71,14 @@ def server_client_two_frame_buf(self, universe, imdsinfo, port):
         server.cleanup()
 
     @pytest.fixture(params=[">", "<"])
-    def server_client(self, universe, imdsinfo, port, request):
+    def server_client(self, universe, imdsinfo, request):
         server = InThreadIMDServer(universe.trajectory)
         imdsinfo.endianness = request.param
         server.set_imdsessioninfo(imdsinfo)
-        server.handshake_sequence("localhost", port, first_frame=False)
+        server.handshake_sequence("localhost", first_frame=False)
         client = IMDClient(
             f"localhost",
-            port,
+            server.port,
             universe.trajectory.n_atoms,
         )
         server.join_accept_thread()
@@ -168,13 +163,13 @@ def test_pause_resume_no_disconnect(self, server_client_two_frame_buf):
         server.expect_packet(IMDHeaderType.IMD_DISCONNECT)
 
     @pytest.mark.parametrize("cont", [True, False])
-    def test_continue_after_disconnect(self, universe, imdsinfo, port, cont):
+    def test_continue_after_disconnect(self, universe, imdsinfo, cont):
         server = InThreadIMDServer(universe.trajectory)
         server.set_imdsessioninfo(imdsinfo)
-        server.handshake_sequence("localhost", port, first_frame=False)
+        server.handshake_sequence("localhost", first_frame=False)
         client = IMDClient(
             f"localhost",
-            port,
+            server.port,
             universe.trajectory.n_atoms,
             continue_after_disconnect=cont,
         )
@@ -198,10 +193,6 @@ def test_incorrect_atom_count(self, server_client_incorrect_atoms, universe):
 
 
 class TestIMDClientV3ContextManager:
-    @pytest.fixture
-    def port(self):
-        return get_free_port()
-
     @pytest.fixture
     def universe(self):
         return mda.Universe(COORDINATES_TOPOLOGY, COORDINATES_H5MD)
@@ -211,19 +202,19 @@ def imdsinfo(self):
         return create_default_imdsinfo_v3()
 
     @pytest.fixture
-    def server(self, universe, imdsinfo, port):
+    def server(self, universe, imdsinfo):
         server = InThreadIMDServer(universe.trajectory)
         server.set_imdsessioninfo(imdsinfo)
         yield server
         server.cleanup()
 
-    def test_context_manager_traj_unchanged(self, server, port, universe):
-        server.handshake_sequence("localhost", port, first_frame=False)
+    def test_context_manager_traj_unchanged(self, server, universe):
+        server.handshake_sequence("localhost", first_frame=False)
 
         i = 0
         with IMDClient(
             "localhost",
-            port,
+            server.port,
             universe.trajectory.n_atoms,
         ) as client:
             server.send_frames(0, 5)