uniqc.algorithmics.circuits.deutsch_jozsa module#

Deutsch-Jozsa algorithm circuit and oracle builder.

uniqc.algorithmics.circuits.deutsch_jozsa.deutsch_jozsa_circuit(circuit, oracle, qubits, ancilla=None)[source]#

Apply the Deutsch-Jozsa algorithm to the circuit.

The Deutsch-Jozsa algorithm determines whether a function \(f: \{0,1\}^n \to \{0,1\}\) is constant or balanced using a single quantum query.

Circuit steps:

  1. Initialise data qubits to \(|+\rangle\) and ancilla to \(|-\rangle\) (via X then H).

  2. Apply the oracle.

  3. Apply Hadamard on all data qubits.

  4. Measure data qubits: all-zeros → constant, otherwise → balanced.

Parameters:

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

  • oracle (Circuit) – Oracle sub-circuit to embed. Must operate on len(qubits) + 1 qubits (data + ancilla), or be empty (constant-zero oracle).

  • qubits (List[int]) – Data-qubit indices (explicit list, no default).

  • ancilla (int | None) – Ancilla qubit index. None means max(qubits) + 1.

Raises:

  • TypeError – qubits is not a list.

  • ValueError – qubits is empty, or oracle qubit count mismatches.

Return type:

None

Example

>>> from uniqc.circuit_builder import Circuit
>>> from uniqc.algorithmics.circuits import (
...     deutsch_jozsa_circuit, deutsch_jozsa_oracle,
... )
>>> n = 3
>>> oracle = deutsch_jozsa_oracle(qubits=list(range(n)), balanced=True)
>>> c = Circuit()
>>> deutsch_jozsa_circuit(c, oracle, qubits=list(range(n)), ancilla=n)
uniqc.algorithmics.circuits.deutsch_jozsa.deutsch_jozsa_oracle(qubits, balanced=True, target_bits=None)[source]#

Build a Deutsch-Jozsa oracle circuit.

Generates either a constant oracle (maps all inputs to 0 or all to 1) or a balanced oracle (maps half the inputs to 0 and half to 1).

  • Constant oracle: does nothing (output = 0) or flips the ancilla (output = 1). Here we implement the identity (output always 0).

  • Balanced oracle: applies CNOT from each target_bit to the ancilla. If target_bits is None, all data qubits are used. This yields a balanced function because the ancilla flips exactly when an odd number of target bits are set.

The oracle acts on the data qubits in qubits plus one ancilla qubit at max(qubits) + 1.

Parameters:

  • qubits (List[int]) – Data-qubit indices (explicit list, no default).

  • balanced (bool) – If True, build a balanced oracle; otherwise constant.

  • target_bits (List[int] | None) – Data-qubit indices (positions within qubits) that control the ancilla flip. Only used when balanced is True. None means all data qubits.

Returns:

A new Circuit containing the oracle gates.

Raises:

  • TypeError – qubits is not a list.

  • ValueError – qubits is empty, or target_bits contains invalid indices.

Return type:

Circuit

Example

>>> oracle = deutsch_jozsa_oracle(qubits=[0, 1, 2], balanced=True)
>>> oracle.qubit_num  # 3 data + 1 ancilla
4