Metadata-Version: 2.4
Name: quantum-flex
Version: 0.1.2
Summary: 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.
Project-URL: Homepage, https://github.com/hinanohart/quantum-flex
Project-URL: Documentation, https://github.com/hinanohart/quantum-flex#readme
Project-URL: Repository, https://github.com/hinanohart/quantum-flex
Project-URL: Issues, https://github.com/hinanohart/quantum-flex/issues
Project-URL: Changelog, https://github.com/hinanohart/quantum-flex/blob/main/CHANGELOG.md
Project-URL: Real-hardware data, https://github.com/hinanohart/quantum-flex/tree/main/data/runs
Project-URL: Failure museum, https://github.com/hinanohart/quantum-flex/tree/main/src/quantum_flex/experiments/_wip
Author: quantum-flex contributors
License: MIT License
        
        Copyright (c) 2026 quantum-flex contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
License-File: LICENSE-DATA
Keywords: bell-inequality,chsh,ibm-quantum,mermin-peres,qaoa,qiskit,quantum-art,quantum-computing,quantum-supremacy,quantum-teleportation,quantum-visualization,reproducible-research,scientific-visualization,vqe
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy<3.0,>=1.26
Requires-Dist: qiskit-aer>=0.17
Requires-Dist: qiskit<3.0,>=2.0
Provides-Extra: all
Requires-Dist: imageio-ffmpeg>=0.5; extra == 'all'
Requires-Dist: imageio>=2.34; extra == 'all'
Requires-Dist: pillow>=12.1.1; extra == 'all'
Requires-Dist: pyscf>=2.5; extra == 'all'
Requires-Dist: qiskit-ibm-runtime>=0.46; extra == 'all'
Provides-Extra: art
Requires-Dist: imageio-ffmpeg>=0.5; extra == 'art'
Requires-Dist: imageio>=2.34; extra == 'art'
Requires-Dist: pillow>=12.1.1; extra == 'art'
Provides-Extra: chemistry
Requires-Dist: pyscf>=2.5; extra == 'chemistry'
Provides-Extra: dev
Requires-Dist: bandit[toml]>=1.7; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: nbformat>=5.10; extra == 'dev'
Requires-Dist: papermill>=2.6; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: ibm
Requires-Dist: qiskit-ibm-runtime>=0.46; extra == 'ibm'
Description-Content-Type: text/markdown

# quantum-flex

[![PyPI version](https://img.shields.io/pypi/v/quantum-flex.svg)](https://pypi.org/project/quantum-flex/)
[![Python versions](https://img.shields.io/pypi/pyversions/quantum-flex.svg)](https://pypi.org/project/quantum-flex/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Data: CC BY 4.0](https://img.shields.io/badge/Data-CC%20BY%204.0-lightgrey.svg)](LICENSE-DATA)
[![CI](https://github.com/hinanohart/quantum-flex/actions/workflows/ci.yml/badge.svg)](https://github.com/hinanohart/quantum-flex/actions/workflows/ci.yml)
[![CodeQL](https://github.com/hinanohart/quantum-flex/actions/workflows/codeql.yml/badge.svg)](https://github.com/hinanohart/quantum-flex/actions/workflows/codeql.yml)

> **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/`](data/runs/) under
**CC BY 4.0**, so anybody can re-render the figures or re-analyse the data.

---

## Install

```bash
# 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

```python
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

```bash
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

```bash
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/`](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:

```bash
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](CONTRIBUTING.md) for the full guidelines, including
the JSON record schema and the figure-style guide.

---

## Citation

```bibtex
@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  = {MIT (code) + CC BY 4.0 (data)},
}
```

---

## Licenses

  - **Source code** (everything under `src/`, `tests/`, configuration, build
    scripts): [MIT License](LICENSE).
  - **Data and imagery** (`data/runs/*.json`, `gallery/**`, notebook outputs):
    [Creative Commons BY 4.0](LICENSE-DATA).

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

---

## Acknowledgements

Built with [Qiskit](https://www.ibm.com/quantum/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.
