Add class method for Box class which create a box from Lx,Ly,Lz and angles

ChangeLog.md

@@ -8,6 +8,10 @@ and this project adheres to
 
 ### Added
 * New continuous coordination number compute `freud.order.ContinuousCoordination`.
+* New class methods for construction of `freud.box.Box` and `freud.data.UnitCell` from
+  lattice vectors and box lengths and angles.
+* New `freud.box.Box.to_box_lengths_and_angles` method for computing box vector lengths
+  and angles
 
 ### Removed
 * `freud.order.Translational`.

doc/source/reference/credits.rst

@@ -369,6 +369,13 @@ Domagoj Fijan
 * Contributed code, design, documentation, and testing for ``freud.locality.FilterSANN`` class.
 * Contributed code, design, documentation, and testing for ``freud.locality.FilterRAD`` class.
 * Added support for ``gsd.hoomd.Frame`` in ``NeighborQuery.from_system`` calls.
+* Added support for ``freud.box.Box`` class methods for construction of boxes and unit
+  cells from lattice vectors (``freud.box.Box.from_lattice_vectors`` and
+  ``freud.data.UnitCell.from_lattice_vectors``) and cell lengths and angles
+  (``freud.box.Box.from_box_lengths_and_angles`` and
+  ``freud.data.UnitCell.from_box_lengths_and_angles``), as well as a method for
+  returning cell vector lengths and angles
+  (``freud.box.Box.to_box_lengths_and_angles``).
 
 Andrew Kerr
 

freud/box.pyx

@@ -689,6 +689,25 @@ cdef class Box:
                            [0, self.Ly, self.yz * self.Lz],
                            [0, 0, self.Lz]])
 
+    def to_box_lengths_and_angles(self):
+        r"""Return the box lengths and angles.
+
+        Returns:
+            tuple: The box vector lengths and angles in radians
+        """
+        alpha = np.arccos(
+            (self.xy * self.xz + self.yz)
+            / (np.sqrt(1 + self.xy**2) * np.sqrt(1 + self.xz**2 + self.yz**2))
+        )
+        beta = np.arccos(self.xz/np.sqrt(1+self.xz**2+self.yz**2))
+        gamma = np.arccos(self.xy/np.sqrt(1+self.xy**2))
+        L1 = self.Lx
+        a2 = [self.Ly*self.xy, self.Ly, 0]
+        a3 = [self.Lz*self.xz, self.Lz*self.yz, self.Lz]
+        L2 = np.linalg.norm(a2)
+        L3 = np.linalg.norm(a3)
+        return (L1, L2, L3, alpha, beta, gamma)
+
     def __repr__(self):
         return ("freud.box.{cls}(Lx={Lx}, Ly={Ly}, Lz={Lz}, "
                 "xy={xy}, xz={xz}, yz={yz}, "
@@ -921,6 +940,75 @@ cdef class Box:
                             "positional argument: L")
         return cls(Lx=L, Ly=L, Lz=0, xy=0, xz=0, yz=0, is2D=True)
 
