Skip to content

Demo readiness: honest results, working backends, classical baselines - #4

Merged
Shashikant86 merged 20 commits into
mainfrom
demo-readiness
Nov 2, 2026
Merged

Shashikant86 merged 20 commits into
mainfrom
demo-readiness

Conversation

@Superagentic-AI

Copy link
Copy Markdown
Contributor

Prepares SuperQuantX for the live demo at the Quantum AI Tech Show (4 Nov 2026, "No hype. Just results."). Every number the library, CLI, examples and docs print now comes from a real computation, and every quantum result comes with a classical reference.

What was fake and is now real

Area Before Now
Backend feature maps and kernels Placeholder maps, silent RBF kernel fallback, Qiskit kernel(x,x)=0, PennyLane ignored the feature map Fidelity kernel from each backend's own statevectors; kernel(x,x)=1 and the feature map is used on every backend (bfee0e3, tested in 451bc30)
Expectation values 0.0 or random Pauli values Exact Hamiltonian expectation
VQE Random / inf fallbacks Seeded, exact expectation, exact-diagonalisation baseline, H2 STO-3G Hamiltonian
QAOA Disconnected from backends Weighted MaxCut on the shared backend circuit, multi-start, brute-force check
QSVM Silent fallback to classical RBF Real quantum kernel, gamma is the kernel bandwidth
QNN Random forward pass Softmax over , exact parameter-shift gradients
Quantum agents Random trading returns, hard-coded 0.08 baseline, template "exponential speedup" text CVaR-VQE portfolio vs brute force and Markowitz; QAOA/VQE with exact checks; classification vs tuned classical models; unbacked parts raise NotImplementedError
superquantx benchmark np.random results compare_to_classical on moons / circles / iris
superquantx list-backends Static list Runs a Bell circuit per backend and reports OK/FAIL; planned backends labelled as such
Simulator Skipped unknown gates, wrong Toffoli, dummy results on error tensordot gate application, raises on unknown gates and errors
Logging basicConfig(force=True) at INFO on import NullHandler on the superquantx logger only

New: superquantx.benchmarks.compare_to_classical following the protocol of arXiv:2610.42029 (equal tuning grids, per-fold scaling and kernel recomputation, Nadeau-Bengio corrected t-test, cost reported in QPU circuit evaluations). New examples/showcase.py (under a minute) and a rewritten examples/vqe_molecule.py.

Backend status

Backend Status
simulator (built-in NumPy) Works, tested
PennyLane default.qubit Works, tested
Qiskit Aer Works, tested (qiskit >= 2.6, IBM hardware via qiskit-ibm-runtime, untested)
Cirq Works, tested
Amazon Braket LocalSimulator Works, tested (device="local:braket_sv"; AWS devices untested)
TKET (pytket + Aer) Works, tested (Quantinuum hardware untested)
D-Wave Ocean QUBO/Ising only, needs a Leap token; gate-model calls raise a clear error
Azure Quantum, Rigetti/pyQuil, cuQuantum, TFQ Planned, not implemented (now labelled as such everywhere)

Tests

main (04e8b11) this branch
Unit 79 passed, 10 failed all pass
Integration 1 passed, 10 failed all pass (rewritten against the real API)
Unit + integration 80 passed, 20 failed 158 passed, 0 failed (fresh venv, Python 3.11, .[all-backends,dev])
ruff F821 (undefined names) 16 0
ruff total 279 221 (remaining are style rules in files this PR does not touch; left alone to avoid conflicts)
mkdocs build --strict about 96 warnings, fails passes

Key new tests: every backend kernel has unit self-fidelity and depends on its feature map; Bell and qubit-order checks run against the real SDKs instead of mocks; H2 VQE against exact diagonalisation; QAOA against brute force; CLI smoke tests.

Docs

  • Broken links and nav fixed so mkdocs build --strict passes without touching the workflow.
  • New pages: Showcase (real output), Benchmarking, FAQ, Troubleshooting. Backends guide, index, quick start and README rewritten; every snippet in them runs.
  • Older pages whose snippets do not run as-is (API reference pages, per-backend pages, tutorials, development guides) now open with an "Unverified examples" warning that states how many snippets run, and link to the verified pages.
  • CHANGELOG has an [Unreleased] section.

CI note (needs a change in the GitHub UI)

