Remove the deprecated reciprocal lattice point class

CHANGELOG.rst

@@ -14,7 +14,7 @@ Added
 -----
 - Explicit support for Python 3.11.
 - Added Pre-Commit for code formatting.
-
+- Added deprecation tools for deprecating functions, parameters, methods, and properties.
 
 Changed
 -------
@@ -28,6 +28,8 @@ Removed
 -------
 - Removed support for Python 3.6 and Python 3.7, leaving 3.8 as the oldest supported
   version.
+- ``ReciprocalLatticePoint`` class; use the ``ReciprocalLatticeVector`` class instead,
+  which is an improved replacement.
 
 Fixed
 -----

CONTRIBUTING.rst

@@ -12,6 +12,7 @@ We have a `Code of Conduct
 <https://github.com/pyxem/diffsims/blob/master/.github/CODE_OF_CONDUCT.md>`_ that must
 be honoured by contributors.
 
+
 Start using diffsims
 ====================
 
@@ -42,6 +43,7 @@ install of diffsims!
 PS: If you choose to develop in Windows/Mac you may find the `Github Desktop
 <https://desktop.github.com>`_ useful.
 
+
 Questions?
 ==========
 
@@ -56,6 +58,7 @@ scary but it ensures that issues are identified and logged until dealt with. Thi
 also a good place to make a proposal for some new feature or tool that you want to work
 on.
 
+
 Good coding practice
 ====================
 
@@ -89,7 +92,6 @@ your newly added and modified files prior to each PR.
 If this doesn't work for you, you can also use the Pre-commit CI to reformat your code
 on github by commenting "pre-commit autofix" on your PR.
 
-
 Run and write tests
 -------------------
 
@@ -128,6 +130,30 @@ Useful hints on testing:
   error-prone. See `pytest documentation for more details
   <https://doc.pytest.org/en/latest/how-to/parametrize.html>`_.
 
+Deprecations
+------------
+
+We attempt to adhere to semantic versioning as best we can. This means that as little,
+ideally no, functionality should break between minor releases. Deprecation warnings
+are raised whenever possible and feasible for functions/methods/properties/arguments,
+so that users get a heads-up one (minor) release before something is removed or changes,
+with a possible alternative to be used.
+
+A deprecation decorator should be placed right above the object signature to be deprecated::
+
+    from diffsims.utils._deprecated import deprecated
+
+    @deprecated(since=0.8, removal=0.9, alternative="bar")
+    def foo(self, n): ...
+
+    @property
+    @deprecated(
+        since="0.9",
+        removal="0.10",
+        alternative="another",
+        alternative_is_function=True
+    ): ...
+
 Build and write documentation
 -----------------------------
 
@@ -152,6 +178,7 @@ in the `reStructuredText (reST)
 plaintext markup language. They should be accessible in the browser by typing
 ``file:///your-absolute/path/to/diffsims/doc/build/html/index.html`` in the address bar.
 
+
 Continuous integration (CI)
 ===========================
 
@@ -160,6 +187,7 @@ diffsims can be installed on Windows, macOS and Linux. After a successful instal
 the CI server runs the tests. After the tests return no errors, code coverage is
 reported to `Coveralls <https://coveralls.io/github/pyxem/diffsims?branch=master>`_.
 
+
 Learn more
 ==========
 

MANIFEST.in

@@ -1,3 +1,7 @@
+# Info on valid syntax for controlling files in the distribution in this file:
+# * https://setuptools.pypa.io/en/latest/userguide/miscellaneous.html
+# * https://setuptools.pypa.io/en/latest/userguide/datafiles.html
+
 include CHANGELOG.rst
 include CONTRIBUTING.rst
 include LICENSE
@@ -6,5 +10,6 @@ include README.rst
 include readthedocs.yaml
 include setup.cfg
 include setup.py
+include diffsims/tests/**/*.npy
 
 recursive-include doc Makefile make.bat *.rst *.py *.png

diffsims/crystallography/__init__.py

