Metadata-Version: 2.4
Name: qlro
Version: 0.2.0
Summary: Show us your quantum circuit. We tell you where to run it.
Author-email: Yeonwoo Oh <linslet77@gmail.com>
Maintainer-email: Yeonwoo Oh <linslet77@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/linsletoh/qlro
Project-URL: Documentation, https://github.com/linsletoh/qlro/blob/main/WCPP_SPEC.md
Project-URL: Paper, https://doi.org/10.5281/zenodo.19601532
Project-URL: Simulator, https://qlro-three.vercel.app/simulator
Project-URL: Issues, https://github.com/linsletoh/qlro/issues
Keywords: quantum,benchmarking,recommendation,qiskit,metriq,wcpp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.5.0
Requires-Dist: qiskit>=1.0.0
Requires-Dist: qiskit-aer>=0.13.0
Provides-Extra: server
Requires-Dist: fastapi>=0.104.0; extra == "server"
Requires-Dist: uvicorn>=0.24.0; extra == "server"
Requires-Dist: sqlalchemy>=2.0.0; extra == "server"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: httpx>=0.25.0; extra == "dev"

# Qlro

**Show us your quantum circuit. We'll tell you where to run it.**

```python
from qiskit import QuantumCircuit
import qlro

qc = QuantumCircuit(4)
qc.h(0); qc.cx(0, 1); qc.cx(1, 2); qc.cx(2, 3)
qc.measure_all()

result = qlro.recommend(qc, category="chemistry")
result.primary      # → 'H2-2'
result.primary_fit  # → 0.8140
```

Qlro is a quantum device recommendation engine. Give it a circuit and a workload type, and it ranks every available quantum device by how well that device fits *your specific workload* — based on real benchmark data from [Metriq](https://metriq.info) (Unitary Foundation), not vendor marketing.

## Install

```bash
pip install qlro
```

Ships with a snapshot of the Metriq benchmark dataset. No API keys, no accounts, no internet required.

## How it works

1. **You have a quantum circuit** (Qiskit `QuantumCircuit` or OpenQASM string).
2. **You tell Qlro what kind of workload it is**: `chemistry`, `simulation`, `optimization`, or `ml`.
3. **Qlro scores every quantum device** across four capability axes:
   - **Γ (Connectivity)** — verified entanglement coverage across the chip
   - **Φ (Coherence)** — information survival over circuit depth
   - **F (Fidelity)** — per-operation accuracy
   - **T (Throughput)** — effective operations per second
4. **You get a ranked list** with scores, uncertainty bands, and the Metriq commit hash so everything is auditable.

The scoring framework is called [WCPP (Workload-Conditioned Physical Projection)](WCPP_SPEC.md). Every number comes from physics, not heuristics. See the [full specification](WCPP_SPEC.md) for the math, axioms, and proofs.

## What Qlro does NOT do

- **Does not run your circuit.** You run it yourself on IBM Quantum, AWS Braket, Quantinuum, etc.
- **Does not build or optimize circuits.** That's Classiq, Qiskit transpiler, etc.
- **Does not measure hardware.** That's [Metriq](https://metriq.info) / Unitary Foundation. We consume their data.
- **Does not hide uncertainty.** Every score shows what's measured vs. estimated vs. assumed.

## Jupyter integration

Qlro auto-renders as an inline HTML table in Jupyter notebooks. For quick interactive use:

```python
%load_ext qlro.jupyter
%qlro my_circuit chemistry
```

See [`examples/vqe_h2_with_qlro.ipynb`](examples/vqe_h2_with_qlro.ipynb) for a complete walkthrough.

## Try the interactive simulator

Don't understand the problem Qlro solves? [Play the simulator](https://qlro-three.vercel.app/simulator) — a 5-minute browser game where you play as a quantum engineer under a paper deadline, with and without Qlro.

## Update benchmark data

```bash
python scripts/sync_metriq.py
```

Pulls the latest from the [metriq-data](https://github.com/unitaryfoundation/metriq-data) repository. Every recommendation is anchored to a specific Metriq commit for reproducibility.

## Development

```bash
git clone https://github.com/linsletoh/qlro.git
cd qlro
pip install -e ".[dev,server]"
pytest  # 107 tests
```

## Architecture

```
src/qlro/
├── scoring/          ← WCPP reference implementation
│   ├── physics.py    ← benchmark → physical value transforms
│   ├── axes.py       ← capability axis aggregation
│   ├── composition.py← workload-conditioned geometric mean
│   └── wcpp.py       ← qlro_fit() entry point
├── public_api.py     ← recommend(), log_outcome()
├── jupyter.py        ← %qlro magic for notebooks
├── runner/           ← Qiskit Aer experiment runner
├── comparison/       ← normalization pipeline
├── recommendation/   ← scoring + explanation engine
└── api.py            ← FastAPI web application
```

## Key documents

- [**WCPP_SPEC.md**](WCPP_SPEC.md) — Full technical specification of the scoring framework
- [**ROADMAP.md**](ROADMAP.md) — Product roadmap + positioning copy
- [**papers/wcpp-draft.md**](papers/wcpp-draft.md) — WCPP preprint (published on Zenodo, [DOI: 10.5281/zenodo.19601379](https://doi.org/10.5281/zenodo.19601379))
- [**test_results/**](test_results/) — Validation records with external vendor cross-references

## Citation

If you use Qlro or WCPP in research, please cite the Zenodo preprint:

```bibtex
@misc{oh2026wcpp,
  author    = {Oh, Yeonwoo},
  title     = {{Workload-Conditioned Physical Projection: A Vendor-Neutral Framework for Quantum Device Selection}},
  year      = {2026},
  publisher = {Zenodo},
  version   = {0.3},
  doi       = {10.5281/zenodo.19601532},
  url       = {https://doi.org/10.5281/zenodo.19601532}
}
```

Latest version DOI: [**10.5281/zenodo.19601532**](https://doi.org/10.5281/zenodo.19601532) (v0.3, includes full technical specification `WCPP_SPEC.md`)

Previous version: v0.2 at [10.5281/zenodo.19601379](https://doi.org/10.5281/zenodo.19601379) (archived).

## License

Apache 2.0
