quantum-flex

Real-hardware Qiskit experiments and quantum visualizations — with the failures kept on display.

quantum-flex is a curated, reproducible collection of small quantum-computing experiments executed on IBM Quantum's 156-qubit Heron r2 hardware (ibm_fez), packaged with the rendering code that turned each measurement record into a static figure or animated video.

It also keeps a failure museum (experiments/_wip/) for hypotheses that were honestly killed by the data — because reviewers, students, and your future self deserve to see the misses, not just the wins.

---

Highlights

Experiment	Result	Backend	Verdict
CHSH Bell inequality	S = 2.6967 > 2 (classical bound)	ibm_fez (156q Heron r2)	Bell violation reproduced
100-qubit unique-state circuit	4 000 / 4 000 unique bitstrings	ibm_fez	Beyond classical-RAM enumeration
Quantum teleportation	Avg fidelity 0.97	ibm_fez	3-qubit protocol verified
Mermin–Peres magic square	Avg 96.4 % > classical bound 88.9 %	ibm_fez	Quantum pseudo-telepathy confirmed across all 9 cells
H₂ VQE	E = −1.2851 Ha (chem. err 13 %)	ibm_fez	Minimal-basis hydrogen molecule
QAOA on 144-qubit graph matching	0 / many valid solutions (noise-dominated)	ibm_fez	Honest failure — see _wip/qaoa_144q_collapsed/

All raw measurement counts are committed under data/runs/ under CC BY 4.0, so anybody can re-render the figures or re-analyse the data.

---

Install

# Core: circuit construction + Aer simulation
pip install quantum-flex

# Add real-hardware execution on IBM Quantum
pip install "quantum-flex[ibm]"

# Add animation / video output (mp4, gif)
pip install "quantum-flex[art]"

# Everything (chemistry + ibm + art)
pip install "quantum-flex[all]"

Python 3.10 – 3.13. The core install carries only qiskit, qiskit-aer, numpy, and matplotlib. Heavy or hardware-specific dependencies are opt-in extras.

---

Quick start — re-render an experiment from committed data

from quantum_flex.core.record import RunRecord
from quantum_flex.art import mandala

# Load a real-hardware execution log (no IBM account needed)
record = RunRecord.load("data/runs/2026-04-04_bell_chsh.json")
print(f"S = {record.metrics['S_chsh']:.4f}  on  {record.backend['name']}")

# Or render an art piece from the same data
mandala.render(record, output="mandala.png")

Quick start — run on real IBM Quantum hardware

export QISKIT_IBM_TOKEN="..."   # never commit this

# Run the CHSH experiment (4 000 shots) on whichever device is available
python -m quantum_flex.experiments.bell_chsh.run \
    --backend ibm_fez --shots 4000

# A new RunRecord JSON appears under data/runs/.

Quick start — start a new experiment

quantum-flex new my_quantum_test
# → src/quantum_flex/experiments/_wip/my_quantum_test/
#   ├── README.md     ← describe hypothesis, method, expected result
#   ├── circuit.py    ← define the QuantumCircuit
#   ├── run.py        ← Aer or IBM run, writes a RunRecord JSON
#   ├── visualize.py  ← JSON → PNG / MP4
#   └── NEXT_STEPS.md ← what you would try next

The _wip/ directory is not a staging area for cleanup — it is a permanent public record. When an experiment matures, quantum-flex promote my_quantum_test moves it from _wip/ to experiments/, but the history of any earlier raw runs stays in git.

---

Repository layout

quantum-flex/
├── src/quantum_flex/
│   ├── core/                    # shared helpers — runner, RunRecord, style, IBM client
│   ├── cli.py                   # `quantum-flex new …` template scaffolding
│   ├── experiments/
│   │   ├── _template/           # what `new` copies from
│   │   ├── _wip/                # honest failures and works-in-progress
│   │   ├── bell_chsh/
│   │   ├── teleportation/
│   │   ├── supremacy_100q/
│   │   ├── mermin_peres/
│   │   └── h2_vqe/
│   └── art/                     # visualizations driven by RunRecord JSON
│       ├── mandala.py
│       ├── terrain.py
│       ├── interference.py
│       ├── game_of_life.py
│       ├── wigner_anim.py
│       └── pinball.py
├── data/runs/                   # CC BY 4.0 — every committed JSON is real-hardware
├── gallery/                     # rendered PNG / MP4 (large files via Release assets)
├── notebooks/                   # Colab-ready Jupyter walkthroughs
├── tests/                       # Aer-only by default; real-hardware tests gated
├── examples/
└── docs/

