Orix

===========================

Added
-----
- Creation of one or more ``Quaternion`` (or instances of inheriting classes) from one
or more SciPy ``Rotation``.
- Creation of one ``Quaternion`` or ``Rotation`` by aligning sets of vectors in two
reference frames, one ``Orientation`` by aligning sets of sample vectors and crystal
vectors, and one ``Misorientation`` by aligning two sets of crystal vectors in two
different crystals.
- ``row`` and ``col`` properties to ``CrystalMap`` giving the row and column coordinate
of each map point given by ``CrystalMap.shape``.
- ``Rotation`` class methods ``from_neo_euler()``, ``from_axes_angles()``,
``from_euler()``, ``from_matrix()``, ``random()`` and ``identity()`` and methods
``to_euler()`` and ``to_matrix()`` are now available from the ``Quaternion`` class as
well.
- ``StereographicPlot.restrict_to_sector()`` allows two new parameters to control the
amount of padding (in degrees in stereographic projection) and whether to show the
sector edges. Keyword arguments can also be passed on to Matplotlib's ``PathPatch()``.
- Option to pass degrees to the ``Quaternion`` methods ``from_axes_angles()``,
``from_euler()`` and ``to_euler()`` by passing ``degrees=True``.
- Option to get degrees from all ``angle_with()`` and ``angle_with_outer()`` methods
by passing ``degrees=True``.
- Option to pass degrees to the ``(Mis)Orientation`` method ``get_distance_matrix()``
by passing ``degrees=True``.
- Option to pass degrees to the ``Vector3d`` methods ``from_polar()`` and ``to_polar()``
by passing ``degrees=True``.
- Option to get spherical coordinates from
``InverseStereographicProjection.xy2spherical()`` in degrees or pass them as degrees
to ``StereographicProjection`` methods ``spherical2xy()`` and ``spherical2xy_split()``
by passing ``degrees=True``.


Changed
-------
- Bumped minimal version of ``diffpy.structure >= 3.0.2``.
- Only ASTAR .ang files return crystal maps with ``"nm"`` as scan unit.

Removed
-------
- Parameter ``z`` when creating a ``CrystalMap`` and the ``z`` and ``dz`` attributes of
the class were deprecated in 0.10.1 and are now removed.
- Passing ``shape`` or ``step_sizes`` with three values to
``create_coordinate_arrays()`` was depreacted in 0.10. and will now raise an error.
- Parameter ``depth`` (and ``axes``) in ``CrystalMapPlot.plot_map()`` was depreacted in
0.10.1 and will now raise an error if passed.
- The ``z`` and ``dz`` datasets are not present in new orix HDF5 files. They are not
read if present in older files.

Fixed
-----
- Reading of EDAX TSL .ang files with ten columns should now work.

===========================

Fixed
-----
- ``Miller.symmetrise(unique=True)`` returns the correct number of symmetrically
equivalent but unique vectors, by rounding to 10 instead of 12 decimals prior to
finding the unique vectors with NumPy.

Changed
-------
- Unique rotations and vectors are now found by rounding to 10 instead of 12 decimals.

===========================

Deprecated
----------
- Parameter ``z`` when creating a ``CrystalMap`` and the ``z`` and ``dz`` attributes of
the class are deprecated and will be removed in 0.11.0. Support for 3D crystal maps is
minimal and brittle, and it was therefore decided to remove it altogether.
- Passing ``shape`` or ``step_sizes`` with three values to ``create_coordinate_arrays()``
is depreacted and will raise an error in 0.11.0. See the previous point for the reason.
- Parameter ``depth`` in ``CrystalMapPlot.plot_map()`` is depreacted and will be removed
in 0.11.0. See the top point for the reason.

Fixed
-----
- ``StereographicPlot.scatter()`` now accepts both ``c``/``color`` and ``s``/``sizes``
to set the color and sizes of scatter points, in line with
``matplotlib.axes.Axes.scatter()``.
- Indexing/slicing into an already indexed/sliced ``CrystalMap`` now correctly returns
the index/slice according to ``CrystalMap.shape`` and not the original shape of the
un-sliced map.

===========================

Added
-----
- Support for type hints has been introduced and a section on this topic has been added
to the contributing guide.
- ``Vector3d.pole_density_function()`` has been implemented which allows for calculation
of the Pole Density Function (PDF) and quantification of poles in the stereographic
projection.
- Seven methods for sampling unit vectors from regular grids on *S2* via
``orix.sampling.sample_S2()``.
- Calculation of the Inverse Pole Density Function (IPDF), ie. pole density in the
crystal point group fundamental sector, through
``InversePoleFigurePlot.pole_density_function()``.
- The ``orix.measure`` module has been introduced. The ``measure`` module is related to
quantification of orientation and vector data.
- Plotting the IPF color key on a created ``InversePoleFigurePlot`` is now possible with
``plot_ipf_color_key()``.
- Examples gallery to documentation.

Changed
-------
- Moved part of documentation showing plotting of Wulff net and symmetry markers from
the tutorials to examples.
- Renamed user guide notebooks to tutorials in documentation.
- Reference frame labels of stereographic projection of ``Symmetry.plot()`` from (a, b)
to (e1, e2), signifying the standard Cartesian reference frame attached to a crystal.
- Tighten distribution of random orientation clusters in tutorial showing clustering
across fundamental region boundaries, to avoid clustering sometimes giving two
clusters instead of three.

