pyxem · argerlt · Feb 2, 2026 · Feb 2, 2026 · Feb 3, 2026 · Feb 3, 2026
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -12,9 +12,16 @@ Unreleased
 
 Added
 -----
+- The unit cells and atomic positions of ``Phase`` objects can now be visualized
+  using ``Phase.plot_unit_cell``.
+- ``Phase`` objects can now be created using the seven crystal class methods ``Phase.triclinic``,
+  ``Phase.monoclinic``, ``Phase.orthorhombic``, ``Phase.tetragonal``, ``Phase.trigonal``, 
+  ``Phase.hexagonal``, and ``Phase.cubic``
 
 Changed
 -------
+- The IPF color keys can take 'x', 'y', and 'z' text strings as direction inputs
+  instead of requiring Vector3d objects.
 
 Removed
 -------

diff --git a/doc/tutorials/clustering_misorientations.ipynb b/doc/tutorials/clustering_misorientations.ipynb
@@ -43,7 +43,6 @@
     "from orix.quaternion.symmetry import D6\n",
     "from orix.vector import Vector3d\n",
     "\n",
-    "\n",
     "plt.rcParams.update({\"font.size\": 20, \"figure.figsize\": (10, 10)})\n",
     "\n",
     "register_projections()"

diff --git a/doc/tutorials/clustering_orientations.ipynb b/doc/tutorials/clustering_orientations.ipynb
@@ -46,7 +46,6 @@
     "from orix.quaternion.symmetry import D6\n",
     "from orix.vector import AxAngle, Vector3d\n",
     "\n",
-    "\n",
     "plt.rcParams.update(\n",
     "    {\"font.size\": 20, \"figure.figsize\": (10, 10), \"figure.facecolor\": \"w\"}\n",
     ")"

diff --git a/doc/tutorials/crystal_directions.ipynb b/doc/tutorials/crystal_directions.ipynb
@@ -42,7 +42,6 @@
     "from orix.quaternion import Orientation, Rotation, symmetry\n",
     "from orix.vector import Miller, Vector3d\n",
     "\n",
-    "\n",
     "plt.rcParams.update(\n",
     "    {\n",
     "        \"figure.figsize\": (7, 7),\n",

diff --git a/doc/tutorials/crystal_map.ipynb b/doc/tutorials/crystal_map.ipynb
diff --git a/doc/tutorials/inverse_pole_figures.ipynb b/doc/tutorials/inverse_pole_figures.ipynb
@@ -61,7 +61,6 @@
     "from orix.quaternion import Orientation, symmetry\n",
     "from orix.vector import Vector3d\n",
     "\n",
-    "\n",
     "# We'll want our plots to look a bit larger than the default size\n",
     "new_params = {\n",
     "    \"figure.facecolor\": \"w\",\n",

diff --git a/doc/tutorials/point_groups.ipynb b/doc/tutorials/point_groups.ipynb
@@ -37,7 +37,6 @@
     "from orix.quaternion import Rotation, symmetry\n",
     "from orix.vector import Vector3d\n",
     "\n",
-    "\n",
     "plt.rcParams.update({\"font.size\": 15})"
    ]
   },

diff --git a/doc/tutorials/s2_sampling.ipynb b/doc/tutorials/s2_sampling.ipynb
@@ -38,7 +38,6 @@
     "from orix.quaternion import symmetry\n",
     "from orix.sampling import sample_S2_methods, sample_S2\n",
     "\n",
-    "\n",
     "plt.rcParams.update({\"font.size\": 20, \"lines.markersize\": 2})"
    ]
   },

diff --git a/doc/tutorials/stereographic_projection.ipynb b/doc/tutorials/stereographic_projection.ipynb
@@ -47,7 +47,6 @@
     "from orix import plot  # Register orix' projections with Matplotlib\n",
     "from orix.vector import Vector3d\n",
     "\n",
-    "\n",
     "# We'll want our plots to look a bit larger than the default size\n",
     "plt.rcParams.update(\n",
     "    {\n",

diff --git a/doc/tutorials/uniform_sampling_of_orientation_space.ipynb b/doc/tutorials/uniform_sampling_of_orientation_space.ipynb
@@ -80,7 +80,6 @@
     "from orix.sampling import get_sample_fundamental\n",
     "from orix.vector import Vector3d\n",
     "\n",
-    "\n",
     "plt.rcParams.update(\n",
     "    {\n",
     "        \"axes.grid\": True,\n",

