uniqc.algorithmics.circuits.grover_oracle module#

Grover oracle and diffusion operator construction.

Provides reusable building blocks for Grover’s quantum search algorithm:

Both functions operate on a Circuit object passed in by the caller, following the standard circuit-building convention of uniqc.algorithmics.circuits.

References

Grover, L. K. (1996). “A fast quantum mechanical algorithm for database search.” STOC ‘96. https://arxiv.org/abs/quant-ph/9605043

uniqc.algorithmics.circuits.grover_oracle.grover_diffusion(circuit, qubits=None, ancilla=None)[source]#

Construct the Grover diffusion (amplitude amplification) operator.

The diffusion operator is:

\[D = 2|s\rangle\langle s| - I\]

where \(|s\rangle = H^{\otimes n}|0\rangle^{\otimes n}\) is the uniform superposition. It is equivalent to:

\[D = H^{\otimes n} \cdot \bigl(2|0\rangle\langle 0| - I\bigr) \cdot H^{\otimes n}\]

The 2|0⟩⟨0| - I part is implemented as X gates followed by a multi-controlled Z and X gates again.

Parameters:

  • circuit (Circuit) – Quantum circuit to operate on (mutated in-place).

  • qubits (List[int] | None) – Data qubit indices. None means [0, 1] (2 qubits).

  • ancilla (int | None) – Deprecated and unused. The current implementation derives the MCZ target directly from qubits[-1], so this argument has no effect regardless of its value. It is retained for API compatibility only and will be removed in a future release.

Raises:

ValueError – Fewer than 1 qubit specified.

Return type:

None

uniqc.algorithmics.circuits.grover_oracle.grover_oracle(circuit, marked_state, qubits=None, ancilla=None)[source]#

Construct a phase-flip oracle for a marked basis state.

The oracle flips the phase of the computational basis state whose integer encoding is marked_state, leaving all other states unchanged:

\[U_f |x\rangle = (-1)^{[x = \text{marked}]} |x\rangle\]

The implementation uses an ancilla qubit prepared in \(|-\rangle\) and a multi-controlled Z gate. X gates are applied before and after the MCZ to match the bit pattern of marked_state.

Parameters:

  • circuit (Circuit) – Quantum circuit to operate on (mutated in-place).

  • marked_state (int) – Non-negative integer encoding the marked basis state.

  • qubits (List[int] | None) – Data qubit indices. None means list(range(n_bits)) where n_bits is the number of bits needed to represent marked_state (at least 1).

  • ancilla (int | None) – Ancilla qubit index for the MCZ target. None means max(qubits) + 1 (auto-allocated).

Returns:

The ancilla qubit index that was used.

Raises:

ValueError – marked_state is negative or exceeds the addressable space of qubits.

Return type:

int

Example

>>> from uniqc.circuit_builder import Circuit
>>> from uniqc.algorithmics.circuits import grover_oracle
>>> c = Circuit()
>>> for i in range(3):
...     c.h(i)          # uniform superposition
>>> anc = grover_oracle(c, marked_state=5, qubits=[0, 1, 2])