toqito.state_props.is_abs_ppt
=============================

.. py:module:: toqito.state_props.is_abs_ppt

.. autoapi-nested-parse::

   Checks if a quantum state is absolutely PPT.





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

.. py:function:: is_abs_ppt(mat, dim = None, rtol = 1e-05, atol = 1e-08)

   Determine whether or not a matrix is absolutely PPT [@Hildebrand_2007_AbsPPT].

   A Hermitian positive semidefinite matrix is absolutely PPT iff it is PPT under all unitary transformations.
   Equivalently, if the matrix operates on a Hilbert space \(H_{nm}\) of dimension \(nm\), then it is
   PPT under *all* possible decompositions of \(H_{nm}\) as \(H_{n} \otimes H_{m}\). Being absolutely
   PPT is a spectral condition (i.e. it is a condition on the eigenvalues of the matrix).

   The function allows passing a `numpy` ndarray or a `cvxpy` Variable for `mat`:

   - If `mat` is a `numpy` ndarray, the function first checks if `mat` is Hermitian positive
       semidefinite. Then, it checks if its eigenvalues satisfy the Gerschgorin circle property (see Theorem 7.2 of
       [@Jivulescu_2015_Reduction]). Then it checks if the matrix belongs to the separable ball by calling
       `in_separable_ball`. Finally, if all the above checks fail to return a definite result, it determines if
       the matrix is absolutely PPT by checking if all the constraint matrices returned by
       `abs_ppt_constraints` are positive semidefinite.
   - If `mat` is a `cvxpy` Variable, `mat` must be a 1D vector representing the eigenvalues of
       a matrix. The function then returns the list of `cvxpy` Constraints required for optimizing over the
       space of absolutely PPT matrices. This includes the positive semidefinite constraint on each constraint matrix
       as well as `mat[0] ≥ mat[1] ≥ ... ≥ mat[-1] ≥ 0`.

   This function is adapted from QETLAB [@QETLAB_link].

   !!! Note
       If `min(dim)` \(\leq 6\), this function checks all constraints
       and therefore returns `True` or `False` in all cases. However, if
       `min(dim)` \(\geq 7\), only the first \(33592\) constraints are
       checked, since there are over \(23178480\) constraints in this case
       [@Johnston_2014_Orderings]. Therefore the function returns either
       `False` if at least one constraint was not satisfied, or `None`
       if all checked constraints were satisfied.

   .. rubric:: Examples

   A random density matrix will likely not be absolutely PPT:

   ```python exec="1" source="above"
   import numpy as np
   from toqito.rand import random_density_matrix
   from toqito.state_props import is_abs_ppt
   rho = random_density_matrix(9) # assumed to act on a 3 x 3 bipartite system
   print(f"ρ is absolutely PPT: {is_abs_ppt(rho, 3)}")
   ```

   The maximally-mixed state is an example of an absolutely PPT state:

   ```python exec="1" source="above"
   import numpy as np
   from toqito.states import max_mixed
   from toqito.state_props import is_abs_ppt
   rho = max_mixed(9) # assumed to act on a 3 x 3 bipartite system
   print(f"ρ is absolutely PPT: {is_abs_ppt(rho, 3)}")
   ```

   :raises TypeError: If `mat` is not a `numpy` ndarray or a `cvxpy` Variable.
   :raises ValueError: If `mat` is a `numpy` ndarray but is not square.
   :raises ValueError: If `mat` is a `cvxpy` Variable but is not 1D.
   :raises ValueError: If `dim` does not divide the dimensions of `mat`.

   :param mat: A square matrix.
   :param dim: The dimension of any one subsystem on which `mat` acts. If `None`, `dim` is selected such that
   :param `min:
   :type `min: dim, mat.shape[0] // dim
   :param (see Theorem 2 of [@Hildebrand_2007_AbsPPT]).:
   :param rtol: The relative tolerance parameter (default 1e-05).
   :param atol: The absolute tolerance parameter (default 1e-08).

   :returns: If `mat` is a 1D `cvxpy` Variable, return a list of `cvxpy` Constraints required for optimizing over the space
             of absolutely PPT matrices.