: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.state_distinguishability
   state_opt.state_distinguishability._min_error_primal
   state_opt.state_distinguishability._min_error_dual



.. 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")
   >>> '%.2f' % res
   '1.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.

   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.

   >>> import numpy as np
   >>> 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)  # doctest: +SKIP
   array([[ 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.



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

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


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

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