Merge pull request #478 from hakonanes/prepare-for-0.12

Minor maintenance updates before 0.12.0 release

.github/workflows/build.yml

@@ -10,9 +10,6 @@ on:
   workflow_dispatch:
     workflow: '*'
 
-env:
-  MPLBACKEND: agg
-
 jobs:
   code:
     name: code style
@@ -59,15 +56,16 @@ jobs:
     name: ${{ matrix.os }}-py${{ matrix.python-version }}${{ matrix.LABEL }}
     runs-on: ${{ matrix.os }}
     timeout-minutes: 15
+    env:
+      MPLBACKEND: agg
     strategy:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ["3.10", "3.11"]
+        python-version: ['3.10', '3.11']
         include:
           - os: ubuntu-latest
             python-version: 3.7
-            OLDEST_SUPPORTED_VERSION: true
             DEPENDENCIES: diffpy.structure==3  matplotlib==3.5
             LABEL: -oldest
     steps:
@@ -84,7 +82,7 @@ jobs:
           pip install -U -e .'[doc, tests]'
 
       - name: Install oldest supported version
-        if: ${{ matrix.OLDEST_SUPPORTED_VERSION }}
+        if: ${{ contains(matrix.LABEL, 'oldest') }}
         run: |
           pip install ${{ matrix.DEPENDENCIES }}
 
@@ -102,7 +100,7 @@ jobs:
 
       - name: Run tests
         run: |
-          pytest -n 2 --cov=orix --pyargs orix
+          pytest --pyargs orix --reruns 2 -n 2 --cov=orix
 
       - name: Generate line coverage
         if: ${{ matrix.os == 'ubuntu-latest' }}

.gitignore

@@ -67,6 +67,7 @@ doc/build/
 doc/examples/
 doc/reference/generated/
 doc/source/_autosummary/
+doc/sg_execution_times.rst
 
 # PyBuilder
 target/

CHANGELOG.rst

@@ -31,9 +31,9 @@ Added
 - The ``random()`` methods of ``Orientation`` and ``Misorientation`` now accept
   ``symmetry``. A ``random()`` method is also added to ``Vector3d`` and ``Miller``, the
   latter accepting a ``phase``.
-- ``Added orix.sampling.get_sample_zone_axis`` for getting zone axes for some point group.
-- ``Added orix.sampling.get_sample_reduced_fundamental`` for getting reduced
-  fundamental zone for some point group.
+- Function ``orix.sampling.get_sample_reduced_fundamental()`` for sampling rotations
+  that rotate the Z-vector (0, 0, 1) onto the fundamental sector of the Laue group of a
+  given ``Symmetry``.
 
 Changed
 -------
@@ -42,22 +42,20 @@ Changed
 - Allow passing a tuple of integers to ``reshape()`` methods of 3D objects.
 - ``random()`` methods no longer accept a list as a valid shape: pass a tuple instead.
 - Increase minimal version of Matplotlib to >= 3.5.
-- Updated copyright year to 2024.
 
 Deprecated
 ----------
 - Creating quaternions from neo-eulerian vectors via ``from_neo_euler()`` is deprecated
   and will be removed in v0.13. Use the existing ``from_axes_angles()`` and the new
   ``from_rodrigues()`` and ``from_homochoric()`` instead.
 
-Removed
--------
-
 Fixed
 -----
 - Transparency of polar stereographic grid lines can now be controlled by Matplotlib's
   ``grid.alpha``, just like the azimuth grid lines.
-- Previously ``Phase`` was failing to adjust atom position to accomodate for the change of basis. This is now fixed.
+- Previously, ``Phase`` did not adjust atom positions when forcing
+  ``Phase.structure.lattice.base`` to use the crystal axes alignment ``e1 || a``,
+  ``e3 || c*``. This is now fixed.
 
 2023-03-14 - version 0.11.1
 ===========================

doc/dev/building_writing_documentation.rst

