:py:mod:`state_opt.state_distinguishability`
============================================

.. py:module:: state_opt.state_distinguishability

.. autoapi-nested-parse::

   State distinguishability.



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


Functions
~~~~~~~~~

.. autoapisummary::

   state_opt.state_distinguishability._min_error_dual
   state_opt.state_distinguishability._min_error_primal
   state_opt.state_distinguishability.state_distinguishability



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

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


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

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


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

   Compute probability of state distinguishability :cite:`Eldar_2003_SDPApproach`.

   The "quantum state distinguishability" 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 given from the collection of states.

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

   .. math::
       \begin{align*}
           \text{maximize:} \quad & \sum_{i=0}^n p_i \langle M_i, \rho_i \rangle \\
           \text{subject to:} \quad & M_0 + \ldots + M_n = \mathbb{I},\\
                                    & M_0, \ldots, M_n \geq 0
       \end{align*}

   .. rubric:: Examples

   State distinguishability for the Bell states (which are perfectly distinguishable).

   >>> from toqito.states import bell
   >>> from toqito.state_opt import state_distinguishability
   >>> states = [bell(0), bell(1), bell(2), bell(3)]
   >>> probs = [1 / 4, 1 / 4, 1 / 4, 1 / 4]
   >>> res, _ = state_distinguishability(vectors=states, probs=probs, primal_dual="dual")
   0.9999999994695794

   Note that if we are just interested in obtaining the optimal value, it is computationally less intensive to compute
   the dual problem over the primal problem. However, the primal problem does allow us to extract the explicit
   measurement operators which may be of interest to us.

   >>> from toqito.states import bell
   >>> from toqito.state_opt import state_distinguishability
   >>> states = [bell(0), bell(1), bell(2), bell(3)]
   >>> probs = [1 / 4, 1 / 4, 1 / 4, 1 / 4]
   >>> res, measurements = state_distinguishability(vectors=states, probs=probs, primal_dual="primal")
   >>> np.around(measurements[0], decimals=5)
   [[ 0.5+0.j -0. +0.j  0. +0.j  0.5-0.j]
    [-0. -0.j  0. +0.j -0. -0.j -0. -0.j]
    [ 0. -0.j -0. +0.j  0. +0.j  0. -0.j]
    [ 0.5+0.j -0. +0.j  0. +0.j  0.5+0.j]]

   .. 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. Default option is `"dual"`.
   :return: The optimal probability with which Bob can guess the state he was
            not given from `states` along with the optimal set of measurements.