.github/workflows/ci.yml ends the lint and test steps with || true (lines 36, 67, 70), so CI is green even when ruff or pytest fails. This PR does not edit workflows (the token lacks workflow scope). Please remove || true from the pytest steps in the GitHub UI; the ruff step can follow once the remaining style errors are cleaned up.

Demo commands

uv sync --extra all-backends
uv run superquantx list-backends
uv run python examples/showcase.py
uv run python examples/quantum_agents_demo.py
uv run superquantx benchmark -d moons -b pennylane
uv run python examples/vqe_molecule.py

Known gaps

  • examples/quantum_ml.py and examples/full_tutorial.py take more than 2 to 4 minutes; not demo material.
  • Older docs pages still describe planned API (flagged with warnings).
  • BaseQuantumAlgorithm.optimize() stores exceptions in .error rather than raising.
  • PyPI release lags this branch.
  • Out of scope here: feature_map_auto (PR Spike: QuantumSVM feature_map=auto (Qmes-style) #2) and the MCP server (separate PR).

setup_logging() called logging.basicConfig(force=True) at INFO on import,
which flooded output with Qiskit and other third-party logs. The library now
only attaches a NullHandler to the superquantx logger; configure_logging()
and configure() set up the superquantx logger alone.
- BaseBackend: replace placeholder feature maps, RBF kernel fallback, 0.0
  expectation and random Pauli values with real generic implementations
  built on each backend's own gates: fidelity kernel from statevectors,
  exact Hamiltonian expectation, RealAmplitudes/EfficientSU2 ansatz,
  weighted MaxCut QAOA circuit. Qubit order is probed per backend so
  counts and statevectors can be normalised to one convention.
- Simulator: tensordot gate application (correct Toffoli), unknown gates
  raise instead of being skipped, no dummy result on errors.
- Qiskit: drop qiskit_ibm_provider/IBMQ; IBM hardware goes through
  qiskit-ibm-runtime QiskitRuntimeService and SamplerV2 (untested).
- PennyLane: record gates in a PennyLaneCircuit and return counts.
- Cirq: fix init order so the simulator is not reset to None.
- Braket: Rx/Ry/Rz gate names, accept local:braket/braket_sv, fixed
  register size, real statevector, raise on errors.
- TKET: AerBackend from pytket.extensions.qiskit, radians to half-turns,
  string count keys, no random-count fallback.
- Ocean: gate-model calls raise a clear annealer message; fix the
  add_measurement signature, the num_reads clash and the MaxCut QUBO sign.
- Tests: parametrised Bell, qubit order, expectation and kernel tests run
  against the real SDKs instead of mocks.
qiskit>=2.6, qiskit-aer>=0.18, qiskit-ibm-runtime>=0.50 (replaces the
deprecated qiskit-ibm-provider path).
VQE: exact expectation from the backend, seeded init, exact-diagonalisation
baseline, H2 STO-3G Hamiltonian, no random or inf fallbacks.
QAOA: weighted MaxCut on the shared backend circuit, multi-start optimisation,
best-of-samples partition and a brute-force classical check (solve()).
QuantumSVM: no silent RBF fallback, gamma is now the kernel bandwidth,
training accuracy no longer double-scales.
QuantumNN: no random forward pass, softmax readout over <Z>, exact
parameter-shift gradients through the chain rule.
Same stratified folds for the quantum classifier, a tuned RBF SVC and a tuned
logistic regression. Quantum kernel bandwidth and C are tuned on a grid the
same size as the RBF grid, the kernel is recomputed per fold, hardware cost is
reported in circuit evaluations, and the gap to the best classical model gets
a Nadeau-Bengio corrected t-test. Protocol follows arXiv:2610.42029.
Remove the fabricated trading numbers (random returns and the hard-coded
0.08 baseline) and the research agent's template 'exponential speedup'
text. Portfolio selection now runs CVaR-VQE on a mean-variance QUBO and
reports brute force and Markowitz references. Optimization runs QAOA MaxCut
or VQE with exact checks. Classification benchmarks against tuned classical
models. Trading and research agents keep only the parts backed by real
computation and raise NotImplementedError for the rest. The agents demo uses
the portfolio and classification agents and exits non-zero on failure.
…howcase, benchmarking, FAQ and troubleshooting pages; rewrite backends guide
@Shashikant86
Shashikant86 merged commit 48c0528 into main Nov 2, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants