| # 🌌 QSBench: Circuit Family Classifier Guide |
|
|
| Welcome to the **QSBench Classification Hub**. This project demonstrates how Machine Learning can identify the "functional signature" of a quantum circuit based solely on its structural topology and complexity metrics. |
|
|
| --- |
|
|
| ## ⚠️ Important: Demo Dataset Notice |
| The datasets used in this interface are **v1.0.0-demo** shards. |
| * **Constraint:** These are reduced versions of the full QSBench library. |
| * **Performance:** Because the training samples are limited, you may observe "confusion" between similar variational families (like HEA and EfficientSU2). |
| * **Goal:** This tool is a prototype for benchmarking how structural features (like gate entropy) serve as unique identifiers for quantum algorithms. |
|
|
| --- |
|
|
| ## 📂 1. The 5 Target Families |
| The classifier is trained to distinguish between five major classes of quantum circuits: |
|
|
| 1. **`QFT` (Quantum Fourier Transform):** Highly structured, deterministic circuits used in Shor’s algorithm and phase estimation. |
| 2. **`HEA` (Hardware Efficient Ansatz):** Variational circuits designed to match specific hardware topologies, often used in VQE. |
| 3. **`RANDOM`:** Circuits with randomly placed gates, used for benchmarking cross-entropy benchmarking (XEB). |
| 4. **`EFFICIENT` (EfficientSU2):** A hardware-efficient heuristic ansatz with specific entanglement patterns. |
| 5. **`REAL_AMPLITUDES`:** A common ansatz for hybrid quantum-classical algorithms that uses only real-valued amplitudes. |
| |
| --- |
| |
| ## 📊 2. Feature Signatures: How the AI "Sees" Circuits |
| The model doesn't "read" the QASM code like a compiler. Instead, it looks at **structural signatures**: |
| |
| * **`meyer_wallach`:** Helps distinguish between high-entanglement algorithms (like QFT) and low-entanglement shallow circuits. |
| * **`gate_entropy`:** Captures the randomness or regularity of gate distribution. QFT has very low entropy (highly structured), while RANDOM circuits have high entropy. |
| * **`adjacency`:** Shows how many qubits interact. This is a key discriminator for "Transpilation" datasets. |
| * **`depth` & `cx_count`:** Provide the "vertical and horizontal" scale of the circuit. |
|
|
| --- |
|
|
| ## 🤖 3. Analyzing the Results |
| Once you click **"Run Classification"**, the system provides two main insights: |
|
|
| ### A. The Confusion Matrix |
| This heatmap shows where the model is confident and where it is confused. |
| * **Diagonal:** Correct predictions. |
| * **Off-diagonal:** If you see a high number of `HEA` circuits being predicted as `REAL_AMPLITUDES`, it suggests these two families share very similar structural "DNA" in small-scale demos. |
|
|
| ### B. Feature Importance |
| This bar chart reveals which metric was the "smoking gun" for the classification. For example, you might find that `meyer_wallach` is the best way to spot a `QFT` circuit. |
|
|
| --- |
|
|
| ## 🔗 4. Project Resources |
| * 🤗 [**Hugging Face Datasets**](https://huggingface.co/QSBench) |
| * 💻 [**GitHub Repository**](https://github.com/QSBench) |
| * 🌐 [**Official Website**](https://qsbench.github.io) |
