:py:mod:`states.singlet`
========================

.. py:module:: states.singlet

.. autoapi-nested-parse::

   Generalized singlet state.



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


Functions
~~~~~~~~~

.. autoapisummary::

   states.singlet.singlet



.. py:function:: singlet(dim)

   Produce a generalized singlet state acting on two n-dimensional systems :cite:`Cabello_2002_NParticle`.

   .. rubric:: Examples

   For :math:`n = 2` this generates the following matrix

   .. math::
       S = \frac{1}{2} \begin{pmatrix}
                       0 & 0 & 0 & 0 \\
                       0 & 1 & -1 & 0 \\
                       0 & -1 & 1 & 0 \\
                       0 & 0 & 0 & 0
                   \end{pmatrix}

   which is equivalent to :math:`|\phi_s \rangle \langle \phi_s |` where

   .. math::
       |\phi_s\rangle = \frac{1}{\sqrt{2}} \left( |01 \rangle - |10 \rangle \right)

   is the singlet state. This can be computed via :code:`toqito` as follows:

   >>> from toqito.states import singlet
   >>> dim = 2
   >>> singlet(dim)
   array([[ 0. ,  0. ,  0. ,  0. ],
          [ 0. ,  0.5, -0.5,  0. ],
          [ 0. , -0.5,  0.5,  0. ],
          [ 0. ,  0. ,  0. ,  0. ]])

   It is possible for us to consider higher dimensional singlet states. For instance, we can consider the
   :math:`3`-dimensional Singlet state as follows:

   >>> from toqito.states import singlet
   >>> dim = 3
   >>> singlet(dim)
   array([[ 0.        ,  0.        ,  0.        ,  0.        ,  0.        ,
            0.        ,  0.        ,  0.        ,  0.        ],
          [ 0.        ,  0.16666667,  0.        , -0.16666667,  0.        ,
            0.        ,  0.        ,  0.        ,  0.        ],
          [ 0.        ,  0.        ,  0.16666667,  0.        ,  0.        ,
            0.        , -0.16666667,  0.        ,  0.        ],
          [ 0.        , -0.16666667,  0.        ,  0.16666667,  0.        ,
            0.        ,  0.        ,  0.        ,  0.        ],
          [ 0.        ,  0.        ,  0.        ,  0.        ,  0.        ,
            0.        ,  0.        ,  0.        ,  0.        ],
          [ 0.        ,  0.        ,  0.        ,  0.        ,  0.        ,
            0.16666667,  0.        , -0.16666667,  0.        ],
          [ 0.        ,  0.        , -0.16666667,  0.        ,  0.        ,
            0.        ,  0.16666667,  0.        ,  0.        ],
          [ 0.        ,  0.        ,  0.        ,  0.        ,  0.        ,
           -0.16666667,  0.        ,  0.16666667,  0.        ],
          [ 0.        ,  0.        ,  0.        ,  0.        ,  0.        ,
            0.        ,  0.        ,  0.        ,  0.        ]])

   .. rubric:: References

   .. bibliography::
       :filter: docname in docnames

   :param dim: The dimension of the generalized singlet state.
   :return: The singlet state of dimension `dim`.