diff --git a/examples/crystal_phase/README.txt b/examples/crystal_phase/README.txt
diff --git a/examples/crystal_phase/create_crystal_phase.py b/examples/crystal_phase/create_crystal_phase.py
diff --git a/examples/phases/Phase_versus_Symmetry.py b/examples/phases/Phase_versus_Symmetry.py
@@ -0,0 +1,85 @@
+#
+# Copyright 2018-2026 the orix developers
+#
+# This file is part of orix.
+#
+# orix is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# orix is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with orix. If not, see <http://www.gnu.org/licenses/>.
+#
+
+r"""
+=====================
+Phase versus Symmetry
+=====================
+"""
+
+import diffpy.structure as dps
+import numpy as np
+
+import orix.crystal_map as ocm
+import orix.quaternion as oqu
+from orix.quaternion import symmetry
+import orix.vector as ove
+
+##############################################################################
+# ORIX includes two different but related classes for describing crystallographic
+# information, :class:`~orix.quaternion.symmetry.Symmetry`, and
+# :class:`~orix.crystal_map.Phase`.
+#
+# A Symmetry object contains ONLY information on symmetrically equivalent transforms,
+# and in most cases is a Laue and/or Point group. For example, the Symmetry of
+# Alumina would be defined as:
+
+Al2O3_sym = symmetry.D3d  # <-- Schoenflies notation for point group '-3m'
+Al2O3_sym.plot()
+print(Al2O3_sym)
+
+##############################################################################
+# On the other hand, a Phase object contains at minimum both the symmetry and
+# the unit cell. Again, using Alumina as the example:
+
+atoms = [
+    dps.Atom("Al", [1 / 3, 2 / 3, 0.815]),
+    dps.Atom("O", [0.361, 1 / 3, 0.583]),
+]
+lattice = dps.Lattice(0.481, 0.481, 1.391, 90, 90, 120)
+structure = dps.Structure(atoms=atoms, lattice=lattice)
+Al2O3_phase = ocm.Phase(
+    name="Alumina",
+    space_group=167,
+    structure=structure,
+    color="red",
+).expand_asymmetric_unit()
+
+unit_cell_figure = Al2O3_phase.plot_unit_cell(return_figure=True)
+unit_cell_figure.suptitle(r"$Al_2O_3$ unit cell")
+Al2O3_phase
+
+##############################################################################
+# Quaternion based transforms (orientation transforms, misorientation calculations,
+# etc.) only require a Symmetry, whereas any calculation involving diffraction,
+# distance calculations, Inverse Pole Figures, and/or Miller indicies require
+# a Phase.
+#
+# Additionally, while it IS possible to define a phase without explicitly giving
+# the cell parameters, this will cause ORIX to fill in default values for cell
+# parameters based on the point group. This is simpler, has no effect on IPF coloring
+# or orientation calculations, and allows for tracking information such as names and
+# preferred plot color(hence why it is allowed), but it WILL cause incorrect Miller
+# calculations and IPF plotting.
+
+lazy_Al2O3_phase = ocm.Phase(space_group=167)
+correct_111 = ove.Miller(uvw=[1, 1, 1], phase=Al2O3_phase).xyz
+incorrect_111 = ove.Miller(uvw=[1, 1, 1], phase=lazy_Al2O3_phase).xyz
+print("Correct xyz for [111]:", np.stack(correct_111).flatten())
+print("Incorrect xyz for [111]:", np.stack(incorrect_111).flatten())
diff --git a/examples/phases/README.rst b/examples/phases/README.rst
@@ -0,0 +1,4 @@
+Crystal phase
+=============
+
+Examples showing how to create and work with crystal phases.
diff --git a/examples/phases/advanced_phase_operations.py b/examples/phases/advanced_phase_operations.py
@@ -0,0 +1,55 @@
+#
+# Copyright 2018-2026 the orix developers
+#
+# This file is part of orix.
+#
+# orix is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# orix is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with orix. If not, see <http://www.gnu.org/licenses/>.
+#
+
+r"""
+=========================
+Advanced Phase operations
+=========================
+
+This example shows some additional uncommon but useful operations related to
+:class:`~orix.crystal_map.Phase`.
+
+"""
+
+import diffpy.structure as dps
+
+import orix.crystal_map as ocm
+import orix.quaternion as oqu
+import orix.vector as ove
+
+# %%
+# Directly accessing `diffpy.structure` operators
+# -----------------------------------------------
+#
+# ORIX is primarily concerned with calculations related to point group symmetries,
+# (i.e., no concern for translations). However, other projects using ORIX might
+# want need this information to, for example, calculate extinction coefficients
+# for a diffraction experiment. For those cases, the rotation matrices and
+# translation vectors can be extracted from `Phase.space_group`.
+
+phase = ocm.Phase(space_group=13)
+
+for element in phase.space_group.symop_list:
+    print("\nrotation:\n", element.R, "\ntranslation:", element.t)
+
+# %%
+# these can also be returned as ORIX objects.
+
+rots = oqu.Quaternion.from_matrix([x.R for x in phase.space_group.symop_list])
+vecs = ove.Vector3d([x.t for x in phase.space_group.symop_list])
-Original file line number
+Diff line change
@@ Expand Up / @@ -37,7 +37,6 @@ @@
         "from orix.quaternion import Rotation, symmetry\n",
         "from orix.vector import Vector3d\n",
         "\n",
-        "\n",
         "plt.rcParams.update({\"font.size\": 15})"
        ]
       },
@@ Expand Down @@