# 🌌 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)