toqito.matrix_props.positive_semidefinite_rank
==============================================

.. py:module:: toqito.matrix_props.positive_semidefinite_rank

.. autoapi-nested-parse::

   Calculates the positive semidefinite rank of a nonnegative matrix.





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

.. py:function:: positive_semidefinite_rank(mat, max_rank = 10)

   Compute the positive semidefinite rank (PSD rank) of a nonnegative matrix.

   The definition of PSD rank is defined in [@Fawzi_2015_Positive].

   Finds the PSD rank of an input matrix by checking feasibility for increasing rank.

   .. rubric:: Examples

   As an example (Equation 21 from [@Heinosaari_2024_Can]), the PSD rank of the following matrix

   \[
       A = \frac{1}{2}
       \begin{pmatrix}
           0 & 1 & 1 \\
           1 & 0 & 1 \\
           1 & 1 & 0
       \end{pmatrix}
   \]

   is known to be \(\text{rank}_{\text{PSD}}(A) = 2\).

   ```python exec="1" source="above"
   import numpy as np
   from toqito.matrix_props import positive_semidefinite_rank

   print(positive_semidefinite_rank(1/2 * np.array([[0, 1, 1], [1,0,1], [1,1,0]])))
   ```


   The PSD rank of the identity matrix is the dimension of the matrix [@Fawzi_2015_Positive].

   ```python exec="1" source="above"
   import numpy as np
   from toqito.matrix_props import positive_semidefinite_rank

   print(positive_semidefinite_rank(np.identity(3)))
   ```