Removed
-------
- Support for Python 3.6 has been removed. The minimum supported version in ``orix`` is
now Python 3.7.
- ``Object3d.check()``, ``Quaternion.check_quaternion()`` and
``Vector3d.check_vector()``, as these methods were not used internally.
- Deprecated method ``distance()`` of ``Misorientation`` and ``Orientation`` classes,
use ``get_distance_matrix()`` instead.

Fixed
-----
- Plotting of unit cells works with Matplotlib v3.6, at the expense of a warning raised
with earlier versions.

will be ``main``. The release body contains a static description and links to the
changelog in the documentation and GitHub. The release draft can be published as is,
or changes to the release body can be made before publishing. Publish.

- Monitor the publish workflow to ensure the release is successfully published to PyPI.

Post-release action
-------------------
- Monitor the `documentation build <https://readthedocs.org/projects/orix/builds>`__ to
ensure that the new stable documentation is successfully built from the release.

- Ensure that `Zenodo <https://doi.org/10.5281/zenodo.3459662>`__ displays the new
release.

- Ensure that Binder can run the tutorial notebooks by clicking the Binder badges in the
top banner of one of the tutorials via the `documentation
<https://orix.readthedocs.io/en/stable>`__.

- Bring changes in ``main`` into ``develop`` by first branching from ``develop``, merge
``main`` into the new branch and fix potential conflicts. After these conflicts are
fixed, update or revert ``__version__`` and make any updates to this guide if
necessary. Make a PR to ``develop`` and merge.

- A PR to the conda-forge feedstock will be created by the conda-forge bot. Follow the
relevant instructions from the conda-forge documentation on updating packages, as well
as the instructions in the PR. Merge after checks pass. Monitor the Azure pipeline CI
to ensure the release is successfully published to conda-forge.

- Tidy up GitHub issues and close the corresponding milestone.

==========================

Added
-----
- Dask computation of ``Quaternion`` and ``Rotation`` ``outer()`` methods through
addition of a ``lazy`` parameter. This is useful to reduce memory usage when working
with large arrays.
- Dask implementation of the ``Quaternion`` - ``Vector3d`` outer product.
- Point group ``Symmetry`` elements can now be viewed in the stereographic projection
using ``Symmetry.plot()``. The notebook point_groups.ipynb has been added to the
documentation.
- Add ``reproject`` argument to ``Vector3d.scatter()`` which reprojects vectors located
on the hidden hemisphere to the visible hemisphere.
- ``reproject`` argument to ``Vector3d.draw_circle()`` which reprojects parts of
circle(s) on the other hemisphere to the current hemisphere.
- ``Rotation`` objects can now be checked for equality. Equality is determined by
comparing their shape, data, and whether the rotations are improper.
- ``angle_with_outer()`` has been added to both ``Rotation`` and ``Orientation``
classes which computes the misorientation angle between every ``Rotation`` in the two
sets of rotations. In the case of ``Orientation.angle_with_outer()``, this is the
symmetry reduced misorientation.
- Notebook on clustering of misorientations across fundamental region boundaries moved
from the orix-demos repository to the user guide.
- ``orix.data`` module with test data used in the user guide and tests.
- ``Misorientation.get_distance_matrix()`` for memory-efficient calculation of a
misorientation angle (geodesic distance) matrix between misorientations using Dask.
- Clarification of crystal axes alignment in documentation.
- Creation of a ``Phase`` instance from a CIF file.

Changed
-------
- ``from_euler()`` method of ``Rotation``-based classes now interprets angles in Bunge
convention by default, ie. ``direction="lab2crystal"``. The returned ``Rotation`` from
this function may be inverted from prior releases and users are advised to check their
code.
- The ``direction`` parameter in ``from_euler()`` methods, in addition to
``"lab2crystal"`` (now default) and ``"crystal2lab"``, now also accepts a convenience
argument ``"mtex"`` which is consistent with the ``"crystal2lab"`` direction in
`MTEX <https://mtex-toolbox.github.io/MTEXvsBungeConvention.html>`_.
- ``S4`` (-4) ``Symmetry`` has been corrected.
- Organized user guide documentation into topics.

Deprecated
----------
- The ``convention`` parameter in ``from_euler()`` and ``to_euler()`` methods has been
deprecated, in favour of ``direction`` in the former. This parameter will be removed
in release 1.0.
- ``Misorientation.distance()`` in favour of ``Misorientation.get_distance_matrix()``.

Fixed
-----
- Fixed bug in ``sample_S2_uv_mesh()`` and removed duplicate vectors at poles.
- The results from ``Orientation.dot_outer()`` are now returned as
``self.shape + other.shape``, which is consistent with ``Rotation.dot_outer()``.
- Writing of property arrays in .ang writer from masked CrystalMap.

Removed
-------
- ``orix.scalar.Scalar`` class has been removed and the data held by ``Scalar`` is now
returned directly as a ``numpy.ndarray``.
- The deprecation of function ``(Mis)Orientation.set_symmetry()`` and property
``Object3d.data_dim`` has expired and have been removed.