Circuit¶

The Circuit class is the core abstraction in QuantSDK. It represents a sequence of quantum gates applied to qubits and provides a fluent API for circuit construction.

Overview¶

import quantsdk as qs

# Create and build a circuit using the fluent API
circuit = (
    qs.Circuit(3, name="ghz")
    .h(0)
    .cx(0, 1)
    .cx(0, 2)
    .measure_all()
)

# Run and inspect
result = qs.run(circuit, shots=1000)
print(result.counts)

API Reference¶

Circuit ¶

Circuit(num_qubits: int, name: str = 'circuit')

A framework-agnostic quantum circuit.

Create quantum circuits using a clean, Pythonic API and run them on any backend — IBM Quantum, IonQ, simulators, and more.

PARAMETER	DESCRIPTION
`num_qubits`	Number of qubits in the circuit. TYPE: `int`
`name`	Optional name for the circuit. TYPE: `str` DEFAULT: `'circuit'`

Example::

import quantsdk as qs

circuit = qs.Circuit(2, name="bell_state")
circuit.h(0)
circuit.cx(0, 1)
circuit.measure_all()

Attributes¶

num_qubits `property` ¶

num_qubits: int

Number of qubits in the circuit.

name `property` ¶

name: str

Name of the circuit.

gates `property` ¶

gates: list[Gate]

List of gates in the circuit (read-only copy).

depth `property` ¶

depth: int

Circuit depth — the number of time steps needed to execute all gates.

Gates on different qubits can execute in parallel (same time step).

gate_count `property` ¶

gate_count: int

Total number of gates (excluding measurements and barriers).

num_measurements `property` ¶

num_measurements: int

Number of measurement operations in the circuit.

Functions¶

h ¶

h(qubit: int) -> Circuit

Apply Hadamard gate.

x ¶

x(qubit: int) -> Circuit

Apply Pauli-X (NOT) gate.

y ¶

y(qubit: int) -> Circuit

Apply Pauli-Y gate.

z ¶

z(qubit: int) -> Circuit

Apply Pauli-Z gate.

s ¶

s(qubit: int) -> Circuit

Apply S (√Z) gate.

t ¶

t(qubit: int) -> Circuit

Apply T (√S) gate.

i ¶

i(qubit: int) -> Circuit

Apply Identity gate.

sdg ¶

sdg(qubit: int) -> Circuit

Apply S-dagger gate.

tdg ¶

tdg(qubit: int) -> Circuit

Apply T-dagger gate.

sx ¶

sx(qubit: int) -> Circuit

Apply square root of X gate.

sxdg ¶

sxdg(qubit: int) -> Circuit

Apply square root of X dagger gate.

rx ¶

rx(qubit: int, theta: float) -> Circuit

Apply RX rotation gate (rotation around X-axis).

ry ¶

ry(qubit: int, theta: float) -> Circuit

Apply RY rotation gate (rotation around Y-axis).

rz ¶

rz(qubit: int, theta: float) -> Circuit

Apply RZ rotation gate (rotation around Z-axis).

u3 ¶

u3(
    qubit: int, theta: float, phi: float, lam: float
) -> Circuit

Apply general single-qubit rotation U3(theta, phi, lambda).

p ¶

p(qubit: int, lam: float) -> Circuit

Apply Phase gate P(lam).

u1 ¶

u1(qubit: int, lam: float) -> Circuit

Apply U1 gate (equivalent to Phase).

u2 ¶

u2(qubit: int, phi: float, lam: float) -> Circuit

Apply U2 gate.

r ¶

r(qubit: int, theta: float, phi: float) -> Circuit

Apply general rotation R(theta, phi) gate.

cx ¶

cx(control: int, target: int) -> Circuit

Apply Controlled-X (CNOT) gate.

cnot ¶

cnot(control: int, target: int) -> Circuit

Apply CNOT gate (alias for cx).

cz ¶

cz(control: int, target: int) -> Circuit

Apply Controlled-Z gate.

swap ¶

swap(qubit1: int, qubit2: int) -> Circuit

Apply SWAP gate.

rzz ¶

rzz(qubit1: int, qubit2: int, theta: float) -> Circuit

Apply RZZ gate (ZZ-rotation).

cy ¶

cy(control: int, target: int) -> Circuit

Apply Controlled-Y gate.

ch ¶

ch(control: int, target: int) -> Circuit

Apply Controlled-Hadamard gate.

cs ¶

cs(control: int, target: int) -> Circuit

Apply Controlled-S gate.

csdg ¶

csdg(control: int, target: int) -> Circuit

Apply Controlled-S-dagger gate.

crx ¶

crx(control: int, target: int, theta: float) -> Circuit

Apply Controlled-RX gate.

cry ¶

cry(control: int, target: int, theta: float) -> Circuit

Apply Controlled-RY gate.

crz ¶

crz(control: int, target: int, theta: float) -> Circuit

Apply Controlled-RZ gate.

cp ¶

cp(control: int, target: int, lam: float) -> Circuit

Apply Controlled-Phase gate.

cu1 ¶

cu1(control: int, target: int, lam: float) -> Circuit

Apply Controlled-U1 gate.

cu3 ¶

cu3(
    control: int,
    target: int,
    theta: float,
    phi: float,
    lam: float,
) -> Circuit

Apply Controlled-U3 gate.

csx ¶

csx(control: int, target: int) -> Circuit

Apply Controlled-SX gate.

rxx ¶

rxx(qubit1: int, qubit2: int, theta: float) -> Circuit

Apply RXX gate (XX-rotation).

ryy ¶

