quantum-backend-bench 0.1.0

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.

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
• JSON export 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

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

For development tools:

python -m pip install -e .[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:

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

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

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

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.core.runner import run_benchmark

benchmark = build_benchmark(n_qubits=5)
results = run_benchmark(benchmark, ["cirq", "pennylane", "braket_local"], shots=1024)

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

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.