toqito.states.w_state
=====================

.. py:module:: toqito.states.w_state

.. autoapi-nested-parse::

   Generalized w-state is an entangled quantum state of `n` qubits.

   This state refers to the quantum superposition in which one of the qubits is in an excited state and others are in
   the ground state.





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

.. py:function:: w_state(num_qubits, coeff = None)

   Produce a W-state [@Dur_2000_ThreeQubits].

   Returns the W-state described in [@Dur_2000_ThreeQubits]. The W-state on `num_qubits` qubits is defined by:

   \[
       |W \rangle = \frac{1}{\sqrt{num\_qubits}}
       \left(|100 \ldots 0 \rangle + |010 \ldots 0 \rangle + \ldots +
       |000 \ldots 1 \rangle \right).
   \]

   .. rubric:: Examples

   Using `|toqito⟩`, we can generate the \(3\)-qubit W-state

   \[
       |W_3 \rangle = \frac{1}{\sqrt{3}} \left( |100\rangle + |010 \rangle +
       |001 \rangle \right)
   \]

   as follows.

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

   We may also generate a generalized \(W\)-state. For instance, here is a \(4\)-dimensional \(W\)-state

   \[
       \frac{1}{\sqrt{30}} \left( |1000 \rangle + 2|0100 \rangle + 3|0010
       \rangle + 4 |0001 \rangle \right).
   \]

   We can generate this state in `|toqito⟩` as

   ```python exec="1" source="above"
   from toqito.states import w_state
   import numpy as np
   coeffs = np.array([1, 2, 3, 4]) / np.sqrt(30)
   print(w_state(4, coeffs))
   ```

   :raises ValueError: The number of qubits must be greater than or equal to 1.

   :param num_qubits: An integer representing the number of qubits.
   :param coeff: default is `[1, 1, ..., 1]/sqrt(num_qubits)`: a 1-by-`num_qubts` vector of coefficients.