:py:mod:`qsearch.comparison`
============================

.. py:module:: qsearch.comparison

.. autoapi-nested-parse::

   This module contains functions for comparing matrices, vectors, and other numerical objects.  These functions do not all follow a standardized form, but many of these have a standardized version found in evaluation.py.



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


Functions
~~~~~~~~~

.. autoapisummary::

   qsearch.comparison.matrix_distance_squared
   qsearch.comparison.matrix_distance
   qsearch.comparison.matrix_distance_squared_jac
   qsearch.comparison.matrix_residuals
   qsearch.comparison.matrix_residuals_jac
   qsearch.comparison.matrix_residuals_v2
   qsearch.comparison.matrix_residuals_v2_jac
   qsearch.comparison.matrix_residuals_slice
   qsearch.comparison.matrix_residuals_slice_jac
   qsearch.comparison.matrix_residuals_blacklist
   qsearch.comparison.matrix_residuals_blacklist_jac
   qsearch.comparison.distance_with_initial_state
   qsearch.comparison.distance_with_initial_state_jac
   qsearch.comparison.residuals_with_initial_state
   qsearch.comparison.residuals_with_initial_state_jac
   qsearch.comparison.eval_func_from_residuals



.. py:function:: matrix_distance_squared(A, B)

   This is a distance function used to compare two matrices. It is phase agnostic and fast to calculate.

   :param A: A unitary matrix in the form of a numpy ndarray.
   :param B: Another unitary matrix of the same size as A, as a numpy ndarray.

   :returns: A single value between 0 and 1, representing how closely A and B match.  A value near 0 indicates that A and B are the same unitary, up to an overall phase difference.
   :rtype: Float


.. py:function:: matrix_distance(A, B)

   The square root of matrix_distance_squared is more analgous to "distance", although for most purposes, working with a distance squared is fine, since inequalities hold.

   :param A: A unitary matrix in the form of a numpy ndarray.
   :param B: Another unitary matrix of the same size as A, as a numpy ndarray.

   :returns: A single value between 0 and 1, representing how closely A and B match.  A value near 0 indicates that A and B are the same unitary, up to an overall phase difference.
   :rtype: Float


.. py:function:: matrix_distance_squared_jac(U, M, J)

   The jacobian version of matrix_distance_squared.

   :param U: A constant unitary matrix in the form of a numpy ndarray.
   :param M: A variable unitary matrix of the same size as A, as a numpy ndarray.
   :param J: A list of nump ndarrays representing the jacobians of M with respect to the parameters of interest.

   :returns: The matrix distance squared as a float (the same value that would be returned from matrix_distance_squared)
             jacs : A list of the derivative of dsq with resepect to each of the parameters.
   :rtype: dsq


.. py:function:: matrix_residuals(A, B, I)


.. py:function:: matrix_residuals_jac(U, M, J)


.. py:function:: matrix_residuals_v2(A, B, I)


.. py:function:: matrix_residuals_v2_jac(U, M, J)


.. py:function:: matrix_residuals_slice(slices, A, B, I)


.. py:function:: matrix_residuals_slice_jac(slices, A, B, J)


.. py:function:: matrix_residuals_blacklist(badrows, badcols, A, B, I)


.. py:function:: matrix_residuals_blacklist_jac(badrows, badcols, A, B, J)


.. py:function:: distance_with_initial_state(stateA, stateB, A, B)


.. py:function:: distance_with_initial_state_jac(stateA, stateB, A, B, J)


.. py:function:: residuals_with_initial_state(stateA, stateB, A, B, I)


.. py:function:: residuals_with_initial_state_jac(stateA, stateB, U, M, J)


.. py:function:: eval_func_from_residuals(f, A, B)