qversus 0.1.0__tar.gz

qversus-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felipe Santibáñez-Leal
+
+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 USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qversus-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: qversus
+Version: 0.1.0
+Summary: Canonical quantum-computing problems solved by real frameworks (Qiskit, PennyLane, Cirq, Stim) next to classical baselines, with replayable, seeded traces.
+Author: Felipe Santibanez-Leal
+License: MIT
+Project-URL: Homepage, https://github.com/fsantibanezleal/CAOS_QVersus
+Project-URL: Documentation, https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/docs/README.md
+Project-URL: Issues, https://github.com/fsantibanezleal/CAOS_QVersus/issues
+Project-URL: Changelog, https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/CHANGELOG.md
+Keywords: quantum computing,quantum algorithms,benchmark,classical baseline,qiskit,pennylane,cirq,stim,grover,qaoa,vqe,quantum error correction,surface code,education
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Education
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Provides-Extra: qiskit
+Requires-Dist: qiskit<3,>=2.4; extra == "qiskit"
+Requires-Dist: qiskit-aer>=0.17; extra == "qiskit"
+Provides-Extra: pennylane
+Requires-Dist: pennylane>=0.45; extra == "pennylane"
+Requires-Dist: networkx>=3.2; extra == "pennylane"
+Provides-Extra: cirq
+Requires-Dist: cirq-core>=1.6; extra == "cirq"
+Provides-Extra: stim
+Requires-Dist: stim>=1.16; extra == "stim"
+Requires-Dist: pymatching>=2.0; extra == "stim"
+Provides-Extra: learn
+Requires-Dist: scikit-learn>=1.5; extra == "learn"
+Provides-Extra: hardware
+Requires-Dist: qiskit<3,>=2.4; extra == "hardware"
+Requires-Dist: qiskit-ibm-runtime>=0.30; extra == "hardware"
+Provides-Extra: all
+Requires-Dist: qiskit<3,>=2.4; extra == "all"
+Requires-Dist: qiskit-aer>=0.17; extra == "all"
+Requires-Dist: pennylane>=0.45; extra == "all"
+Requires-Dist: networkx>=3.2; extra == "all"
+Requires-Dist: cirq-core>=1.6; extra == "all"
+Requires-Dist: stim>=1.16; extra == "all"
+Requires-Dist: pymatching>=2.0; extra == "all"
+Requires-Dist: scikit-learn>=1.5; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff==0.15.18; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: qiskit<3,>=2.4; extra == "dev"
+Requires-Dist: qiskit-aer>=0.17; extra == "dev"
+Requires-Dist: pennylane>=0.45; extra == "dev"
+Requires-Dist: networkx>=3.2; extra == "dev"
+Requires-Dist: cirq-core>=1.6; extra == "dev"
+Requires-Dist: stim>=1.16; extra == "dev"
+Requires-Dist: pymatching>=2.0; extra == "dev"
+Requires-Dist: scikit-learn>=1.5; extra == "dev"
+Dynamic: license-file
+
+# qversus
+
+[![CI](https://github.com/fsantibanezleal/CAOS_QVersus/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fsantibanezleal/CAOS_QVersus/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/qversus)](https://pypi.org/project/qversus/)
+[![License](https://img.shields.io/github/license/fsantibanezleal/CAOS_QVersus)](https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/LICENSE)
+
+**Canonical quantum-computing problems, solved by the real frameworks next to the classical baseline that is
+usually still more practical, with every run recorded as a replayable, seeded trace.**
+
+`qversus` separates *what* to compute from *how*. A `Problem` is a formulation (Grover search, MaxCut, the H2
+ground state, a surface-code memory, ...) with a set of parameter regimes (`Instance`s). A `Solver` is a thin
+adapter that attacks a problem with **one** real framework (Qiskit + Aer, PennyLane, Cirq, Stim + PyMatching)
+or with a classical method, and returns the same `SolverResult` shape whatever the framework. A registry pairs
+them, so running a quantum method and the classical baseline side by side is one loop, not one script per
+framework.
+
+Circuit-model solvers also return a `Trace`: the state after every gate (amplitudes, per-qubit Bloch vectors,
+probabilities), the circuit as a flat op list, and a seeded shot histogram. A run is a pure function of
+`(params, seed)`: with the same framework versions, the same inputs give the same bytes.
+
+The package makes no claim of quantum advantage. Every problem ships a classical baseline, and on these
+textbook-scale instances the classical method wins on wall time; what the quantum methods show are real
+phenomena (interference, entanglement, query separations, error-correction thresholds) at a scale a laptop
+simulates exactly.
+
+## Install
+
+```bash
+pip install qversus                 # core: NumPy only (formulations, registry, trace schema, RNG)
+pip install "qversus[all]"          # every simulator-based adapter
+```
+
+| Extra | Brings | Enables |
+|---|---|---|
+| `qiskit` | `qiskit>=2.4,<3`, `qiskit-aer>=0.17` | the circuit adapters (16 problems), the step tracer, the Aer noise model |
+| `pennylane` | `pennylane>=0.45`, `networkx` | QAOA cross-check, VQE on H2, the quantum-kernel classifier, the H2 Hamiltonian for the exact baseline |
+| `cirq` | `cirq-core>=1.6` | the third QAOA implementation |
+| `stim` | `stim>=1.16`, `pymatching>=2.0` | repetition and surface-code memories decoded by minimum-weight matching |
+| `learn` | `scikit-learn>=1.5` | the classical RBF-SVM baseline and the precomputed-kernel SVM |
+| `hardware` | `qiskit-ibm-runtime>=0.30` | the opt-in IBM Quantum adapter (real QPU, needs a token) |
+| `all` | every extra except `hardware` | |
+
+A missing framework disables only its own adapters (a warning names it); the rest of the registry works.
+
+## Quick start
+
+```python
+from qversus.registry import get_problem, solvers_for
+
+problem = get_problem("maxcut")
+instance = problem.instance("square")            # the 4-cycle; optimum cut = 4
+
+for solver in solvers_for(problem):              # QAOA on Qiskit, PennyLane and Cirq + two classical methods
+    result = solver.run(problem, instance, seed=42, shots=2048)
+    print(f"{result.paradigm:12} {result.solver:18} cut={result.value['cut']}  cost={result.cost}")
+```
+
+```python
+from qversus.registry import get_problem, solvers_for
+
+problem = get_problem("grover")
+instance = problem.instance("grover-4-10")       # N = 16 items, item 10 marked
+qiskit = next(s for s in solvers_for(problem) if s.framework == "qiskit")
+result = qiskit.run(problem, instance, seed=42, shots=2048)
+
+trace = result.trace.to_dict()                   # JSON-ready: steps, circuit_ops, measurements, provenance
+print(result.value, trace["measurements"]["counts"])
+```
+
+More: [quick start guide](https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/docs/guides/01_quickstart.md).
+
+## The catalogue
+
+Twenty problems in six families, 119 instances. Each has at least one quantum method and one classical baseline.
+
+| Problem | Family | Quantum solvers | Classical baseline |
+|---|---|---|---|
+| `single-qubit`, `qrng`, `interference` | fundamentals | Qiskit | Bloch/bit model, PRNG, wave optics |
+| `state-prep`, `chsh`, `teleportation`, `superdense` | entanglement | Qiskit | the amplitudes written down directly, local hidden variables, measure-and-resend, one bit per carrier |
+| `deutsch-jozsa`, `bernstein-vazirani`, `simon` | oracle algorithms | Qiskit | query-counting classical algorithms |
+| `grover`, `qft`, `qpe`, `shor` | flagship algorithms | Qiskit | linear scan, FFT, exact phase, trial division |
+| `maxcut`, `vqe`, `qml` | variational | Qiskit, PennyLane, Cirq | brute force + greedy, exact diagonalisation, RBF-SVM |
+| `noise`, `qec-repetition`, `qec-surface` | noise and QEC | Qiskit-Aer, Stim + PyMatching | the exact answer, the unprotected qubit |
+
+Per-problem parameters, result fields and the closed-form checks the tests enforce:
+[docs/problems](https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/docs/problems.md).
+
+## Contracts
+
+- **`Problem` / `Instance`**: identity (id, bilingual EN/ES title and concept, category, metric, references),
+  the instances, and a `live_capable` hint (small and noise-free enough to re-simulate interactively).
+- **`Solver` / `SolverResult`**: `run(problem, instance, seed, shots) -> SolverResult` with `value`, `cost`,
+  bilingual `notes`, an optional `trace`, `optimal` (an exact classical baseline) and `extra` (landscapes,
+  curves, kernel matrices). Paradigm is one of `quantum-sim`, `quantum-hardware`, `classical`.
+- **`Trace`** (schema `qversus-trace/1`): JSON-first and free of framework types, so a reader needs neither
+  Python nor a quantum SDK.
+- **Bit order**: amplitude and probability arrays use Qiskit's little-endian index (qubit 0 is the least
+  significant bit); count keys are that index in binary, highest qubit leftmost.
+
+Details: [docs/architecture](https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/docs/architecture.md).
+
+## Real hardware (opt-in)
+
+The `ibm-hardware` adapter submits small circuits to IBM Quantum (Open Plan, free tier) and returns the counts
+with the backend named in the provenance. It is never part of the default solver set: it is offered only when
+named explicitly **and** `QISKIT_IBM_TOKEN` is set. See
+[docs/solvers/06_ibm-hardware.md](https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/docs/solvers/06_ibm-hardware.md).
+
+## Development
+
+```bash
+python -m venv .venv && .venv/Scripts/python -m pip install -e ".[dev]"   # bash: .venv/bin/python
+python -m pytest                     # core, registry and physics tests
+python -m ruff check qversus tests
+python scripts/check_content_standards.py
+```
+
+CI runs lint, the tests, a core-only install check, and the repository guards on `develop` and `main`.
+Releases are tagged `vX.XX.XXX` and published to PyPI by trusted publishing
+([docs/guides/04_releasing.md](https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/docs/guides/04_releasing.md)).
+
+## Used by
+
+- **QLab** ([qlab.fasl-work.com](https://qlab.fasl-work.com)): a public, didactic quantum-computing lab whose
+  committed traces are produced by this engine.
+
+## License
+
+MIT. See [LICENSE](https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/LICENSE).

qversus-0.1.0/README.md

@@ -0,0 +1,129 @@
+# qversus
+
+[![CI](https://github.com/fsantibanezleal/CAOS_QVersus/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fsantibanezleal/CAOS_QVersus/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/qversus)](https://pypi.org/project/qversus/)
+[![License](https://img.shields.io/github/license/fsantibanezleal/CAOS_QVersus)](https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/LICENSE)
+
+**Canonical quantum-computing problems, solved by the real frameworks next to the classical baseline that is
+usually still more practical, with every run recorded as a replayable, seeded trace.**
+
+`qversus` separates *what* to compute from *how*. A `Problem` is a formulation (Grover search, MaxCut, the H2
+ground state, a surface-code memory, ...) with a set of parameter regimes (`Instance`s). A `Solver` is a thin
+adapter that attacks a problem with **one** real framework (Qiskit + Aer, PennyLane, Cirq, Stim + PyMatching)
+or with a classical method, and returns the same `SolverResult` shape whatever the framework. A registry pairs
+them, so running a quantum method and the classical baseline side by side is one loop, not one script per
+framework.
+
+Circuit-model solvers also return a `Trace`: the state after every gate (amplitudes, per-qubit Bloch vectors,
+probabilities), the circuit as a flat op list, and a seeded shot histogram. A run is a pure function of
+`(params, seed)`: with the same framework versions, the same inputs give the same bytes.
+
+The package makes no claim of quantum advantage. Every problem ships a classical baseline, and on these
+textbook-scale instances the classical method wins on wall time; what the quantum methods show are real
+phenomena (interference, entanglement, query separations, error-correction thresholds) at a scale a laptop
+simulates exactly.
+
+## Install
+
+```bash
+pip install qversus                 # core: NumPy only (formulations, registry, trace schema, RNG)
+pip install "qversus[all]"          # every simulator-based adapter
+```
+
+| Extra | Brings | Enables |
+|---|---|---|
+| `qiskit` | `qiskit>=2.4,<3`, `qiskit-aer>=0.17` | the circuit adapters (16 problems), the step tracer, the Aer noise model |
+| `pennylane` | `pennylane>=0.45`, `networkx` | QAOA cross-check, VQE on H2, the quantum-kernel classifier, the H2 Hamiltonian for the exact baseline |
+| `cirq` | `cirq-core>=1.6` | the third QAOA implementation |
+| `stim` | `stim>=1.16`, `pymatching>=2.0` | repetition and surface-code memories decoded by minimum-weight matching |
+| `learn` | `scikit-learn>=1.5` | the classical RBF-SVM baseline and the precomputed-kernel SVM |
+| `hardware` | `qiskit-ibm-runtime>=0.30` | the opt-in IBM Quantum adapter (real QPU, needs a token) |
+| `all` | every extra except `hardware` | |
+
+A missing framework disables only its own adapters (a warning names it); the rest of the registry works.
+
+## Quick start
+
+```python
+from qversus.registry import get_problem, solvers_for
+
+problem = get_problem("maxcut")
+instance = problem.instance("square")            # the 4-cycle; optimum cut = 4
+
+for solver in solvers_for(problem):              # QAOA on Qiskit, PennyLane and Cirq + two classical methods
+    result = solver.run(problem, instance, seed=42, shots=2048)
+    print(f"{result.paradigm:12} {result.solver:18} cut={result.value['cut']}  cost={result.cost}")
+```
+
+```python
+from qversus.registry import get_problem, solvers_for
+
+problem = get_problem("grover")
+instance = problem.instance("grover-4-10")       # N = 16 items, item 10 marked
+qiskit = next(s for s in solvers_for(problem) if s.framework == "qiskit")
+result = qiskit.run(problem, instance, seed=42, shots=2048)
+
+trace = result.trace.to_dict()                   # JSON-ready: steps, circuit_ops, measurements, provenance
+print(result.value, trace["measurements"]["counts"])
+```
+
+More: [quick start guide](https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/docs/guides/01_quickstart.md).
+
+## The catalogue
+
+Twenty problems in six families, 119 instances. Each has at least one quantum method and one classical baseline.
+
+| Problem | Family | Quantum solvers | Classical baseline |
+|---|---|---|---|
+| `single-qubit`, `qrng`, `interference` | fundamentals | Qiskit | Bloch/bit model, PRNG, wave optics |
+| `state-prep`, `chsh`, `teleportation`, `superdense` | entanglement | Qiskit | the amplitudes written down directly, local hidden variables, measure-and-resend, one bit per carrier |
+| `deutsch-jozsa`, `bernstein-vazirani`, `simon` | oracle algorithms | Qiskit | query-counting classical algorithms |
+| `grover`, `qft`, `qpe`, `shor` | flagship algorithms | Qiskit | linear scan, FFT, exact phase, trial division |
+| `maxcut`, `vqe`, `qml` | variational | Qiskit, PennyLane, Cirq | brute force + greedy, exact diagonalisation, RBF-SVM |
+| `noise`, `qec-repetition`, `qec-surface` | noise and QEC | Qiskit-Aer, Stim + PyMatching | the exact answer, the unprotected qubit |
+
+Per-problem parameters, result fields and the closed-form checks the tests enforce:
+[docs/problems](https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/docs/problems.md).
+
+## Contracts
+
+- **`Problem` / `Instance`**: identity (id, bilingual EN/ES title and concept, category, metric, references),
+  the instances, and a `live_capable` hint (small and noise-free enough to re-simulate interactively).
+- **`Solver` / `SolverResult`**: `run(problem, instance, seed, shots) -> SolverResult` with `value`, `cost`,
+  bilingual `notes`, an optional `trace`, `optimal` (an exact classical baseline) and `extra` (landscapes,
+  curves, kernel matrices). Paradigm is one of `quantum-sim`, `quantum-hardware`, `classical`.
+- **`Trace`** (schema `qversus-trace/1`): JSON-first and free of framework types, so a reader needs neither
+  Python nor a quantum SDK.
+- **Bit order**: amplitude and probability arrays use Qiskit's little-endian index (qubit 0 is the least
+  significant bit); count keys are that index in binary, highest qubit leftmost.
+
+Details: [docs/architecture](https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/docs/architecture.md).
+
+## Real hardware (opt-in)
+
+The `ibm-hardware` adapter submits small circuits to IBM Quantum (Open Plan, free tier) and returns the counts
+with the backend named in the provenance. It is never part of the default solver set: it is offered only when
+named explicitly **and** `QISKIT_IBM_TOKEN` is set. See
+[docs/solvers/06_ibm-hardware.md](https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/docs/solvers/06_ibm-hardware.md).
+
+## Development
+
+```bash
+python -m venv .venv && .venv/Scripts/python -m pip install -e ".[dev]"   # bash: .venv/bin/python
+python -m pytest                     # core, registry and physics tests
+python -m ruff check qversus tests
+python scripts/check_content_standards.py
+```
+
+CI runs lint, the tests, a core-only install check, and the repository guards on `develop` and `main`.
+Releases are tagged `vX.XX.XXX` and published to PyPI by trusted publishing
+([docs/guides/04_releasing.md](https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/docs/guides/04_releasing.md)).
+
+## Used by
+
+- **QLab** ([qlab.fasl-work.com](https://qlab.fasl-work.com)): a public, didactic quantum-computing lab whose
+  committed traces are produced by this engine.
+
+## License
+
+MIT. See [LICENSE](https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/LICENSE).

qversus-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qversus"
+version = "0.1.0"
+description = "Canonical quantum-computing problems solved by real frameworks (Qiskit, PennyLane, Cirq, Stim) next to classical baselines, with replayable, seeded traces."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Felipe Santibanez-Leal" }]
+keywords = [
+  "quantum computing", "quantum algorithms", "benchmark", "classical baseline", "qiskit", "pennylane",
+  "cirq", "stim", "grover", "qaoa", "vqe", "quantum error correction", "surface code", "education",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Intended Audience :: Education",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Physics",
+  "Topic :: Education",
+  "Operating System :: OS Independent",
+]
+# The core (RNG, trace schema, problem formulations, the registry and the classical adapters' module) needs
+# NumPy only. Each framework is an extra, imported where it is used, so a missing framework disables only
+# its own adapters and `import qversus` stays light.
+dependencies = ["numpy>=1.26"]
+
+[project.optional-dependencies]
+qiskit = ["qiskit>=2.4,<3", "qiskit-aer>=0.17"]
+pennylane = ["pennylane>=0.45", "networkx>=3.2"]
+cirq = ["cirq-core>=1.6"]
+stim = ["stim>=1.16", "pymatching>=2.0"]
+learn = ["scikit-learn>=1.5"]
+hardware = ["qiskit>=2.4,<3", "qiskit-ibm-runtime>=0.30"]
+all = [
+  "qiskit>=2.4,<3", "qiskit-aer>=0.17", "pennylane>=0.45", "networkx>=3.2", "cirq-core>=1.6",
+  "stim>=1.16", "pymatching>=2.0", "scikit-learn>=1.5",
+]
+dev = [
+  "pytest>=8.0", "ruff==0.15.18", "build>=1.0",
+  "qiskit>=2.4,<3", "qiskit-aer>=0.17", "pennylane>=0.45", "networkx>=3.2", "cirq-core>=1.6",
+  "stim>=1.16", "pymatching>=2.0", "scikit-learn>=1.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/fsantibanezleal/CAOS_QVersus"
+Documentation = "https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/docs/README.md"
+Issues = "https://github.com/fsantibanezleal/CAOS_QVersus/issues"
+Changelog = "https://github.com/fsantibanezleal/CAOS_QVersus/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+include = ["qversus*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 110
+target-version = "py311"
+
+[tool.ruff.lint]
+# The classic rule set, stated explicitly so a new ruff release cannot redden trunk CI.
+select = ["E4", "E7", "E9", "F"]
+ignore = ["E741"]

qversus-0.1.0/qversus/__init__.py

@@ -0,0 +1,17 @@
+"""qversus: canonical quantum-computing problems, solved by real frameworks next to classical baselines.
+
+A `Problem` is a formulation (Grover search, MaxCut, H2 ground state, a surface-code memory, ...) with a
+set of `Instance`s. A `Solver` is a thin adapter that attacks a problem with ONE real framework (Qiskit +
+Aer, PennyLane, Cirq, Stim + PyMatching) or with a classical method, and returns the same `SolverResult`
+shape whatever the framework. The registry pairs them, so putting a quantum method next to the classical
+baseline that is usually still more practical is one loop, not a per-framework script.
+
+Circuit-model solvers also return a `Trace`: a replayable, JSON-first recording of the run (the state after
+every gate, per-qubit Bloch vectors, probabilities, a seeded shot histogram). A run is a pure function of
+`(params, seed)`.
+
+The core needs NumPy only. Each framework is an optional extra; a missing framework disables only its own
+adapters. See the README and docs/ for the contracts.
+"""
+
+__version__ = "0.01.000"  # display form X.XX.XXX; pyproject.toml carries the PEP 440 form 0.1.0

qversus-0.1.0/qversus/core/__init__.py

@@ -0,0 +1,22 @@
+"""qversus.core, the framework-free substrate (no quantum SDK imported here).
+
+- rng:   seeded RNG and shot sampling, so a run is a pure function of (params, seed).
+- trace: the quantum trace schema (the artifact contract every circuit-model solver emits).
+
+`qversus.core.circuit_trace` (the Qiskit step tracer) is deliberately NOT imported here, so importing the
+core never requires Qiskit.
+"""
+
+from qversus.core.rng import DEFAULT_SEED, make_rng, sample_counts
+from qversus.core.trace import ROUND, SCHEMA_VERSION, Step, Trace, amp
+
+__all__ = [
+    "DEFAULT_SEED",
+    "make_rng",
+    "sample_counts",
+    "ROUND",
+    "SCHEMA_VERSION",
+    "Step",
+    "Trace",
+    "amp",
+]

qversus-0.1.0/qversus/core/circuit_trace.py

@@ -0,0 +1,107 @@
+"""Shared circuit→trace tracer (Qiskit). NOT imported by qversus.core.__init__, so `import qversus.core`
+stays Qiskit-free (live-thin); only the precompute solvers import this.
+
+Given a Qiskit circuit built gate-by-gate, `evolve` replays it one instruction at a time on a
+`Statevector`, recording, after every step, the full statevector, the per-qubit reduced Bloch vector,
+and the basis-state probabilities. That sequence of `Step`s IS the animation a consumer replays. Any
+circuit-model solver (Qiskit, Cirq via QASM, …) funnels through here so every framework yields the same
+trace shape, the adapter boundary the registry depends on.
+
+Qubit/index convention (documented once, used everywhere): Qiskit's native little-endian, basis index
+`i` has qubit 0 as its least-significant bit. The web renderer uses the same arrays, never reversed.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from qiskit import QuantumCircuit
+from qiskit.quantum_info import Pauli, Statevector, partial_trace
+
+from qversus.core.rng import sample_counts
+from qversus.core.trace import ROUND, Step, amp
+
+_PAULIS = ("X", "Y", "Z")
+
+
+def bloch(sv: Statevector, n: int) -> list[list[float]]:
+    """Per-qubit reduced Bloch vector [⟨X⟩, ⟨Y⟩, ⟨Z⟩] via the reduced density matrix."""
+    out: list[list[float]] = []
+    for q in range(n):
+        others = [j for j in range(n) if j != q]
+        rho = partial_trace(sv, others)
+        out.append([round(float(rho.expectation_value(Pauli(p)).real), ROUND) for p in _PAULIS])
+    return out
+
+
+def _scalar_params(params) -> list[float]:
+    """Keep only real scalar gate params (a UnitaryGate carries a matrix, not floats, skip those)."""
+    out: list[float] = []
+    for x in params or []:
+        try:
+            out.append(round(float(x), ROUND))
+        except (TypeError, ValueError):
+            pass
+    return out
+
+
+def step_of(index: int, gate: str, targets, label: dict, sv: Statevector, n: int, params=None) -> Step:
+    return Step(
+        index=index,
+        gate=gate,
+        targets=[int(t) for t in targets],
+        label=label,
+        statevector=[amp(z) for z in sv.data],
+        bloch=bloch(sv, n),
+        probabilities=[round(float(p), ROUND) for p in sv.probabilities()],
+        params=_scalar_params(params),
+    )
+
+
+def evolve(qc: QuantumCircuit, captions: list[dict] | None = None) -> list[Step]:
+    """Step-replay a circuit, returning the per-step trace (incl. an initial |0…0⟩ frame).
+
+    `captions[k]` (optional) is the bilingual label for the k-th unitary instruction (0-based).
+    """
+    n = qc.num_qubits
+    sv = Statevector.from_int(0, 2**n)
+    steps = [step_of(0, "init", [], {"en": "Initial state |0…0⟩", "es": "Estado inicial |0…0⟩"}, sv, n)]
+    k = 0
+    for inst in qc.data:
+        op = inst.operation
+        if op.name in ("measure", "barrier"):
+            continue
+        qargs = [qc.find_bit(q).index for q in inst.qubits]
+        sub = QuantumCircuit(n)
+        sub.append(op, qargs)
+        sv = sv.evolve(sub)
+        label = captions[k] if (captions and k < len(captions) and captions[k]) else {
+            "en": f"{op.name.upper()} q{qargs}",
+            "es": f"{op.name.upper()} q{qargs}",
+        }
+        steps.append(step_of(k + 1, op.name.upper(), qargs, label, sv, n, list(op.params)))
+        k += 1
+    return steps
+
+
+def circuit_ops(qc: QuantumCircuit) -> list[dict]:
+    """A flat, JSON-able op list for the diagram renderer (excludes barriers)."""
+    ops: list[dict] = []
+    for inst in qc.data:
+        op = inst.operation
+        if op.name == "barrier":
+            continue
+        ops.append(
+            {
+                "gate": op.name,
+                "targets": [qc.find_bit(q).index for q in inst.qubits],
+                "params": _scalar_params(op.params),
+            }
+        )
+    return ops
+
+
+def measure_counts(qc: QuantumCircuit, shots: int, seed: int) -> dict:
+    """Final measurement histogram, sampled deterministically from the exact final statevector."""
+    sv = Statevector.from_int(0, 2**qc.num_qubits).evolve(qc)
+    counts = sample_counts(np.asarray(sv.probabilities()), shots=shots, seed=seed)
+    return {"counts": counts, "shots": shots}

qversus-0.1.0/qversus/core/rng.py

@@ -0,0 +1,38 @@
+"""Seeded RNG. A qversus run is a pure function of (params, seed): same seed → byte-identical trace.
+
+Measurement sampling (shot histograms) is the only stochastic step in the pipeline; everything else
+(statevector evolution) is deterministic. We route all sampling through one seeded NumPy Generator so the
+committed counts reproduce exactly.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+DEFAULT_SEED = 42
+
+
+def make_rng(seed: int = DEFAULT_SEED) -> np.random.Generator:
+    """Return a NumPy Generator seeded deterministically (PCG64)."""
+    return np.random.default_rng(seed)
+
+
+def sample_counts(probabilities: np.ndarray, shots: int, seed: int = DEFAULT_SEED) -> dict[str, int]:
+    """Sample `shots` measurements from a probability vector over 2**n basis states.
+
+    Returns a {bitstring: count} dict, omitting zero counts. Each key is the basis index written in binary,
+    most significant bit first: the HIGHEST qubit is leftmost and qubit 0 is the rightmost character (Qiskit's
+    little-endian convention, the same order as `format(index, f"0{n}b")`).
+    """
+    n_states = len(probabilities)
+    n_qubits = int(np.log2(n_states))
+    rng = make_rng(seed)
+    # Guard against tiny negative/round-off so np.random.choice accepts the vector.
+    p = np.clip(np.asarray(probabilities, dtype=float), 0.0, None)
+    p = p / p.sum()
+    draws = rng.choice(n_states, size=shots, p=p)
+    counts: dict[str, int] = {}
+    for idx, c in zip(*np.unique(draws, return_counts=True)):
+        bitstring = format(int(idx), f"0{n_qubits}b")
+        counts[bitstring] = int(c)
+    return dict(sorted(counts.items()))