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

.. py:module:: matrix_props.is_k_incoherent

.. autoapi-nested-parse::

   Checks if the matrix is $k$-incoherent.



Functions
---------

.. autoapisummary::

   matrix_props.is_k_incoherent.is_k_incoherent


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

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

   Determine whether a quantum state is k-incoherent :footcite:`Johnston_2022_Absolutely`.

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

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

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

   The function first handles trivial cases. Then it computes the comparison matrix (via
   :func:`matrices.comparison.comparison`) and performs further tests based on the trace of :math:`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 :math:`n = 3` and :math:`k = 2`, then the following matrix is :math:`2`-incoherent:

   .. jupyter-execute::

       import numpy as np
       from toqito.matrix_props import is_k_incoherent
       mat = np.array([[2, 1, 2],
                   [1, 2, -1],
                   [2, -1, 5]])
       is_k_incoherent(mat, 2)

   .. seealso:: :func:`.is_antidistinguishable`, :func:`.is_absolutely_k_incoherent`

   .. rubric:: References

   .. footbibliography::

   :param mat: Density matrix to test.
   :param k: The positive integer coherence level.
   :param tol: Tolerance for numerical comparisons (default is 1e-15).
   :raises ValueError: If k ≤ 0 or if :code:`mat` is not square.
   :return: True if :code:`mat` is k-incoherent, False otherwise.