update changelog and cleanup example for from_path_ends

Author: argerlt

CHANGELOG.rst

@@ -34,6 +34,8 @@ Added
   An example of a custom projection is the :class:`~orix.plot.StereographicPlot`.
   This function replaces the previous behavior of relying on a side-effect of importing
   the :mod:`orix.plot` module, which also registered the projections.
+- :func:`~orix.quaternion.Rotation.from_path_ends` returns evenly spaced points
+  mapping the shortest path betwen two or more rotations.
 
 Changed
 -------

examples/plotting/paths_through_orientation_space.py renamed to examples/plotting/visualizing_crystallographic_paths.py

@@ -1,16 +1,22 @@
 r"""
 =========================================
- Plot Paths In Rotation and Vector Space
+Visualizing crystallographic paths
 =========================================
-This example shows how paths though either rotation or vector space
-can be plotted using ORIX. These are the shortest paths through their
-respective spaces, and thus not always straight lines in euclidean
-projections (axis-angle, stereographic, etc.).
+
+This example shows how define and plot paths through either
+rotation or vector space.This is akin to describing crystallographic
+fiber textures in metallurgy, or the shortest arcs connecting points on
+the surface of a unit sphere.
+
+In both cases, "shortest" is defined as the route that minimizes the
+movement required to transform from point to point, which is typically
+not a stright line when plotted into a euclidean projection
+(axis-angle, stereographic, etc.).
+
 This functionality is available in :class:`~orix.vector.Vector3d`,
 :class:`~orix.quaternions.Rotation`,
 :class:`~orix.quaternions.Orientation`,
-and :class:`~orix.quaternions.Misorientation`.
-"""
+and :class:`~orix.quaternions.Misorientation`."""
 
 from matplotlib import cm
 import matplotlib.pyplot as plt
@@ -31,16 +37,18 @@
 fig = plt.figure(figsize=(6, 6))
 n_steps = 30
 
-# ========= #
+# ============ #
 # Example 1: Plotting multiple paths into a user defined axis
-# ========= #
+
 # This subplot shows several paths through the cubic (m3m) fundamental zone
 # created by rotating 20 randomly chosen points 30 degrees around the z axis.
 # these paths are drawn in rodrigues space, which is an equal-angle projection
 # of rotation space. As such, notice how all lines tracing out axial rotations
 # are straight, but lines starting closer to the center of the fundamental zone
 # appear shorter.
+
 # the sampe paths are then also plotted on an Inverse Pole Figure (IPF) plot.
+
 rod_ax = fig.add_subplot(2, 2, 1, projection="rodrigues", proj_type="ortho")
 ipf_ax = fig.add_subplot(2, 2, 2, projection="ipf", symmetry=Oh)
 
@@ -86,20 +94,22 @@
 ipf_ax.set_title(r"IPF, multiple paths        ")
 
 
-# %%
-# ========= #
+# ============ #
 # Example 2: Plotting a path using `Rotation.scatter'
-# ========= #
 # This subplot traces the path of an object rotated 90 degrees around the
 # X axis, then 90 degrees around the Y axis.
+
 rots = Orientation.from_axes_angles(
     [[1, 0, 0], [1, 0, 0], [0, 1, 0]], [0, 90, 90], degrees=True, symmetry=C1
 )
 rots[2] = rots[1] * rots[2]
 path = Orientation.from_path_ends(rots, steps=n_steps)
 # create a list of RGBA color values for a gradient red line and blue line
 path_colors = np.vstack(
-    [cm.Reds(np.linspace(0.5, 1, n_steps)), cm.Blues(np.linspace(0.5, 1, n_steps))]
+    [
+        cm.Reds(np.linspace(0.5, 1, n_steps)),
+        cm.Blues(np.linspace(0.5, 1, n_steps)),
+    ]
 )
 
 # Here, we instead use the in-built plotting tool from
@@ -108,11 +118,10 @@
 path.scatter(figure=fig, position=[2, 2, 3], marker=">", c=path_colors)
 fig.axes[2].set_title(r"Axis-Angle, two $90^\circ$ rotations")
 
-# %%
 
-# ========= #
+# ============ #
 # Example 3: paths in stereographic plots
-# ========= #
+
 # This is similar to the second example, but now vectors are being rotated
 # 30 degrees around the [1,1,1] axis on a stereographic plot.
 

orix/quaternion/misorientation.py

@@ -84,7 +84,9 @@ def symmetry(self) -> tuple[Symmetry, Symmetry]:
         return self._symmetry
 
     @symmetry.setter
-    def symmetry(self, value: list[Symmetry] | tuple[Symmetry, Symmetry]) -> None:
+    def symmetry(
+        self, value: list[Symmetry] | tuple[Symmetry, Symmetry]
+    ) -> None:
         if not isinstance(value, (list, tuple)):
             raise TypeError("Value must be a 2-tuple of Symmetry objects.")
         if len(value) != 2 or not all(isinstance(s, Symmetry) for s in value):
@@ -277,41 +279,43 @@ def from_scipy_rotation(
     def from_path_ends(
         cls, points: Misorientation, closed: bool = False, steps: int = 100
     ) -> Misorientation:
-        """Return misorientations tracing the shortest path (ignoring
-        symmetry) between two or more consecutive points.
+        """Return misorientations tracing the shortest path between
+        two or more consecutive points.
 
         Parameters
         ----------
         points
-            Two or more misorientations that define waypoints along
-            a path through rotation space (SO3).
+            Two or more misorientations that define points along the
+            path.
         closed
-            Option to add a final trip from the last waypoint back to
+            Option to add a final trip from the last point back to
             the first, thus closing the loop. The default is False.
         steps
-            Number of misorientations to return along the path
-            between each pair of waypoints. The default is 100.
+            Number of misorientations to return between each point
+            along the path defined by `points`. The default is 100.
 
         Returns
         -------
         path
-            misorientations that map a path between the given waypoints.
+            regularly spaced misorientations following the shortest
+            path.
 
-        Note
-        -------
-        This function traces a path between points in SO(3), in which there
-        is one and only one direct path between every point. The equivalent
-        is not well-defined for misorientations, which define multiple
-        symmetrically-equivalent points in SO(3) with non-equivalent paths
-        between them.
+        Notes
+        -----
+        This function traces the shortest path between points without
+        any regard to symmetry. Concept of "shortest path" is not
+        well-defined for misorientations, which can define multiple
+        symmetrically equivalent points with non-equivalent paths.
         """
         # Confirm `points` are misorientations.
         if type(points) is not cls:
             raise TypeError(
                 f"Points must be a Misorientation, not of type {type(points)}"
             )
         # Create a path through Quaternion space, then reapply the symmetry.
