GUIDE.md

🌌 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
• 💻 GitHub Repository
• 🌐 Official Website