Create GUIDE.md

GUIDE.md

@@ -0,0 +1,62 @@
+# 🌌 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.
+
+---
+
+## 📂 1. Dataset Architecture
+
+QSBench provides unified datasets for the *Quantum Machine Learning (QML)* task. In this demo, 4 core datasets are available:
+
+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.
+
+### 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).
+
+---
+
+## 📊 2. Feature Description
+
+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.
+
+**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.
+
+---
+
+## 🎯 3. Target Variables
+
+In the basic experiment on the ML tab, the model is trained to predict the **Global Z‑axis Expectation Value** (`ideal_expval_Z_global`). 
+
+* **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.
+
+---
+
+## 🤖 4. How to Use the ML Training Module
+
+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.
+
+---
+
+## 🔗 5. Project Resources
+* 🤗 [**Hugging Face**](https://huggingface.co/QSBench)
+* 💻 [**GitHub**](https://github.com/QSBench)
+* 🌐 [**Project Website**](https://qsbench.github.io)