Create GUIDE.md

GUIDE.md

@@ -0,0 +1,120 @@
+# 🌌 Quantum Noise Robustness Benchmark Guide
+
+Welcome to the **Quantum Noise Robustness Benchmark**.  
+This tool shows how well Machine Learning can **predict the impact of noise** on quantum circuits using only structural and topological features — without running any noisy simulation.
+
+---
+
+## ⚠️ Important: Demo Dataset Notice
+
+This Space uses the **demo shard** of the QSBench Amplitude Damping dataset.
+
+- **Limited size**: Only a small subset of circuits is loaded for fast demonstration.
+- **Impact**: Results may vary depending on the random split and selected features.
+- **Goal**: Showcase how circuit structure correlates with noise-induced errors — not achieve production-level accuracy.
+
+---
+
+## 🎯 1. What is Being Predicted?
+
+The model performs **multi-output regression** and predicts **three error values** simultaneously:
+
+### Targets
+- **`error_Z_global`** — deviation in Z-basis expectation value  
+- **`error_X_global`** — deviation in X-basis expectation value  
+- **`error_Y_global`** — deviation in Y-basis expectation value  
+
+These errors are calculated as:  
+**`error = noisy_expval - ideal_expval`**
+
+The goal is to estimate **how much noise distorts** the observable without actually applying the noise channel.
+
+---
+
+## 🧩 2. How the Model “Sees” a Circuit
+
+The model never simulates quantum states or noise.  
+It only uses **structural proxies**:
+
+### 🔹 Topology Features
+- `adj_density` — how densely qubits are connected  
+- `adj_degree_mean` / `adj_degree_std` — average and variability of connectivity  
+
+### 🔹 Gate Structure & Complexity
+- `depth`, `total_gates`, `cx_count`, `two_qubit_gates`  
+- `gate_entropy` — measure of randomness vs regularity  
+
+### 🔹 QASM-derived Signals
+- `qasm_length`, `qasm_line_count`, `qasm_gate_keyword_count`  
+
+These features capture **entanglement potential** and **circuit complexity** — the main factors that determine noise sensitivity.
+
+---
+
+## 🤖 3. Model Overview
+
+The system uses:
+
+### MultiOutput HistGradientBoostingRegressor
+- Fast and accurate gradient boosting  
+- Predicts all three errors (`Z`, `X`, `Y`) at once  
+- Pipeline includes median imputation + standard scaling  
+
+This is currently the strongest and fastest model for tabular quantum data.
+
+---
+
+## 📊 4. Understanding the Results
+
+After clicking **"Train Multi-Output Regressor"** you get:
+
+### A. Predicted vs True Error (three plots)
+- Each point = one circuit  
+- Red dashed line = perfect prediction  
+- The tighter the points around the line → the better the model
+
+### B. Residual Distribution
+- Shows prediction errors (`True - Predicted`)  
+- Centered around zero = unbiased model  
+- Narrow spread = high precision
+
+---
+
+## 📉 5. Metrics Explained
+
+For each basis (**Z**, **X**, **Y**) the model reports:
+
+- **MAE** — average absolute error (in expectation value units)  
+- **RMSE** — root mean squared error (penalizes large mistakes)  
+- **R²** — coefficient of determination (1.0 = perfect fit, 0 = no better than mean)
+
+Higher R² and lower MAE/RMSE = better noise robustness prediction.
+
+---
+
+## 🧪 6. Experimentation Tips
+
+Try these experiments to understand the model better:
+
+- Use **only topology features** (`adj_*`) → isolate structural effect  
+- Remove `cx_count` → see how much two-qubit gates matter  
+- Increase **Max Iterations** to 600–800 for more stable predictions  
+- Change **Test Split** and re-train several times → check robustness  
+- Compare results with and without `gate_entropy`
+
+---
+
+## 🔬 7. Key Insight
+
+> Noise does not appear randomly — it leaves clear fingerprints in circuit structure.  
+Even without running expensive noisy simulations, features like connectivity, depth, and gate counts already contain enough signal to predict how much the expectation values will be distorted.
+
+This demonstrates the power of **structure-aware** quantum machine learning for noise benchmarking.
+
+---
+
+## 🔗 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)