microquantum MQ-16 Compiler-Runtime Report

Scope

MQ-16 proves that programs handed from the Compiler to the execution runtime keep the observable semantics of the original circuit: exact probability vectors on shots=None and matching seeded sampling estimates, across all four simulators and all three optimization levels, including directed two-qubit gates, measurements, symbolic parameters and negative rotation angles. It adds three executable examples, a consolidated-notebook extension, documentation, a shared equivalence helper module, and a regression + conformance suite that enforce the contract permanently.

The milestone rides entirely on existing APIs. No second runtime, no duplicate abstraction, no nearby API breakage and no new dependency were introduced.

A single genuine core defect surfaced during validation — two-qubit gate target ordering was ignored on the density-matrix and executor expansion paths — and is documented and fixed below (agent should report, not paper-over: user approved fixing it now).

Deliverables

  • Three execution routes, one semantics. A compiled program runs identically through (A) explicit backend.run(compiled), (B) ExecutionPlan(compiled=...) reuse, and (C) runtime compilation via execute(..., optimization_level=...) (examples 30–31 + tests).

  • Differential oracle. For the corpus (Bell, GHZ(3), a rotation gate over ±π across all quadrants, CZ, SWAP) every level 0/1/2 preserves: exact probability vectors (max |Δp| < 1e-9) on all four simulators — statevector, density matrix, MPS, TTN — and seeded statistical agreement (≤ 0.05, 4000 shots).

  • Directed two-qubit gates are part of the contract. cnot(1, 0) must act with reversed targets; SWAP and CZ basis decompositions must match on every backend. This is what exposed the core defect below.

  • Measurements survive the hand-off. Compiling an unmeasured circuit appends terminal measurements; both original and compiled produce full-width counts/probabilities.

  • Parameters through the runtime. compile(bind) == bind(compile) (state fidelity 1.00); the runtime resolves parameter_bindings on a compiled plan (metadata["strategy"] == "compiled"); unbound/unknown parameters raise ValueError.

  • Error contracts preserved. ExecutionPlan.compiled is validated to be a CompilationResult (TypeError otherwise, after the plan’s exclusivity ValueError); incompatible targets are reported via is_compatible and rejected unless raise_on_incompatible=False; reset nodes and classically conditioned blocks raise ValueError at rebuild.

  • Examples 30–32. 30_compile_and_execute.py (the three routes), 31_compile_compare_execution.py (the differential oracle), 32_parameterized_compile_execute.py (compile → bind → runtime).

  • Shared helpers. tests/compiler_runtime_helpers.py — tolerances (TOL_EXACT = 1e-9, TOL_FIDELITY = 1e-9, TOL_SAMPLING = 0.05, SHOTS_SAMPLED = 4000), corpus, simulator collection and assert_execution_equivalent / assert_runtime_equivalent.

  • Regression suite. tests/test_compiler_mq16_integration.py — 249 tests.

  • Conformance suite. tests/conformance/test_compiler_runtime_integration.py — 92 tests, run with the regular pytest command (self-contained; it imports the shared helpers by inserting the tests/ directory on sys.path).

  • Documentation. docs/execution/compiler-runtime.rst registered in the Execution & Backends toctree; the examples README, examples index tree and this report updated.

Core defect found and fixed

expand_operator (src/microquantum/core/tensor.py) short-circuited when the gate qubit count equals the system width, using sorted(targets) to recognize the “full-width” fast path. When the two qubits were the full system but not in canonical order, both orderings collapsed to the canonical gate: on two qubits cnot(1, 0) executed as cnot(0, 1). The statevector path (einsum apply_gate) and the MPS/TTN simulators were already order-correct; the density-matrix and executor backends shared the flawed expand_operator path. This is why cx(1, 0) from a SWAP decomposition went unnoticed at the routine level but was caught by the MQ-16 cross-backend determinism gate.

Fix: the fast path now requires the exact canonical order (targets == list(range(n))); any permutation is routed through the general, order-correct expansion path. Regression tests: tests/test_tensor.py (test_expand_cnot_reversed_targets_respects_order) and the cross-backend determinism tests in the MQ-16 suite.

API change from this milestone (reported, additive)

  • ExecutionPlan.compiled — plan validation now raises TypeError when compiled is not a CompilationResult (in the compiled-only branch, after the exclusivity ValueError). Existing valid plans construct unchanged; the change is a stricter, local validation, no signature or behavior regression.

Gate results

Note: the default pytest addopts add --cov=microquantum; there is no fail_under threshold, so the functional gates are reported with --no-cov.

MQ-16 suite contents

tests/test_compiler_mq16_integration.py

  • Equivalent semantics through the runtime: per-corpus exact probability agreement (all 4 backends × levels 0/1/2) and seeded sampling agreement.

  • Route equivalence (A/B/C) and rich-result parity.

  • Measurements: unmeasured compilation appends terminal measurements; compiled vs original counts match.

  • Parameter pipeline: symbolic compile → bind; bind-after-compile fidelity; compiled-plan parameter_bindings; equals IR-facing param counts.

  • Negative rotation angles across the four quadrants.

  • Metadata: compiled_gates_by_type counts for canonical IR names.

  • ExecutionPlan/error contracts and incompatible-target diagnostics.

  • TestCrossBackendDeterminism: directed cnot(1, 0), SWAP and CZ basis decompositions agree across all four simulators.

tests/conformance/test_compiler_runtime_integration.py

The same contract as a compact, permanent gate (92 items): corpus matrix, sampling, routes, directed gates, basis decompositions, parameters, measurements, empty circuit, negative rotations, TypeError/ValueError contracts, incompatible plans and reset-IR rejection.

Design notes

  • MockBackend is intentionally excluded from the simulator collection: it is a routing stub, not a simulator, and the equivalence contract is defined for real simulation targets.

  • IR gate names are canonical (cnot), so metadata assertions use them rather than source spellings.

  • The conformance file keeps a bare sys.path insertion (tests/) so it can reuse the shared helpers without duplicating logic; the import is marked # noqa: E402.

Count reconciliation

MQ-15 recorded tests/conformance/ as 395 collected items. MQ-16 adds: 92 items from test_compiler_runtime_integration.py, +3 example-execute and +3 example-output parametrizations (examples 30–32), and a +1 docs-consistency item for the new execution/compiler-runtime.rst page (one self-contained .. code-block:: python). The suite remains 100% green with no skips, no xfails, no quarantines and no weakened assertions.

Examples

The three new examples are auto-discovered by the conformance gate (conformance_helpers.all_example_files()); all 86 scripts run clean as standalone programs and again, in order, inside the consolidated notebook.

Notebook

examples/MicroQuantum_Examples.ipynb was regenerated to include examples 30–32; validation (14 sections, full example coverage, in-order execution) is unchanged and enforced by the conformance suite.

No dependency changes

MQ-16 adds no runtime, test or documentation dependencies.

Release prerequisite reminder (AGENTS.md)

No PyPI release without: push + green CI + v<version> tag + TestPyPI check first.