chore: deprecate expansion functional utilities method.

news/deprecate-expansion-utilities-1.rst

@@ -0,0 +1,27 @@
+**Added:**
+
+* Added ``find_center`` method in ``expansion/shapeutils.py``
+* Added ``make_sphere`` method in ``expansion/makeellipsoid.py``
+* Added ``make_ellipsoid`` method in ``expansion/makeellipsoid.py``
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* Deprecated ``findCenter`` method in ``expansion/shapeutils.py`` for removal in version 4.0.0
+* Deprecated ``makeSphere`` method in ``expansion/makeellipsoid.py`` for removal in version 4.0.0
+* Deprecated ``makeEllipsoid`` method in ``expansion/makeellipsoid.py`` for removal in version 4.0.0
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/structure/expansion/makeellipsoid.py

@@ -19,10 +19,36 @@
 from numpy import array
 
 from diffpy.structure import Structure
-from diffpy.structure.expansion.shapeutils import findCenter
+from diffpy.structure.expansion.shapeutils import find_center
+from diffpy.utils._deprecator import build_deprecation_message, deprecated
+
+base = "diffpy.structure"
+removal_version = "4.0.0"
+makeSphere_deprecation_msg = build_deprecation_message(
+    base,
+    "makeSphere",
+    "make_sphere",
+    removal_version,
+)
+makeEllipsoid_deprecation_msg = build_deprecation_message(
+    base,
+    "makeEllipsoid",
+    "make_ellipsoid",
+    removal_version,
+)
+
+
+@deprecated(makeSphere_deprecation_msg)
+def makeSphere(S, radius):
+    """This function has been deprecated and will be removed in version
+    4.0.0.
+
+    Please use diffpy.structure.make_sphere instead.
+    """
+    return make_sphere(S, radius)
 
 
-def makeSphere(S, radius):
+def make_sphere(S, radius):
     """Create a spherical nanoparticle.
 
     Parameters
@@ -37,10 +63,20 @@ def makeSphere(S, radius):
     Structure
         A new `Structure` instance.
     """
-    return makeEllipsoid(S, radius)
+    return make_ellipsoid(S, radius)
 
 
+@deprecated(makeEllipsoid_deprecation_msg)
 def makeEllipsoid(S, a, b=None, c=None):
+    """This function has been deprecated and will be removed in version
+    4.0.0.
+
+    Please use diffpy.structure.make_ellipsoid instead.
+    """
+    return make_ellipsoid(S, a, b, c)
+
+
+def make_ellipsoid(S, a, b=None, c=None):
     """Cut a `Structure` out of another one.
 
     Parameters
@@ -78,7 +114,7 @@ def makeEllipsoid(S, a, b=None, c=None):
     lat = newS.lattice
 
     # Find the central atom
-    ncenter = findCenter(newS)
+    ncenter = find_center(newS)
 
     cxyz = lat.cartesian(newS[ncenter].xyz)
 
@@ -111,17 +147,17 @@ def makeEllipsoid(S, a, b=None, c=None):
     datadir = "../../tests/testdata"
     S = Structure()
     S.read(os.path.join(datadir, "CdSe_bulk.stru"), "pdffit")
-    newS = makeEllipsoid(S, 12)
+    newS = make_ellipsoid(S, 12)
     newS.write("CdSe_d24.stru", "pdffit")
-    newS = makeEllipsoid(S, 20, 10, 10)
+    newS = make_ellipsoid(S, 20, 10, 10)
     newS.write("CdSe_a20_b10_c10.stru", "pdffit")
-    newS = makeEllipsoid(S, 20, 15, 10)
+    newS = make_ellipsoid(S, 20, 15, 10)
     newS.write("CdSe_a20_b15_c10.stru", "pdffit")
     S = Structure()
     S.read(os.path.join(datadir, "Ni.stru"), "pdffit")
-    newS = makeEllipsoid(S, 10)
+    newS = make_ellipsoid(S, 10)
     newS.write("Ni_d20.stru", "pdffit")
-    newS = makeEllipsoid(S, 20, 4)
+    newS = make_ellipsoid(S, 20, 4)
     newS.write("Ni_a20_b4_c20.stru", "pdffit")
-    newS = makeEllipsoid(S, 20, 15, 10)
+    newS = make_ellipsoid(S, 20, 15, 10)
     newS.write("Ni_a20_b15_c10.stru", "pdffit")

src/diffpy/structure/expansion/shapeutils.py

@@ -12,10 +12,30 @@
 # See LICENSE_DANSE.txt for license information.
 #
 ##############################################################################
+from diffpy.utils._deprecator import build_deprecation_message, deprecated
+
+base = "diffpy.structure"
+removal_version = "4.0.0"
+findCenter_deprecation_msg = build_deprecation_message(
+    base,
+    "findCenter",
+    "find_center",
+    removal_version,
+)
 """Utilities for making shapes."""
 
 
+@deprecated(findCenter_deprecation_msg)
 def findCenter(S):
+    """This function has been deprecated and will be removed in version
+    4.0.0.
+
+    Please use diffpy.structure.find_center instead.
+    """
+    return find_center(S)
+
+
+def find_center(S):
     """Find the approximate center `Atom` of a `Structure`.
 
     The center of the `Structure` is the `Atom` closest to ``(0.5, 0.5, 0.5)``.

