Qiskit Inspect

Production-ready debugging, tracing, and analysis helpers for Qiskit.

Overview

qiskit_inspect augments Qiskit v2.0+ with practical tooling for stepping through circuits, tracing prefix probabilities, logging sampler execution, and exporting structured results. It was built to help practitioners debug classical control flow, validate sampler output against exact statevectors, and ship robust tests for production quantum applications.

Why Qiskit Inspect?

• Deterministic debugging – Step through instructions with full statevector snapshots, classical bit snapshots, and support for control-flow constructs (IfElseOp, loops, and SwitchCaseOp).
• Prefix analytics – Compute exact probabilities, sampler-backed probabilities, counts, marginals, expectation values, Shannon entropies, divergences (cross entropy, KL, Jensen-Shannon), and total-variation/ Hellinger distances for every prefix of a circuit. Compare traced prefixes against reference distributions with per-step divergence series to spot drift quickly.
• Testing confidence – Assertion helpers compare counts, probabilities, and statevectors with configurable tolerances for noisy hardware.
• Operational insights – CSV/JSON export, pandas integration, ASCII/Matplotlib histograms, and structured trace logging make it simple to observe and share what your primitives are doing.

Installation

Install via pip

pip install qiskit-inspect

Install the package in editable mode while iterating locally:

pip install -e .

Optional extras install integrations used by some helpers and examples:

• Aer sampling: pip install qiskit-aer or pip install -e .[aer]
• IBM Runtime SamplerV2: pip install qiskit-ibm-runtime or pip install -e .[runtime]
• Data wrangling: pip install pandas or pip install -e .[data]
• Visualization: pip install matplotlib seaborn or pip install -e .[visualization]
• Development (all extras + tooling): pip install -e .[dev]

Install extras with pip install -e .[extra] to pull in the optional dependencies directly from this repository while you iterate locally.

Quickstart

from qiskit import QuantumCircuit
from qiskit.primitives import StatevectorSampler
from qiskit_inspect import (
    CircuitDebugger,
    jensen_shannon_divergence,
    prefix_jensen_shannon_divergences,
    trace_probabilities_with_sampler,
    trace_probabilities_with_statevector_exact,
    trace_shannon_entropy_with_statevector,
)

qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)
qc.measure(0, 0)
qc.ry(0.3, 1)
qc.measure(1, 1)

# Step through each prefix deterministically.
debugger = CircuitDebugger(qc)
for record in debugger.trace(include_initial=True):
    print(
        "step",
        record.step_index,
        ":",
        record.instruction,
        "bits=",
        record.classical_bits,
    )

# Compare exact vs sampled prefix probabilities.
exact = trace_probabilities_with_statevector_exact(qc, include_initial=True)
sampler = StatevectorSampler(default_shots=2048)
sampled = trace_probabilities_with_sampler(qc, sampler, shots=2048)
print("last-prefix exact probs:", exact[-1])
print("last-prefix sampler probs:", sampled[-1])
entropies = trace_shannon_entropy_with_statevector(qc)
print("prefix entropies:", entropies)
print(
    "final-prefix JS divergence vs uniform:",
    jensen_shannon_divergence(
        exact[-1], {"00": 0.25, "01": 0.25, "10": 0.25, "11": 0.25}
    ),
)
print(
    "exact vs sampler JS divergence:",
    jensen_shannon_divergence(exact[-1], sampled[-1]),
)
print(
    "per-prefix JS divergence vs sampler:",
    prefix_jensen_shannon_divergences(exact, sampled),
)

Set flatten_control_flow=True on the exact helpers to emit intermediate snapshots for operations inside control-flow blocks (for example every iteration of a ForLoopOp).

Every element yielded by CircuitDebugger.trace() is a TraceRecord exposing step_index, the executed instruction, the post-instruction quantum state, and an ordered tuple of classical_bits. Those records can be fed directly into helpers such as trace_records_to_dataframe or persisted with write_trace_json for offline analysis.

Continue with the cookbook for deeper recipes covering breakpoints, control-flow flattening, expectation values, exporting, pandas integration, and parameter broadcasting. If you prefer runnable scripts, see the examples directory.

Documentation

• Cookbook – Comprehensive, task-oriented how-to guide.
• Examples – Directory tour with command-line entry points.
• API reference – Detailed API documentation.

Examples

All scripts live in examples/ and can be executed directly:

• debugger_trace_walkthrough.py – Structured traces, flattening, and breakpoints with trace logging.
• probabilities_and_counts_walkthrough.py – Compare exact probabilities, sampler counts, marginals, and Aer sampling.
• expectations_and_exports.py – Prefix expectation values, DataFrame helpers, and CSV/JSON export utilities.
• parameter_broadcasting.py – Accepted parameter binding formats for prefix tracing helpers.
• testing_helpers.py – Assertion utilities for unit tests.
• bell_backend_trace.py – Minimal prefix tracing on a Bell circuit.
• compare_methods.py – Exact, marginal, and Aer-based probability tracing.
• breakpoints_demo.py – Quick look at run_until_* helpers.
• custom_condition_evaluator.py – Override classical evaluation in the debugger.
• marginal_histograms.py and plot_histogram_example.py – Visualization utilities leveraging Qiskit's Matplotlib histogram helper (requires Matplotlib).
• teleportation_ifelse.py – Debug an If/Else controlled teleportation circuit.

Compatibility

• Requires Python 3.10+ and Qiskit 2.0 or newer.
• Works with SamplerV2/EstimatorV2 primitives and classical control-flow constructs introduced in Qiskit 2.x.
• Optional extras (Aer, IBM Runtime, pandas, Matplotlib) are auto-detected where relevant; helpers degrade gracefully when packages are missing.

Development

Clone the repository, install with the dev extra, and run the test suite:

pip install -e .[dev]
pytest

We welcome issues and pull requests that improve compatibility with the latest Qiskit releases, add diagnostics that make real-world debugging easier, or expand the cookbook and examples with practical workflows.

License

This project is licensed under the Apache License - see the LICENSE file for details.

Acknowledgements

We extend our thanks to the Qiskit project and IBM Quantum team.