matrix_props.is_density
=======================

.. py:module:: matrix_props.is_density

.. autoapi-nested-parse::

   Checks if the matrix is a density matrix.



Functions
---------

.. autoapisummary::

   matrix_props.is_density.is_density


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

.. py:function:: is_density(mat)

   Check if matrix is a density matrix :cite:`WikiDen`.

   A matrix is a density matrix if its trace is equal to one and it has the
   property of being positive semidefinite (PSD).

   .. rubric:: Examples

   Consider the Bell state:

   .. math::
      u = \frac{1}{\sqrt{2}} |00 \rangle + \frac{1}{\sqrt{2}} |11 \rangle.

   Constructing the matrix :math:`\rho = u u^*` defined as

   .. math::
       \rho = \frac{1}{2} \begin{pmatrix}
                               1 & 0 & 0 & 1 \\
                               0 & 0 & 0 & 0 \\
                               0 & 0 & 0 & 0 \\
                               1 & 0 & 0 & 1
                          \end{pmatrix}

   our function indicates that this is indeed a density operator as the trace
   of :math:`\rho` is equal to :math:`1` and the matrix is positive
   semidefinite.

   .. jupyter-execute::

    from toqito.matrix_props import is_density
    from toqito.states import bell
    import numpy as np
    rho = bell(0) @ bell(0).conj().T
    is_density(rho)

   Alternatively, the following example matrix :math:`\sigma` defined as

   .. math::
       \sigma = \frac{1}{2} \begin{pmatrix}
                               1 & 2 \\
                               3 & 1
                            \end{pmatrix}

   does satisfy :math:`\text{Tr}(\sigma) = 1`, however fails to be positive
   semidefinite, and is therefore not a density operator. This can be
   illustrated using :code:`|toqito⟩` as follows.

   .. jupyter-execute::

    import numpy as np
    from toqito.states import bell
    from toqito.matrix_props import is_density

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

    is_density(sigma)

   .. rubric:: References

   .. bibliography::
       :filter: docname in docnames

   :param mat: Matrix to check.
   :return: Return :code:`True` if matrix is a density matrix,
            and :code:`False` otherwise.