@@ -20,8 +20,7 @@
 g, hkl) for a crystal structure.
 """
 
-from diffsims.crystallography.reciprocal_lattice_point import (
-    ReciprocalLatticePoint,
+from diffsims.crystallography.get_hkl import (
     get_equivalent_hkl,
     get_highest_hkl,
     get_hkl,
@@ -32,6 +31,5 @@
     "get_equivalent_hkl",
     "get_highest_hkl",
     "get_hkl",
-    "ReciprocalLatticePoint",
     "ReciprocalLatticeVector",
 ]

diffsims/crystallography/get_hkl.py

@@ -0,0 +1,132 @@
+# -*- coding: utf-8 -*-
+# Copyright 2017-2023 The diffsims developers
+#
+# This file is part of diffsims.
+#
+# diffsims 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.
+#
+# diffsims 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 diffsims.  If not, see <http://www.gnu.org/licenses/>.
+
+from itertools import product
+
+import numpy as np
+from orix.vector import Vector3d
+
+from diffsims.utils._deprecated import deprecated
+
+
+@deprecated(
+    since="0.6",
+    alternative="diffsims.crystallography.ReciprocalLatticeVector.from_min_dspacing",
+    removal="0.7",
+)
+def get_highest_hkl(lattice, min_dspacing=0.5):
+    """Return the highest Miller indices hkl of the plane with a direct
+    space interplanar spacing (d-spacing) greater than but closest to
+    *min_dspacing*.
+
+    Parameters
+    ----------
+    lattice : diffpy.structure.Lattice
+        Crystal lattice.
+    min_dspacing : float, optional
+        Smallest interplanar spacing to consider. Default is 0.5 Å.
+
+    Returns
+    -------
+    highest_hkl : np.ndarray
+        Highest Miller indices.
+    """
+    highest_hkl = np.ones(3, dtype=int)
+    for i in range(3):
+        hkl = np.zeros(3)
+        d = min_dspacing + 1
+        while d > min_dspacing:
+            hkl[i] += 1
+            d = 1 / lattice.rnorm(hkl)
+        highest_hkl[i] = hkl[i]
+    return highest_hkl
+
+
+@deprecated(
+    since="0.6",
+    alternative="diffsims.crystallography.ReciprocalLatticeVector.from_highest_hkl",
+    removal="0.7",
+)
+def get_hkl(highest_hkl):
+    """Return a list of planes from a set of highest Miller indices.
+
+    Parameters
+    ----------
+    highest_hkl : orix.vector.Vector3d, np.ndarray, list, or tuple of int
+        Highest Miller indices to consider.
+
+    Returns
+    -------
+    hkl : np.ndarray
+        An array of Miller indices.
+    """
+    index_ranges = [np.arange(-i, i + 1) for i in highest_hkl]
+    return np.asarray(list(product(*index_ranges)))
+
+
+@deprecated(
+    since="0.6",
+    alternative="diffsims.crystallography.ReciprocalLatticeVector.symmetrise",
+    removal="0.7",
+)
+def get_equivalent_hkl(hkl, operations, unique=False, return_multiplicity=False):
+    """Return symmetrically equivalent Miller indices.
+
+    Parameters
+    ----------
+    hkl : orix.vector.Vector3d, np.ndarray, list or tuple of int
+        Miller indices.
+    operations : orix.quaternion.symmetry.Symmetry
+        Point group describing allowed symmetry operations.
+    unique : bool, optional
+        Whether to return only unique Miller indices. Default is False.
+    return_multiplicity : bool, optional
+        Whether to return the multiplicity of the input indices. Default
+        is False.
+
+    Returns
+    -------
+    new_hkl : orix.vector.Vector3d
+        The symmetrically equivalent Miller indices.
+    multiplicity : np.ndarray
+        Number of symmetrically equivalent indices. Only returned if
+        `return_multiplicity` is True.
+    """
+    new_hkl = operations.outer(Vector3d(hkl))
+    new_hkl = new_hkl.flatten().reshape(*new_hkl.shape[::-1])
+
+    multiplicity = None
+    if unique:
+        n_families = new_hkl.shape[0]
+        multiplicity = np.zeros(n_families, dtype=int)
+        temp_hkl = new_hkl[0].unique().data
+        multiplicity[0] = temp_hkl.shape[0]
+        if n_families > 1:
+            for i, hkl in enumerate(new_hkl[1:]):
+                temp_hkl2 = hkl.unique()
+                multiplicity[i + 1] = temp_hkl2.size
+                temp_hkl = np.append(temp_hkl, temp_hkl2.data, axis=0)
+        new_hkl = Vector3d(temp_hkl[: multiplicity.sum()])
+
+    # Remove 1-dimensions
+    new_hkl = new_hkl.squeeze()
+
+    if unique and return_multiplicity:
+        return new_hkl, multiplicity
+    else:
+        return new_hkl