API Reference

Core Modules

QuantumCircuit

class quantum_debugger.QuantumCircuit(num_qubits: int, num_classical: int = 0, noise_model: Any | None = None, noise_simulation_method: str = 'density_matrix', backend: str = 'auto')

Bases: object

Quantum circuit with gate operations

ccx(control1: int, control2: int, target: int)

Alias for Toffoli

cnot(control: int, target: int)

Apply CNOT (controlled-NOT) gate

count_gates(gate_name: str = None) → int

Count gates of specific type

Parameters:

gate_name – Name of gate to count (None for all gates)

cp(theta: float, control: int, target: int)

Apply controlled-phase gate

cx(control: int, target: int)

Alias for CNOT

cz(control: int, target: int)

Apply CZ (controlled-Z) gate

depth() → int

Calculate circuit depth (number of gate layers)

draw(output: str = 'text') → str

Draw the circuit

Parameters:

output – Output format (‘text’ for ASCII art)

Returns:

String representation of circuit

get_statevector(initial_state: QuantumState | None = None, use_gpu: bool = False, precision: str = 'double') → QuantumState

Get final state vector without measurements.

Parameters:

• initial_state – Optional initial state

• use_gpu – Run the whole circuit on the GPU (CuPy). The state lives on the GPU for every gate and is transferred back to the CPU once at the end. Falls back to CPU if CuPy is unavailable.

• precision – ‘double’ (complex128, default, exact) or ‘single’ (complex64 – much faster on consumer GPUs, at reduced precision).

Returns:

Final quantum state (always CPU/NumPy-backed)

h(qubit: int)

Apply Hadamard gate

measure(qubit: int, classical_bit: int = None)

Measure a qubit

Parameters:

• qubit – Qubit index to measure

• classical_bit – Classical bit to store result (defaults to same as qubit)

measure_all()

Measure all qubits

phase(theta: float, qubit: int)

Apply phase shift gate

run(shots: int = 1, initial_state: QuantumState | None = None, use_gpu: bool = False, precision: str = 'double') → dict

Execute the circuit.

The statevector is computed once and all shots are sampled from the resulting distribution. This is equivalent, for independent projective Z-measurements, to collapsing the state per shot, but costs O(gates + shots) instead of the previous O(shots x gates) (which re-simulated the whole circuit for every shot).

Parameters:

• shots – Number of measurement samples

• initial_state – Optional initial state (defaults to |0...0>)

• use_gpu – Simulate the circuit on the GPU (see get_statevector)

• precision – ‘double’ (complex128) or ‘single’ (complex64) for the GPU path

Returns:

Dictionary with measurement results and statistics

rx(theta: float, qubit: int)

Apply RX rotation gate

ry(theta: float, qubit: int)

Apply RY rotation gate

rz(theta: float, qubit: int)

Apply RZ rotation gate

s(qubit: int)

Apply S (phase) gate

set_noise_model(noise_model: Any | None, noise_simulation_method: str = 'density_matrix')

Set or update noise model for the circuit

Parameters:

• noise_model – NoiseModel instance, HardwareProfile, or None to disable

• noise_simulation_method – ‘density_matrix’, ‘stochastic’, or ‘approximate’

size() → int

Total number of gates

swap(qubit1: int, qubit2: int)

Apply SWAP gate

t(qubit: int)

Apply T gate

toffoli(control1: int, control2: int, target: int)

Apply Toffoli (CCNOT) gate

x(qubit: int)

Apply Pauli-X (NOT) gate

y(qubit: int)

Apply Pauli-Y gate

z(qubit: int)

Apply Pauli-Z gate

QuantumDebugger

class quantum_debugger.QuantumDebugger(circuit: QuantumCircuit, initial_state: QuantumState | None = None)

Bases: object

Interactive debugger for quantum circuits

add_breakpoint_at_gate(gate_index: int)

Add breakpoint at specific gate index

clear_breakpoints()

Remove all breakpoints

compare_with_expected(expected_state: QuantumState) → Dict

Compare current state with expected state

Parameters:

expected_state – Expected quantum state

Returns:

Comparison metrics

continue_execution()

Continue execution until end (alias for run_to_end)

get_current_state()

Get current quantum state (alias for get_state)

get_execution_trace() → List[Dict]

Get full execution trace

Returns:

List of execution states with information

get_state() → QuantumState

Get current quantum state

inspect_state() → Dict

Get detailed information about current state

Returns:

Dictionary with state information

print_status()

Print current debugging status

reset()

Reset debugger to initial state

run_to_end()

Execute all remaining gates

run_until_breakpoint()

Execute until a breakpoint is hit or circuit ends

set_breakpoint(gate: int | None = None, condition=None, description: str = '') → Breakpoint

Set a breakpoint

Parameters:

