Update GUIDE.md

GUIDE.md

@@ -1,62 +1,122 @@
 # 🌌 QSBench: Complete User Guide
 
-Welcome to **QSBench Analytics Hub**. This space is designed for exploring synthetic quantum datasets, training machine learning (ML) models, and evaluating the impact of quantum noise on expectation values.
+Welcome to the **QSBench Analytics Hub**.  
+This platform is designed to bridge the gap between quantum circuit topology and machine learning, allowing researchers to study how structural characteristics influence quantum simulation outcomes.
 
 ---
 
-## 📂 1. Dataset Architecture
+## ⚠️ Important: Demo Dataset Notice
 
-QSBench provides unified datasets for the *Quantum Machine Learning (QML)* task. In this demo, 4 core datasets are available:
+The datasets currently loaded in this hub are **v1.0.0-demo versions**.
 
-1. **Core (Clean):** Base set of ideal simulations. No physical noise influence. Great starting point for testing neural network architectures.
-2. **Depolarizing Noise:** Simulation of depolarizing noise (equal‑probability error on quantum gates).
-3. **Amplitude Damping:** Simulation of amplitude damping (asymmetric energy loss process by qubits).
-4. **Transpilation (10q):** Circuits optimised and compiled for a specific hardware topology.
+- **Scale**: These are small *shards* (subsets) of the full QSBench library.  
+- **Accuracy**: Because the training data is limited in size, ML models trained here will show lower accuracy and higher variance compared to models trained on full-scale production datasets.  
+- **Purpose**: These sets are intended for **demonstration and prototyping** of analytical pipelines before moving to high-performance computing (HPC) environments.  
 
-### Circuit Families Covered
-Each set includes a balanced sample from the following circuit classes:
-* `QFT` — Quantum Fourier Transform.
-* `HEA` — Hardware Efficient Ansatz (variational forms).
-* `RANDOM` — Circuits with random gate placements.
-* `EFFICIENT` / `REAL_AMPLITUDES` — Popular ansätze for hybrid quantum networks (VQA, QAOA).
+---
+
+## 📂 1. Dataset Architecture & Selection
+
+QSBench provides high-fidelity simulation data for the Quantum Machine Learning (QML) community.  
+We provide four distinct environments to test how different noise models affect data:
+
+### Core (Clean)
+Ideal state-vector simulations.  
+Used as a **"Golden Reference"** to understand the theoretical limits of a circuit's expressivity without physical interference.
+
+### Depolarizing Noise
+Simulates the effect of qubits losing their state toward a maximally mixed state.  
+This is the standard **"white noise"** of quantum computing.
+
+### Amplitude Damping
+Represents **T1 relaxation (energy loss)**.  
+This is an asymmetric noise model where qubits decay from ∣1⟩ to ∣0⟩, critical for studying superconducting hardware.
+
+### Transpilation (10q)
+Circuits are mapped to a **hardware topology (heavy-hex or grid)**.  
+Used to study how SWAP gates and routing overhead affect final results.
 
 ---
 
-## 📊 2. Feature Description
+## 📊 2. Feature Engineering: Structural Metrics
 
-When you switch to the **ML Training** tab, the system automatically parses the CSV file and extracts numerical features. These metrics describe the structure and complexity of the quantum circuit.
+Why do we extract these specific features?  
+In QML, the **structure ("shape") of a circuit directly impacts performance**.
 