tests/test_expansion.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python
+##############################################################################
+#
+# diffpy.structure  Complex Modeling Initiative
+#                   (c) 2016 Brookhaven Science Associates,
+#                   Brookhaven National Laboratory.
+#                   All rights reserved.
+#
+# File coded by:    Pavol Juhas
+#
+# See AUTHORS.rst for a list of people who contributed.
+# See LICENSE.rst for license information.
+#
+##############################################################################
+"""Tests for the expansion module utilities."""
+import pytest
+
+from diffpy.structure.atom import Atom
+from diffpy.structure.expansion.makeellipsoid import make_ellipsoid, make_sphere, makeEllipsoid, makeSphere
+from diffpy.structure.expansion.shapeutils import find_center, findCenter
+from diffpy.structure.lattice import Lattice
+from diffpy.structure.structure import Structure
+
+
+def test_findCenter():
+    # C1: We have single atom, expect to return the index of the single atom.
+    structure_1 = Structure([Atom("Ni", [0.8, 1.2, 0.9])], lattice=Lattice())
+    expected = 0
+    actual = findCenter(structure_1)
+    assert actual == expected
+
+    # C2: We have multiple atoms.
+    # Expect to find the index of the atom which has the closest distance to [0.5, 0.5, 0.5].
+    # In this case it corresponds to atom "C".
+    structure_2 = Structure(
+        [Atom("Ni", [0.8, 1.2, 0.9]), Atom("C", [0.1, 0.2, 0.3])],
+        lattice=Lattice(),
+    )
+    actual = findCenter(structure_2)
+    expected = 1
+    assert actual == expected
+
+
+def test_makeEllipsoid_and_makeSphere():
+    structure = Structure(
+        [
+            Atom("Ni", [0.0, 0.0, 0.0]),
+            Atom("C", [0.5, 0.5, 0.5]),
+            Atom("O", [1.0, 0.0, 0.0]),
+            Atom("H", [1.1, 0.0, 0.0]),
+        ],
+        lattice=Lattice(1, 1, 1, 90, 90, 90),
+    )
+    # C1: set primary, secondary, and polar radius the same in makeEllipsoid, expect to be the same as makeSphere
+    ellipsoid_1 = makeEllipsoid(structure, 1, 1, 1)
+    sphere = makeSphere(structure, 1)
+    assert [atom.element for atom in ellipsoid_1] == [atom.element for atom in sphere]
+    assert [tuple(atom.xyz) for atom in ellipsoid_1] == [tuple(atom.xyz) for atom in sphere]
+    # C2: set the radius to be 0.5, expect to exclude the atom that is too far from the center of ellipsoid.
+    ellipsoid_2 = makeEllipsoid(structure, 0.5)
+    actual = [(atom.element, tuple(atom.xyz)) for atom in ellipsoid_2]
+    expected = [("C", (0.5, 0.5, 0.5))]
+    assert actual == expected
+
+
+@pytest.mark.parametrize(
+    "atom_params, expected",
+    [
+        pytest.param([Atom("Ni", [0.8, 1.2, 0.9])], 0),
+        pytest.param([Atom("Ni", [0.8, 1.2, 0.9]), Atom("C", [0.1, 0.2, 0.3])], 1),
+    ],
+)
+def test_find_center(atom_params, expected):
+    structure = Structure(atom_params, lattice=Lattice())
+    actual = find_center(structure)
+    assert actual == expected
+
+
+@pytest.mark.parametrize(
+    ("ellipsoid_args", "sphere_radius"),
+    [
+        ((1, 1, 1), 1),
+        ((0.8, 0.8, 0.8), 0.8),
+        ((0.5, 0.5, 0.5), 0.5),
+    ],
+)
+def test_make_ellipsoid_equiv_to_make_sphere(ellipsoid_args, sphere_radius):
+    structure = Structure(
+        [
+            Atom("Ni", [0.0, 0.0, 0.0]),
+            Atom("C", [0.5, 0.5, 0.5]),
+            Atom("O", [1.0, 0.0, 0.0]),
+            Atom("H", [1.1, 0.0, 0.0]),
+        ],
+        lattice=Lattice(1, 1, 1, 90, 90, 90),
+    )
+
+    actual = [(atom.element, tuple(atom.xyz)) for atom in make_ellipsoid(structure, *ellipsoid_args)]
+    expected = [(atom.element, tuple(atom.xyz)) for atom in make_sphere(structure, sphere_radius)]
+
+    assert actual == expected
+
+
+@pytest.mark.parametrize(
+    ("ellipsoid_args", "expected"),
+    [
+        ((0.5,), [("C", (0.5, 0.5, 0.5))]),
+        ((0.4,), [("C", (0.5, 0.5, 0.5))]),
+    ],
+)
+def test_make_ellipsoid(ellipsoid_args, expected):
+    structure = Structure(
+        [
+            Atom("Ni", [0.0, 0.0, 0.0]),
+            Atom("C", [0.5, 0.5, 0.5]),
+            Atom("O", [1.0, 0.0, 0.0]),
+            Atom("H", [1.1, 0.0, 0.0]),
+        ],
+        lattice=Lattice(1, 1, 1, 90, 90, 90),
+    )
+    actual = [(atom.element, tuple(atom.xyz)) for atom in make_ellipsoid(structure, *ellipsoid_args)]
+    assert actual == expected