uniqc.circuit_builder.qcircuit module

Quantum circuit builder with OriginIR and OpenQASM 2.0 output.

This module provides a Circuit class for building quantum circuits programmatically. It supports various quantum gates, controlled operations, dagger (adjoint) blocks, and measurement operations. The circuit can be exported to OriginIR or OpenQASM format.

Key exports:

Circuit: Main quantum circuit builder class. OpcodeType: Type alias for opcode tuples.

class uniqc.circuit_builder.qcircuit.Circuit(qregs=None)

Bases: object

Quantum circuit builder that generates OriginIR and OpenQASM output.

Variables:

• used_qubit_list (list[int]) – Qubits referenced in the circuit.

• circuit_str (str) – Raw string builder used by context managers.

• max_qubit (int) – Highest qubit index used.

• qubit_num (int) – Total number of qubits.

• cbit_num (int) – Total number of classical bits.

• measure_list (list[int]) – Qubits scheduled for measurement.

• opcode_list (list[OpCode]) – Internal list of gate opcodes.

• _qregs (dict[str, QReg]) – Named quantum registers (if created with qregs parameter).

Parameters:

qregs (Optional[dict[str, int] | list['QReg'] | int])

add_circuit(other)

Add all gates from another circuit into this circuit.

Parameters:

other (Circuit)

Return type:

None

add_gate(operation, qubits, cbits=None, params=None, dagger=False, control_qubits=None)

Add a gate to the circuit.

Parameters:

• operation (str) – Gate name (e.g., “H”, “CNOT”, “RX”)

• qubits (QubitInput) – Target qubit(s) - can be int, Qubit, QRegSlice, or list

• cbits (CbitSpec) – Classical bit(s) for measurement

• params (ParamSpec) – Gate parameters

• dagger (bool) – Whether to apply dagger (adjoint)

• control_qubits (QubitInput) – Control qubit(s)

Return type:

None

barrier(*qubits)

Insert a barrier across the specified qubits.

Parameters:

*qubits (QubitInput) – Qubits to include in the barrier.

Return type:

None

cbit_num: int

property circuit: str

Generate the circuit in OriginIR format.

circuit_str: str

cnot(controller, target)

Apply CNOT (controlled-X) gate.

Parameters:

• controller (QubitInput) – Control qubit - can be int, Qubit, or QRegSlice

