From 6ab5ab561daa86c8ed8faa18531c8720a2376783 Mon Sep 17 00:00:00 2001 From: Allan Scott Date: Fri, 17 Apr 2026 10:14:13 -0400 Subject: [PATCH] Add execution-backends raw feature spec to docs/specs/ 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 --- docs/specs/spec-execution-backends.md | 294 ++++++++++++++++++++++++++ 1 file changed, 294 insertions(+) create mode 100644 docs/specs/spec-execution-backends.md diff --git a/docs/specs/spec-execution-backends.md b/docs/specs/spec-execution-backends.md new file mode 100644 index 0000000..2857bdd --- /dev/null +++ b/docs/specs/spec-execution-backends.md @@ -0,0 +1,294 @@ +# Q-Orca Language Specification — Execution Backends + +**Version:** 0.1 (draft) +**Status:** Proposed +**Scope:** Defines supported simulation and compilation backends, mapping rules, CLI flags, configuration syntax, and fallback behaviour. + +--- + +## 1. Overview + +Q-Orca machines are backend-agnostic by default. A machine definition (`.q.orca.md`) describes *what* the quantum state machine does; the backend determines *how* it is verified, simulated, or compiled. Three tiers of backends are defined: + +| Tier | Backend | Role | Required? | +|------|---------|------|-----------| +| 0 | **QuTiP** (default) | Dynamic verification (Stage 4b), simulation | Soft dependency | +| 1 | **NVIDIA cuQuantum** | GPU-accelerated dynamic verification and simulation | Optional | +| 2 | **NVIDIA CUDA-Q** | Compilation and runtime target for GPU/QPU execution | Optional | + +All backends must produce semantically identical verification results. Switching backends changes performance and scalability, not correctness. + +--- + +## 2. Default Backend: QuTiP + +QuTiP is the reference backend for dynamic verification (Stage 4b). It is used when no `--backend` flag is specified and no `backend` key is set in `orca.yaml`. + +**Capabilities:** +- State-vector simulation for up to ~25 qubits on typical hardware +- Von Neumann entropy and Schmidt rank computation for entanglement verification +- Lindblad master equation integration for open-system noise models + +**Graceful degradation:** If QuTiP is not installed (`pip install qutip`), Stage 4b is skipped and a warning is emitted. All other verification stages run normally. + +--- + +## 3. NVIDIA cuQuantum Backend + +### 3.1 Purpose + +The cuQuantum backend accelerates Stage 4b dynamic verification and simulation using NVIDIA GPU hardware via the `qutip-cuquantum` plugin and the underlying `cuDensityMat` and `cuTensorNet` libraries. + +**Expected performance:** Up to 4000× speedup over CPU-only QuTiP for large composite quantum systems (benchmarks from NVIDIA cuQuantum 24.x documentation). Enables practical verification of 30–100+ qubit quantum automata via tensor network contraction. + +### 3.2 CLI Flags + +```bash +# Verification with cuQuantum acceleration +q-orca verify machine.q.orca.md --backend cuquantum + +# Simulation with cuQuantum +q-orca simulate machine.q.orca.md --run --backend cuquantum + +# Multi-GPU mode +q-orca verify machine.q.orca.md --backend cuquantum --gpu-count 4 +``` + +The `--backend nvidia` alias is also accepted. + +### 3.3 Configuration (orca.yaml) + +```yaml +backend: cuquantum + +cuquantum: + gpu_ids: [0, 1] # GPU device indices to use (default: [0]) + gpu_count: 2 # Number of GPUs (shorthand; overrides gpu_ids length) + workstream_device: 0 # cuDensityMat WorkStream device index + tensor_network: true # Use cuTensorNet for contraction (default: false) + precision: float64 # float32 | float64 (default: float64) + seed: 42 # RNG seed for reproducibility +``` + +### 3.4 Machine-level Backend Annotation + +A machine may declare a preferred backend in its `## invariants` section: + +```markdown +## invariants +- backend: cuquantum +- entanglement(q0,q1) = True +- schmidt_rank(q0,q1) >= 2 +``` + +The `backend` invariant is advisory — it is used when no CLI flag is present. It does not affect verification semantics. + +### 3.5 Fallback Behaviour + +If the cuQuantum backend is requested but unavailable (no GPU, no `qutip-cuquantum` installed), the verifier falls back to default QuTiP and emits: + +``` +[WARN] BACKEND_UNAVAILABLE: cuquantum backend requested but not available. + Falling back to default QuTiP backend. + Install: pip install qutip-cuquantum +``` + +Verification proceeds normally. The `--strict` flag does **not** treat this warning as an error by default; pass `--strict --no-backend-fallback` to fail hard on backend unavailability. + +### 3.6 Output Metadata + +When cuQuantum is used, verification and simulation JSON output includes a `backend` metadata block: + +```json +{ + "machine": "BellEntangler", + "valid": true, + "errors": [], + "backend": { + "name": "cuquantum", + "version": "24.03.0", + "gpu_ids": [0], + "precision": "float64", + "seed": 42 + } +} +``` + +--- + +## 4. NVIDIA CUDA-Q Backend + +### 4.1 Purpose + +CUDA-Q is a compilation and runtime target that maps Q-Orca quantum state machines to CUDA-Q kernel functions. It supports: + +- GPU-accelerated state-vector and tensor network simulation +- Hardware execution via CUDA-Q's QPU-agnostic layer (~75% of public QPUs) +- Tight classical-quantum interleaving for hybrid control loops +- Future: `cudaq-realtime` and NVQLink for microsecond-latency GPU ↔ QPU callbacks + +### 4.2 Mapping Rules + +#### 4.2.1 States → Kernel Boundaries + +Each distinct quantum state in the machine maps to a named section in the CUDA-Q kernel. Terminal states (marked `[final]`) map to classical post-processing blocks. + +#### 4.2.2 Transitions → Gate Sequences + +| Q-Orca action effect | CUDA-Q primitive | +|----------------------|-----------------| +| `Hadamard(qs[N])` | `cudaq::h(q[N])` | +| `CNOT(qs[N], qs[M])` | `cudaq::x(q[N], q[M])` | +| `Rx(qs[N], theta)` | `cudaq::rx(theta, q[N])` | +| `Ry(qs[N], theta)` | `cudaq::ry(theta, q[N])` | +| `Rz(qs[N], theta)` | `cudaq::rz(theta, q[N])` | +| `CRz(qs[N], qs[M], theta)` | `cudaq::rz(theta, q[N], q[M])` | +| `RZZ(qs[N], qs[M], theta)` | `cudaq::rzz(theta, q[N], q[M])` | + +Custom gate matrices (declared via `## gates`) are emitted as `cudaq::unitary` calls. + +#### 4.2.3 Mid-Circuit Measurement + Feedforward + +Mid-circuit `measure(qs[N]) -> bits[M]` effects and `if bits[M] == val: Gate(...)` conditionals map to CUDA-Q's hybrid programming model: + +```python +# Generated by Q-Orca CUDA-Q compiler +import cudaq + +@cudaq.kernel +def active_teleportation(): + q = cudaq.qvector(3) + # ... gate sequence ... + c0 = mz(q[0]) # mid-circuit measurement + if c0: # classical feedforward + x(q[2]) +``` + +This leverages CUDA-Q's native support for classical control flow interleaved with quantum gates — the defining feature of its hybrid model. + +#### 4.2.4 Noise Context → cudaq noise_model + +`## context` noise declarations map to CUDA-Q noise models: + +| Q-Orca context field | CUDA-Q equivalent | +|---------------------|-------------------| +| `noise: depolarizing(p)` | `cudaq.DepolarizationChannel(p)` | +| `noise: amplitude_damping(gamma)` | `cudaq.AmplitudeDampingChannel(gamma)` | +| `noise: thermal(T1, T2)` | `cudaq.ThermalRelaxationChannel(T1, T2)` | + +### 4.3 CLI Flags + +```bash +# Compile to CUDA-Q Python kernel +q-orca compile cudaq machine.q.orca.md + +# Simulate using CUDA-Q state-vector simulator +q-orca simulate machine.q.orca.md --run --backend cudaq + +# Simulate using CUDA-Q tensor network simulator +q-orca simulate machine.q.orca.md --run --backend cudaq --cudaq-target tensornet + +# Target real hardware via CUDA-Q QPU layer +q-orca simulate machine.q.orca.md --run --backend cudaq --cudaq-target +``` + +### 4.4 Configuration (orca.yaml) + +```yaml +backend: cudaq + +cudaq: + target: nvidia # nvidia | tensornet | qpp-cpu | + shots: 1024 # Number of shots for sampling (default: 1024) + seed: 42 # RNG seed + precision: float64 # float32 | float64 +``` + +### 4.5 Example: Bell Entangler compiled to CUDA-Q + +Given `examples/bell-entangler.q.orca.md`, `q-orca compile cudaq` produces: + +```python +# Generated by Q-Orca CUDA-Q compiler v0.1 +# Machine: BellEntangler + +import cudaq + +@cudaq.kernel +def bell_entangler(): + q = cudaq.qvector(2) + # |00> --prepare_H--> |+0> + h(q[0]) + # |+0> --entangle--> |ψ> + x.ctrl(q[0], q[1]) + # Measurement + mz(q) + +counts = cudaq.sample(bell_entangler, shots_count=1024) +print(counts) +``` + +### 4.6 Future: cudaq-realtime and NVQLink + +A future extension (`--backend cudaq-realtime`) will target the `cudaq-realtime` runtime with NVQLink for microsecond-latency GPU ↔ QPU callbacks. This is the target execution model for real-time hybrid applications such as: + +- Quantum error correction with adaptive syndrome feedback +- Closed-loop variational quantum algorithms (ADAPT-VQE) +- Real-time quantum state tomography + +This extension is not yet implemented. The spec reserves the `cudaq-realtime` backend identifier. + +--- + +## 5. Tensor Network Mode (cuTensorNet) + +For quantum automata with 30–100+ qubits, state-vector simulation is intractable. Both the cuQuantum and CUDA-Q backends support tensor network contraction via cuTensorNet. + +```bash +# cuQuantum tensor network mode +q-orca verify large-machine.q.orca.md --backend cuquantum --tensor-network + +# CUDA-Q tensor network simulator +q-orca simulate large-machine.q.orca.md --run --backend cudaq --cudaq-target tensornet +``` + +Tensor network mode is automatically selected when qubit count exceeds the threshold defined in `orca.yaml` (`tensornet_qubit_threshold`, default: 30). It can also be forced explicitly. + +**Limitations:** Tensor network contraction is efficient for low-entanglement circuits. Highly entangled states (e.g. GHZ at large N) may still require exponential contraction time. The verifier emits a `WARN: HIGH_ENTANGLEMENT_TENSOR_NETWORK` advisory in these cases. + +--- + +## 6. Backend Selection Summary + +| Flag / Config | Effect | +|---------------|--------| +| *(none)* | QuTiP (CPU) for Stage 4b; Qiskit for simulation | +| `--backend cuquantum` | GPU-accelerated QuTiP via cuDensityMat | +| `--backend cudaq` | CUDA-Q state-vector simulator | +| `--backend cudaq --cudaq-target tensornet` | CUDA-Q tensor network simulator | +| `--backend cudaq --cudaq-target ` | Real QPU hardware via CUDA-Q | +| `--tensor-network` | Force tensor network mode on cuQuantum | +| `--gpu-count N` | Multi-GPU mode (cuQuantum only) | + +--- + +## 7. Reproducibility + +All backend outputs include a `backend` metadata block in JSON mode (see §3.6). For reproducible research: + +- Always set `seed` in `orca.yaml` or pass `--seed N` +- Pin backend versions in CI (`cuquantum==24.x`, `cuda-quantum==0.x`) +- Use `--json` output and archive the `backend` metadata alongside results + +--- + +## 8. Error Codes + +| Code | Severity | Description | +|------|----------|-------------| +| `BACKEND_UNAVAILABLE` | Warning | Requested backend not installed; fell back to default | +| `BACKEND_GPU_NOT_FOUND` | Warning | No CUDA-capable GPU detected | +| `BACKEND_VERSION_MISMATCH` | Warning | Installed backend version differs from pinned version | +| `BACKEND_TENSORNET_HIGH_ENTANGLEMENT` | Warning | Tensor network mode may be slow due to high entanglement | +| `BACKEND_UNSUPPORTED_GATE` | Error | Gate has no mapping in the target backend | +| `BACKEND_REALTIME_NOT_AVAILABLE` | Error | `cudaq-realtime` target requested but not yet implemented |