⚛️ Quantum Circuit Noise Analysis Dashboard

PROJECT-Q Community — 30-Day Quantum Challenge — Capstone Project (Day 24+)

Quantum computers available today are NISQ (Noisy Intermediate-Scale Quantum) devices — unlike the clean, idealized circuits used in textbooks and simulators, real qubits are constantly disturbed by heat, stray electromagnetic fields, and imperfect control pulses. This dashboard makes that noise measurable and visible:

• Runs a quantum circuit in a perfect, noiseless world (ideal Aer simulator)
• Runs the same circuit again under a realistic noise model — choose between depolarizing, bit-flip, phase-flip, thermal relaxation (T1/T2), or a combined device-like model (all layered together, plus readout error)
• Compares both results side by side
• Quantifies the difference with three complementary metrics: Total Variation Distance, fidelity, and Hellinger distance
• Shows the difference using interactive charts in a Streamlit dashboard, so anyone can see how much the noise changed the output
• Includes a noise-sweep dataset (data/noise_dataset.csv, 180 rows) generated across every circuit × every noise model × 9 noise levels
• Renders the system architecture and workflow diagrams directly in the app

Full problem statement, objectives, and design rationale: see docs/problem_statement.md.

Tech stack

• Python 3.10+
• Qiskit + Qiskit Aer (circuit construction & noise modeling)
• NumPy (metrics: TVD, fidelity, Hellinger distance)
• Matplotlib (dark "quantum lab" themed charts)
• Streamlit (interactive dashboard)

Project structure

quantum-noise-dashboard/
├── data/
│   └── noise_dataset.csv         # generated noise-sweep dataset (180 rows)
├── notebooks/
│   └── exploratory_analysis.ipynb
├── docs/
│   ├── problem_statement.md      # full design document
│   ├── architecture_diagram.svg
│   └── workflow_diagram.svg
├── src/
│   ├── circuits.py                # Bell, GHZ, superposition, custom sequence
│   ├── noise_models.py            # depolarizing, bit/phase-flip, thermal, combined
│   ├── simulator.py                # ideal / noisy execution logic
│   ├── metrics.py                  # TVD, fidelity, Hellinger distance
│   ├── visualize.py                 # Matplotlib plotting (dark theme)
│   └── dataset_generator.py        # circuit x noise_type x noise_level sweep
├── dashboard/
│   ├── app.py                      # Streamlit dashboard entry point
│   └── components/
│       └── architecture.py         # renders architecture/workflow diagrams
├── results/                        # saved comparison charts (CLI mode)
├── main.py                         # CLI entry point
├── requirements.txt
└── README.md

Setup (VS Code / local machine)

# 1. Create & activate a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 2. Install dependencies
pip install -r requirements.txt

Usage

Option A — Interactive dashboard (recommended)

Run from the project root:

streamlit run dashboard/app.py

Opens a browser tab with the system architecture diagram up top, then a sidebar where you pick a circuit, a noise model, noise level, and shot count. Click Run comparison to see the ideal-vs-noisy bar chart, TVD/fidelity/Hellinger metrics, and the full noise-sweep dataset with trend charts.

Option B — Command line

# Run a single comparison (Bell state, combined noise, 2%)
python main.py --circuit bell_state --noise 0.02

# Try a specific noise channel
python main.py --circuit ghz_state --qubits 4 --noise-type bit_flip --noise 0.05

# Regenerate the full noise-sweep dataset (data/noise_dataset.csv)
python main.py --generate-dataset

Charts from CLI runs are saved to results/.

Option C — Notebook

Open notebooks/exploratory_analysis.ipynb for ad-hoc exploration of the generated dataset.

Noise models

Model	Channel	What it represents
depolarizing	Depolarizing error	Random Pauli scrambling of the qubit state after each gate
bit_flip	Pauli-X channel	Flips |0⟩ ↔ |1⟩ with some probability
phase_flip	Pauli-Z channel	Corrupts relative phase / interference, not populations
thermal_relaxation	T1/T2 relaxation	Amplitude damping & dephasing — decoherence over time
combined	Depolarizing + thermal + readout, layered	Approximates a real device (e.g. IBM Quantum backend)

Every model takes a single noise_level in [0, 1] so strength can be compared consistently across channels.

Comparison metrics

Given an ideal distribution p and noisy distribution q:

• Total Variation Distance — TVD(p, q) = 0.5 * Σ|p(x) − q(x)|. 0 = identical, 1 = disjoint.
• Fidelity (Bhattacharyya coefficient) — F(p, q) = Σ√(p(x)·q(x)). 1 = identical, 0 = disjoint.
• Hellinger distance — H(p, q) = √(0.5 * Σ(√p(x) − √q(x))²). 0 = identical, 1 = disjoint.

Using three metrics guards against any single metric's blind spots — see docs/problem_statement.md §9 for the full rationale.

About the dataset

data/noise_dataset.csv is generated, not downloaded — produced by src/dataset_generator.py, which sweeps 4 benchmark circuits × 5 noise models × 9 noise levels (0% to 20%), running ideal + noisy Qiskit Aer simulations for each combination. This keeps the dataset fully reproducible and tied directly to the circuits and noise models used elsewhere in the project. Regenerate anytime with:

python main.py --generate-dataset

Status

Current stage: simulator-validated, multi-channel noise analysis complete, with an interactive dashboard and full design documentation. Next stage: execution on real IBM Quantum hardware, comparing simulator vs. hardware results.

Roadmap

• Project foundation, folder structure, core circuit module
• Depolarizing, bit-flip, phase-flip, thermal-relaxation, combined noise models
• Ideal vs. noisy comparison — TVD, fidelity, Hellinger distance
• Interactive Streamlit dashboard with dark "quantum lab" theme
• Noise-sweep dataset (circuits × noise models × levels)
• System architecture & workflow diagrams
• IBM Quantum hardware execution & simulator-vs-hardware comparison
• Final documentation, demo video, and submission