quantum-flex 0.1.0

Real-hardware Qiskit experiments and quantum visualizations — CHSH Bell, 100-qubit supremacy, Mermin-Peres magic square, teleportation, mandala/terrain art, and a museum of honest failures.

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_chsh_S=2.69.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_chsh_S=2.69.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" concept is borrowed from the yuragi project, which set the precedent of committing the kill-shots one's own hypotheses received.