toqito.state_props.purity
=========================

.. py:module:: toqito.state_props.purity

.. autoapi-nested-parse::

   Calcultes the purity of a quantum state.





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

.. py:function:: purity(rho)

   Compute the purity of a quantum state [@WikiPurity].

   The negativity of a subsystem can be defined in terms of a density matrix \(\rho\): The
   purity of a quantum state \(\rho\) is defined as

   \[
       \text{Tr}(\rho^2),
   \]

   where \(\text{Tr}\) is the trace function.

   .. rubric:: Examples

   Consider the following scaled state defined as the scaled identity matrix

   \[
       \rho = \frac{1}{4} \begin{pmatrix}
                        1 & 0 & 0 & 0 \\
                        0 & 1 & 0 & 0 \\
                        0 & 0 & 1 & 0 \\
                        0 & 0 & 0 & 1
                      \end{pmatrix} \in \text{D}(\mathcal{X}).
   \]

   Calculating the purity of \(\rho\) yields \(\frac{1}{4}\). This can be observed using
   `|toqito⟩` as follows.

   ```python exec="1" source="above" session="purity_example"
   from toqito.state_props import purity
   import numpy as np
   print(purity(np.identity(4) / 4))
   ```


   Calculate the purity of the Werner state:

   ```python exec="1" source="above" session="purity_example"
   from toqito.states import werner
   rho = werner(2, 1 / 4)
   print(purity(rho))
   ```

   :raises ValueError: If matrix is not density operator.

   :param rho: A density matrix of a pure state vector.

   :returns: A value between 0 and 1 that corresponds to the purity of \(\rho\).