Merge branch 'develop' into fix-hbond-iterator

Author: BradyAJohnston

.github/workflows/deploy.yaml

@@ -38,7 +38,6 @@ jobs:
       matrix:
         buildplat:
           - [ubuntu-22.04, manylinux_x86_64, x86_64]
-          - [macos-13, macosx_*, x86_64]
           - [windows-2022, win_amd64, AMD64]
           - [macos-14, macosx_*, arm64]
         python: ["cp311", "cp312", "cp313", "cp314"]

.github/workflows/gh-ci-cron.yaml

@@ -140,7 +140,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-22.04, macos-13]
+        os: [ubuntu-22.04, macos-14]
 
     steps:
     - uses: actions/checkout@v4

package/CHANGELOG

@@ -22,6 +22,8 @@ The rules for this file:
 Fixes
  * HydrogenBondAnalysis: Fixed `count_by_time()` when using `run(FrameIterator)` that
    results in `self.start` and `self.end` being None (Issue #5200, PR #5202)
+ * NoJump shows a more informative message and fails  when applied
+   outside of the first frame (Issue #4915, PR #5201)
  * DSSP now explicitly checks for a minimum of 6 residues and raises a clear
    error message, unlike the previous behavior where it would fail with an
    incomprehensible broadcasting error at execution time (Issue #5046, PR #5163)

package/MDAnalysis/analysis/msd.py

@@ -70,7 +70,34 @@
    
    In MDAnalysis you can use the 
    :class:`~MDAnalysis.transformations.nojump.NoJump`
-   transformation. 
+   transformation to unwrap coordinates on-the-fly.
+    
+   A minimal example:
+
+   .. code-block:: python
+      
+      import MDAnalysis as mda
+      from MDAnalysis.transformations import NoJump
+      
+      u = mda.Universe(TOP, TRAJ)
+      
+      # Apply NoJump transformation to unwrap coordinates
+      u.trajectory.add_transformations(NoJump(u))
+       
+      # Now the trajectory is unwrapped and MSD can be computed normally:
+      from MDAnalysis.analysis.msd import EinsteinMSD
+      MSD = EinsteinMSD(u, select="all", msd_type="xyz")
+      MSD.run()
+
+   This example assumes that the trajectory contains periodic box
+   dimensions. If no periodic boundary information is present, box
+   dimensions must be defined before applying ``NoJump``, which can
+   be accomplished by applying the
+   :class:`~MDAnalysis.transformations.boxdimensions.set_dimensions`
+   transformation *before* the 
+   :class:`~MDAnalysis.transformations.nojump.NoJump` transformation.
+   
+   This replaces the need to preprocess trajectories externally.
    
    In GROMACS, for example, this can be done using `gmx trjconv`_ with the
    ``-pbc nojump`` flag.

package/MDAnalysis/transformations/nojump.py

@@ -118,6 +118,13 @@ def _transform(self, ts):
         except np.linalg.LinAlgError:
             msg = f"Periodic box dimensions are not invertible at step {ts.frame}"
             raise NoDataError(msg)
+
+        if self.prev is None and ts.frame != 0:
+            raise ValueError(
+                "NoJump transformation must be applied starting from frame 0. "
+                f"Currently at frame {ts.frame}. Please reset trajectory to frame 0 before adding this transformation."
+            )
+
         if ts.frame == 0:
             # We don't need to apply the transformation here. However, we need to
             # ensure we have the 0th frame coordinates in reduced form. We also need to

testsuite/MDAnalysisTests/transformations/test_nojump.py

@@ -379,3 +379,18 @@ def test_notinvertible(nojump_universe):
         ]
         u.trajectory.add_transformations(*workflow)
         transformed_coordinates = u.trajectory.timeseries()[0]
+
+
+@pytest.mark.parametrize("frame_index", [-1, 5])
+def test_nojump_fails_when_not_at_frame_0(frame_index):
+    """
+    Test that NoJump raises a clear error when applied to a trajectory
+    that is not at frame 0.
+    """
+    u = mda.Universe(data.PSF_TRICLINIC, data.DCD_TRICLINIC)
+    u.trajectory[frame_index]
+
+    with pytest.raises(
+        ValueError, match="must be applied starting from frame 0"
+    ):
+        u.trajectory.add_transformations(NoJump())