toqito.state_metrics.matsumoto_fidelity
=======================================

.. py:module:: toqito.state_metrics.matsumoto_fidelity

.. autoapi-nested-parse::

   Matsumoto fidelity is the maximum classical fidelity associated with a classical-to-quantum preparation procedure.





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

.. py:function:: matsumoto_fidelity(rho, sigma)

   Compute the Matsumoto fidelity of two density matrices [@Matsumoto_2010_Reverse].

   Calculate the Matsumoto fidelity between the two density matrices `rho` and `sigma`, defined by:

   \[
       \mathrm{tr}(\rho\#\sigma),
   \]

   where \(\#\) denotes the matrix geometric mean, which for invertible states is

   \[
       \rho\#\sigma = \rho^{1/2}\sqrt{\rho^{-1/2}\sigma\rho^{-1/2}}\rho^{1/2}.
   \]

   For singular states it is defined by the limit

   \[
       \rho\#\sigma = \lim_{\epsilon\to0}(\rho+\epsilon\mathbb{I})\#(+\epsilon\mathbb{I}).
   \]

   The return is a value between \(0\) and \(1\), with \(0\) corresponding to matrices `rho` and
   `sigma` with orthogonal support, and \(1\) corresponding to the case `rho = sigma`. The Matsumoto
   fidelity is a lower bound for the fidelity.

   .. 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 Matsumoto fidelity between states that are identical, we should obtain
   the value
   of \(1\). This can be observed in `|toqito⟩` as follows.

   ```python exec="1" source="above"
   import numpy as np
   from toqito.state_metrics import matsumoto_fidelity

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

   print(np.around(matsumoto_fidelity(rho, sigma), decimals=2))
   ```

   :raises ValueError: If matrices are not of equal dimension.

   :param rho: Density operator.
   :param sigma: Density operator.

   :returns: The Matsumoto fidelity between `rho` and `sigma`.