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

.. py:module:: toqito.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.





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

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

   Compute the Bures angle of two density matrices [@WikiBures].

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

   \[
       \arccos{\sqrt{F (\rho_1, \rho_2)}}
   \]

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

   .. rubric:: Examples

   Consider the following Bell state

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

   The corresponding density matrix of \(u\) may be calculated by:

   \[
       \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
   \(0\). This can be observed in `|toqito⟩` as follows.

   ```python exec="1" source="above"
   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

   print(bures_angle(rho, sigma))
   ```

   :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).

   :returns: The Bures angle between `rho_1` and `rho_2`.