Create GUIDE.md

GUIDE.md

@@ -0,0 +1,52 @@
+# 🌌 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)