@@ -10,7 +10,7 @@ New documents should fit into one of these categories.
 We use :doc:`Sphinx <sphinx:index>` for documenting functionality.
 Install necessary dependencies to build the documentation::
 
-    pip install --editable .[doc]
+    pip install --editable ".[doc]"
 
 .. note::
 
@@ -19,9 +19,6 @@ Install necessary dependencies to build the documentation::
     See the section on the :ref:`data module <adding-data-to-data-module>` for more
     details.
 
-If you get an error message running the above in a ``zsh`` shell, try wrapping the last
-part in a string, like ``'.[doc]'``.
-
 Then, build the documentation from the ``doc`` directory::
 
     cd doc

doc/dev/running_writing_tests.rst

@@ -6,10 +6,7 @@ The tests reside in a ``tests`` module.
 Tests are short methods that call functions in ``orix`` and compare resulting output
 values with known answers. Install necessary dependencies to run the tests::
 
-   pip install --editable .[tests]
-
-If you get an error message running the above in a ``zsh`` shell, try wrapping the last
-part in a string, like ``'.[tests]'``.
+   pip install --editable ".[tests]"
 
 Some useful :doc:`fixtures <pytest:explanation/fixtures>` are available in the
 ``conftest.py`` file.
@@ -39,7 +36,7 @@ Docstring examples are tested :doc:`with pytest <pytest:how-to/doctest>` as well
 already available in the namespace as ``np`` and ``plt``, respectively.
 The docstring tests can be run from the top directory::
 
