StabiliserSuite

Toolbox for benchmarking and stress‑testing NISQ quantum processors
Clifford circuits • topology‑aware routing • gate‑transformation search

✨ Key Features

• Random Clifford generator – O(n²) tableau routine for uniformly random stabiliser circuits
• Topology‑aware routing – 4‑CNOT “bridge’’ pattern for non‑adjacent CNOTs on heavy‑hex and ion‑trap layouts
• Gate‑transformation search – meet‑in‑the‑middle engine (canonical‑phase hashing, memoisation) finds depth‑bounded Clifford / non‑Clifford substitutions
• Unified workflow – circuit synthesis → classical stabiliser simulation → Qiskit hardware run → fidelity report
• Open‑source & extensible – MIT licence, clean Python API, minimal external deps

🚀 Quick Start

Conda (recommended)

mamba create -n stabilisersuite -c conda-forge stabiliser_suite
mamba activate stabilisersuite

Pure‑pip (light‑weight alternative)

python -m venv .venv
source .venv/bin/activate
pip install stabiliser_suite

Example usage

import stabiliser_suite as ss
from qiskit.circuit.library import CXGate

# 1. random 6‑qubit Clifford circuit
circ = ss.clifford.sample_clifford_group(3)
print(circ.draw())

# 2. non‑Clifford substitute for CX at depth ≤3
subs = ss.gate_utils.find_non_clifford_transformations(CXGate(), max_depth=3)
print("First match:", subs[0][0])

🗂 Project Layout

stabiliser_suite/
├── benchmark     # simple benchmarking scripts
├── clifford      # Clifford-circuit generation
├── circuit       # 4-CNOT construction
├── gate_utils    # gate transformation search
└── tests/        # pytest suite

📖 Documentation

Full API reference and tutorials will be later put in docs/.
Rendered docs will be hosted at https://achaad.github.io/StabiliserSuite/.

🤝 Contributing

1. Fork → feature branch → pull request against main.
2. Run pytest and mypy locally (mamba env update -f environment.yml -n stabilisersuite --prune).
3. Code is auto‑formatted with Black.

The project uses semantic versioning 2.0, i.e. v${MAJOR}.${MINOR}.${PATCH} (e.g. v0.1.123)

The project is configured with automatic releases on any commits to the master branch. All the merge commits should be prepended with a tag from the list below (e.g. "feat: Add ESR support"):

📄 License

StabiliserSuite is released under the MIT License (see LICENSE).

📑 Citation

@misc{stabilisersuite2025,
  author       = {Anton Perepelenko},
  title        = {StabiliserSuite: Toolbox for Quantum Computer Testing},
  year         = {2025},
  howpublished = {\url{https://github.com/Achaad/StabiliserSuite}},
  note         = {MIT License}
}