ryy(qubit1: int, qubit2: int, theta: float) -> Circuit

Apply RYY gate (YY-rotation).

rzx ¶

rzx(qubit1: int, qubit2: int, theta: float) -> Circuit

Apply RZX gate (ZX-rotation).

iswap ¶

iswap(qubit1: int, qubit2: int) -> Circuit

Apply iSWAP gate.

dcx ¶

dcx(qubit1: int, qubit2: int) -> Circuit

Apply Double-CX gate.

ecr ¶

ecr(qubit1: int, qubit2: int) -> Circuit

Apply Echoed Cross-Resonance gate.

ccx ¶

ccx(control1: int, control2: int, target: int) -> Circuit

Apply Toffoli (CCX) gate.

toffoli ¶

toffoli(
    control1: int, control2: int, target: int
) -> Circuit

Apply Toffoli gate (alias for ccx).

cswap ¶

cswap(control: int, target1: int, target2: int) -> Circuit

Apply Fredkin (CSWAP) gate.

fredkin ¶

fredkin(
    control: int, target1: int, target2: int
) -> Circuit

Apply Fredkin gate (alias for cswap).

ccz ¶

ccz(control1: int, control2: int, target: int) -> Circuit

Apply CCZ (double-controlled Z) gate.

measure ¶

measure(
    qubit: int, classical_bit: int | None = None
) -> Circuit

Measure a qubit in the computational basis.

PARAMETER	DESCRIPTION
`qubit`	Qubit index to measure. TYPE: `int`
`classical_bit`	Optional classical bit to store the result. Defaults to same index as qubit. TYPE: `int \| None` DEFAULT: `None`

measure_all ¶

measure_all() -> Circuit

Measure all qubits in the computational basis.

barrier ¶

barrier(qubits: Sequence[int] | None = None) -> Circuit

Add a barrier to prevent gate optimization across this point.

reset ¶

reset(qubit: int) -> Circuit

Reset a qubit to the |0> state.

copy ¶

copy() -> Circuit

Create a deep copy of this circuit.

to_qiskit ¶

to_qiskit() -> Any

Convert this circuit to a Qiskit QuantumCircuit.

Requires: pip install quantsdk[ibm]

RETURNS	DESCRIPTION
`Any`	A `qiskit.circuit.QuantumCircuit` equivalent.

Example::

circuit = qs.Circuit(2).h(0).cx(0, 1).measure_all()
qiskit_circuit = circuit.to_qiskit()

to_openqasm ¶

to_openqasm() -> str

Export this circuit as an OpenQASM 2.0 string.

RETURNS	DESCRIPTION
`str`	An OpenQASM 2.0 compliant string.

Example::

circuit = qs.Circuit(2).h(0).cx(0, 1).measure_all()
print(circuit.to_openqasm())

from_qiskit `classmethod` ¶

from_qiskit(qiskit_circuit: Any) -> Circuit

Create a QuantSDK Circuit from a Qiskit QuantumCircuit.

Requires: pip install quantsdk[ibm]

PARAMETER	DESCRIPTION
`qiskit_circuit`	A `qiskit.circuit.QuantumCircuit`. TYPE: `Any`

RETURNS	DESCRIPTION
`Circuit`	A QuantSDK Circuit equivalent.

from_openqasm `classmethod` ¶

from_openqasm(qasm_str: str) -> Circuit

Create a QuantSDK Circuit from an OpenQASM 2.0 string.

PARAMETER	DESCRIPTION
`qasm_str`	An OpenQASM 2.0 compliant string. TYPE: `str`

RETURNS	DESCRIPTION
`Circuit`	A QuantSDK Circuit.

count_ops ¶

count_ops() -> dict[str, int]

Count the number of each gate type in the circuit.

RETURNS	DESCRIPTION
`dict[str, int]`	Dictionary mapping gate name to count.

draw ¶

draw() -> str

Draw the circuit as ASCII art.

RETURNS	DESCRIPTION
`str`	String representation of the circuit.

Example::

>>> circuit = qs.Circuit(2)
>>> circuit.h(0).cx(0, 1).measure_all()
>>> print(circuit.draw())
q0: ──H──●──M──
q1: ─────X──M──

Circuit¶

Overview¶

API Reference¶

Circuit ¶

Attributes¶

num_qubits property ¶

name property ¶

gates property ¶

depth property ¶

gate_count property ¶

num_measurements property ¶

Functions¶

h ¶

x ¶

y ¶

z ¶

s ¶

t ¶

i ¶

sdg ¶

tdg ¶

sx ¶

sxdg ¶

rx ¶

ry ¶

rz ¶

u3 ¶

p ¶

u1 ¶

u2 ¶

r ¶

cx ¶

cnot ¶

cz ¶

swap ¶

rzz ¶

cy ¶

ch ¶

cs ¶

csdg ¶

crx ¶

cry ¶

crz ¶

cp ¶

cu1 ¶

cu3 ¶

csx ¶

rxx ¶

ryy ¶

rzx ¶

iswap ¶

dcx ¶

ecr ¶

ccx ¶

toffoli ¶

cswap ¶

fredkin ¶

ccz ¶

measure ¶

measure_all ¶

barrier ¶

reset ¶

copy ¶

to_qiskit ¶

to_openqasm ¶

from_qiskit classmethod ¶

from_openqasm classmethod ¶

count_ops ¶

draw ¶

num_qubits `property` ¶

name `property` ¶

gates `property` ¶

depth `property` ¶

gate_count `property` ¶

num_measurements `property` ¶

from_qiskit `classmethod` ¶

from_openqasm `classmethod` ¶