Update GUIDE.md

GUIDE.md

@@ -1,120 +1,95 @@
 # 🌌 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.
+This tool demonstrates how Machine Learning can **predict the impact of noise** on quantum circuits using only structural and topological features — without running any expensive noisy simulations.
 
 ---
 
 ## ⚠️ Important: Demo Dataset Notice
 
-This Space uses the **demo shard** of the QSBench Amplitude Damping dataset.
+This Hub uses **v1.0.0-demo shards** of the QSBench dataset family.
 
-- **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.
+- **Limited Scale**: Only a small subset of circuits is loaded for fast demonstration.
+- **Complexity**: Predicting quantum observables from pure structure is a **non-trivial mapping**. 
+- **Goal**: Showcase the correlation between circuit topology and noise sensitivity — not to achieve production-level $R^2$ on a limited sample.
 
 ---
 
 ## 🎯 1. What is Being Predicted?
 
-The model performs **multi-output regression** and predicts **three error values** simultaneously:
+The model performs **multi-target regression** to estimate how much noise distorts the final signal.
 
-### Targets
+### Targets (The Error Vector)
 - **`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`**
+**Formula:** `error = noisy_expval - ideal_expval`
 
-The goal is to estimate **how much noise distorts** the observable without actually applying the noise channel.
+Unlike predicting the state itself, predicting the **error shift** allows us to understand the "noise fingerprint" left by the circuit's architecture.
 
 ---
 
 ## 🧩 2. How the Model “Sees” a Circuit
 
-The model never simulates quantum states or noise.  
-It only uses **structural proxies**:
+The model never simulates quantum states. It uses **structural proxies** to guess the noise impact:
 
 ### 🔹 Topology Features
-- `adj_density` — how densely qubits are connected  
-- `adj_degree_mean` / `adj_degree_std` — average and variability of connectivity  
+- `adj_density` — how densely qubits are connected (proxy for crosstalk risk).
+- `adj_degree_mean` — average connectivity (proxy for entanglement speed).
 
-### 🔹 Gate Structure & Complexity
-- `depth`, `total_gates`, `cx_count`, `two_qubit_gates`  
-- `gate_entropy` — measure of randomness vs regularity  
+### 🔹 Complexity & Entanglement
+- `depth` / `total_gates` — length of the decoherence window.
+- `cx_count` / `two_qubit_gates` — the most noise-sensitive components in NISQ hardware.
+- `gate_entropy` — measures circuit regularity vs. randomness.
 
-### 🔹 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.
+### 🔹 QASM Signals
+- `qasm_length` & `gate_keyword_count` — capture the overall "instruction weight".
 
 ---
 
-## 📊 4. Understanding the Results
-
-After clicking **"Train Multi-Output Regressor"** you get:
+## 🤖 3. Technical Overview: The ML Pipeline
 
-### 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
+To handle the non-linear nature of quantum data, we use:
 
-### B. Residual Distribution
-- Shows prediction errors (`True - Predicted`)  
-- Centered around zero = unbiased model  
-- Narrow spread = high precision
+- **HistGradientBoostingRegressor**: A high-performance boosting algorithm designed for large tabular data.
+- **MultiOutput Wrapper**: Ensures all three axes ($X, Y, Z$) are learned in a unified context.
+- **Robust Preprocessing**: Median imputation for missing values and Standard Scaling for feature parity.
 
 ---
 
-## 📉 5. Metrics Explained
+## 📊 4. Interpreting the Analytics
 
-For each basis (**Z**, **X**, **Y**) the model reports:
+### A. Physics Emulation Plot (Crucial!)
+- **Gray Points**: Actual simulated noisy values.
+- **Red Points**: ML-predicted noisy values ($Ideal + Predicted Error$).
+- **Insight**: If red points follow the trend of gray points, the model has successfully "learned" the physics of the noise channel without a simulator.
 
-- **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)
+### B. Why is my $R^2$ near Zero?
+Even with 200,000+ samples, structural metrics alone (like `depth` or `entropy`) provide a "complexity baseline" but do not capture specific gate rotation angles.
 
-Higher R² and lower MAE/RMSE = better noise robustness prediction.
+1. **The Result:** Standard regressors (Random Forest/XGBoost) will hit a performance ceiling near R2≈0, as they see the circuit's skeleton but not its parameters.
+   
+2. **The Opportunity:** This makes QSBench the perfect playground for **Graph Neural Networks (GNN)** and **Geometric Deep Learning**, where models can integrate gate parameters as node features to break this "structural ceiling."
 
 ---
 
-## 🧪 6. Experimentation Tips
+## 🧪 5. 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`
+- **Isolate Topology**: Select only `adj_*` features to see how much qubit mapping alone affects noise.
+- **The "CX" Test**: Remove `cx_count` and see how much the MAE increases. This quantifies the "cost" of entanglement in your noise model.
+- **Iteration Scaling**: Increase **Max Iterations** (400 -> 800) to see if the model can find deeper patterns in the demo data.
 
 ---
 
-## 🔬 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.
+## 🔬 6. Key Insight
 
-This demonstrates the power of **structure-aware** quantum machine learning for noise benchmarking.
+> **Noise is not random.** It is a deterministic function of circuit complexity and hardware topology. Even without a quantum simulator, ML can "guess" the fidelity of a result just by looking at the circuit diagram.
 
 ---
 
-## 🔗 8. Project Resources
+## 🔗 7. 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)
+- 🤗 **Hugging Face**: [Datasets & Shards](https://huggingface.co/QSBench)  
+- 💻 **GitHub**: [Source Code & Tools](https://github.com/QSBench)  
+- 🌐 **Official Store**: [Get Full-Scale Datasets](https://qsbench.bgng.io)