state_metrics.bures_angle
=========================

.. py:module:: state_metrics.bures_angle

.. autoapi-nested-parse::

   Bures angle, also known as Bures arc, Bures length or quantum angle is a distance metric.

   The Bures angle metric is a measure of the statistical distance between quantum states.



Functions
---------

.. autoapisummary::

   state_metrics.bures_angle.bures_angle


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

.. py:function:: bures_angle(rho_1, rho_2, decimals = 10)

   Compute the Bures angle of two density matrices :cite:`WikiBures`.

   Calculate the Bures angle between two density matrices :code:`rho_1` and :code:`rho_2` defined by:

   .. math::
       \arccos{\sqrt{F (\rho_1, \rho_2)}}

   where :math:`F(\cdot)` denotes the fidelity between :math:`\rho_1` and :math:`\rho_2`. The return is a value between
   :math:`0` and :math:`\pi / 2`, with :math:`0` corresponding to matrices :code:`rho_1 = rho_2` and :math:`\pi / 2`
   corresponding to the case :code:`rho_1` and :code:`rho_2` with orthogonal support.

   .. rubric:: Examples

   Consider the following Bell state

   .. math::
       u = \frac{1}{\sqrt{2}} \left( |00 \rangle + |11 \rangle \right) \in \mathcal{X}.

   The corresponding density matrix of :math:`u` may be calculated by:

   .. math::
       \rho = u u^* = \frac{1}{2} \begin{pmatrix}
                        1 & 0 & 0 & 1 \\
                        0 & 0 & 0 & 0 \\
                        0 & 0 & 0 & 0 \\
                        1 & 0 & 0 & 1
                      \end{pmatrix} \in \text{D}(\mathcal{X}).

   In the event where we calculate the Bures angle between states that are identical, we should obtain the value of
   :math:`0`. This can be observed in :code:`|toqito⟩` as follows.

   .. jupyter-execute::

    import numpy as np
    from toqito.state_metrics import bures_angle

    rho = 1 / 2 * np.array(
        [[1, 0, 0, 1],
         [0, 0, 0, 0],
         [0, 0, 0, 0],
         [1, 0, 0, 1]]
    )
    sigma = rho

    bures_angle(rho, sigma)

   .. rubric:: References

   .. bibliography::
       :filter: docname in docnames

   :raises ValueError: If matrices are not of equal dimension.
   :param rho_1: Density operator.
   :param rho_2: Density operator.
   :param decimals: Number of decimal places to round to (default 10).
   :return: The Bures angle between :code:`rho_1` and :code:`rho_2`.