toqito.matrix_props.is_totally_positive
=======================================

.. py:module:: toqito.matrix_props.is_totally_positive

.. autoapi-nested-parse::

   Checks if the matrix is totally positive.





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

.. py:function:: is_totally_positive(mat, tol = 1e-06, sub_sizes = None)

   Determine whether a matrix is totally positive. [@WikiTotPosMat].

   A totally positive matrix is a square matrix where all the minors are positive. Equivalently, the determinant of
   every square submatrix is a positive number.

   .. rubric:: Examples

   Consider the matrix

   \[
       X = \begin{pmatrix}
           1 & 2 \\
           3 & 4
       \end{pmatrix}
   \]

   To determine if this matrix is totally positive, we need to check the positivity of all of its minors. The 1x1
   minors are simply the individual entries of the matrix. For \(X\), these are

   \[
       \begin{equation}
           \begin{aligned}
               X_{1,1} &= 1 \\
               X_{1,2} &= 2 \\
               X_{2,1} &= 3 \\
               X_{2,2} &= 4 \\
           \end{aligned}
       \end{equation}
   \]

   Each of these entries is positive. There is only one 2x2 minor in this case, which is the determinant of
   the entire
   matrix \(X\). The determinant of \(X\) is calculated as:

   \[
       \text{det}(X) = 1 \times 4 - 2 \times 3 = 4 - 6 = 2
   \]

   Our function indicates that this matrix is indeed totally positive.

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

   A = np.array([[1, 2], [3, 4]])

   print(is_totally_positive(A))
   ```

   However, the following example matrix \(B\) defined as

   \[
       B = \begin{pmatrix}
               1 & 2 \\
               3 & -4
           \end{pmatrix}
   \]

   is not totally positive. The 2x2 minor of \(B\) is the determinant of the entire matrix \(B\). The
   determinant of \(B\) is calculated as:

   \[
       \text{det}(B) = 1 \times -4 - 2 \times 3 = -4 - 6 = -10
   \]

   Since the determinant is negative, \(B\) is not totally positive.

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

   B = np.array([[1, 2], [3, -4]])

   print(is_totally_positive(B))
   ```

   :param mat: Matrix to check.
   :param tol: The absolute tolerance parameter (default 1e-06).
   :param sub_sizes: List of sizes of submatrices to consider. Default is all sizes up to `min(mat.shape)`.

   :returns: Return `True` if matrix is totally positive, and `False` otherwise.