:py:mod:`qsearch.utils`
=======================

.. py:module:: qsearch.utils

.. autoapi-nested-parse::

   This module contains miscellaneous helper functions and tools.

   The functions you may want to be aware of:

   .. attribute:: endian_reverse

      Reverses the endianness of the specified unitary.  Necessary for working with unitaries from Qiskit.

   .. attribute:: matrix_distance_squared

      The default error_func.  Returns the Hilbert-Schmidt norm between two matrices.

   .. attribute:: matrix_distance_squared_jac

      Returns the value that matrix_distance_squared would return, as well as the jacobian.

   .. attribute:: matrix_residuals

      The default error_residuals.  Returns residuals based on difference between the poduct of the implemented matrix and the hermitian conjugate of the target and the identitiy.

   .. attribute:: matrix_residuals_jac

      Returns the jacobian of matrix_residuals.  Does not return the value of matrix_residuals as well.

   .. attribute:: remap

      Remaps a unitary for acting on qudits in a different order.

   .. attribute:: upgrade_qudits

      Upgrades a unitary from a lower qudit size to a larger qudit size.



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


Functions
~~~~~~~~~

.. autoapisummary::

   qsearch.utils.matrix_product
   qsearch.utils.matrix_kron
   qsearch.utils.op_norm
   qsearch.utils.nearest_unitary
   qsearch.utils.index_test
   qsearch.utils.downgrade_qudits_residuals
   qsearch.utils.downgrade_qudits_residuals_jac
   qsearch.utils.generate_stateprep_target_matrix
   qsearch.utils.re_rot_z
   qsearch.utils.re_rot_z_jac
   qsearch.utils.q1_unitary
   qsearch.utils.qt_arb_rot
   qsearch.utils.random_near_identity
   qsearch.utils.remap
   qsearch.utils.upgrade_qudits
   qsearch.utils.endian_reverse
   qsearch.utils.mpi_rank
   qsearch.utils.mpi_do_work
   qsearch.utils.mpi_worker



Attributes
~~~~~~~~~~

.. autoapisummary::

   qsearch.utils.MPI


.. py:data:: MPI

   

.. py:function:: matrix_product(*LU)

   Performs matrix multiplication of a list of matrices.


.. py:function:: matrix_kron(*LU)

   Performs the kronecker product on a list of matrices.


.. py:function:: op_norm(A)

   An implementation of the l1-l1 operator norm.


.. py:function:: nearest_unitary(A)

   Calculate the closest unitary to a given matrix.

   Calculate the unitary matrix U that is closest with respect to the
   operator norm distance to the general matrix A.

   D.M.Reich. "Characterisation and Identification of Unitary Dynamics
   Maps in Terms of Their Action on Density Matrices"

   :param A: The matrix input.
   :type A: np.ndarray

   :returns: The unitary matrix closest to A.
             Return U as a numpy matrix.
   :rtype: (np.ndarray)

   Thank you to Ed Younis, this is based on code from qfast


.. py:function:: index_test(i, di, df)


.. py:function:: downgrade_qudits_residuals(di, df, A, B, I)


.. py:function:: downgrade_qudits_residuals_jac(di, df, A, B, J)


.. py:function:: generate_stateprep_target_matrix(state)


.. py:function:: re_rot_z(theta, old_z)


.. py:function:: re_rot_z_jac(theta, old_z, multiplier=1)


.. py:function:: q1_unitary(x)


.. py:function:: qt_arb_rot(Theta_1, Theta_2, Theta_3, Phi_1, Phi_2, Phi_3, Phi_4, Phi_5)

   Using the parameterization found in https://journals.aps.org/prd/pdf/10.1103/PhysRevD.38.1994,
   this method constructs an arbitrary single_qutrit unitary operation.

   :param qutrit_params: a list of eight parameters, in the following order
                         Theta_1, Theta_2, Theta_3, Phi_1, Phi_2, Phi_3, Phi_4, Phi_5
                         The formula for the matrix is:
                             u11 = cos[Theta_1]*cos[Theta_2]*exp[i*Phi_1]
                             u12 = sin[Theta_1]*exp[i*Phi_3]
                             u13 = cos[Theta_1]*sin[Theta_2]*exp[i*Phi_4]
                             u21 = sin[Theta_2]*sin[Theta_3]*exp[-i*Phi_4 - i*Phi_5] -
                                     sin[Theta_1]*cos[Theta_2]*cos[Theta_3]*exp[i*Phi_1+i*Phi_2-i*Phi_3]
                             u22 = cos[Theta_1]*cos[Theta_3]*exp[i*Phi_2]
                             u23 = -cos[Theta_2]*sin[Theta_3]*exp[-i*Phi_1 - i*Phi_5] -
                                     sin[Theta_1]*sin[Theta_2]*cos[Theta_3]*exp[i*Phi_2 - i*Phi_3 + i*Phi_4]
                             u31 = -sin[Theta_1]*cos[Theta_2]*sin[Theta_3]*exp[i*Phi_1 - i*Phi_3 + i*Phi_5]
                                     - sin[Theta_2]*cos[Theta_3]*exp[-i*Phi_2-i*Phi_4]
                             u32 = cos[Theta_1]*sin[Theta_3]*exp[i*Phi_5]
                             u33 = cos[Theta_2]*cos[Theta_3]*exp[-i*Phi_1 - i*Phi_2] -
                                     sin[Theta_1]*sin[Theta_2]*sin[Theta_3]*exp[-i*Phi_3 + i*Phi_4 + i*Phi_5]


.. py:function:: random_near_identity(n, alpha)


.. py:function:: remap(U, order, d=2)


.. py:function:: upgrade_qudits(U, di=2, df=3)


.. py:function:: endian_reverse(U, d=2)


.. py:function:: mpi_rank()


.. py:function:: mpi_do_work(comm)

   Do the work of a single compilation.

   :param comm: An MPI communication object


.. py:function:: mpi_worker()

   Create a worker that will keep running compilation requests until told to stop