quantum-backend-bench 0.1.2

Backend-agnostic benchmarking toolkit for local quantum SDK simulators.

Quantum Backend Bench

Backend-agnostic benchmarking toolkit for local quantum circuit simulators. The package runs the same benchmark definitions across Cirq, PennyLane, and Amazon Braket LocalSimulator, then reports standardized runtime, structural, and distribution metrics. pytket is used for circuit analysis and compilation-style metrics, not as an execution backend.

See USAGE.md for a task-oriented guide to the CLI and Python API, and CHANGELOG.md for release notes.

Features

• Unified BenchmarkSpec abstraction for reusable benchmark definitions
• Local-only execution backends with no cloud credentials required
• Built-in benchmarks for GHZ, QFT, random circuits, Grover search, Hamiltonian simulation, and noise sweeps
• Standardized metrics including depth, gate counts, runtime, success probability, and total variation distance
• CLI commands for single runs, backend comparison, and noise sweeps
• Named benchmark suites for smoke, standard, and scaling runs
• Native circuit drawing through Cirq, PennyLane, Braket, and pytket renderers
• JSON/CSV export, summary rankings, and matplotlib plot generation
• Installable in GitHub Codespaces with Python 3.11+

Backend Support

Backend	Execution	Notes
Cirq	cirq.Simulator	Supports depolarizing noise injection in this project
PennyLane	default.qubit / default.mixed	Uses local devices only
Amazon Braket	LocalSimulator only	Offline execution, no AWS credentials required
pytket	Analysis only	Used for depth and gate metrics, not execution

Installation

Install from PyPI:

python -m pip install quantum-backend-bench

Install execution backends as needed:

python -m pip install "quantum-backend-bench[cirq]"
python -m pip install "quantum-backend-bench[pennylane]"
python -m pip install "quantum-backend-bench[braket]"
python -m pip install "quantum-backend-bench[all]"

Install from a local checkout:

python -m pip install --upgrade pip
python -m pip install -e .

For development tools:

python -m pip install -e .[dev]

For the full local test matrix:

python -m pip install -e ".[all,dev]"

GitHub Codespaces

The repository includes a Codespaces-ready .devcontainer/devcontainer.json using a Python 3.11 base image. On container creation it installs the package in editable mode with development dependencies.

Quickstart

Run a single benchmark:

quantum-bench run ghz --backend cirq --n-qubits 5

Compare a benchmark across all execution backends and print summary rankings:

quantum-bench compare qft --backends cirq pennylane braket_local --n-qubits 5 --summary

Run a random circuit:

quantum-bench run random-circuit --backend braket_local --n-qubits 4 --depth 10 --seed 42

Run Grover:

quantum-bench run grover --backend pennylane --n-qubits 3 --marked-state 101

Run Hamiltonian simulation:

quantum-bench run hamiltonian-sim --backend cirq --n-qubits 4 --time 1.0 --trotter-steps 2

Run a noise sweep:

quantum-bench noise-sweep ghz --backend cirq --n-qubits 5

Draw a circuit with a native SDK renderer:

quantum-bench draw ghz --backend cirq --n-qubits 5
quantum-bench draw qft --backend pennylane --n-qubits 5 --save-path artifacts/qft_pennylane.png
quantum-bench draw ghz --backend tket --n-qubits 5 --save-path artifacts/ghz_tket.txt

Save JSON and plots:

quantum-bench compare ghz --backends cirq pennylane braket_local --n-qubits 5 --save-json artifacts/ghz.json --save-plot artifacts/ghz.png

Save CSV:

quantum-bench compare ghz --backends cirq pennylane --n-qubits 5 --save-csv artifacts/ghz.csv

Run a named suite:

quantum-bench suite smoke --backends cirq --summary
quantum-bench suite standard --backends cirq pennylane braket_local --save-csv artifacts/standard.csv

For more complete workflows, result interpretation, and Python examples, see USAGE.md.

Benchmark Suite

GHZ

Generates GHZ states for configurable qubit counts. Ideal output is concentrated on 00...0 and 11...1.

QFT

Implements the Quantum Fourier Transform for structural and runtime comparisons.

Random Circuit

Builds reproducible random circuits using a fixed gate set and explicit seed control.

Grover

Implements a small search benchmark for 2 to 4 qubits and reports marked-state success probability.

Hamiltonian Simulation

Implements first-order Trotterized evolution for a simple Ising-style Hamiltonian:

H = sum_i Z_i Z_{i+1} + 0.5 * sum_i X_i

Noise Sensitivity

Wraps a base benchmark and sweeps depolarizing noise levels. Noise behavior differs by backend and is reported in result metadata. Braket remains local-only and does not inject noise in this adapter.

Python API

from quantum_backend_bench.benchmarks.ghz import build_benchmark
from quantum_backend_bench import build_suite, run_benchmark, summarize_results

benchmark = build_benchmark(n_qubits=5)
results = run_benchmark(benchmark, ["cirq", "pennylane", "braket_local"], shots=1024)
suite_results = [
    result
    for benchmark in build_suite("smoke")
    for result in run_benchmark(benchmark, ["cirq"], shots=128)
]
summary = summarize_results(suite_results)

Project Layout

quantum_backend_bench/
├── backends/
├── benchmarks/
├── core/
├── utils/
└── cli.py

Example scripts live in examples/, including backend comparison, GHZ execution, and a Cirq noise sweep demo.

Development

Run formatting and linting:

black quantum_backend_bench tests examples
ruff check quantum_backend_bench tests examples

Run tests:

pytest

Build and inspect release artifacts:

python -m build
python -m twine check dist/*

Continuous integration is handled by .github/workflows/ci.yml, which runs formatting, linting, tests, build, and distribution checks. Publishing is handled by .github/workflows/publish.yml when a version tag such as v0.1.2 is pushed. The workflow expects PyPI trusted publishing to be configured for this repository.

Notes

• The project targets standard pip environments with Python 3.11 or newer.
• No AWS account, cloud credentials, GPUs, or paid services are required.
• The internal circuit model is intentionally simple to keep backend translation maintainable.