-        out = Rotation.from_path_ends(points=points, closed=closed, steps=steps)
+        out = Rotation.from_path_ends(
+            points=points, closed=closed, steps=steps
+        )
         return cls(out.data, symmetry=points.symmetry)
 
     @classmethod
@@ -390,7 +394,9 @@ def equivalent(self, grain_exchange: bool = False) -> Misorientation:
         return self.__class__(equivalent).flatten()
 
     @deprecated(since="0.14", removal="0.15", alternative="reduce")
-    def map_into_symmetry_reduced_zone(self, verbose: bool = False) -> Misorientation:
+    def map_into_symmetry_reduced_zone(
+        self, verbose: bool = False
+    ) -> Misorientation:
         """Return equivalent transformations which have the smallest
         angle of rotation as a new misorientation.
 
@@ -549,7 +555,9 @@ def scatter(
         ax._correct_aspect_ratio(fundamental_zone)
 
         ax.axis("off")
-        figure.subplots_adjust(left=0, right=1, bottom=0, top=1, hspace=0, wspace=0)
+        figure.subplots_adjust(
+            left=0, right=1, bottom=0, top=1, hspace=0, wspace=0
+        )
 
         if size is not None:
             to_plot = self.get_random_sample(size)

orix/quaternion/orientation.py

@@ -75,7 +75,9 @@ def symmetry(self) -> Symmetry:
     @symmetry.setter
     def symmetry(self, value: Symmetry) -> None:
         if not isinstance(value, Symmetry):
-            raise TypeError("Value must be an instance of orix.quaternion.Symmetry.")
+            raise TypeError(
+                "Value must be an instance of orix.quaternion.Symmetry."
+            )
         self._symmetry = (C1, value)
 
     @property
@@ -356,39 +358,40 @@ def from_scipy_rotation(
     def from_path_ends(
         cls, points: Orientation, closed: bool = False, steps: int = 100
     ) -> Misorientation:
-        """Return orientations tracing the shortest path (ignoring
-        symmetry) between two or more consecutive points.
+        """Return orientations tracing the shortest path between two
+        or more consecutive points.
 
         Parameters
         ----------
         points
-            Two or more orientations that define waypoints along
-            a path through rotation space (SO3).
+            Two or more orientations that define points along the
+            path.
         closed
-            Option to add a final trip from the last waypoint back to
+            Option to add a final trip from the last point back to
             the first, thus closing the loop. The default is False.
         steps
-            Number of orientations to return along the path
-            between each pair of waypoints. The default is 100.
+            Number of orientations to return between each point
+            along the path defined by `points`. The default is 100.
 
         Returns
         -------
         path
-            orientations that map a path between the given waypoints.
+            regularly spaced orientations following the shortest path.
 
-        Note
-        -------
-        This function traces a path between points in SO(3), in which there
-        is one and only one direct path between every point. The equivalent
-        is not well-defined for orientations, which define multiple
-        symmetrically-equivalent points in SO(3) with non-equivalent paths
-        between them.
+        Notes
+        -----
+        This function traces the shortest path between points without
+        any regard to symmetry. Concept of "shortest path" is not
+        well-defined for orientations, which can define multiple
+        symmetrically equivalent points with non-equivalent paths.
         """
         if type(points) is not cls:
             raise TypeError(
                 f"Points must be an Orientation instance, not of type {type(points)}"
             )