• target (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

Return type:

None

control(*args)

Return a context manager that wraps gates in a CONTROL block.

All gates added inside the with block will be executed only when all specified control qubits are in state |1>.

Parameters:

*args (QubitInput) – One or more control qubits - can be int, Qubit, or QRegSlice

Returns:

A CircuitControlContext context manager.

Raises:

ValueError – No control qubits were supplied.

Return type:

CircuitControlContext

copy()

Return a deep copy of this circuit.

Return type:

Circuit

cswap(q1, q2, q3)

Apply CSWAP (Fredkin) gate to three qubits.

Parameters:

• q1 (QubitInput) – Control qubit - can be int, Qubit, or QRegSlice

• q2 (QubitInput) – First target qubit

• q3 (QubitInput) – Second target qubit

Return type:

None

cx(controller, target)

Apply CX gate (alias for CNOT).

Parameters:

• controller (QubitInput) – Control qubit - can be int, Qubit, or QRegSlice

• target (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

Return type:

None

cz(q1, q2)

Apply controlled-Z gate to two qubits.

Parameters:

• q1 (QubitInput) – First qubit - can be int, Qubit, or QRegSlice

• q2 (QubitInput) – Second qubit - can be int, Qubit, or QRegSlice

Return type:

None

dagger()

Return a context manager that wraps gates in a DAGGER block.

All gates added inside the with block will be conjugate-transposed (adjoint).

Returns:

A CircuitDagContext context manager.

Return type:

CircuitDagContext

property depth: int

Calculate the depth of the quantum circuit.

get_qreg(name)

Get a named quantum register by name.

Parameters:

name (str) – Register name

Returns:

QReg object

Raises:

KeyError – If register name not found

Return type:

QReg

h(qn)

Apply single-qubit Hadamard gate to qubit.

Parameters:

qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

Return type:

None

identity(qn)

Apply the identity (no-op) gate to qubit.

Parameters:

qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

Return type:

None

iswap(q1, q2)

Apply iSWAP gate to two qubits.

Parameters:

• q1 (QubitInput) – First qubit - can be int, Qubit, or QRegSlice

• q2 (QubitInput) – Second qubit - can be int, Qubit, or QRegSlice

Return type:

None

max_qubit: int

measure(*qubits)

Schedule qubits for measurement.

Appends the given qubits to the measurement list. Multiple calls accumulate measurements; classical bit indices are assigned in the order qubits are added.

Parameters:

*qubits (QubitInput) – One or more qubits to measure - can be int, Qubit, or QRegSlice

Raises:

ValueError – Called inside an active CONTROL or DAGGER context block.

Return type:

None

measure_list: list[int]

opcode_list: list[OpCode]

property originir: str

Generate the circuit in OriginIR format.

phase2q(q1, q2, theta1, theta2, thetazz)

Apply two-qubit phase gate with local and ZZ terms.

Parameters:

• q1 (QubitInput) – First qubit - can be int, Qubit, or QRegSlice

• q2 (QubitInput) – Second qubit - can be int, Qubit, or QRegSlice

• theta1 (float) – Local phase angle for q1 in radians.

• theta2 (float) – Local phase angle for q2 in radians.

• thetazz (float) – ZZ interaction angle in radians.

Return type:

None

property qasm: str

Generate the circuit in OpenQASM format.

property qregs: dict[str, 'QReg']

Return the named quantum registers.

qubit_num: int

record_qubit(qubits)

Record the qubits used in the circuit.

Parameters:

qubits (int | list[int])

Return type:

None

remapping(mapping)

Create a new circuit with qubits remapped according to mapping.

Parameters:

mapping (dict[int, int])

Return type:

Circuit

rphi(qn, theta, phi)

Apply RPhi rotation gate.

Parameters:

• qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

• theta (float) – Polar rotation angle in radians.

• phi (float) – Azimuthal angle in radians.

Return type:

None

rx(qn, theta)

Apply RX rotation gate.

Parameters:

• qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

• theta (float) – Rotation angle in radians.

Return type:

None

ry(qn, theta)

Apply RY rotation gate.

Parameters:

• qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

• theta (float) – Rotation angle in radians.

Return type:

None

rz(qn, theta)

Apply RZ rotation gate.

Parameters:

• qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

• theta (float) – Rotation angle in radians.

Return type:

None

s(qn)

Apply S (phase) gate to qubit.

Parameters:

qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

Return type:

None

sdg(qn)

Apply S-dagger (inverse phase) gate to qubit.

Parameters:

qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

Return type:

None

set_control(*args)

Manually open a CONTROL block (low-level API; prefer control()).

Parameters:

*args (QubitInput) – Control qubits - can be int, Qubit, or QRegSlice

Return type:

None

set_dagger()

Manually open a DAGGER block (low-level API; prefer dagger()).

Return type:

None

swap(q1, q2)

Apply SWAP gate to two qubits.

Parameters:

• q1 (QubitInput) – First qubit - can be int, Qubit, or QRegSlice

• q2 (QubitInput) – Second qubit - can be int, Qubit, or QRegSlice

Return type:

None

sx(qn)

Apply square-root-of-X (SX) gate to qubit.

Parameters:

qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

Return type:

None

sxdg(qn)

Apply conjugate-transpose of SX gate to qubit.

Parameters:

qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

Return type:

None

t(qn)

Apply T gate to qubit.

Parameters:

qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

Return type:

None

tdg(qn)

Apply T-dagger (inverse T) gate to qubit.

Parameters:

qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

Return type:

None

toffoli(q1, q2, q3)

Apply Toffoli (CCNOT) gate to three qubits.

Parameters:

• q1 (QubitInput) – First control qubit

• q2 (QubitInput) – Second control qubit

• q3 (QubitInput) – Target qubit

Return type:

None

u1(qn, lam)

Apply U1 single-parameter unitary gate.

Parameters:

• qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

• lam (float) – Phase angle lambda in radians.

Return type:

None

u2(qn, phi, lam)

Apply U2 two-parameter unitary gate.

Parameters:

• qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

• phi (float) – Phi angle in radians.

• lam (float) – Lambda angle in radians.

Return type:

None

u3(qn, theta, phi, lam)

Apply U3 three-parameter unitary gate.

Parameters:

• qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

• theta (float) – Theta angle in radians.

• phi (float) – Phi angle in radians.

• lam (float) – Lambda angle in radians.

Return type:

None

unset_control()

Manually close a CONTROL block (low-level API; prefer control()).

Return type:

None

unset_dagger()

Manually close a DAGGER block (low-level API; prefer dagger()).

Return type:

None

used_qubit_list: list[int]

uu15(q1, q2, params)

Apply general two-qubit UU15 gate with 15 parameters.

Parameters:

• q1 (QubitInput) – First qubit - can be int, Qubit, or QRegSlice

• q2 (QubitInput) – Second qubit - can be int, Qubit, or QRegSlice

• params (list[float]) – List of 15 rotation parameters in radians.

Return type:

None

x(qn)

Apply Pauli-X (NOT) gate to qubit.

Parameters:

qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

Return type:

None

xx(q1, q2, theta)

Apply XX Ising interaction gate.

Parameters:

• q1 (QubitInput) – First qubit - can be int, Qubit, or QRegSlice

• q2 (QubitInput) – Second qubit - can be int, Qubit, or QRegSlice

• theta (float) – Interaction angle in radians.

Return type:

None

y(qn)

Apply Pauli-Y gate to qubit.

Parameters:

qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

Return type:

None

yy(q1, q2, theta)

Apply YY Ising interaction gate.

Parameters:

• q1 (QubitInput) – First qubit - can be int, Qubit, or QRegSlice

• q2 (QubitInput) – Second qubit - can be int, Qubit, or QRegSlice

• theta (float) – Interaction angle in radians.

Return type:

None

z(qn)

Apply Pauli-Z gate to qubit.

Parameters:

qn (QubitInput) – Target qubit - can be int, Qubit, or QRegSlice

Return type:

None

zz(q1, q2, theta)

Apply ZZ Ising interaction gate.

Parameters:

• q1 (QubitInput) – First qubit - can be int, Qubit, or QRegSlice

• q2 (QubitInput) – Second qubit - can be int, Qubit, or QRegSlice

• theta (float) – Interaction angle in radians.

Return type:

None

class uniqc.circuit_builder.qcircuit.CircuitControlContext(c, control_list)

Bases: object

Context manager for controlled gate blocks.

Parameters:

• c (Circuit)

• control_list (tuple[int, ...])

c: Circuit

control_list: tuple[int, ...]

class uniqc.circuit_builder.qcircuit.CircuitDagContext(c)

Bases: object

Context manager for dagger (adjoint) gate blocks.

Parameters:

c (Circuit)

c: Circuit