toqito.state_opt.npa_hierarchy
==============================

.. py:module:: toqito.state_opt.npa_hierarchy

.. autoapi-nested-parse::

   Generates the NPA constraints.









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

.. py:class:: Symbol

   Bases: :py:obj:`tuple`


   .. py:attribute:: player


   .. py:attribute:: question


   .. py:attribute:: answer


.. py:data:: IDENTITY_SYMBOL

.. py:data:: PLAYERS
   :value: ('Alice', 'Bob')


.. py:function:: npa_constraints(assemblage, k = 1, referee_dim = 1, no_signaling = True)

   Generate the constraints specified by the NPA hierarchy up to a finite level.

   [@Navascues_2008_AConvergent]

   You can determine the level of the hierarchy by a positive integer or a string
   of a form like "1+ab+aab", which indicates that an intermediate level of the hierarchy
   should be used, where this example uses all products of 1 measurement, all products of
   one Alice and one Bob measurement, and all products of two Alice and one Bob measurement.

   The commuting measurement assemblage operator must be given as a dictionary. The keys are
   tuples of Alice and Bob questions \(x, y\) and the values are cvxpy Variables which
   are matrices with entries:

   \[
       K_{xy}\Big(i + a \cdot dim_R, j + b \cdot dim_R \Big) =
       \langle i| \text{Tr}_{\mathcal{H}} \Big( \big(
           I_R \otimes A_a^x B_b^y \big) \sigma \Big) |j \rangle
   \]

   :param assemblage: The commuting measurement assemblage operator.
   :param k: The level of the NPA hierarchy to use (default=1).
   :param referee_dim: The dimension of the referee's quantum system (default=1).
   :param no_signaling: bool

   :returns: A list of cvxpy constraints.


.. py:function:: bell_npa_constraints(p_var, desc, k = 1)

   Generate NPA hierarchy constraints for Bell inequalities [@Navascues_2008_AConvergent].

   The constraints are based on the positivity of a moment matrix constructed from measurement
   operators. This function generates constraints for a CVXPY variable representing probabilities
   or correlations in the Collins-Gisin notation. [@Collins_2004]

   The level of the hierarchy ``k`` can be an integer (standard NPA level) or a string specifying
   intermediate levels (e.g., "1+ab", "2+aab").

   The input ``p_var`` is a CVXPY variable representing the probabilities in the Collins-Gisin (CG)
   notation. It should have dimensions \(((oa-1) \times ma+1, (ob-1) \times mb+1)\),
   where \(oa, ob\) are the number of outputs and \(ma, mb\) are the number of inputs for Alice
   and Bob, respectively, as specified in ``desc`` = [\(oa\), \(ob\), \(ma\), \(mb\)].
   The entries of ``p_var`` correspond to:
   - ``p_var[0, 0]``: The overall probability (should be 1).
   - ``p_var[i, 0]`` (for \(i > 0\)): Marginal probabilities/correlations for Alice.
   - ``p_var[0, j]`` (for \(j > 0\)): Marginal probabilities/correlations for Bob.
   - ``p_var[i, j]`` (for \(i > 0, j > 0\)): Joint probabilities/correlations for Alice and Bob.

   The mapping from indices \((i, j)\) to specific operators depends on the ordering defined by ``desc``.
   Specifically, if \(i = (oa-1) \times x + a + 1\) and \(j = (ob-1) \times y + b + 1\)

   - ``p_var[i, 0]`` corresponds to the expectation of Alice's operator
                     \(A_{a|x}\) (using \(0\) to \(oa-2\) for \(a\)).
   - ``p_var[0, j]`` corresponds to the expectation of Bob's operator
                     \(B_{b|y}\) (using \(0\) to \(ob-2\) for \(b\)).
   - ``p_var[i, j]`` corresponds to the expectation of the product \(A_{a|x} B_{b|y}\).

   .. rubric:: Examples

   Consider the CHSH inequality scenario with ``desc = [2, 2, 2, 2]``. We want to generate the NPA level 1
   constraints.

   ```python exec="1" source="above" session="npa_example"
   import cvxpy
   import numpy as np
   from toqito.state_opt.npa_hierarchy import bell_npa_constraints
   desc = [2, 2, 2, 2]
   oa, ob, ma, mb = desc
   p_var_dim = ((oa - 1) * ma + 1, (ob - 1) * mb + 1)
   p_var = cvxpy.Variable(p_var_dim, name="p_cg")
   constraints = bell_npa_constraints(p_var, desc, k=1)
   print(len(constraints))
   print(constraints[0])
   ```

   We can also use intermediate levels, like "1+ab":

   ```python exec="1" source="above" session="npa_example"
   constraints_1ab = bell_npa_constraints(p_var, desc, k="1+ab")
   print(len(constraints_1ab))
   print(constraints_1ab[0])
   ```

   For the CGLMP inequality with ``dim=3``, ``desc = [3, 3, 2, 2]``, level 1:

   ```python exec="1" source="above"
   import cvxpy
   import numpy as np
   from toqito.state_opt.npa_hierarchy import bell_npa_constraints
   desc_cglmp = [3, 3, 2, 2]
   oa_c, ob_c, ma_c, mb_c = desc_cglmp
   p_var_dim_c = ((oa_c - 1) * ma_c + 1, (ob_c - 1) * mb_c + 1)
   p_var_c = cvxpy.Variable(p_var_dim_c, name="p_cglmp")
   constraints_c = bell_npa_constraints(p_var_c, desc_cglmp, k=1)
   print(len(constraints_c))
   print(constraints_c[0])
   ```

   :raises ValueError: If internal identity mapping fails.

   :param p_var: A CVXPY Variable representing probabilities/correlations in Collins-Gisin notation.
                 Shape: \(((oa-1) \times ma+1, (ob-1) \times mb+1)\).
   :param desc: A list [\(oa\), \(ob\), \(ma\), \(mb\)]
                specifying outputs and inputs for Alice and Bob.
   :param k: The level of the NPA hierarchy (integer or string like "1+ab"). Default is 1.

   :returns: A list of CVXPY constraints.