+    @classmethod
+    def from_lattice_vectors(cls, lattice_vectors, dimensions: int = None):
+        """Create a unit cell from lattice vectors.
+
+        Args:
+            lattice_vectors (array-like):
+                The lattice vectors. The dimensions of the object should be 3x3. Lattice
+                vector a1 is lattice_vectors[0], etc.
+            dimensions (int): The number of dimensions (Default value = :code:`None`)
+
+        Returns:
+            :class:`~.UnitCell`: A unit cell with the given lattice vectors.
+        """
+        lattice_matrix = np.asarray(lattice_vectors, dtype=np.float32)
+        v0 = lattice_matrix[0]
+        v1 = lattice_matrix[1]
+        v2 = lattice_matrix[2]
+        Lx = np.sqrt(np.dot(v0, v0))
+        a2x = np.dot(v0, v1) / Lx
+        Ly = np.sqrt(np.dot(v1, v1) - a2x * a2x)
+        xy = a2x / Ly
+        v0xv1 = np.cross(v0, v1)
+        v0xv1mag = np.sqrt(np.dot(v0xv1, v0xv1))
+        Lz = np.dot(v2, v0xv1) / v0xv1mag
+        if Lz != 0:
+            a3x = np.dot(v0, v2) / Lx
+            xz = a3x / Lz
+            yz = (np.dot(v1, v2) - a2x * a3x) / (Ly * Lz)
+        else:
+            xz = yz = 0
+        if dimensions is None:
+            dimensions = 2 if Lz == 0 else 3
+        return cls.from_box([Lx, Ly, Lz, xy, xz, yz], dimensions=dimensions)
+
+    @classmethod
+    def from_box_lengths_and_angles(
+        cls,
+        L1: float,
+        L2: float,
+        L3: float,
+        alpha: float,
+        beta: float,
+        gamma: float,
+        dimensions: int = None,
+    ):
+        r"""Construct a box from lengths and angles.
+
+        Args:
+            L1 (float): The length of the first lattice vector
+            L2 (float): The length of the second lattice vector
+            L3 (float): The length of the third lattice vector
+            alpha (float): The angle between the y and z axes in radians
+            beta (float): The angle between the x and z axes in radians
+            gamma (float): The angle between the x and y axes in radians
+            dimensions (int): The number of dimensions (Default value = :code:`None`)
+
+        Returns:
+            :class:`freud.box.Box`: The resulting box object.
+        """
+        a1 = np.array([L1, 0, 0])
+        a2 = np.array([L2 * np.cos(gamma), L2 * np.sin(gamma), 0])
+        a3x = np.cos(beta)
+        a3y = (np.cos(alpha) - np.cos(beta) * np.cos(gamma)) / np.sin(gamma)
+        a3z = np.sqrt(1 - a3x**2 - a3y**2)
+        a3 = np.array([L3 * a3x, L3 * a3y, L3 * a3z])
+        if dimensions is None:
+            dimensions = 2 if L3 == 0 else 3
+        return cls.from_lattice_vectors(np.array([a1, a2, a3]), dimensions=dimensions)
+
 
 cdef BoxFromCPP(const freud._box.Box & cppbox):
     b = Box(cppbox.getLx(), cppbox.getLy(), cppbox.getLz(),

freud/data.py

@@ -233,6 +233,56 @@ def hex(cls):
         fractions = np.array([[0, 0, 0], [0.5, 0.5, 0]])
         return cls([1, np.sqrt(3)], fractions)
 
+    @classmethod
+    def from_lattice_vectors(
+        cls, lattice_vectors: np.ndarray, unique_positions: np.ndarray
+    ):
+        """Create a unit cell from lattice vectors.
+
+        Args:
+            lattice_vectors (:math:`(3, 3)` :class:`np.ndarray
+                The lattice vectors. Lattice vector a1 is lattice_vectors[0], etc.
+            unique_positions (:math:`(N_{points}, 3)` :class:`np.ndarray`):
+                The basis positions.
+
+        Returns:
+            :class:`~.UnitCell`: A unit cell with the given lattice vectors.
+        """
+        return cls(
+            freud.box.Box.from_lattice_vectors(lattice_vectors), unique_positions
+        )
+
+    @classmethod
+    def from_box_lengths_and_angles(
+        cls,
+        L1: float,
+        L2: float,
+        L3: float,
+        alpha: float,
+        beta: float,
+        gamma: float,
+        unique_positions: np.ndarray,
+    ):
+        """Create a unit cell from box lengths and angles.
+
+        Args:
+            L1 (float): The length of the first box vector.
+            L2 (float): The length of the second box vector.
+            L3 (float): The length of the third box vector.
+            alpha (float): The angle between the x and y lattice vectors.
+            beta (float): The angle between the x and z lattice vectors.
+            gamma (float): The angle between the y and z lattice vectors.
+            unique_positions (:math:`(N_{points}, 3)` :class:`np.ndarray
+                The basis positions.
+
+        Returns:
+            :class:`~.UnitCell`: A unit cell with the given box lengths and angles.
+        """
+        return cls(
+            freud.box.Box.from_box_lengths_and_angles(L1, L2, L3, alpha, beta, gamma),
+            unique_positions,
+        )
+
 
 def make_random_system(box_size, num_points, is2D=False, seed=None):
     r"""Helper function to make random points with a cubic or square box.

tests/test_box_Box.py

@@ -485,6 +485,64 @@ def test_from_box(self):
         box7 = freud.box.Box.from_matrix(box.to_matrix())
         assert np.isclose(box.to_matrix(), box7.to_matrix()).all()
 
+    def test_standard_orthogonal_box(self):
+        box = freud.box.Box.from_box((1, 2, 3, 0, 0, 0))
+        Lx, Ly, Lz, alpha, beta, gamma = box.to_box_lengths_and_angles()
+        npt.assert_allclose(
+            (Lx, Ly, Lz, alpha, beta, gamma), (1, 2, 3, np.pi / 2, np.pi / 2, np.pi / 2)
+        )
+
+    def test_to_and_from_box_lengths_and_angles(self):
+        original_box_lengths_and_angles = (
+            1,
+            2,
+            3,
+            np.pi / 3,
+            np.pi / 2.25,
+            np.pi / 2.35,
+        )
+        box = freud.box.Box.from_box_lengths_and_angles(
+            *original_box_lengths_and_angles
+        )
+        lengths_and_angles_computed = box.to_box_lengths_and_angles()
+        assert np.allclose(lengths_and_angles_computed, original_box_lengths_and_angles)
+
+    def test_from_lattice_vectors_cubic_lattice(self):
+        lattice_vectors = np.array([[1, 0, 0], [0, 1, 0], [0, 0, 1]])
+        unit_cell = freud.box.Box.from_lattice_vectors(lattice_vectors)
+        assert unit_cell.Lx == 1
+        assert unit_cell.Ly == 1
+        assert unit_cell.Lz == 1
+        assert unit_cell.xy == 0
+        assert unit_cell.xz == 0
+        assert unit_cell.yz == 0
+
+    def test_from_lattice_vectors_non_cubic_lattice(self):
+        box = freud.box.Box.from_lattice_vectors([[1, 0, 0], [0, 2, 0], [0, 0, 3]])
+        assert box.Lx == 1
+        assert box.Ly == 2
+        assert box.Lz == 3
+        assert box.xy == 0
+        assert box.xz == 0
+        assert box.yz == 0
+
+    def test_tilted_lattice(self):
+        lattice_vectors = np.array([[1, 0, 0], [0.5, np.sqrt(3) / 2, 0], [0, 0, 1]])
+        unit_cell = freud.box.Box.from_lattice_vectors(lattice_vectors)
+        assert np.isclose(unit_cell.Lx, 1.0)
+        assert np.isclose(unit_cell.Ly, np.sqrt(3) / 2)
+        assert np.isclose(unit_cell.Lz, 1.0)
+        assert np.isclose(unit_cell.xy, np.sqrt(3) / 3)
+        assert np.isclose(unit_cell.xz, 0.0)
+        assert np.isclose(unit_cell.yz, 0.0)
+
+    @pytest.mark.parametrize("dim", [2, None])
+    def test_dimensions(self, dim):
+        lattice_vectors = np.array([[1, 0, 0], [0, 1, 0], [0, 0, 0]])
+        unit_cell = freud.box.Box.from_lattice_vectors(lattice_vectors, dimensions=dim)
+        assert unit_cell.dimensions == 2
+        assert np.isclose(unit_cell.Lz, 0)
+
     def test_matrix(self):
         box = freud.box.Box(2, 2, 2, 1, 0.5, 0.1)
         box2 = freud.box.Box.from_matrix(box.to_matrix())