GUIDE.md

# 🌌 QSBench: Complete User Guide

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.

---

## ⚠️ Important: Demo Dataset Notice

The datasets currently loaded in this hub are **v1.0.0-demo versions**.

- **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.  

---

## 📂 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 Engineering: Structural Metrics

Why do we extract these specific features?  
In QML, the **structure ("shape") of a circuit directly impacts performance**.

- **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.

**Note on Feature Correlation:** While structural metrics (like `gate_entropy` or `depth`) describe the complexity of the circuit, they do not encode the specific rotation angles of individual gates. 
Therefore, predicting the exact expectation value using only structural features is an **extremely challenging task** (Non-Trivial Mapping).

---

## 🎯 3. Multi-Target Regression (The Bloch Vector)

Unlike traditional benchmarks that focus on a single observable, QSBench targets the **full global Bloch vector**:

[⟨X⟩global, ⟨Y⟩global, ⟨Z⟩global]

```text
       | +Z (0)
       |
  -----|---- +Y
      /|
     / | -Z (1)
   +X
```

---

### Why predict all three?

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.)

📉 **How to Interpret "Bad" Metrics?**

If you see a **negative** R2 or clustering around zero, don't panic. This is the expected behavior for standard regression on quantum data:

- **Mean Predictor Baseline:** In complex circuits (n=8, depth=6), expectation values naturally concentrate around 0. A model that simply predicts "0" for everything will have a low MAE but a zero/negative R2.

- **The Complexity Gap:** A negative R2 proves that the relationship between circuit shape and quantum output is highly non-linear.

- **Research Challenge:** Use these baseline results to justify the need for more advanced architectures like **Graph Neural Networks (GNNs)** or **Recursive Quantum Filters** that can process the gate sequence itself.

---

## 🔗 5. Project Resources

- 🤗 Hugging Face Datasets — download dataset shards  
- 💻 GitHub Repository — QSBench generator source code  
- 🌐 Official Website — documentation and benchmarking leaderboards  

---

*QSBench — Synthetic Quantum Dataset Benchmarks*