Refactor Transformations from closure into class

package/CHANGELOG

@@ -111,6 +111,7 @@ Changes
   * Sets the minimal RDKit version for CI to 2020.03.1 (Issue #2827, PR #2831)
   * Removes deprecated waterdynamics.HydrogenBondLifetimes (PR #2842)
   * Make NeighborSearch return empty atomgroup, residue, segments instead of list (Issue #2892, PR #2907)
+  * Updated Universe creation function signatures to named arguments (Issue #2921)  
   * The transformation was changed from a function/closure to a class with
     `__call__` (Issue #2860, PR #2859)
 

package/MDAnalysis/transformations/__init__.py

@@ -22,7 +22,7 @@
 #
 
 
-"""\
+"""
 Trajectory transformations --- :mod:`MDAnalysis.transformations`
 ================================================================
 
@@ -32,7 +32,9 @@
 are often required for some analyses and visualization, and the functions in
 this module allow transformations to be applied on-the-fly.
 
-A typical transformation class looks like this:
+A typical transformation class looks like this (note that we keep its name
+lowercase because we will treat it as a function, thanks to the ``__call__``
+method):
 
 .. code-blocks:: python
 
@@ -48,7 +50,32 @@ def __call__(self, ts):
 
             return ts
 
-See `MDAnalysis.transformations.translate` for a simple example.
+As a concrete example we will write a transformation that rotates a group of
+atoms around the z-axis through the center of geometry by a fixed increment
+for every time step. We will use
+:meth:`MDAnalysis.core.groups.AtomGroup.rotateby`
+and simply increment the rotation angle every time the
+transformation is called ::
+
+    class spin_atoms(object):
+        def __init__(self, atoms, dphi):
+            #  Rotate atoms by dphi degrees for every ts around the z axis
+            self.atoms = atoms
+            self.dphi = dphi
+            self.axis = np.array([0, 0, 1])
+            self.phi = 0
+
+        def __call__(self, ts):
+            self.atoms.rotateby(self.phi, self.axis)
+            self.phi += self.dphi
+            return ts
+
+This transformation can be used as ::
+
+   u = mda.Universe(PSF, DCD)
+   u.trajectory.add_transformations(spin_atoms(u.select_atoms("protein"), 1.0))
+
+Alos see :mod:`MDAnalysis.transformations.translate` for a simple example.
 
 These transformation functions can be called by the user for any given timestep
 of the trajectory, added as a workflow using :meth:`add_transformations`

testsuite/MDAnalysisTests/parallelism/test_pickle_transformation.py

@@ -22,7 +22,7 @@
 #
 import pytest
 import pickle
-from numpy.testing import assert_equal
+from numpy.testing import assert_almost_equal
 
 import MDAnalysis as mda
 
@@ -93,7 +93,7 @@ def test_add_fit_translation_pickle(fit_translation_transformation, u):
     u_p = pickle.loads(pickle.dumps(u))
     u.trajectory[0]
     for u_ts, u_p_ts in zip(u.trajectory[:5], u_p.trajectory[:5]):
-        assert_equal(u_ts.positions, u_p_ts.positions)
+        assert_almost_equal(u_ts.positions, u_p_ts.positions)
 
 
 def test_add_fit_rot_trans_pickle(fit_rot_trans_transformation,
@@ -102,52 +102,52 @@ def test_add_fit_rot_trans_pickle(fit_rot_trans_transformation,
     u_p = pickle.loads(pickle.dumps(u))
     u.trajectory[0]
     for u_ts, u_p_ts in zip(u.trajectory[:5], u_p.trajectory[:5]):
-        assert_equal(u_ts.positions, u_p_ts.positions)
+        assert_almost_equal(u_ts.positions, u_p_ts.positions)
 
 
 def test_add_PositionAverager_pickle(PositionAverager_transformation, u):
     u.trajectory.add_transformations(PositionAverager_transformation)
     u_p = pickle.loads(pickle.dumps(u))
     u.trajectory[0]
     for u_ts, u_p_ts in zip(u.trajectory[:5], u_p.trajectory[:5]):
-        assert_equal(u_ts.positions, u_p_ts.positions)
+        assert_almost_equal(u_ts.positions, u_p_ts.positions)
 
 
 def test_add_rotateby_pickle(rotateby_transformation, u):
     u.trajectory.add_transformations(rotateby_transformation)
     u_p = pickle.loads(pickle.dumps(u))
     u.trajectory[0]
     for u_ts, u_p_ts in zip(u.trajectory[:5], u_p.trajectory[:5]):
-        assert_equal(u_ts.positions, u_p_ts.positions)
+        assert_almost_equal(u_ts.positions, u_p_ts.positions)
 
 
 def test_add_translate_pickle(translate_transformation, u):
     u.trajectory.add_transformations(translate_transformation)
     u_p = pickle.loads(pickle.dumps(u))
     u.trajectory[0]
     for u_ts, u_p_ts in zip(u.trajectory[:5], u_p.trajectory[:5]):
-        assert_equal(u_ts.positions, u_p_ts.positions)
+        assert_almost_equal(u_ts.positions, u_p_ts.positions)
 
 
 def test_add_center_in_box_pickle(center_in_box_transformation, u):
     u.trajectory.add_transformations(center_in_box_transformation)
     u_p = pickle.loads(pickle.dumps(u))
     u.trajectory[0]
     for u_ts, u_p_ts in zip(u.trajectory[:5], u_p.trajectory[:5]):
-        assert_equal(u_ts.positions, u_p_ts.positions)
+        assert_almost_equal(u_ts.positions, u_p_ts.positions)
 
 
 def test_add_wrap_pickle(wrap_transformation, u):
     u.trajectory.add_transformations(wrap_transformation)
     u_p = pickle.loads(pickle.dumps(u))
     u.trajectory[0]
     for u_ts, u_p_ts in zip(u.trajectory[:5], u_p.trajectory[:5]):
-        assert_equal(u_ts.positions, u_p_ts.positions)
+        assert_almost_equal(u_ts.positions, u_p_ts.positions)
 
 
 def test_add_unwrap_pickle(unwrap_transformation, u):
     u.trajectory.add_transformations(unwrap_transformation)
     u_p = pickle.loads(pickle.dumps(u))
     u.trajectory[0]
     for u_ts, u_p_ts in zip(u.trajectory[:5], u_p.trajectory[:5]):
-        assert_equal(u_ts.positions, u_p_ts.positions)
+        assert_almost_equal(u_ts.positions, u_p_ts.positions)