toqito.matrix_ops.tensor_unravel
================================

.. py:module:: toqito.matrix_ops.tensor_unravel

.. autoapi-nested-parse::

   Generate the 1D contraint.





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

.. py:function:: tensor_unravel(constraint_tensor)

   Decode a clause tensor (indicator tensor) into its raw 1D representation.

   In binary constraint system (BCS) games, parity constraints can be encoded as
   **clause tensors** — n-dimensional NumPy arrays of shape `(2, 2, ..., 2)`,
   filled with a constant background value (e.g., `(-1)**b[i]`) except for a
   single unique entry that marks the satisfying assignment.

   This function unravels such a tensor by:

      1. Locating the unique element (the one appearing exactly once).
      2. Extracting its multi-dimensional index `(i1, i2, ..., in)`.
      3. Returning a 1D NumPy array `[i1, i2, ..., in, value]`, where the first `n`
         entries are the coordinates and the last entry is the unique value (±1).

   Conceptually, this is a form of structured tensor decoding, closely related to:

   - Indicator (Kronecker delta) tensors in multilinear algebra refer to [@Kolda_2009_Tensor].
   - The matrix ``vec``-operator for flattening matrices refer to [@Horn_1985_Matrix].
   - Parity-projector encodings in linear-system games refer to [@Cleve_2016_Perfect].

   The tensor-form constraint representation is commonly used in implementations of
   binary constraint system (BCS) games. For background on BCS games, refer to [@Cleve_2014_Characterization].

   .. rubric:: Examples

   ```python exec="1" source="above"
   import numpy as np
   from toqito.matrix_ops import tensor_unravel

   tensor_constraint = np.array([[-1, -1], [-1, 1]])
   print(tensor_unravel(tensor_constraint))
   ```

   :param constraint_tensor: An n-dimensional tensor with shape `(2,)*n`, where each element is either -1 or +1.
   :param All entries should be equal except for one unique position that marks the satisfying assignment.:

   :returns: A 1D `numpy` array of length \(n+1\) where the first \(n\) elements are the coordinates (indices), and the last
             element is the unique constant (rhs).