cirq.subwavefunction(wavefunction: numpy.ndarray, keep_indices: List[int], *, default: TDefault = array([], dtype=float64), atol: Union[int, float] = 1e-08) → numpy.ndarray[source]

Attempts to factor a wavefunction into two parts and return one of them.

The input wavefunction must have shape (2,) * n or (2 ** n)
where wavefunction is expressed over n qubits. The returned array
will retain the same type of shape as the input wavefunction, either
(2 ** k) or (2,) * k where k is the number of qubits kept.
If a wavefunction $|\psi\rangle$ defined on n qubits is an outer
product of kets like $|\psi\rangle$ = $|x\rangle \otimes
|y\rangle$, and $|x\rangle$ is defined over the subset
keep_indices of k qubits, then this method will factor
$|\psi\rangle$ into $|x\rangle$ and $|y\rangle$ and return
$|x\rangle$. Note that $|x\rangle$ is not unique, because scalar
multiplication may be absorbed by any factor of a tensor product:
$$ e^{i \theta} |y \rangle \otimes |x \rangle = |y \rangle \otimes e^{i \theta} |x \rangle $$
This method randomizes the global phase of $|x\rangle$ in order to
avoid accidental reliance on the global phase being some specific value.
If the provided wavefunction cannot be factored into a pure state over
keep_indices, the method will fall back to return default. If
default is not provided, the method will fail and raise
  • wavefunction – A wavefunction to express over a qubit subset.

  • keep_indices – Which indices to express the wavefunction on.

  • default – Determines the fallback behavior when wavefunction doesn’t have a pure state factorization. If the factored state is not pure and default is not set, a ValueError is raised. If default is set to a value, that value is returned.

  • atol – The minimum tolerance for comparing the output state’s coherence measure to 1.


The wavefunction expressed over the desired subset of qubits.

  • ValueError – if the wavefunction is not of the correct shape or the

  • indices are not a valid subset of the input wavefunction's indices, or

  • the result of factoring is not a pure state.