toqito.state_opt.state_distinguishability
=========================================

.. py:module:: toqito.state_opt.state_distinguishability

.. autoapi-nested-parse::

   Calculates the probability of optimally distinguishing quantum states.





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

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

   Compute probability of state distinguishability [@Eldar_2003_SDPApproach].

   The "quantum state distinguishability" problem involves a collection of \(n\) quantum states

   \[
       \rho = \{ \rho_1, \ldots, \rho_n \},
   \]

   as well as a list of corresponding probabilities

   \[
       p = \{ p_1, \ldots, p_n \}.
   \]

   Alice chooses \(i\) with probability \(p_i\) and creates the state \(\rho_i\). Bob
   wants to guess which state he was given from the collection of states.

   For `strategy = "min_error"`, this is the default method that yields the minimal
   probability of error for Bob.

   In that case, this function implements the following semidefinite program that provides the
   optimal probability with which Bob can conduct quantum state distinguishability.

   \[
       \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*}
   \]

   For `strategy = "unambiguous"`, Bob never provides an incorrect answer, although it is
   possible that his answer is inconclusive.

   In that case, this function implements the following semidefinite program that provides the
   optimal probability with which Bob can conduct unambiguous quantum state distinguishability.

   \[
       \begin{align*}
           \text{maximize:} \quad & \mathbf{p} \cdot \mathbf{q} \\
           \text{subject to:} \quad & \Gamma - Q \geq 0,\\
                                    & \mathbf{q} \geq 0
       \end{align*}
   \]

   \[
       \begin{align*}
           \text{minimize:} \quad & \text{Tr}(\Gamma Z) \\
           \text{subject to:} \quad & z_i + p_i + \text{Tr}\left(F_iZ\right)=0,\\
                                    & Z, z \geq 0
       \end{align*}
   \]

   where \(\mathbf{p}\) is the vector whose \(i\)-th coordinate contains the probability
   that the state is prepared in state \(\left|\psi_i\right\rangle\), \(\Gamma\) is
   the Gram matrix of \(\left|\psi_1\right\rangle,\cdots,\left|\psi_n\right\rangle\) and \(F_i\) is
   \(-|i\rangle\langle i|\).

   !!! Note
       For unambiguous discrimination, this function supports both pure states (vectors) and mixed states
       (density matrices). For pure states, the states should be linearly independent. For mixed states,
       the Gram matrix is computed as Tr(ρᵢ ρⱼ). If the states cannot be unambiguously distinguished,
       the optimal probability will be low or zero.

   .. rubric:: Examples

   Minimal-error state distinguishability for the Bell states (which are perfectly distinguishable).

   ```python exec="1" source="above"
   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, _ = state_distinguishability(vectors=states, probs=probs, primal_dual="dual")

   print(np.around(res, decimals=2))
   ```

   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.

   ```python exec="1" source="above"
   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")

   print(np.around(measurements[0], decimals=5))
   ```

   Unambiguous state distinguishability for unbiased pure states.

   ```python exec="1" source="above"
   import numpy as np
   from toqito.state_opt import state_distinguishability

   states = [np.array([[1.], [0.]]), np.array([[1.],[1.]]) / np.sqrt(2)]
   probs = [1 / 2, 1 / 2]

   res, _ = state_distinguishability(vectors=states, probs=probs, primal_dual="primal", strategy="unambiguous")

   print(np.around(res, decimals=2))
   ```

   Unambiguous state distinguishability for mixed states.

   ```python exec="1" source="above"
   import numpy as np
   from toqito.state_opt import state_distinguishability

   # Two mixed states (Werner-like states)
   rho1 = 0.7 * np.array([[1., 0.], [0., 0.]]) + 0.3 * np.eye(2) / 2
   rho2 = 0.7 * np.array([[0., 0.], [0., 1.]]) + 0.3 * np.eye(2) / 2
   states = [rho1, rho2]
   probs = [1 / 2, 1 / 2]

   res, _ = state_distinguishability(vectors=states, probs=probs, primal_dual="primal", strategy="unambiguous")

   print(np.around(res, decimals=2))
   ```

   :param vectors: A list of states provided as vectors (for pure states) or density matrices (for mixed states).
   :param probs: Respective list of probabilities each state is selected. If no probabilities are provided, a uniform
   :param probability distribution is assumed.:
   :param strategy: Whether to perform unambiguous or minimal error discrimination task. Possible values are "min_error"
   :param and "unambiguous". Default option is `strategy="min_error"`. Both strategies support pure and mixed states.:
   :param solver: Optimization option for `picos` solver. Default option is `solver="cvxopt"`.
   :param primal_dual: Option for the optimization problem. Default option is `"dual"`.
   :param kwargs: Additional arguments to pass to picos' solve method.

   :returns: The optimal probability with which Bob can guess the state he was not given from `states` along with the optimal
             set of measurements.