-**Key structural metrics:**
-* **`n_qubits` & `depth`:** Physical size of the circuit. Depth determines the coherence time required for execution.
-* **`gate_entropy`:** Entropy of the gate distribution. Shows how uniformly or “chaotically” gates are distributed among qubits.
-* **`meyer_wallach`:** Meyer‑Wallach measure. A scalar describing the degree of global quantum entanglement in the final circuit state. A value close to 1 means maximal entanglement.
-* **`adjacency`:** Connectivity graph density. Shows how actively qubits interact with each other via two‑qubit gates (CX).
-* **Gate counters (`total_gates`, `cx_count`, `rx_count`, etc.):** Exact number of applied operations. Special attention should be paid to `cx_count`, because CNOT gates introduce the most noise on real hardware.
+- **gate_entropy**  
+  Measures distribution of gates.  
+  High entropy → complex, less repetitive circuits → harder for classical models to learn.
+
+- **meyer_wallach**  
+  Quantifies **global entanglement**.  
+  Entanglement provides quantum advantage but increases sensitivity to noise.
+
+- **adjacency**  
+  Represents qubit interaction graph density.  
+  High adjacency → faster information spread, but higher risk of cross-talk errors.
+
+- **cx_count (Two-Qubit Gates)**  
+  The most critical complexity metric.  
+  On NISQ devices, CNOT gates are **10x–100x noisier** than single-qubit gates.
 
 ---
 
-## 🎯 3. Target Variables
+## 🎯 3. Multi-Target Regression (The Bloch Vector)
 
-In the basic experiment on the ML tab, the model is trained to predict the **Global Z‑axis Expectation Value** (`ideal_expval_Z_global`). 
+Unlike traditional benchmarks that focus on a single observable, QSBench targets the **full global Bloch vector**:
 
-* **What does this mean?** It is the averaged measurement outcome of the ideal quantum state (ranging from -1 to 1). 
-* **Why are other targets hidden?** The dataset contains local expectation values (`ideal_expval_Z_q0`, `error_Z_global`, etc.). They are excluded from the list of available features to avoid data leakage when training the regressor.
+[⟨X⟩global, ⟨Y⟩global, ⟨Z⟩global]
 
 ---
 
-## 🤖 4. How to Use the ML Training Module
+### Why predict all three?
 
-1. **Select the dataset:** Choose one of the four packs (e.g., Amplitude Damping).
-2. **Select metrics:** Pick the features on which the model will be trained. Recommended baseline set: *gate_entropy, meyer_wallach, depth, cx_count*.
-3. **Training:** When you click the “Execute Baseline” button, the system splits the data (80% Train / 20% Test) and trains a **Random Forest Regressor** (100 trees, depth 10).
-4. **Result analysis:**
-   * **Parity Plot (Scatter):** Shows how accurately predictions align with the ideal diagonal line.
-   * **Feature Importance:** Which metrics contributed most to the prediction (useful for understanding how topology affects the outcome).
-   * **Residuals:** Distribution of prediction errors.
+A quantum state is a point on (or inside) the **Bloch sphere**.
+
+- Predicting only Z gives an incomplete picture  
+- Multi-target regression learns correlations between:
+  - circuit structure  
+  - full quantum state orientation  
+  - behavior in Hilbert space  
+
+---
+
+## 🤖 4. Using the ML Analytics Module
+
+The Hub uses a **Random Forest Regressor** to establish a baseline of predictability.
+
+### Workflow
+
+1. **Select Dataset**  
+   Choose a noise model and observe how it affects predictability.
+
+2. **Select Features**  
+   Recommended starting set:
+   - `gate_entropy`
+   - `meyer_wallach`
+   - `depth`
+   - `cx_count`
+
+3. **Execute Baseline**  
+   Performs an **80/20 train-test split**.
+
+4. **Analyze the Triple Parity Plot**
+
+   - 🔴 **Diagonal Red Line** → perfect prediction  
+   - 📈 **Clustering near line** → strong predictive signal  
+   - 🔍 **Basis comparison**:
+     - Z often easier to predict  
+     - X/Y depend more on circuit structure  
+     - reveals architectural biases (HEA vs QFT, etc.)
 
 ---
 
 ## 🔗 5. Project Resources
-* 🤗 [**Hugging Face**](https://huggingface.co/QSBench)
-* 💻 [**GitHub**](https://github.com/QSBench)
-* 🌐 [**Project Website**](https://qsbench.github.io)
+
+- 🤗 Hugging Face Datasets — download dataset shards  
+- 💻 GitHub Repository — QSBench generator source code  
+- 🌐 Official Website — documentation and benchmarking leaderboards  
+
+---
+
+*QSBench — Synthetic Quantum Dataset Benchmarks*