matrix_props.is_absolutely_k_incoherent
=======================================

.. py:module:: matrix_props.is_absolutely_k_incoherent

.. autoapi-nested-parse::

   Checks if the matrix is absolutely $k$-incoherent.



Functions
---------

.. autoapisummary::

   matrix_props.is_absolutely_k_incoherent.is_absolutely_k_incoherent


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

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

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

   Formally, for positive integers :math:`n` and :math:`k`, a mixed quantum state is said to be absolutely k-incoherent
   if :math:`U \rho U^* \in \mathbb{I}_{k, n}` for all unitary matrices :math:`U \in \text{U}(\mathbb{C}^n)`.

   This function checks if the provided density matrix is absolutely k-incoherent based on the criteria introduced in
   :footcite:`Johnston_2022_Absolutely` and the corresponding QETLAB functionality :footcite:`QETLAB_link`. When
   necessary, an SDP is set up via ``cvxpy``.

   The notion of absolute k-incoherence is connected to the notion of quantum state antidistinguishability as discussed
   in :footcite:`Johnston_2025_Tight`.

   .. rubric:: Examples

   .. jupyter-execute::

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

   .. seealso:: :func:`.is_antidistinguishable`, :func:`.is_k_incoherent`

   .. rubric:: References

   .. footbibliography::

   :param mat: Matrix to check for absolute k-incoherence.
   :param k: The positive integer indicating the absolute coherence level.
   :param tol: Tolerance for numerical comparisons (default is 1e-15).
   :raises ValueError: If the input matrix is not square.
   :return: True if the quantum state is absolutely k-incoherent, False otherwise.