• gate – Gate index to break at

• condition – Conditional function

• description – Breakpoint description

Returns:

Created breakpoint

step(steps: int = 1) → bool

Execute one or more gates

Parameters:

steps – Number of gates to execute

Returns:

True if stepped successfully, False if at end

step_back(steps: int = 1) → bool

Step backwards in execution history

Parameters:

steps – Number of steps to go back

Returns:

True if stepped back successfully

visualize()

Print visualization of current state

QuantumState

class quantum_debugger.QuantumState(num_qubits: int, state_vector: ndarray | None = None, backend='auto')

Bases: object

Represents a quantum state vector

apply_gate(gate_matrix: ndarray, target_qubits: List[int])

Apply a quantum gate to specific qubits.

Uses tensor contraction, applying the k-qubit gate directly to the relevant axes of the state tensor. This is O(2**n) per gate instead of the O(4**n) cost of materializing the full 2**n x 2**n operator, so it is dramatically faster and more memory efficient for multi-qubit circuits.

Parameters:

• gate_matrix – Unitary matrix of the gate (2**k x 2**k for k qubits)

• target_qubits – List of qubit indices to apply gate to. Gate qubit j acts on target_qubits[j] (matches the previous convention).

bloch_vector(qubit: int = 0) → Tuple[float, float, float]

Get Bloch sphere coordinates for a single qubit

Parameters:

qubit – Index of qubit (for multi-qubit systems, traces out other qubits)

Returns:

(x, y, z) coordinates on Bloch sphere

copy()

Create a deep copy of this state

entropy() → float

Calculate von Neumann entropy

fidelity(other: QuantumState) → float

Calculate fidelity with another quantum state

Parameters:

other – Another quantum state

Returns:

Fidelity value between 0 and 1

get_measurement_probability(qubit: int, outcome: int) → float

Get probability of measuring a specific outcome for a qubit

get_probabilities() → ndarray

Get probability distribution over all basis states

is_entangled() → bool

Check if state is entangled (simple check for 2-qubit systems)

For 2 qubits: state is entangled if it cannot be written as tensor product

measure(qubit: int) → int

Measure a qubit and collapse the state

Parameters:

qubit – Index of qubit to measure

Returns:

Measurement result (0 or 1)

measure_all() → List[int]

Measure all qubits

Integrations

QiskitAdapter

class quantum_debugger.integrations.QiskitAdapter

Bases: object

Adapter for converting between Qiskit and QuantumDebugger circuits

GATE_MAP = {'ccx': 'toffoli', 'cp': 'cp', 'cx': 'cnot', 'cz': 'cz', 'h': 'h', 'p': 'phase', 'rx': 'rx', 'ry': 'ry', 'rz': 'rz', 's': 's', 'swap': 'swap', 't': 't', 'x': 'x', 'y': 'y', 'z': 'z'}

static check_qiskit_available()

Check if Qiskit is installed

classmethod compare_circuits(qiskit_circuit: None, qd_circuit: QuantumCircuit) → dict

Compare a Qiskit circuit with a QuantumDebugger circuit

Returns:

Dictionary with comparison results

classmethod from_qiskit(qiskit_circuit: None) → QuantumCircuit

Convert a Qiskit QuantumCircuit to QuantumDebugger circuit

Parameters:

qiskit_circuit – Qiskit QuantumCircuit to convert

Returns:

QuantumDebugger QuantumCircuit

Example

>>> from qiskit import QuantumCircuit
>>> qc_qiskit = QuantumCircuit(2)
>>> qc_qiskit.h(0)
>>> qc_qiskit.cx(0, 1)
>>> qc_qd = QiskitAdapter.from_qiskit(qc_qiskit)

classmethod to_qiskit(qd_circuit: QuantumCircuit) → None

Convert a QuantumDebugger circuit to Qiskit QuantumCircuit

Parameters:

qd_circuit – QuantumDebugger circuit to convert

Returns:

Qiskit QuantumCircuit

Example

>>> from quantum_debugger import QuantumCircuit
>>> qc_qd = QuantumCircuit(2)
>>> qc_qd.h(0)
>>> qc_qd.cnot(0, 1)
>>> qc_qiskit = QiskitAdapter.to_qiskit(qc_qd)

Profiling

CircuitProfiler

class quantum_debugger.CircuitProfiler(circuit: QuantumCircuit)

Bases: object

Profiler for analyzing quantum circuit performance

analyze() → CircuitMetrics

Analyze the circuit and return metrics

Returns:

CircuitMetrics object with analysis results

compare_with_ideal() → Dict

Compare circuit with theoretical ideal

Returns:

Comparison metrics

get_optimization_suggestions() → List[str]

Get suggestions for circuit optimization

Returns:

List of optimization suggestions

print_report()

Print comprehensive profiling report