# 🌌 QSBench: Entanglement Score Regression Guide Welcome to the **QSBench Regression Hub**. This tool demonstrates how Machine Learning can predict the **degree of quantum entanglement** β€” measured by the **Meyer–Wallach score** β€” using only circuit structure and topology. --- ## ⚠️ Important: Demo Dataset Notice This Space uses **demo shards** of the QSBench datasets. - **Limited size:** The dataset is intentionally reduced. - **Impact:** Model performance may be unstable or noisy. - **Goal:** Showcase how structural features correlate with entanglement β€” not achieve production-level accuracy. --- ## 🧠 1. What is Being Predicted? The model predicts: ### `meyer_wallach` A continuous entanglement measure: - **0.0 β†’ No entanglement** - **1.0 β†’ Maximum entanglement** This metric captures how strongly qubits are globally correlated in a circuit. --- ## 🧩 2. How the Model β€œSees” a Circuit The model does **not simulate quantum states**. Instead, it uses **structural proxies**: ### πŸ”Ή Topology Features - `adj_density` β€” how densely qubits interact - `adj_degree_mean` β€” average connectivity - `adj_degree_std` β€” variability in connectivity β†’ These reflect **entanglement potential** in the circuit graph. --- ### πŸ”Ή Gate Structure - `total_gates` - `single_qubit_gates` - `two_qubit_gates` - `cx_count` β†’ Two-qubit gates are the **primary drivers of entanglement**. --- ### πŸ”Ή Complexity Metrics - `depth` - `gate_entropy` β†’ Capture how β€œdeep” and β€œstructured” the circuit is. --- ### πŸ”Ή QASM-derived Signals - `qasm_length` - `qasm_line_count` - `qasm_gate_keyword_count` β†’ Lightweight proxies for circuit complexity without parsing semantics. --- ## πŸ€– 3. Model Overview The system uses: ### Random Forest Regressor - Works well on tabular data - Handles non-linear relationships - Provides feature importance Pipeline includes: - Missing value imputation - Feature scaling - Ensemble regression --- ## πŸ“Š 4. Understanding the Results After clicking **"Train & Evaluate"**, you get: --- ### A. Actual vs Predicted - Each point = one circuit - Diagonal line = perfect prediction β†’ The closer to the line β†’ the better --- ### B. Residual Distribution - Shows prediction errors - Centered around 0 β†’ good model β†’ Wide spread = uncertainty or weak features --- ### C. Feature Importance Top contributing features to prediction. Typical patterns: - `cx_count` β†’ strong signal - `adj_density` β†’ topology influence - `depth` β†’ complexity contribution --- ## πŸ“‰ 5. Metrics Explained - **RMSE** β€” penalizes large errors - **MAE** β€” average absolute error - **RΒ²** β€” goodness of fit (1 = perfect) --- ## πŸ§ͺ 6. Experimentation Tips Try: - Removing `cx_count` β†’ see how performance drops - Using only topology β†’ isolate structural effect - Increasing trees β†’ more stable predictions - Changing test split β†’ robustness check --- ## πŸ”¬ 7. Key Insight > Entanglement is not random β€” it is encoded in circuit structure. Even without simulation: - Gate distribution - Connectivity - Depth …already contain enough signal to estimate entanglement. --- ## πŸ”— 8. Project Resources - πŸ€— Hugging Face: https://huggingface.co/QSBench - πŸ’» GitHub: https://github.com/QSBench - 🌐 Website: https://qsbench.github.io