qlro 0.3.0

Describe your quantum workload. We recommend where to run it.

Qlro

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

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 (Unitary Foundation), not vendor marketing.

Install

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). Every number comes from physics, not heuristics. See the full specification 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 / 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:

%load_ext qlro.jupyter
%qlro my_circuit chemistry

See examples/vqe_h2_with_qlro.ipynb for a complete walkthrough.

Try the interactive simulator

Don't understand the problem Qlro solves? Play the simulator — a 5-minute browser game where you play as a quantum engineer under a paper deadline, with and without Qlro.

Update benchmark data

python scripts/sync_metriq.py

Pulls the latest from the metriq-data repository. Every recommendation is anchored to a specific Metriq commit for reproducibility.

Development

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 — Full technical specification of the scoring framework
• ROADMAP.md — Product roadmap + positioning copy
• papers/wcpp-draft.md — WCPP preprint (published on Zenodo, DOI: 10.5281/zenodo.19622226)
• test_results/ — Validation records with external vendor cross-references

Citation

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

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

Latest version DOI: 10.5281/zenodo.19622226 (v0.6, includes empirical axis priors, §8.8 sensitivity analysis, §8.9 Metriq Score baseline-invariance comparison, and the full technical specification WCPP_SPEC.md).

Concept DOI (always resolves to the latest version): 10.5281/zenodo.19601378.

Previous versions: v0.3 at 10.5281/zenodo.19601532, v0.2 at 10.5281/zenodo.19601379 (archived).

License

Apache 2.0