:py:mod:`state_opt.state_exclusion`
===================================

.. py:module:: state_opt.state_exclusion

.. autoapi-nested-parse::

   State exclusion.



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


Functions
~~~~~~~~~

.. autoapisummary::

   state_opt.state_exclusion.state_exclusion
   state_opt.state_exclusion._min_error_primal
   state_opt.state_exclusion._min_error_dual



.. py:function:: state_exclusion(vectors, probs = None, solver = 'cvxopt', primal_dual = 'dual')

   Compute probability of single state conclusive state exclusion.

   The *quantum state exclusion* problem involves a collection of :math:`n` quantum states

   .. math::
       \rho = \{ \rho_0, \ldots, \rho_n \},

   as well as a list of corresponding probabilities

   .. math::
       p = \{ p_0, \ldots, p_n \}.

   Alice chooses :math:`i` with probability :math:`p_i` and creates the state :math:`\rho_i`.

   Bob wants to guess which state he was *not* given from the collection of states. State exclusion implies that
   ability to discard (with certainty) at least one out of the "n" possible quantum states by applying a measurement.

   This function implements the following semidefinite program that provides the optimal probability with which Bob can
   conduct quantum state exclusion.

       .. math::
           \begin{equation}
               \begin{aligned}
                   \text{minimize:} \quad & \sum_{i=1}^n p_i \langle M_i, \rho_i \rangle \\
                   \text{subject to:} \quad & \sum_{i=1}^n M_i = \mathbb{I}_{\mathcal{X}}, \\
                                            & M_0, \ldots, M_n \in \text{Pos}(\mathcal{X}).
               \end{aligned}
           \end{equation}

       .. math::
           \begin{equation}
               \begin{aligned}
                   \text{maximize:} \quad & \text{Tr}(Y)
                   \text{subject to:} \quad & Y \leq M_1, \\
                                            & Y \leq M_2, \\
                                            & \vdots \\
                                            & Y \leq M_n, \\
                                            & Y \text{Herm}(\mathcal{X}).
               \end{aligned}
           \end{equation}


   The conclusive state exclusion SDP is written explicitly in :cite:`Bandyopadhyay_2014_Conclusive`. The problem
   of conclusive state exclusion was also thought about under a different guise in :cite:`Pusey_2012_On`.

   .. rubric:: Examples

   Consider the following two Bell states

   .. math::
       \begin{equation}
           \begin{aligned}
               u_0 &= \frac{1}{\sqrt{2}} \left( |00 \rangle + |11 \rangle \right), \\
               u_1 &= \frac{1}{\sqrt{2}} \left( |00 \rangle - |11 \rangle \right).
           \end{aligned}
       \end{equation}

   It is not possible to conclusively exclude either of the two states. We can see that the result of the function in
   :code:`toqito` yields a value of :math:`0` as the probability for this to occur.

   >>> from toqito.state_opt import state_exclusion
   >>> from toqito.states import bell
   >>> import numpy as np
   >>>
   >>> vectors = [bell(0), bell(1)]
   >>> probs = [1/2, 1/2]
   >>>
   >>> '%.2f' % state_exclusion(vectors, probs)[0]
   '0.00'

   .. note::
       You do not need to use `'%.2f' %` when you use this function.

       We use this to format our output such that `doctest` compares the calculated output to the
       expected output upto two decimal points only. The accuracy of the solvers can calculate the
       `float` output to a certain amount of precision such that the value deviates after a few digits
       of accuracy.

   .. rubric:: References

   .. bibliography::
       :filter: docname in docnames

   :param vectors: A list of states provided as vectors.
   :param probs: Respective list of probabilities each state is selected. If no
                 probabilities are provided, a uniform probability distribution is assumed.
   :param solver: Optimization option for `picos` solver. Default option is `solver_option="cvxopt"`.
   :param primal_dual: Option for the optimization problem.
   :return: The optimal probability with which Bob can guess the state he was
            not given from `states` along with the optimal set of measurements.



.. py:function:: _min_error_primal(vectors, dim, probs = None, solver = 'cvxopt')

   Find the primal problem for minimum-error quantum state exclusion SDP.


.. py:function:: _min_error_dual(vectors, dim, probs = None, solver = 'cvxopt')

   Find the dual problem for minimum-error quantum state exclusion SDP.