toqito.states.dicke
===================

.. py:module:: toqito.states.dicke

.. autoapi-nested-parse::

   Dicke states are an equal-weight superposition of all n-qubit states with Hamming Weight k.





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

.. py:function:: dicke(num_qubit, num_exfootcited, return_dm = False)

   Produce a Dicke state with specified excitations.

   The Dicke state is a quantum state with a fixed number of excitations (i.e., `num_exfootcited`)
   distributed across the given number of qubits (i.e., `num_qubit`). It is symmetric and represents
   an equal superposition of all possible states with the specified number of exfootcited qubits.

   Example
   Consider generating a Dicke state with 3 qubits and 1 excitation:

   ```python exec="1" source="above"
   from toqito.states import dicke
   print(dicke(3, 1))
   ```

   If we request the density matrix for this state, the return value is:

   ```python exec="1" source="above"
   from toqito.states import dicke
   print(dicke(3, 1, return_dm=True))
   ```


   :raises ValueError: If the number of excitations exceeds the number of qubits.

   :param num_qubit: The total number of qubits in the system.
   :param num_exfootcited: The number of qubits that are in the exfootcited state.
   :param return_dm: If True, returns the state as a density matrix (default is False).

   :returns: The Dicke state vector or density matrix as a NumPy array.