Rephrase docstring of get_sample_reduced_fundamental()

Signed-off-by: Håkon Wiik Ånes <[email protected]>

orix/sampling/sample_generators.py

@@ -20,8 +20,8 @@
 
 import numpy as np
 
-from orix.quaternion import OrientationRegion, Rotation, Symmetry, symmetry
-from orix.quaternion.symmetry import get_point_group
+from orix.quaternion import OrientationRegion, Rotation, Symmetry
+from orix.quaternion.symmetry import C1, get_point_group
 from orix.sampling import sample_S2
 from orix.sampling.SO3_sampling import _three_uniform_samples_method, uniform_SO3_sample
 from orix.sampling._cubochoric_sampling import cubochoric_sampling
@@ -40,7 +40,7 @@ def get_sample_fundamental(
     ----------
     resolution
         The characteristic distance between a rotation and its neighbour
-        in degrees.
+        in degrees. Default is 2 degrees.
     point_group
         One of the 11 proper point groups. If not given, ``space_group``
         must be.
@@ -104,13 +104,13 @@ def get_sample_local(
     ----------
     resolution
         The characteristic distance between a rotation and its neighbour
-        in degrees.
+        in degrees. Default is 2 degrees.
     center
         The rotation at which the grid is centered. The identity is used
         if not given.
     grid_width
         The largest angle of rotation in degrees away from center that
-        is acceptable.
+        is acceptable. Default is 10 degrees.
     method
         ``"cubochoric"`` (default), ``"haar_euler"`` or
         ``"quaternion"``. See :func:`~orix.sampling.uniform_SO3_sample`
@@ -169,37 +169,42 @@ def _remove_larger_than_angle(rot: Rotation, max_angle: Union[int, float]) -> Ro
 
 
 def get_sample_reduced_fundamental(
-    resolution: float,
-    mesh: str = None,
-    point_group: Symmetry = None,
+    resolution: float = 2,
+    method: Optional[str] = None,
+    point_group: Optional[Symmetry] = None,
 ) -> Rotation:
-    """Produces rotations to align various crystallographic directions with
-    the z-axis, with the constraint that the first Euler angle phi_1=0.
-    The crystallographic directions sample the fundamental zone, representing
-    the smallest region of symmetrically unique directions of the relevant
-    crystal system or point group.
+    r"""Return a grid of rotations that rotate the Z-vector (0, 0, 1)
+    into the fundamental sector of a point group's Laue group.
+
+    The rotations are constrained in that the first Euler angle is
+    :math:`\phi_1 = 0^{\circ}`.
+
     Parameters
     ----------
     resolution
-        An angle in degrees representing the maximum angular distance to a
-        first nearest neighbor grid point.
-    mesh
-        Type of meshing of the sphere that defines how the grid is created. See
-        orix.sampling.sample_S2 for all the options. A suitable default is
-        chosen depending on the crystal system.
+        The characteristic distance between a rotation and its neighbour
+        in degrees. Default is 2 degrees.
+    method
+        Name of method to mesh the unit sphere. See
+        :func:`orix.sampling.sample_S2` for options. If not given, a
+        suitable default is chosen given by the crystal system of the
+        given point group.
     point_group
-        Symmetry operations that determines the unique directions. Defaults to
-        no symmetry, which means sampling all 3D unit vectors.
+        Point group with symmetry operations that define the
+        :attr:`~orix.quaternion.symmetry.Symmetry.fundamental_sector`
+        on the unit sphere. If not given, rotations that rotate the
+        Z-vector onto the whole sphere are returned.
+
     Returns
     -------
-    Rotation
-        (N, 3) array representing Euler angles for the different orientations
+    R
+        Rotations of shape ``(n, 3)``.
     """
     if point_group is None:
-        point_group = symmetry.C1
+        point_group = C1
 
-    if mesh is None:
-        s2_auto_sampling_map = {
+    if method is None:
+        sampling_method = {
             "triclinic": "icosahedral",
             "monoclinic": "icosahedral",
             "orthorhombic": "spherified_cube_edge",
@@ -208,14 +213,14 @@ def get_sample_reduced_fundamental(
             "trigonal": "hexagonal",
             "hexagonal": "hexagonal",
         }
-        mesh = s2_auto_sampling_map[point_group.system]
+        method = sampling_method[point_group.system]
 
-    s2_sample = sample_S2(resolution, method=mesh)
-    fundamental = s2_sample[s2_sample <= point_group.fundamental_sector]
+    v = sample_S2(resolution, method=method)
+    v_fs = v[v <= point_group.fundamental_sector]
 
-    phi = fundamental.polar
-    phi2 = (np.pi / 2 - fundamental.azimuth) % (2 * np.pi)
+    phi = v_fs.polar
+    phi2 = (np.pi / 2 - v_fs.azimuth) % (2 * np.pi)
     phi1 = np.zeros(phi2.shape[0])
-    euler_angles = np.vstack([phi1, phi, phi2]).T
+    euler = np.vstack([phi1, phi, phi2]).T
 
-    return Rotation.from_euler(euler_angles, degrees=False)
+    return Rotation.from_euler(euler, degrees=False)

orix/tests/sampling/test_sampling.py

@@ -197,7 +197,7 @@ def test_get_sample_reduced_fundamental(self):
         v_C6 = R_C6 * vz
         assert np.all(v_C6 <= C6.fundamental_sector)
 
-        R_Oh = get_sample_reduced_fundamental(resolution=4, point_group=Oh)
+        R_Oh = get_sample_reduced_fundamental(point_group=Oh)
         v_Oh = R_Oh * vz
         assert np.all(v_Oh <= Oh.fundamental_sector)
 
@@ -207,3 +207,6 @@ def test_get_sample_reduced_fundamental(self):
         assert np.allclose(np.unique(R_C4.to_euler()[:, 0]), [0, np.pi / 2])
         assert np.allclose(np.unique(R_C6.to_euler()[:, 0]), [0, np.pi / 2])
         assert np.allclose(np.unique(R_Oh.to_euler()[:, 0]), [0, np.pi / 2])
+
+        R_Oh2 = get_sample_reduced_fundamental(point_group=Oh, method="icosahedral")
+        assert R_Oh.size > R_Oh2.size