-        out = Rotation.from_path_ends(points=points, closed=closed, steps=steps)
+        out = Rotation.from_path_ends(
+            points=points, closed=closed, steps=steps
+        )
         return cls(out.data, symmetry=points.symmetry)
 
     @classmethod
@@ -417,7 +420,9 @@ def random(
 
     # --------------------- Other public methods --------------------- #
 
-    def angle_with(self, other: Orientation, degrees: bool = False) -> np.ndarray:
+    def angle_with(
+        self, other: Orientation, degrees: bool = False
+    ) -> np.ndarray:
         """Return the smallest symmetry reduced angles of rotation
         transforming the orientations to the other orientations.
 
@@ -707,7 +712,9 @@ def plot_unit_cell(
             If :attr:`size` > 1.
         """
         if self.size > 1:
-            raise ValueError("Can only plot a single unit cell, so *size* must be 1")
+            raise ValueError(
+                "Can only plot a single unit cell, so *size* must be 1"
+            )
 
         from orix.plot.unit_cell_plot import _plot_unit_cell
 
@@ -748,8 +755,12 @@ def in_euler_fundamental_region(self) -> np.ndarray:
 
         # Find the first triplet among the symmetrically equivalent ones
         # inside the fundamental region
-        max_alpha, max_beta, max_gamma = np.radians(pg.euler_fundamental_region)
-        is_inside = (alpha <= max_alpha) * (beta <= max_beta) * (gamma <= max_gamma)
+        max_alpha, max_beta, max_gamma = np.radians(
+            pg.euler_fundamental_region
+        )
+        is_inside = (
+            (alpha <= max_alpha) * (beta <= max_beta) * (gamma <= max_gamma)
+        )
         first_nonzero = np.argmax(is_inside, axis=1)
 
         euler_in_region = np.column_stack(
@@ -764,7 +775,9 @@ def in_euler_fundamental_region(self) -> np.ndarray:
 
     def scatter(
         self,
-        projection: Literal["axangle", "rodrigues", "homochoric", "ipf"] = "axangle",
+        projection: Literal[
+            "axangle", "rodrigues", "homochoric", "ipf"
+        ] = "axangle",
         figure: mfigure.Figure | None = None,
         position: int | tuple[int, int, int] | SubplotSpec | None = None,
         return_figure: bool = False,
@@ -890,7 +903,9 @@ def inv(self) -> Orientation:
 
     # -------------------- Other private methods --------------------- #
 
-    def _dot_outer_dask(self, other: Orientation, chunk_size: int = 20) -> da.Array:
+    def _dot_outer_dask(
+        self, other: Orientation, chunk_size: int = 20
+    ) -> da.Array:
         """Symmetry reduced dot product of every orientation in this
         instance to every orientation in another instance, returned as a
         Dask array.