toqito.matrix_props.is_k_incoherent
===================================

.. py:module:: toqito.matrix_props.is_k_incoherent

.. autoapi-nested-parse::

   Checks if the matrix is $k$-incoherent.





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

.. py:function:: is_k_incoherent(mat, k, tol = 1e-15)

   Determine whether a quantum state is k-incoherent [@Johnston_2022_Absolutely].

   For a positive integers, \(k\) and \(n\), the matrix \(X \in \text{Pos}(\mathbb{C}^n)\) is called
   \(k\)-incoherent if there exists a positive integer \(m\), a set  \(S = \{|\psi_0\rangle,
   |\psi_1\rangle,\ldots, |\psi_{m-1}\rangle\} \subset \mathbb{C}^n\) with the property that each \(|\psi_i\rangle\)
   has at most \(k\) non-zero entries, and real scalars \(c_0, c_1, \ldots, c_{m-1} \geq 0\) for which

   \[
       X = \sum_{j=0}^{m-1} c_j |\psi_j\rangle \langle \psi_j|.
   \]

   This function checks if the provided density matrix `mat` is k-incoherent. It returns True if `mat` is
   k-incoherent and False if `mat` is not.

   The function first handles trivial cases. Then it computes the comparison matrix (via
   [`comparison()`][toqito.matrices.comparison.comparison]) and performs further tests based on the trace of \(mat^2\)
   and a dephasing channel. If no decision is reached, the function recurses by checking incoherence for k-1.  Finally,
   if still indeterminate, an SDP is formulated to decide incoherence.

   .. rubric:: Examples

   If \(n = 3\) and \(k = 2\), then the following matrix is \(2\)-incoherent:

   ```python exec="1" source="above"
   import numpy as np
   from toqito.matrix_props import is_k_incoherent
   mat = np.array([[2, 1, 2],
               [1, 2, -1],
               [2, -1, 5]])
   print(is_k_incoherent(mat, 2))
   ```

   !!! See
       [is_antidistinguishable()][toqito.state_props.is_antidistinguishable.is_antidistinguishable],
       [is_absolutely_k_incoherent()][toqito.matrix_props.is_absolutely_k_incoherent.is_absolutely_k_incoherent]

   :raises ValueError: If k ≤ 0 or if `mat` is not square.

   :param mat: Density matrix to test.
   :param k: The positive integer coherence level.
   :param tol: Tolerance for numerical comparisons (default is 1e-15).

   :returns: True if `mat` is k-incoherent, False otherwise.