uniqc.algorithms.core.circuits.deutsch_jozsa module¶

Deutsch-Jozsa algorithm circuit and oracle builder.

The oracular convention here (per the design notes in the project README) is:

deutsch_jozsa_oracle() returns a fresh Circuit (the oracle).
deutsch_jozsa_circuit() accepts a quantum-circuit oracle as its argument and returns a fresh full-DJ Circuit (fragment style).

A legacy in-place form deutsch_jozsa_circuit(circuit, oracle, qubits) is preserved as a deprecated dispatch and emits DeprecationWarning.

uniqc.algorithms.core.circuits.deutsch_jozsa.deutsch_jozsa_circuit(*args, qubits=None, ancilla=None, oracle=None)[source]¶

Build (or apply) the Deutsch-Jozsa algorithm circuit.

Two calling conventions are supported:

# Fragment style (recommended):
ora = deutsch_jozsa_oracle(qubits=[0, 1, 2], balanced=True)
circuit = deutsch_jozsa_circuit(ora, qubits=[0, 1, 2])      # returns Circuit

# Legacy in-place style (deprecated):
c = Circuit()
deutsch_jozsa_circuit(c, ora, qubits=[0, 1, 2], ancilla=3)  # mutates c

Parameters:

*args – Either (oracle: Circuit, ...) (fragment) or (circuit: Circuit, oracle: Circuit, ...) (deprecated in-place).
qubits (list[int] | None) – Data-qubit indices.
ancilla (int | None) – Ancilla qubit index. None means max(qubits) + 1.
oracle (Circuit | None) – The oracle Circuit (positional or keyword).

Returns:

A fresh Circuit in fragment mode; None in legacy mode.

uniqc.algorithms.core.circuits.deutsch_jozsa.deutsch_jozsa_example()[source]¶

Return a 3-qubit balanced-DJ algorithm circuit for tests/docs.

Return type:: Circuit

uniqc.algorithms.core.circuits.deutsch_jozsa.deutsch_jozsa_oracle(qubits, balanced=True, target_bits=None)[source]¶

Build a Deutsch-Jozsa oracle circuit.

See module docstring; behaviour is unchanged from previous releases — this is already a fragment-style API (returns a fresh Circuit).

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.

Return type:

Circuit