magnon.common
=============

.. py:module:: magnon.common


Attributes
----------

.. autoapisummary::

   magnon.common.default_distance_tol


Functions
---------

.. autoapisummary::

   magnon.common.normalize_scaled_coordinate
   magnon.common.modulo_lattice
   magnon.common.squared_distance
   magnon.common.find_site_index
   magnon.common.lattice_translation_vector
   magnon.common.reciprocal_lattice


Module Contents
---------------

.. py:data:: default_distance_tol
   :value: 1e-05


   Default precision used in determining equivalent distances, value = 1e-5

.. py:function:: normalize_scaled_coordinate(r, distance_tolerance = default_distance_tol)

   Normalizes a scaled coordinate vector or an array of scaled coordinates
   to the range [0, 1) for each component.

   :param r: A scaled coordinate vector or an array of scaled coordinates
   :type r: array_like
   :param distance_tolerance: Precision used for rounding near cell boundaries.
   :type distance_tolerance: float

   :returns: A normalized scaled coordinate vector or an array of normalized scaled coordinates
   :rtype: numpy.ndarray, dtype = np.float64


.. py:function:: modulo_lattice(x, distance_tol = default_distance_tol)

   Reduces a lattice vector x modulo 1, ensuring that values numerically close to 1 or 0 are wrapped to 0.

   :param x: A lattice vector
   :type x: array_like
   :param distance_tol: Precision used for rounding near cell boundaries.
   :type distance_tol: float

   :returns: A reduced lattice vector x modulo 1
   :rtype: numpy.ndarray


.. py:function:: squared_distance(a, b)

   Computes squared Euclidean distance between two points.

   :param a: Coordinates of the first point
   :type a: array_like
   :param b: Coordinates of the second point
   :type b: array_like

   :returns: Squared Euclidean norm of distance vector :math:`a-b`.
   :rtype: float


.. py:function:: find_site_index(position, scaled_atom_positions, distance_tol = default_distance_tol)

   Given a position in scaled coordinates, find the equivalent site index in the unit cell.

   :param position: A scaled coordinate vector to search for
   :type position: array_like
   :param scaled_atom_positions: An array of scaled coordinates in which to search
   :type scaled_atom_positions: array_like
   :param distance_tol: Precision used for determining equivalent positions
   :type distance_tol: float

   :raises ValueError: If a matching site could not be found

   :returns: The index of site which matches the coordinates
   :rtype: int


.. py:function:: lattice_translation_vector(r_ij_scaled, r_i_scaled, r_j_scaled, distance_tol = default_distance_tol)

   Returns the integer lattice translation vector T of an arbitrary vector r_scaled.

   :param r_ij_scaled: A scaled distance vector from position i to position j.
   :type r_ij_scaled: array_like
   :param r_i_scaled: The scaled coordinates of point i
   :type r_i_scaled: array_like
   :param r_j_scaled: The scaled coordinates of point j
   :type r_j_scaled: array_like
   :param distance_tol: Precision used for checking if a value is an integer
   :type distance_tol: float

   :raises ValueError: If the three vectors are inconsistent and do not result in an integer scaled lattice translation vector

   :returns: The integer lattice translation vector
   :rtype: numpy.ndarray, dtype = int


.. py:function:: reciprocal_lattice(lattice)

   Compute reciprocal lattice basis vectors from lattice vectors.

   :param lattice: A 3x3 array of lattice basis vectors; each row is a vector
   :type lattice: array_like

   :returns: A 3x3 array of reciprocal lattice basis vectors; each row is a vector
   :rtype: numpy.ndarray