Unbalanced W State Preparation#

unbalanced_w_state(qv: QuantumVariable | Sequence[Qubit], amplitudes: ndarray | Array | Tracer) → None[source]#

Prepare a generalized W state, i.e. an unbalanced Dicke state of Hamming weight 1, on the given QuantumVariable.

The resulting quantum state is

\[|\psi\rangle \;=\; \sum_{i=0}^{n-1} a_i \,|e_i\rangle\]

where \(|e_i\rangle\) is the computational basis state with a single 1 at position \(i\), and \(a_i\) are the (possibly complex) amplitudes given by amplitudes. The input array is automatically normalized so that \(\sum_i |a_i|^2 = 1\).

Parameters:

qvQuantumVariable: A freshly allocated QuantumVariable in the \(|0\dots0\rangle\) state whose size matches len(amplitudes).
amplitudesNDArrayLike: A 1-D sequence of complex (or real) target amplitudes, one per qubit. Its length must be equal qv.size.

Raises:

ValueError: If len(amplitudes) != qv.size or if the amplitude vector is zero.

Notes

Algorithm. The circuit distributes a single excitation across all qubits using a linear chain of XXYY gates:

Precompute all required \(\theta_i\) angles using \(r_i = \sqrt{ \sum_{ j = i }^{ n - 1 }{ |a_j| ^ 2 } }\) and \(\theta_i = 2\arccos(|a_i|\,/\,r_i)\), where \(r_i\) is the precomputed remaining (undistributed) amplitude magnitude.
Apply X to qubit 0, producing \(|10\dots0\rangle\).
For each qubit \(i = 0, \dots, n{-}2\):
1. Apply XXYY(θ, π/2) on qubits \((i,\, i{+}1)\), using the precomputed angles \(\theta = \theta_i\). In the single-excitation subspace this acts as a parametrized partial swap, leaving magnitude \(|a_i|\) on qubit \(i\) and passing the rest to qubit \(i{+}1\).
2. Apply a phase gate \(P(\arg a_i)\) on qubit \(i\) to imprint the correct complex phase.
Apply \(P(\arg a_{n-1})\) on the last qubit.

Resources. The circuit uses \(n{-}1\) XXYY gates (each decomposable into 2 CNOTs + single-qubit rotations) and \(n\) phase gates, yielding \(\mathcal{O}(n)\) depth and gate count.

Examples

>>> import numpy as np
>>> from qrisp import QuantumVariable, unbalanced_w_state
>>> a = np.array([1j, 2, 3, 4])
>>> qv = QuantumVariable(4)
>>> unbalanced_w_state(qv, a)
>>> print(qv.qs.statevector())