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]

       | +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