Quantum Circuit Benchmarking in Rust

Quantum Circuit Benchmarking in Rust

1. How We Found a Silent Bug That Quantum Volume Misses
2. About This Book
3. Contents

About the Author

Chapter 1: The Problem with Quantum Software Testing

1. 1.1 The Promise and the Fragmentation
2. 1.2 The Illusion of Correctness
3. 1.3 What Quantum Volume Does Not Measure
4. 1.4 The OpenQASM Standard and Why It Matters
5. 1.5 What We Built
6. 1.6 What This Book Covers
7. Summary

Chapter 2: The Bug We Found

1. 2.1 The Setup: Four Simulators, One Circuit
2. 2.2 The QAOA Circuit
3. 2.3 The Sign Convention
4. 2.4 Why Orthogonal?
5. 2.5 The Invisible Nature of the Bug
6. 2.6 Reproducing the Bug
7. 2.7 The Fix
8. 2.8 What This Means in Practice
9. Summary

Chapter 3: The Architecture of CleitonForge

1. 3.1 The Design Goal
2. 3.2 The Workspace
3. 3.3 The Canonical IR: cforge-core
4. 3.4 The Plugin Trait: SimulationBackend
5. 3.5 The Native Backend
6. 3.6 The QuantRS2 Backend
7. 3.7 Adding a New Backend
8. 3.8 Why Rust?
9. Summary

Chapter 4: The OpenQASM Parser

1. 4.1 Why Build a Parser?
2. 4.2 OpenQASM 2 vs OpenQASM 3
3. 4.3 The Two-Pass Parser for QASM 2
4. 4.4 Whole-Register Broadcasting
5. 4.5 User-Defined Gates
6. 4.6 Gate Aliases
7. 4.7 Parameter Evaluation
8. 4.8 The QASM 3 Parser
9. 4.9 The Full Parse Pipeline
10. 4.10 Parsing in Python
11. Summary

Chapter 5: Metrics — Fidelity, Memory, and Time

1. 5.1 What Should a Quantum Benchmark Measure?
2. 5.2 Statevector Fidelity
3. 5.3 The Inner Product in Practice
4. 5.4 Circuit Statistics
5. 5.5 Timing
6. 5.6 Memory Measurement
7. 5.7 The measure Function
8. 5.8 JSON Output for CI/CD
9. Summary

Chapter 6: How to Use CleitonForge in Your Project

1. 6.1 Three Ways to Use CleitonForge
2. 6.2 Installation
3. 6.3 The CLI: cforge run
4. 6.4 The CLI: cforge validate
5. 6.5 Python: pip install cleitonforge
6. 6.6 Integrating with Qiskit
7. 6.7 GitHub Actions: Fidelity Checks in CI/CD
8. 6.8 PyPI Package Details
9. 6.9 Noisy Simulation
10. Summary

Chapter 7: What Comes Next

1. 7.1 Where We Are
2. 7.2 Hardware Backends
3. 7.3 Noise Modeling
4. 7.4 More Rust Backends
5. 7.5 Cross-Backend Fidelity as a Standard
6. 7.6 The Book You Are Reading as a Data Point
7. 7.7 How to Contribute
8. 7.8 Final Words
9. Summary

Appendix A: Supported Gate Reference

1. Single-Qubit Gates — No Parameters
2. Single-Qubit Gates — With Parameters
3. Two-Qubit Gates — No Parameters
4. Two-Qubit Gates — With Parameters
5. Three-Qubit Gates
6. Qubit Limits
7. Gate Coverage by Backend

Appendix B: CLI Reference

1. Installation
2. Global Options
3. cforge run
4. cforge validate
5. Default Seed
6. Supported QASM Features

Appendix C: Frequently Asked Questions