fixed parse_rotation for simpler interface

It can now do + and cross-products so xy is
around the xy-plane normal vector.
This might be a bit unintuitive, but it makes
other things more consistent.

Author: zerothi

src/sisl/_core/_ufuncs_geometry.py

@@ -1176,14 +1176,12 @@ def rotate(
 
     Parameters
     ----------
-    angle :
-         the angle in degrees to rotate the geometry. Set the ``rad``
-         argument to use radians.
-    v     :
-         the normal vector to the rotated plane, i.e.
-         ``[1, 0, 0]`` will rotate around the :math:`yz` plane.
-         If a str it refers to the Cartesian direction (xyz), or the
-         lattice vectors (abc). Providing several is the combined direction.
+    rotation :
+         the rotation method used for rotating the geometry.
+         It is parsed through `sisl.utils.parse_rotation` and allows
+         a consecutive rotation method.
+
+         See examples for details.
     origin :
          the origin of rotation. Anything but ``[0, 0, 0]`` is equivalent
          to a ``geometry.translate(-origin).rotate(...).translate(origin)``.
@@ -1203,11 +1201,15 @@ def rotate(
     Examples
     --------
     rotate coordinates around the :math:`x`-axis
-    >>> geom_x45 = geom.rotate(45, [1, 0, 0])
+    >>> geom_x45 = geom.rotate([45, [1, 0, 0]])
 
     rotate around the ``(1, 1, 0)`` direction but project the rotation onto the :math:`x`
     axis
-    >>> geom_xy_x = geom.rotate(45, "xy", what='x')
+    >>> geom_xy_x = geom.rotate([45, "xy"], what='x')
+
+    Currently, there is a compatibility layer with the older API (pre 0.16.3)
+    which will be removed at some point. Please update your code to use the new-style
+    rotation arguments which is much more versatile; allowing consecutive rotations.
 
     See Also
     --------

src/sisl/_core/geometry.py

@@ -4223,7 +4223,7 @@ def __call__(self, parser, ns, values, option_string=None):
                 # Convert value[0] to the direction
                 # The rotate function expects degree
                 ang = angle(values[0], rad=False, in_rad=False)
-                ns._geometry = ns._geometry.rotate(ang, values[1], what="abc+xyz")
+                ns._geometry = ns._geometry.rotate([ang, values[1]], what="abc+xyz")
 
         p.add_argument(
             *opts("--rotate", "-R"),
@@ -4239,7 +4239,7 @@ class RotationX(argparse.Action):
                 def __call__(self, parser, ns, value, option_string=None):
                     # The rotate function expects degree
                     ang = angle(value, rad=False, in_rad=False)
-                    ns._geometry = ns._geometry.rotate(ang, "x", what="abc+xyz")
+                    ns._geometry = ns._geometry.rotate([ang, "x"], what="abc+xyz")
 
             p.add_argument(
                 *opts("--rotate-x", "-Rx"),
@@ -4252,7 +4252,7 @@ class RotationY(argparse.Action):
                 def __call__(self, parser, ns, value, option_string=None):
                     # The rotate function expects degree
                     ang = angle(value, rad=False, in_rad=False)
-                    ns._geometry = ns._geometry.rotate(ang, "y", what="abc+xyz")
+                    ns._geometry = ns._geometry.rotate([ang, "y"], what="abc+xyz")
 
             p.add_argument(
                 *opts("--rotate-y", "-Ry"),
@@ -4265,7 +4265,7 @@ class RotationZ(argparse.Action):
                 def __call__(self, parser, ns, value, option_string=None):
                     # The rotate function expects degree
                     ang = angle(value, rad=False, in_rad=False)
-                    ns._geometry = ns._geometry.rotate(ang, "z", what="abc+xyz")
+                    ns._geometry = ns._geometry.rotate([ang, "z"], what="abc+xyz")
 
             p.add_argument(
                 *opts("--rotate-z", "-Rz"),

src/sisl/_core/tests/test_geometry.py

@@ -408,67 +408,76 @@ def test_nsc2(self, setup):
         assert len(lattice.sc_off) == np.prod(lattice.nsc)
 
     def test_rotation1(self, setup):
-        rot = setup.g.rotate(180, [0, 0, 1], what="xyz+abc")
+        rot = setup.g.rotate([180, [0, 0, 1]], what="xyz+abc")
         rot.lattice.cell[2, 2] *= -1
         assert np.allclose(-rot.lattice.cell, setup.g.lattice.cell)
         assert np.allclose(-rot.xyz, setup.g.xyz)
 
-        rot = setup.g.rotate(np.pi, [0, 0, 1], rad=True, what="xyz+abc")
+        rot = setup.g.rotate([np.pi, [0, 0, 1]], rad=True, what="xyz+abc")
         rot.lattice.cell[2, 2] *= -1
         assert np.allclose(-rot.lattice.cell, setup.g.lattice.cell)
         assert np.allclose(-rot.xyz, setup.g.xyz)
 
-        rot = rot.rotate(180, "z", what="xyz+abc")
+        rot = rot.rotate([180, "z"], what="xyz+abc")
         rot.lattice.cell[2, 2] *= -1
         assert np.allclose(rot.lattice.cell, setup.g.lattice.cell)
         assert np.allclose(rot.xyz, setup.g.xyz)
 
+        # Just check it runs,
+        # xy-plane == z-direction
+        rot = setup.g.rotate([180, "xy"], what="xyz+abc")
+        rot.lattice.cell[2, 2] *= -1
+        assert np.allclose(-rot.lattice.cell, setup.g.lattice.cell)
+        assert np.allclose(-rot.xyz, setup.g.xyz)
+
+        rot.rotate([180, "x+y"], what="xyz+abc")
+
     def test_rotation2(self, setup):
-        rot = setup.g.rotate(180, "z", what="abc")
+        rot = setup.g.rotate([180, "z"], what="abc")
         rot.lattice.cell[2, 2] *= -1
         assert np.allclose(-rot.lattice.cell, setup.g.lattice.cell)
         assert np.allclose(rot.xyz, setup.g.xyz)
 
-        rot = setup.g.rotate(np.pi, [0, 0, 1], rad=True, what="abc")
+        rot = setup.g.rotate([np.pi, [0, 0, 1]], rad=True, what="abc")
         rot.lattice.cell[2, 2] *= -1
         assert np.allclose(-rot.lattice.cell, setup.g.lattice.cell)
         assert np.allclose(rot.xyz, setup.g.xyz)
 
-        rot = rot.rotate(180, [0, 0, 1], what="abc")
+        rot = rot.rotate([180, [0, 0, 1]], what="abc")
         rot.lattice.cell[2, 2] *= -1
         assert np.allclose(rot.lattice.cell, setup.g.lattice.cell)
         assert np.allclose(rot.xyz, setup.g.xyz)
 
     def test_rotation3(self, setup):
-        rot = setup.g.rotate(180, [0, 0, 1], what="xyz")
+        rot = setup.g.rotate([180, [0, 0, 1]], what="xyz")
         assert np.allclose(rot.lattice.cell, setup.g.lattice.cell)
         assert np.allclose(-rot.xyz, setup.g.xyz)
 
-        rot = setup.g.rotate(np.pi, [0, 0, 1], rad=True, what="xyz")
+        rot = setup.g.rotate([np.pi, [0, 0, 1]], rad=True, what="xyz")
         assert np.allclose(rot.lattice.cell, setup.g.lattice.cell)
         assert np.allclose(-rot.xyz, setup.g.xyz)
 
-        rot = rot.rotate(180, "z", what="xyz")
+        rot = rot.rotate([180, "z"], what="xyz")
         assert np.allclose(rot.lattice.cell, setup.g.lattice.cell)
         assert np.allclose(rot.xyz, setup.g.xyz)
 
     def test_rotation4(self, setup):
         ref = setup.g.tile(2, 0).tile(2, 1)
 
-        rot = ref.rotate(10, "z", atoms=1)
+        rot = ref.rotate([10, "z"], atoms=1)
         assert not np.allclose(ref.xyz[1], rot.xyz[1])
 
-        rot = ref.rotate(10, "z", atoms=[1, 2])
+        rot = ref.rotate([10, "z"], atoms=[1, 2])
         assert not np.allclose(ref.xyz[1], rot.xyz[1])
         assert not np.allclose(ref.xyz[2], rot.xyz[2])
         assert np.allclose(ref.xyz[3], rot.xyz[3])
 
-        rot = ref.rotate(10, "z", atoms=[1, 2], what="y")
+        rot = ref.rotate([10, "z"], atoms=[1, 2], what="y")
         assert ref.xyz[1, 0] == rot.xyz[1, 0]
         assert ref.xyz[1, 1] != rot.xyz[1, 1]
         assert ref.xyz[1, 2] == rot.xyz[1, 2]
 
-        rot = ref.rotate(10, "z", atoms=[1, 2], what="xy", origin=ref.xyz[2])
+        rot = ref.rotate([10, "z"], atoms=[1, 2], what="xy", origin=ref.xyz[2])
         assert ref.xyz[1, 0] != rot.xyz[1, 0]
         assert ref.xyz[1, 1] != rot.xyz[1, 1]
         assert ref.xyz[1, 2] == rot.xyz[1, 2]
@@ -669,8 +678,8 @@ def test___add1__(self, setup):
         assert np.allclose(double.xyz, d.xyz)
 
     def test___add2__(self, setup):
-        g1 = setup.g.rotate(15, setup.g.cell[2, :])
-        g2 = setup.g.rotate(30, setup.g.cell[2, :])
+        g1 = setup.g.rotate([15, setup.g.cell[2, :]])
+        g2 = setup.g.rotate([30, setup.g.cell[2, :]])
 
         assert g1 != g2
         assert g1 + g2 == g1.add(g2)
@@ -1559,11 +1568,11 @@ def test_geometry_dispatch(self):
         gr = sisl_geom.graphene()
         to_ase = gr.to.ase()
 
-        ase_rotate = si.rotate(to_ase, 30, [0, 0, 1])
+        ase_rotate = si.rotate(to_ase, [30, [0, 0, 1]])
         assert isinstance(ase_rotate, type(to_ase))
-        ase_sisl_rotate = si.rotate(to_ase, 30, [0, 0, 1], ret_sisl=True)
+        ase_sisl_rotate = si.rotate(to_ase, [30, [0, 0, 1]], ret_sisl=True)
         assert isinstance(ase_sisl_rotate, Geometry)
-        geom_rotate = si.rotate(gr, 30, [0, 0, 1])
+        geom_rotate = si.rotate(gr, [30, [0, 0, 1]])
 
         assert geom_rotate.equal(ase_sisl_rotate, R=False)
 

src/sisl/_core/tests/test_lattice.py

@@ -126,28 +126,28 @@ def test_add1(self, setup):
             assert np.allclose(s.cell, sc.cell + np.diag([R] * 3))
 
     def test_rotation1(self, setup):
-        rot = setup.lattice.rotate(180, [0, 0, 1])
+        rot = setup.lattice.rotate([180, [0, 0, 1]])
         rot.cell[2, 2] *= -1
         assert np.allclose(-rot.cell, setup.lattice.cell)
 
-        rot = setup.lattice.rotate(m.pi, [0, 0, 1], rad=True)
+        rot = setup.lattice.rotate([m.pi, [0, 0, 1]], rad=True)
         rot.cell[2, 2] *= -1
         assert np.allclose(-rot.cell, setup.lattice.cell)
 
-        rot = rot.rotate(180, [0, 0, 1])
+        rot = rot.rotate([180, [0, 0, 1]])
         rot.cell[2, 2] *= -1
         assert np.allclose(rot.cell, setup.lattice.cell)
 
     def test_rotation2(self, setup):
-        rot = setup.lattice.rotate(180, setup.lattice.cell[2, :])
+        rot = setup.lattice.rotate([180, setup.lattice.cell[2, :]])
         rot.cell[2, 2] *= -1
         assert np.allclose(-rot.cell, setup.lattice.cell)
 
-        rot = setup.lattice.rotate(m.pi, setup.lattice.cell[2, :], rad=True)
+        rot = setup.lattice.rotate([m.pi, setup.lattice.cell[2, :]], rad=True)
         rot.cell[2, 2] *= -1
         assert np.allclose(-rot.cell, setup.lattice.cell)
 
-        rot = rot.rotate(180, setup.lattice.cell[2, :])
+        rot = rot.rotate([180, setup.lattice.cell[2]])
         rot.cell[2, 2] *= -1
         assert np.allclose(rot.cell, setup.lattice.cell)
 
@@ -317,9 +317,9 @@ def test_creation_rotate(self, setup):
         assert np.allclose(parama, np.array(lattice.parameters(True)))
         for ang in range(0, 91, 5):
             s = (
-                lattice.rotate(ang, lattice.cell[0, :])
-                .rotate(ang, lattice.cell[1, :])
-                .rotate(ang, lattice.cell[2, :])
+                lattice.rotate([ang, lattice.cell[0]])
+                .rotate([ang, lattice.cell[1]])
+                .rotate([ang, lattice.cell[2]])
             )
             assert np.allclose(param, np.array(s.parameters()))
             assert np.allclose(parama, np.array(s.parameters(True)))
@@ -388,7 +388,7 @@ def test_parallel1(self, setup):
         gbig = g.repeat(40, 0).repeat(40, 1)
         assert g.lattice.parallel(gbig.lattice)
         assert gbig.lattice.parallel(g.lattice)
-        g = g.rotate(90, g.cell[0, :], what="abc")
+        g = g.rotate([90, g.cell[0]], what="abc")
         assert not g.lattice.parallel(gbig.lattice)
 
     def test_tile_multiply_orthogonal(self):
@@ -432,7 +432,7 @@ def test_angle2(self, setup):
 
     def test_cell2length(self):
         gr = graphene(orthogonal=True)
-        lattice = (gr * (40, 40, 1)).rotate(24, gr.cell[2, :]).lattice
+        lattice = (gr * (40, 40, 1)).rotate([24, gr.cell[2]]).lattice
         assert np.allclose(
             lattice.length, (lattice.cell2length(lattice.length) ** 2).sum(1) ** 0.5
         )

src/sisl/utils/mathematics.py

@@ -30,6 +30,7 @@
 from sisl import _array as _a
 from sisl._core.quaternion import Quaternion
 from sisl._indices import indices_le
+from sisl._internal import set_module
 from sisl.typing import RotationType
 
 from .misc import direction
@@ -356,6 +357,7 @@ def intersect_and_diff_sets(a, b):
     return int1d, aover, bover, aonly, bonly
 
 
+@set_module("sisl.utils")
 def parse_rotation(
     rotation: Union[RotationType, Sequence[RotationType]],
     rad: bool,
@@ -383,6 +385,12 @@ def parse_rotation(
     2nd index of the abc argument
     >>> q = parse_rotation([45, "b"], rad=False, abc=[[1, 0, 0], [0, 1, 0], [0, 0, 1]])
 
+    A rotation of 45 degrees around the :math:`xy` plane:
+    >>> q = parse_rotation([45, "xy"], rad=False)
+
+    A rotation of 45 degrees around the vector along :math:`x+y`:
+    >>> q = parse_rotation([45, "x+y"], rad=False)
+
     Explicitly specify the angle and the vector of rotation (around :math:`xy` vector)
     >>> q = parse_rotation([np.pi/4, [0.4, 0.4, 0]])
 
@@ -428,21 +436,27 @@ def parse_rotation(
         return q
 
     if lrot == 2 and (isinstance(rotation[0], str) or isinstance(rotation[1], str)):
+        # this is:
+        #  angle, direction
+        # or
+        #  direction, angle
 
         if isinstance(rotation[0], str):
-            dirs, angles = rotation
+            dirs, angle = rotation
         elif isinstance(rotation[1], str):
-            angles, dirs = rotation
-
-        if not isinstance(angles, (Sequence, np.ndarray)):
-            angles = [angles]
+            angle, dirs = rotation
 
         xyz = np.identity(3)
 
-        for angle, dir in zip_longest(angles, dirs):
-            # Convert to q
-            dir = direction(dir, abc=abc, xyz=xyz)
-            q = Quaternion(angle, dir / fnorm(dir), rad=rad) * q
+        dir = 0.0
+        for outer_dir in dirs.split("+"):
+            tmp_dir = direction(outer_dir[0], abc=abc, xyz=xyz)
+            for inner_dir in outer_dir[1:]:
+                tmp_dir = np.cross(tmp_dir, direction(inner_dir, abc=abc, xyz=xyz))
+
+            dir = dir + tmp_dir
+
+        q = Quaternion(angle, dir / fnorm(dir), rad=rad)
 
         return q