toqito.state_metrics.trace_distance
===================================

.. py:module:: toqito.state_metrics.trace_distance

.. autoapi-nested-parse::

   Trace distance metric gives a measure of distinguishability between two quantum states.

   The trace distance is calculated via density matrices.





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

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

   Compute the trace distance between density operators `rho` and `sigma`.

   The trace distance between \(\rho\) and \(\sigma\) is defined as

   \[
       \delta(\rho, \sigma) = \frac{1}{2} \left( \text{Tr}(\left| \rho - \sigma
        \right| \right).
   \]

   More information on the trace distance can be found in [@Quantiki_TrDist].

   .. 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^* = \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}).
   \]

   The trace distance between \(\rho\) and another state \(\sigma\) is equal to \(0\) if any only if
   \(\rho = \sigma\). We can check this using the `|toqito⟩` package.

   ```python exec="1" source="above"
   from toqito.states import bell
   from toqito.state_metrics import trace_distance

   rho = bell(0) @ bell(0).conj().T
   sigma = rho

   print(trace_distance(rho, sigma))
   ```

   :raises ValueError: If matrices are not of density operators.

   :param rho: An input matrix.
   :param sigma: An input matrix.

   :returns: The trace distance between `rho` and `sigma`.