Add Transformation to set box dimensions

package/CHANGELOG

@@ -84,6 +84,8 @@ Fixes
   * Fix syntax warning over comparison of literals using is (Issue #3066)
 
 Enhancements
+  * Introduce possibility for setting box dimensions for all timesteps in 
+    trajectory (Issue #2691)
   * Adds preliminary support for the ppc64le platform with minimal
     dependencies (Issue #3127, PR #3149)
   * Caches can now undergo central validation at the Universe level, opening

package/MDAnalysis/transformations/__init__.py

@@ -130,3 +130,4 @@ def wrapped(ts):
 from .positionaveraging import PositionAverager
 from .fit import fit_translation, fit_rot_trans
 from .wrap import wrap, unwrap
+from .boxdimensions import SetDimensions

package/MDAnalysis/transformations/boxdimensions.py

@@ -0,0 +1,78 @@
+# -*- Mode: python; tab-width: 4; indent-tabs-mode:nil; coding:utf-8 -*-
+# vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4
+#
+# MDAnalysis --- https://www.mdanalysis.org
+# Copyright (c) 2006-2017 The MDAnalysis Development Team and contributors
+# (see the file AUTHORS for the full list of names)
+#
+# Released under the GNU Public Licence, v2 or any higher version
+#
+# Please cite your use of MDAnalysis in published work:
+#
+# R. J. Gowers, M. Linke, J. Barnoud, T. J. E. Reddy, M. N. Melo, S. L. Seyler,
+# D. L. Dotson, J. Domanski, S. Buchoux, I. M. Kenney, and O. Beckstein.
+# MDAnalysis: A Python package for the rapid analysis of molecular dynamics
+# simulations. In S. Benthall and S. Rostrup editors, Proceedings of the 15th
+# Python in Science Conference, pages 102-109, Austin, TX, 2016. SciPy.
+# doi: 10.25080/majora-629e541a-00e
+#
+# N. Michaud-Agrawal, E. J. Denning, T. B. Woolf, and O. Beckstein.
+# MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations.
+# J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
+#
+
+"""\
+Set box dimensions --- :mod: `MDAnalysis.transformations.boxdimensions`
+=======================================================================
+
+Set dimensions of the simulation box to a constant vector across all timesteps.
+
+
+..autocalss:: setdimensions
+"""
+import numpy as np
+
+
+class SetDimensions:
+    """
+    Set simulation box dimensions.
+
+    Timestep dimensions are modified in place.
+
+    Example
+    -------
+
+    e.g. set simulation box dimensions to a vector containing unit cell
+    dimensions [*a*, *b*, *c*, *alpha*, *beta*, *gamma*], lengths *a*,
+    *b*, *c* are in the MDAnalysis length unit (Å), and angles are in degrees.
+
+    dim = [2, 2, 2, 90, 90, 90]
+    transform = mda.transformations.boxdimensions.setdimensions(dim)
+    u.trajectory.add_transformations(transform)
+
+    Parameters
+    ----------
+    dimensions: array-like
+        vector that contains unit cell lengths and angles.
+        Expected shapes are (6, 0) or (1, 6)
+
+    Returns
+    -------
+    MDAnalysis.coordinates.base.Timestep
+    """
+
+    def __init__(self, dimensions):
+        self.dimensions = dimensions
+
+        try:
+            self.dimensions = np.asarray(self.dimensions, np.float32)
+            if self.dimensions.shape != (6, ) and \
+               self.dimensions.shape != (1, 6):
+                raise ValueError(f'{self.dimensions} are not valid box dimensions')
+            self.dimensions = self.dimensions.reshape(6, )
+        except ValueError:
+            raise ValueError(f'{self.dimensions} are not valid box dimensions')
+
+    def __call__(self, ts):
+        ts.dimensions = self.dimensions
+        return ts

testsuite/MDAnalysisTests/transformations/test_boxdimensions.py

@@ -0,0 +1,77 @@
+#-*- Mode: python; tab-width: 4; indent-tabs-mode:nil; coding:utf-8 -*-
+# vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4 fileencoding=utf-8
+#
+# MDAnalysis --- https://www.mdanalysis.org
+# Copyright (c) 2006-2017 The MDAnalysis Development Team and contributors
+# (see the file AUTHORS for the full list of names)
+#
+# Released under the GNU Public Licence, v2 or any higher version
+#
+# Please cite your use of MDAnalysis in published work:
+#
+# R. J. Gowers, M. Linke, J. Barnoud, T. J. E. Reddy, M. N. Melo, S. L. Seyler,
+# D. L. Dotson, J. Domanski, S. Buchoux, I. M. Kenney, and O. Beckstein.
+# MDAnalysis: A Python package for the rapid analysis of molecular dynamics
+# simulations. In S. Benthall and S. Rostrup editors, Proceedings of the 15th
+# Python in Science Conference, pages 102-109, Austin, TX, 2016. SciPy.
+# doi: 10.25080/majora-629e541a-00e
+#
+# N. Michaud-Agrawal, E. J. Denning, T. B. Woolf, and O. Beckstein.
+# MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations.
+# J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
+#
+
+import numpy as np
+import pytest
+from numpy.testing import assert_array_almost_equal
+
+import MDAnalysis as mdanalysis
+from MDAnalysis.transformations import SetDimensions
+from MDAnalysisTests import make_Universe
+
+
+@pytest.fixture()
+def boxdimensions_universes():
+    # create Universe objects for tests
+    ref_u = make_Universe(trajectory=True)
+    new_u = ref_u
+    return ref_u, new_u
+
+
+def test_boxdimensions_dims(boxdimensions_universes):
+    ref_u, new_u = boxdimensions_universes
+    ref = ref_u.trajectory.ts
+    new_dims = np.float32([2, 2, 2, 90, 90, 90])
+    ref.dimensions = new_dims
+    new = SetDimensions(new_dims)(new_u.trajectory.ts)
+    assert_array_almost_equal(ref.dimensions, new.dimensions, decimal=6)
+
+
+@pytest.mark.parametrize('dim_vector', (
+    [1, 1, 1, 90, 90],
+    [1, 1, 1, 1, 90, 90, 90],
+    ['a', 'b', 'c', 'd', 'e', 'f'],
+    np.array([1, 1, 1, 90, 90]),
+    np.array([1, 1, 1, 1, 90, 90, 90]),
+    np.array([[1], [1], [90], [90], [90]]),
+    np.array(['a', 'b', 'c', 'd', 'e', 'f']),
+    111,
+    'abcd')
+)
+
+
+def test_dimensions_vector(boxdimensions_universes, dim_vector):
+    # wrong box dimension vector size
+    ts = boxdimensions_universes[0].trajectory.ts
+    with pytest.raises(ValueError):
+        SetDimensions(dim_vector)(ts)
+
+
+def test_dimensions_transformations_api(boxdimensions_universes):
+    # test if transformation workes with on-the-fly transformations API
+    ref_u, new_u = boxdimensions_universes
+    ref = ref_u.trajectory.ts
+    new_dims = np.float32([2, 2, 2, 90, 90, 90])
+    ref.dimensions = new_dims
+    new = SetDimensions(new_dims)(new_u.trajectory.ts)
+    assert_array_almost_equal(ref.dimensions, new.dimensions, decimal=6)