-    pytest --doctest-modules --ignore-glob=orix/tests orix/*.py
+    pytest orix --doctest-modules --ignore-glob=orix/tests
 
 Tips for writing tests of Numba decorated functions:
 

doc/dev/setting_up_development_installation.rst

@@ -26,7 +26,7 @@ with the `Miniconda distribution <https://docs.conda.io/en/latest/miniconda.html
 Then, install the required dependencies while making the development version available
 globally (in the ``conda`` environment)::
 
-    pip install --editable .[dev]
+    pip install --editable ".[dev]"
 
 This installs all necessary development dependencies, including those for running tests
 and building documentation.

doc/tutorials/crystal_reference_frame.ipynb

@@ -220,7 +220,7 @@
    "source": [
     "## Alignment of symmetry operations\n",
     "\n",
-    "To see where the crystallographic axes about which the point group symmetry operations rotate, we can add symmetry operations to the figure, like is done in the [Visualizing point groups](point_groups.ipynb) tutorial for all point groups supported in orix"
+    "To see which crystallographic axes the point group symmetry operations rotate about, we can add symmetry operations to the figure, like is done in the [Visualizing point groups](point_groups.ipynb) tutorial for all point groups supported in orix"
    ]
   },
   {
@@ -238,7 +238,7 @@
    "outputs": [],
    "source": [
     "R = Rotation.from_axes_angles([0, 1, 0], -65, degrees=True)\n",
-    "phase.point_group.plot(figure=fig, orientation=R, fc=\"none\", ec=\"C0\", s=150)\n",
+    "phase.point_group.plot(figure=fig, orientation=R)\n",
     "fig"
    ]
   },
@@ -299,7 +299,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.6"
+   "version": "3.11.8"
   }
  },
  "nbformat": 4,

doc/tutorials/point_groups.ipynb

@@ -127,10 +127,10 @@
     "    # respectively, for Symmetry.plot()\n",
     "\n",
     "    # vectors on the upper hemisphere are shown as open circles\n",
-    "    ax[i].scatter(v, marker=\"o\", fc=\"None\", ec=\"k\", s=150)\n",
+    "    ax[i].scatter(v, marker=\"o\", c=\"None\", ec=\"C0\", s=150)\n",
     "    # vectors on the lower hemisphere are reprojected onto the upper\n",
     "    # hemisphere and shown as crosses\n",
-    "    ax[i].scatter(v_reproject, marker=\"+\", ec=\"C0\", s=150)\n",
+    "    ax[i].scatter(v_reproject, marker=\"+\", c=\"C0\", s=150)\n",
     "\n",
     "    ax[i].set_title(f\"${S}$ $({Si.name})$\")\n",
     "    ax[i].set_labels(\"$e_1$\", \"$e_2$\", None)"
@@ -156,7 +156,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.6"
+   "version": "3.11.8"
   }
  },
  "nbformat": 4,

doc/user/applications.rst

@@ -12,6 +12,14 @@ If you think your work should be listed here, please raise an issue `on GitHub
 <https://github.com/pyxem/orix>`__ or `contact the developers
 <[email protected]>`__.
 
+2024
+====
+- I. MacLaren, E. Frutos-Myro, S. Zeltmann, C. Ophus, "A method for crystallographic
+  mapping of an alpha-beta titanium alloy with nanometre resolution using scanning
+  precession electron diffraction and open-source software libraries," *Journal of
+  Microscopy*, 1-9 (2024).
+  https://doi/10.1111/jmi.13275.
+
 2022
 ====
 

doc/user/related_projects.rst

@@ -24,6 +24,8 @@ find useful:
   orix depends on numpy-quaternion for quaternion multiplication.
 - `texture <https://github.com/usnistgov/texture>`_: Python scripts for analysis of
   crystallographic texture.
-- pymicro: Python package to work with material microstructures and 3D data sets.
-- Dream3D: C++ library to reconstruct, instatiate, quantify, mesh, handle and visualize
-  multidimensional (3D), multimodal data (mainly EBSD orientation data).
+- `pymicro <https://pymicro.readthedocs.io>`_`: Python package to work with material
+  microstructures and 3D data sets.
+- `DREAM.3D <https://dream3d.io/>`_`: C++ library to reconstruct, instatiate, quantify,
+  mesh, handle and visualize multidimensional (3D), multimodal data (mainly EBSD
+  orientation data).

examples/crystal_maps/create_empty_map.py

@@ -0,0 +1,19 @@
+"""
+========================
+Create empty crystal map
+========================
+
+This example shows how to create an empty crystal map of a given shape.
+By empty, we mean that it is filled with identity rotations.
+
+This crystal map can be useful for testing.
+"""
+
+from orix.crystal_map import CrystalMap
+
+xmap = CrystalMap.empty((5, 10))
+
+print(xmap)
+print(xmap.rotations)
+
+xmap.plot("x")

examples/misorientations/misorientation_from_aligning_directions.py

@@ -64,8 +64,8 @@
 # Plot the two directions in the (unrotated) first crystal's reference
 # frame as open circles
 fig = t_cubic.scatter(
+    c="none",
     ec=["r", "b"],
-    fc="none",
     grid=True,
     axes_labels=["e1", "e2"],
     return_figure=True,

examples/orientations/orientation_from_aligning_directions.py

@@ -1,3 +1,4 @@
+# %%
 r"""
 ====================================
 Orientation from aligning directions
@@ -39,8 +40,8 @@
 
 # Plot the reference orientation sample directions as empty circles
 fig = v.scatter(
+    c="none",
     ec=["r", "b"],
-    fc="none",
     grid=True,
     axes_labels=["X", "Y"],
     return_figure=True,

examples/rotations/rotating_z_to_high_symmetry_directions.py

@@ -0,0 +1,59 @@
+"""
+=====================================================
+Rotating z-vector to high-symmetry crystal directions
+=====================================================
+
+This example shows how to sample high-symmetry crystal directions
+:math:`\mathbf{t} = [u, v, w]` (or zone axes) using
+:meth:`orix.vector.Miller.from_highest_indices`.
+We will also return the rotations :math:`R` which rotate
+:math:`\mathbf{v_z} = (0, 0, 1)` to :math:`\mathbf{t}`.
+
+We do the following to obtain the high-symmetry crystal directions:
+
+1. Select a point group, here :math:`S = mmm`.
+2. Sample all directions :math:`\mathbf{t_i}` with indices of -1, 0, and 1
+3. Project :math:`\mathbf{t_i}` to the fundamental sector of the Laue group of :math:`S`
+   (which in this case is itself)
+4. Discard symmetrically equivalent and other duplicate crystal directions.
+   Vectors such as [001] and [002] are considered equal after we make them unit vectors.
+5. Round the vector indices to the closest smallest integer (below a default of 20).
+
+The rotations :math:`R` can be useful e.g. when simulating diffraction patterns from
+crystals with one of the high-symmetry zone axes :math:`\mathbf{t}` aligned along the
+beam path.
+"""
+
+from orix.crystal_map import Phase
+from orix.quaternion import Rotation
+from orix.vector import Miller, Vector3d
+
+phase = Phase(point_group="mmm")
+t = Miller.from_highest_indices(phase, uvw=[1, 1, 1])
+t = t.in_fundamental_sector()
+t = t.unit.unique(use_symmetry=True).round()
+print(t)
+
+########################################################################
+# Get the rotations that rotate :math:`\mathbf{v_z}` to these crystal
+# directions
+vz = Miller(uvw=[0, 0, 1], phase=t.phase)
+R = Rotation.identity(t.size)
+for i, t_i in enumerate(t):
+    R[i] = Rotation.from_align_vectors(t_i, vz)
+print(R)
+
+########################################################################
+# Plot the crystal directions within the fundamental sector of Laue
+# group :math:`mmm`
+
+fig = t.scatter(
+    vector_labels=[str(vi).replace(".", "") for vi in t.coordinates],
+    text_kwargs={
+        "size": 15,
+        "offset": (0, 0.03),
+        "bbox": {"fc": "w", "pad": 2, "alpha": 0.75},
+    },
+    return_figure=True,
+)
+fig.axes[0].restrict_to_sector(t.phase.point_group.fundamental_sector)

examples/rotations/rotations_mapping_fundamental_sector.py

@@ -0,0 +1,57 @@
+"""
+================================================
+Rotations mapping the fundamental sector on *S2*
+================================================
+
+This example shows how to sample rotations :math:`\mathbf{R}` that when rotating the
+vector :math:`\mathbf{v_z} = (0, 0, 1)`, the resulting vectors cover the fundamental
+sector of a given Laue class.
+
+We show this by comparing the vectors we get by: 
+
+1. Sampling rotations for *4/mmm* and then rotating :math:`\mathbf{v_z}`
+2. Sampling all of *S2* but only keeping those within the corresponding fundamental
+   sector.
+
+Apart from the first rotation, all rotations have a Euler angle
+:math:`\phi = 0^{\circ}`.
+These "reduced" rotations can be useful in template matching of spot patterns from the
+transmission electron microscope.
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from orix import plot, sampling
+from orix.quaternion import symmetry
+from orix.vector import Vector3d
+
+# Sample rotations with an average misorientation
+res = 2
+pg = symmetry.D4h  # 4/mmm
+
+R = sampling.get_sample_reduced_fundamental(res, point_group=pg)
+print(np.allclose(R.to_euler()[1:, 0], 0))
+
+########################################################################
+# Get vectors within the fundamental sector following the two routes
+v1 = R * Vector3d.zvector()
+
+v2 = sampling.sample_S2(res)
+v2 = v2[v2 <= pg.fundamental_sector]
+
+# Only equivalent for the same S2 sampling method
+print(np.allclose(v1.data, v2.data))
+print(v1)
+print(v2)
+
+########################################################################
+# Plot the vectors in the fundamental sector of Laue group 4/mmm
+fig, (ax0, ax1) = plt.subplots(
+    ncols=2, subplot_kw={"projection": "ipf", "symmetry": pg}, layout="tight"
+)
+ax0.scatter(v1, s=5)
+ax1.scatter(v2, c="C1", s=5)
+ax0.set_title("Rotated Z vectors", loc="left")
+ax1.set_title("Directly sampled", loc="left")
+_ = fig.suptitle("Vectors in the fundamental sector of 4/mmm", y=0.8)