Spaces:
Running
Running
| # 🌌 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](https://huggingface.co/QSBench) | |
| - 💻 **GitHub**: [https://github.com/QSBench](https://github.com/QSBench) | |
| - 🌐 **Website**: [https://qsbench.github.io](https://qsbench.github.io) |