GUIDE.md

🌌 QSBench: Noise Classification Guide

Welcome to the QSBench Noise Classification Hub.
This tool demonstrates how Machine Learning can distinguish different noise conditions in quantum circuits using only structural and topological features — without running expensive simulations.

---

⚠️ Important: Demo Dataset Notice

This Space uses demo shards of the QSBench datasets.

• Limited size: The dataset is intentionally reduced for fast loading and demonstration.
• Impact: Model performance may be unstable or noisy, especially on the minority class.
• Goal: Showcase how circuit structure correlates with noise type — not achieve production-level accuracy.

---

🧠 1. What is Being Predicted?

The model performs multi-class classification into four noise conditions:

Classes

• clean — Ideal circuit without noise
• depolarizing — Uniform depolarizing noise
• amplitude_damping — Energy relaxation / amplitude damping
• hardware_aware — Realistic hardware-aware noise after transpilation

The task is to predict the noise_label from circuit features only.

---

🧩 2. How the Model “Sees” a Circuit

The model does not simulate quantum states or noise channels.
Instead, it relies on structural proxies:

🔹 Topology Features

• adj_density — How densely qubits are connected
• adj_degree_mean — Average qubit connectivity
• adj_degree_std — Variability in connectivity

→ These reflect the interaction graph and entanglement potential.

🔹 Gate Structure

• total_gates
• single_qubit_gates
• two_qubit_gates
• cx_count (or similar two-qubit counts)

→ Two-qubit gates strongly influence noise sensitivity.

🔹 Complexity Metrics

• depth
• gate_entropy

→ Capture how “deep” and “structured” the circuit is.

🔹 QASM-derived Signals

• qasm_length
• qasm_line_count
• qasm_gate_keyword_count

→ Lightweight text-based proxies for circuit complexity.

---

🤖 3. Model Overview

The system uses:

HistGradientBoostingClassifier

• Fast and accurate gradient boosting on tabular data
• Handles non-linear relationships well
• Supports class_weight="balanced" to deal with class imbalance

Pipeline includes:

• Median imputation for missing values
• Standard scaling
• Gradient boosting classifier

---

📊 4. Understanding the Results

After clicking "Train & Evaluate", you get:

A. Confusion Matrix

Shows how often each true noise type is predicted correctly or confused with others.

B. Correct vs Incorrect

Simple histogram of prediction accuracy.

C. Top-10 Feature Importances

Highlights which circuit features contribute most to distinguishing noise types.
Typical strong signals:

• cx_count / two-qubit gate counts
• Topology features (adj_density, adj_degree_*)
• depth and complexity metrics

---

📉 5. Metrics Explained

• Accuracy — Overall fraction of correctly classified circuits
• Macro F1 — Average F1-score per class (treats all classes equally — sensitive to minority class clean)
• Weighted F1 — F1-score weighted by class support
• Per-class Precision / Recall / F1 — Detailed view, especially important for the underrepresented clean class

---

🧪 6. Experimentation Tips

Try the following to better understand the model:

• Focus on clean class — select features carefully and observe how class_weight="balanced" helps
• Remove strong features (e.g. cx_count) → see performance drop
• Use only topology features → isolate structural effect
• Increase Trees (max_iter) to 300–500 for more stable predictions
• Adjust Max depth and Test split to check robustness
• Compare results with and without class_weight

---

🔬 7. Key Insight

Noise type is not invisible — it leaves detectable fingerprints in circuit structure.
Even without expensive noisy simulation, features like gate counts, connectivity, and depth already contain enough signal to classify the underlying noise condition.

This demonstrates the power of structure-aware quantum machine learning.

---

🔗 8. Project Resources

• 🤗 Hugging Face: https://huggingface.co/QSBench
• 💻 GitHub: https://github.com/QSBench
• 🌐 Website: https://qsbench.github.io