magnon.linalg
=============

.. py:module:: magnon.linalg


Functions
---------

.. autoapisummary::

   magnon.linalg.normalised_vector
   magnon.linalg.generate_orthonormal_vectors
   magnon.linalg.rotation_matrix_pair
   magnon.linalg.paraidentity
   magnon.linalg.is_purely_real


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

.. py:function:: normalised_vector(vec)

   Return a normalised vector in the direction of `vec`.

   :param vec: The vector to normalize.
   :type vec: array_like

   :returns: **out** -- Normalised vector with the same direction as `vec`. If the input norm is zero, returns a vector of zeros with the same shape as `vec`.
   :rtype: ndarray

   .. rubric:: Examples

   >>> normalised_vector([3, 4])
   array([0.6, 0.8])
   >>> normalised_vector([0, 0])
   array([0., 0.])


.. py:function:: generate_orthonormal_vectors(vec)

   Generate an orthonormal set of vectors including the given input vector.

   Given a 2D or 3D input vector, this function returns a set of orthonormal
   vectors where the first vector is the normalised input vector, and the
   remaining vectors are mutually orthogonal and normalised.


   :param vec: Input vector of length 2 or 3.
   :type vec: array_like

   :returns: **orthonormals** -- Tuple containing orthonormal vectors:

             For 2D input: (v0, v1), where v0 is the normalised input vector,
             and v1 is perpendicular to v0.

             For 3D input: (v0, v1, v2), where v0 is the normalised input vector,
             and v1, v2 are mutually orthogonal and normalised.
   :rtype: tuple of ndarray

   :raises AssertionError: If the length of the input vector is not 2 or 3.

   .. rubric:: Examples

   >>> generate_orthonormal_vectors([1, 0, 0])
   (array([1., 0., 0.]), array([0., 0., 1.]), array([0., 1., 0.]))

   >>> generate_orthonormal_vectors([0, 1])
   (array([0., 1.]), array([1., 0.]))


.. py:function:: rotation_matrix_pair(axis, angle)

   Return the generalized rotation matrix describing a rotation of [angle] radians around [axis], and a rotation of -[angle] radians around [axis]

   This is an implementation of Rodrigues' rotation formula [1]_.

   :param axis: The axis around which the rotation is to occur
   :type axis: array_like
   :param angle: The angle of the rotation in radians
   :type angle: float

   :returns: **R** -- The rotation matrix
   :rtype: numpy.ndarray

   .. rubric:: References

   .. [1] https://arxiv.org/pdf/1810.02999


.. py:function:: paraidentity(size, dtype = np.float64)

   Create a paraidentity (:math:`\sigma_3`) matrix of shape (2*size, 2*size).

   The paraidentity matrix, also known as the generalized Pauli :math:`\sigma_3` matrix,
   is a diagonal matrix with the first `size` diagonal entries set to 1, and
   the next `size` diagonal entries set to -1.


   :param size: The block size. The output matrix will have shape (2*size, 2*size).
   :type size: int
   :param dtype: Desired output data type (default is `np.float64`).
   :type dtype: data-type, optional

   :returns: **out** -- Paraidentity matrix of shape (2*size, 2*size) and specified dtype.
   :rtype: ndarray

   .. rubric:: Examples

   >>> paraidentity(2)
   array([[ 1.,  0.,  0.,  0.],
   [ 0.,  1.,  0.,  0.],
   [ 0.,  0., -1.,  0.],
   [ 0.,  0.,  0., -1.]])


.. py:function:: is_purely_real(arr, zero_tol = magnon.default_numerical_tol)

   Test whether all elements of an array are real within a tolerance.


   :param arr: Input array to be tested.
   :type arr: array_like
   :param zero_tol: Tolerance for considering the imaginary part as zero (default is 1e-8).
   :type zero_tol: float, optional

   :returns: **is_real** -- True if all elements have imaginary part less than `tol` in magnitude, False otherwise.
   :rtype: bool

   .. rubric:: Examples

   >>> import numpy as np
   >>> is_purely_real([1, 2, 3])
   True
   >>> is_purely_real([1+1e-9j, 2, 3])
   True
   >>> is_purely_real([1+1e-6j, 2, 3], zero_tol=1e-7)
   False
   >>> is_purely_real([1+0j, 2+0j, 3+0j])
   True