---

Why a "failure museum"?

A research repository that only shows successes is a selection-bias machine. Anybody using it has to re-discover, by themselves and from scratch, every dead end the original author already walked into. That is a giant tax on everybody else's time.

quantum-flex commits raw failure data deliberately. Every directory under src/quantum_flex/experiments/_wip/ includes:

• the original hypothesis,
• the circuit,
• the raw measurement counts (under data/runs/ like any other run),
• a LESSONS_LEARNED.md explaining why it failed,
• and what would need to change for it to work.

Two opening exhibits in v0.1.0:

• qaoa_144q_collapsed/ — A QAOA attempt at graph matching on a 144-qubit problem with depth ~3000. The result was indistinguishable from uniform noise (0 valid solutions). NISQ is not yet ready for problems at this depth.
• quantum_lost_to_hungarian/ — Quantum-optimization vs. classical Hungarian algorithm on the same matching task. Classical won 200 vs. 588 cells assigned (+193 %).

---

Reproducibility checklist

Every committed run record contains:

• qflex_version, qiskit_version, qiskit_aer_version
• backend.name, backend.type, backend.qubits, backend.version
• execution.shots, session_id, job_id, timestamp_jst, duration_seconds
• circuit.qasm (full OpenQASM source), circuit.depth, circuit.gate_count
• raw_counts (the bare measurement histogram)
• metrics (whatever the experiment computed from raw_counts)

IBM Quantum API tokens, account names, and any personally-identifiable session metadata are redacted before commit. Only public IBM job/session identifiers (which carry no credentials) are retained.

To verify a record:

python -m quantum_flex.core.record verify data/runs/2026-04-04_bell_chsh.json

---

Hardware time and noise honesty

These results were obtained over roughly 200 seconds of cumulative real-hardware execution time on IBM Quantum's Open Plan (10 minutes / month allowance, residual ~400 s at the time of measurement). On any given device the calibration changes hourly: re-running bell_chsh.run tomorrow will give a slightly different S value. That is a feature, not a bug — data/runs/ preserves the snapshot, and your re-run will accumulate alongside it.

For experiments that exceed Open-Plan minutes (most multi-thousand-shot sweeps), you will need a paid IBM Quantum subscription or institutional allocation. quantum-flex never spends your minutes without an explicit --backend flag pointing to a real device.

---

Contributing

Bug reports, new experiments, and (especially) new failures are welcome.

1. Fork and clone.
2. pip install -e ".[dev,all]"
3. quantum-flex new <my_experiment> to scaffold under _wip/.
4. Open a draft PR early. We do not require an experiment to "succeed" before merging — we require it to be honestly recorded and reproducible.

See CONTRIBUTING.md for the full guidelines, including the JSON record schema and the figure-style guide.

---

Citation

@software{quantum_flex,
  title    = {quantum-flex: Real-hardware Qiskit experiments and quantum visualizations},
  author   = {{quantum-flex contributors}},
  year     = {2026},
  url      = {https://github.com/hinanohart/quantum-flex},
  license  = {Apache-2.0 (code) + CC BY 4.0 (data)},
}

---

Licenses

• Source code (everything under src/, tests/, configuration, build scripts): Apache License 2.0.
• Data and imagery (data/runs/*.json, gallery/**, notebook outputs): Creative Commons BY 4.0.

The dual-licensing is deliberate: code carries patent grants, data carries attribution requirements that are appropriate for a benchmark / dataset.

---

Acknowledgements

Built with Qiskit and executed on the IBM Quantum Network's Heron r2 devices. The "failure museum" convention — committing failed experiments alongside their post-mortems rather than silently dropping them — is borrowed from prior research-code work the author did on honest negative-result reporting.