qlro 0.2.0__tar.gz

qlro-0.2.0/PKG-INFO

@@ -0,0 +1,159 @@
+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

qlro-0.2.0/README.md

@@ -0,0 +1,126 @@
+# 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

qlro-0.2.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qlro"
+version = "0.2.0"
+description = "Show us your quantum circuit. We tell you where to run it."
+requires-python = ">=3.11"
+license = {text = "Apache-2.0"}
+readme = "README.md"
+authors = [
+    {name = "Yeonwoo Oh", email = "linslet77@gmail.com"},
+]
+maintainers = [
+    {name = "Yeonwoo Oh", email = "linslet77@gmail.com"},
+]
+keywords = ["quantum", "benchmarking", "recommendation", "qiskit", "metriq", "wcpp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Physics",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "pydantic>=2.5.0",
+    "qiskit>=1.0.0",
+    "qiskit-aer>=0.13.0",
+]
+
+[project.optional-dependencies]
+server = [
+    "fastapi>=0.104.0",
+    "uvicorn>=0.24.0",
+    "sqlalchemy>=2.0.0",
+]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.23.0",
+    "httpx>=0.25.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/linsletoh/qlro"
+Documentation = "https://github.com/linsletoh/qlro/blob/main/WCPP_SPEC.md"
+Paper = "https://doi.org/10.5281/zenodo.19601532"
+Simulator = "https://qlro-three.vercel.app/simulator"
+Issues = "https://github.com/linsletoh/qlro/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+qlro = ["data/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

qlro-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

qlro-0.2.0/src/qlro/__init__.py

@@ -0,0 +1,37 @@
+"""Qlro: the evaluation layer for quantum pilot decisions.
+
+Primary use is as an importable library:
+
+    >>> 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  # auto-renders in Jupyter
+
+See WCPP_SPEC.md and ROADMAP.md at the repo root for the full framework
+and product context.
+"""
+
+from qlro.public_api import (
+    CircuitInfo,
+    DeviceRanking,
+    Recommendation,
+    log_outcome,
+    recommend,
+)
+from qlro.scoring.priors import WorkloadCategory
+
+__all__ = [
+    "recommend",
+    "log_outcome",
+    "Recommendation",
+    "DeviceRanking",
+    "CircuitInfo",
+    "WorkloadCategory",
+]