toqito.perms.symmetric_projection
=================================

.. py:module:: toqito.perms.symmetric_projection

.. autoapi-nested-parse::

   Symmetric projection operator produces a projection onto a symmetric subspace.





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

.. py:function:: symmetric_projection(dim, p_val = 2, partial = False)

   Produce the projection onto the symmetric subspace [@Chen_2014_Symmetric].

   For a complex Euclidean space \(\mathcal{X}\) and a positive integer \(n\), the projection onto the
   symmetric subspace is given by

   \[
       \frac{1}{n!} \sum_{\pi \in S_n} W_{\pi}
   \]

   where \(W_{\pi}\) is the swap operator and where \(S_n\) is the symmetric group on \(n\) symbols.

   Produces the orthogonal projection onto the symmetric subspace of `p_val` copies of `dim`-dimensional space.
   If `partial = True`, then the symmetric projection (PS) isn't the orthogonal projection itself, but rather a matrix
   whose columns form an orthonormal basis for the symmetric subspace (and hence the PS * PS' is the orthogonal
   projection onto the symmetric subspace).

   This function was adapted from the QETLAB package.

   .. rubric:: Examples

   The \(2\)-dimensional symmetric projection with \(p=1\) is given as \(2\)-by-\(2\) identity matrix

   \[
       \begin{pmatrix}
           1 & 0 \\
           0 & 1
       \end{pmatrix}.
   \]

   Using `|toqito⟩`, we can see this gives the proper result.

   ```python exec="1" source="above"
   from toqito.perms import symmetric_projection

   print(symmetric_projection(2, 1))
   ```


   When \(d = 2\) and \(p = 2\) we have that

   \[
       \begin{pmatrix}
           1 & 0 & 0 & 0 \\
           0 & 1/2 & 1/2 & 0 \\
           0 & 1/2 & 1/2 & 0 \\
           0 & 0 & 0 & 1
       \end{pmatrix}.
   \]

   Using `|toqito⟩` we can see this gives the proper result.

   ```python exec="1" source="above"
   from toqito.perms import symmetric_projection

   print(symmetric_projection(dim=2))
   ```

   :param dim: The dimension of the local systems.
   :param p_val: Default value of 2.
   :param partial: Default value of 0.

   :returns: Projection onto the symmetric subspace.