Add pluggable execution backends (qutip, cuquantum, cudaq) - #7
Merged
Conversation
Implements the execution-backends OpenSpec change: - New `q_orca/backends/` package with `BackendAdapter` ABC, `BackendResult`, `BackendUnavailableError`, and `BackendRegistry` with graceful fallback logic - `qutip_backend.py`: delegates to existing `dynamic_verify()` - `cuquantum_backend.py`: stub adapter (AVAILABLE=False in CI), raises `BackendUnavailableError` so registry falls back to QuTiP with warning - `cudaq_backend.py`: stub adapter for CUDA-Q, same fallback pattern - `q_orca/compiler/cudaq.py`: `compile_to_cudaq()` emitting `@cudaq.kernel` scripts with H→`cudaq.h`, CNOT→`cudaq.x.ctrl`, X/Y/Z, Rx/Ry/Rz gate mapping - `VerifyOptions.backend` field routes Stage 4b through the registry - CLI gains `--backend`, `--gpu-count`, `--tensor-network`, `--cudaq-target` flags on `verify` and `simulate`; `compile cudaq` format target added - JSON output for `verify` and `simulate` now includes a `backend` block - `OrcaConfig` gains `backend`, `cuquantum`, `cudaq` fields; `_resolve_backend()` merges CLI flag over `orca.yaml` config value - 19 new tests covering registry fallback, BACKEND_UNAVAILABLE warnings, CUDA-Q kernel structure, and CLI integration; 371 tests pass, 0 failures Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Remove unused Optional/Type from registry.py, Any/Dict from cudaq.py, Optional from config/types.py, and unused dynamic_verify/BackendResult imports from verifier/__init__.py — all flagged by ruff F401 in CI. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Rename ambiguous loop variable l → ln (E741) in test files - Remove unused variables: error_codes, result, slots_needed, bred_any (F841) - 27 further issues were auto-fixed (F541 f-strings, unused imports) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add --backend, --gpu-count, --tensor-network to CLI flags table - Add Verification Backends section with backend comparison table - Add backends/ and compiler/cudaq.py to file tree - Mark pluggable backends as shipped in roadmap Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- CUDA-Q: pip install cuda-quantum, works on macOS Apple Silicon via qpp-cpu target - cuQuantum: Linux + NVIDIA GPU only, not supported on macOS - Add platform column to backends table Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add 'Verify the installation' smoke test under Install - Add 'Optional backends' install block with cudaq and cuquantum commands - Remove duplicate install subsections from Verification Backends section - Replace with a link back to Install Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The correct PyPI package name on macOS Apple Silicon is 'cudaq', not 'cuda-quantum'. Update README and backend error message. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
cudaq fails to import if matplotlib is absent. Update install instructions and backend unavailable error message. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
jascal
pushed a commit
that referenced
this pull request
Apr 16, 2026
PR #7 (8cc65fc) shipped the implementation of the pluggable execution backends change but only committed tasks.md. The supporting OpenSpec artifacts (proposal, design, five spec deltas, .openspec.yaml) and the raw feature spec under docs/specs/ were left orphaned on a local machine and never committed. This commit brings them into the repo so the change is fully documented and archivable. No code changes — documentation backfill only. Artifacts: - openspec/changes/execution-backends/.openspec.yaml - openspec/changes/execution-backends/proposal.md - openspec/changes/execution-backends/design.md - openspec/changes/execution-backends/specs/backend-selection/spec.md - openspec/changes/execution-backends/specs/cuquantum-backend/spec.md - openspec/changes/execution-backends/specs/cudaq-backend/spec.md - openspec/changes/execution-backends/specs/verifier/spec.md - openspec/changes/execution-backends/specs/compiler/spec.md - docs/specs/spec-execution-backends.md Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
jascal
pushed a commit
that referenced
this pull request
Apr 17, 2026
Brings `docs/specs/spec-execution-backends.md` into the repo. The pre-OpenSpec-era feature spec for PR #7 was orphaned on a local machine and never committed alongside the implementation. Everything else that was missing (proposal, design, capability specs) already landed in `openspec/changes/archive/2026-04-17-execution-backends/` when the nightly archived the change, so this is the last piece. Docs-only. No code changes. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2 tasks
jascal
added a commit
that referenced
this pull request
Apr 17, 2026
Brings `docs/specs/spec-execution-backends.md` into the repo. The pre-OpenSpec-era feature spec for PR #7 was orphaned on a local machine and never committed alongside the implementation. Everything else that was missing (proposal, design, capability specs) already landed in `openspec/changes/archive/2026-04-17-execution-backends/` when the nightly archived the change, so this is the last piece. Docs-only. No code changes. Co-authored-by: Allan Scott <allans@Allans-Mac-mini.lan> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
q_orca/backends/package —BackendAdapterABC,BackendResultdataclass,BackendUnavailableError, andBackendRegistrywith graceful fallback (requests unavailable backend → falls back to QuTiP + emitsBACKEND_UNAVAILABLEwarning)qutip_backend(delegates to existingdynamic_verify()),cuquantum_backend(stub,AVAILABLE=Falsein CI, fallback-safe),cudaq_backend(stub, same pattern)q_orca/compiler/cudaq.py::compile_to_cudaq()emits@cudaq.kernelscripts; gate mapping: H→cudaq.h, CNOT→cudaq.x.ctrl, X/Y/Z, Rx/Ry/Rz, measure→mzVerifyOptions.backend = "qutip"routes Stage 4b throughBackendRegistry.get_with_fallback()--backend,--gpu-count,--tensor-network,--cudaq-targetflags onverifyandsimulate;compile cudaqformat target addedverify --jsonandsimulate --run --jsonnow include a"backend": {"name": ..., "version": ...}blockOrcaConfiggainsbackend,cuquantum,cudaqfields;_resolve_backend()merges CLI flag overorca.yamlBACKEND_UNAVAILABLEwarning,BackendResultfields, CUDA-Q kernel structure/syntax, CLI integrationTest plan
pytest tests/test_backends.py— 19 tests passpytest— 375 passed, 0 failed, 1 skipped (after lint fixes)cuquantumandcudaqstubs confirmed unavailable in CI; fallback path exercised by testsq-orca compile cudaq examples/bell-entangler.q.orca.md— emits correct@cudaq.kernelwithcudaq.handcudaq.x.ctrlq-orca verify examples/bell-entangler.q.orca.md --backend cudaq— verified working on macOS Apple Silicon withcudaq==0.14.0+matplotlibNote: cuquantum requires Linux + NVIDIA GPU. cudaq (
pip install cudaq matplotlib) works on macOS Apple Silicon via CPU simulation.🤖 Generated with Claude Code