Optimization validation core

[sacpis]

Goal

An independent correctness oracle for CUDA-Q compiler optimizations. Given a baseline and a candidate pass/pipeline, it decides (without a simulator or target) whether the candidate preserves the circuit's meaning, and reports resource metrics (gate/two-qubit/T counts, depth). It's built for the automated improvement pipeline, where untrusted agents propose pass changes and something they can't influence has to accept or reject them.

It fails closed: anything outside the supported domain (measurement, reset, dynamic control flow, too many qubits) is rejected, never silently passed. It also verifies the IR at every stage boundary, so a broken candidate gets caught and categorized instead of slipping through.

How it decides equivalence

Builds the exact unitary of each circuit straight from the IR and compares them (element-wise and up-to-global-phase). I think this is the safest check for small circuits. The result also advertises an oracle roadmap naming the tiers we'll add next like Clifford/tableau for scaling, density-matrix for mixed states, statevector as advisory-only.

The oracle is a plug-in point too. DenseUnitaryOracle is the built-in one, but you can pass your own Oracle for a fast optimization loop. Each in-domain case also reports the invariants it checked (equivalence, determinism, fixed-point).

Metrics

The core reports the metric tuple and each predicate outcome, but never a single weighted reward. That reduction is the caller's objective, on the untrusted side, since a weighted score is exactly what an optimizer could game. Metrics are either gating (a violated predicate fails the case) or informational (reported but doesn't fail it).

Usage

CLI (agents / CI):

python3 -m cudaq._compiler
    --input circuit.qke
    --prepare 'builtin.module(func.func(memtoreg))'
    --candidate 'builtin.module(func.func(phase-folding))'
    --oracle up-to-global-phase
    --metric operation-count:nonincreasing

It emits JSON and its exit code is the category
0 -> pass
1 -> invariant-failure
2 -> unsupported-domain
3 -> invalid-request
4 -> infrastructure-failure

Python:

from cudaq._compiler import validate, ValidationRequest, PipelineTarget, OracleSpec, MetricSpec

The input is target-shaped. A PipelineTarget for the baseline, with the candidate injected via .with_pipeline(...), so a future CompileTarget binding can slot in without breaking the API.

It never raises. Failures is obtained from result.status

result = validate(request)

There's also validate_artifacts(...) for the case where you've already compiled the candidate yourself (out-of-process) and just want the compare + metrics on the two modules, so a crashing candidate compile can't take down the validator.

Benchmark

GHZ (H + full n-CX chain), two kernels compared through compareTableaux, Used the same binary, just flipped the inverse argument.

| qubits | build IR | compare (before) | compare (after) | speedup | peak RSS |
|--------|----------|------------------|-----------------|---------|----------|
| 1,000  | 3.7 ms   | 35 ms            | 3.8 ms          | 9×      | 15 MB    |
| 5,000  | 6.9 ms   | 1.32 s           | 25.8 ms         | 51×     | 68 MB    |
| 10,000 | 9.1 ms   | 8.91 s           | 98.7 ms         | 90×     | 225 MB   |
| 20,000 | 18.8 ms  | 86.5 s           | 372 ms          | 233×    | 817 MB   |

Note

This is a working prototype. Some of the hardening is in already (IR verification at stage boundaries, the invariants, and reproducible corpora with pinned seeds plus a small canonical set ported from OpenQASM). What's still missing for the hardened acceptance gate is frozen schemas, subprocess sandboxing wired end-to-end, the regression corpora, and canonical CI. Will have follow up commits in this PR.

[github-actions]

CI Summary (push) — ❌ failed

Run #31133581280 · ✅ 5 · ⏩ 7 · ❌ 1 · ⛔ 0

❌ Failed or cancelled

Job	Result	Link
build_and_test	❌ failure	view

Top-level jobs (13)

Job	Result
binaries	⏩ skipped
build_and_test	❌ failure
config_devdeps	✅ success
config_source_build	⏩ skipped
config_wheeldeps	✅ success
devdeps	✅ success
docker_image	⏩ skipped
gen_code_coverage	⏩ skipped
metadata	✅ success
python_metapackages	⏩ skipped
python_wheels	⏩ skipped
source_build	⏩ skipped
wheeldeps	✅ success

⏩ Skipped jobs (7) — intentionally skipped on PR builds; run on merge_group / workflow_dispatch

Job
binaries
config_source_build
docker_image
gen_code_coverage
python_metapackages
python_wheels
source_build

All sub-jobs (42) — every matrix leg, with links

Job	Status	Link
Build and test (amd64, gcc12, openmpi) / Dev environment (Debug)	✅ success	view
Build and test (amd64, gcc12, openmpi) / Dev environment (Python)	❌ failure	view
Build and test (amd64, llvm, openmpi) / Dev environment (Debug)	✅ success	view
Build and test (amd64, llvm, openmpi) / Dev environment (Python)	❌ failure	view
Build and test (arm64, llvm, openmpi) / Dev environment (Debug)	✅ success	view
Build and test (arm64, llvm, openmpi) / Dev environment (Python)	❌ failure	view
CI Summary	❔ in_progress	view
Configure build (devdeps)	✅ success	view
Configure build (source_build)	⏩ skipped	view
Configure build (wheeldeps)	✅ success	view
Create CUDA Quantum installer	⏩ skipped	view
Create Docker images	⏩ skipped	view
Create Python metapackages	⏩ skipped	view
Create Python wheels	⏩ skipped	view
Gen code coverage	⏩ skipped	view
Load dependencies (amd64, gcc12) / Caching	✅ success	view
Load dependencies (amd64, gcc12) / Finalize	✅ success	view
Load dependencies (amd64, gcc12) / Metadata	✅ success	view
Load dependencies (amd64, llvm) / Caching	✅ success	view
Load dependencies (amd64, llvm) / Finalize	✅ success	view
Load dependencies (amd64, llvm) / Metadata	✅ success	view
Load dependencies (arm64, gcc12) / Caching	✅ success	view
Load dependencies (arm64, gcc12) / Finalize	✅ success	view
Load dependencies (arm64, gcc12) / Metadata	✅ success	view
Load dependencies (arm64, llvm) / Caching	✅ success	view
Load dependencies (arm64, llvm) / Finalize	✅ success	view
Load dependencies (arm64, llvm) / Metadata	✅ success	view
Load source build cache	⏩ skipped	view
Load wheel dependencies (amd64, 12.6) / Caching	✅ success	view
Load wheel dependencies (amd64, 12.6) / Finalize	✅ success	view
Load wheel dependencies (amd64, 12.6) / Metadata	✅ success	view
Load wheel dependencies (amd64, 13.0) / Caching	✅ success	view
Load wheel dependencies (amd64, 13.0) / Finalize	✅ success	view
Load wheel dependencies (amd64, 13.0) / Metadata	✅ success	view
Load wheel dependencies (arm64, 12.6) / Caching	✅ success	view
Load wheel dependencies (arm64, 12.6) / Finalize	✅ success	view
Load wheel dependencies (arm64, 12.6) / Metadata	✅ success	view
Load wheel dependencies (arm64, 13.0) / Caching	✅ success	view
Load wheel dependencies (arm64, 13.0) / Finalize	✅ success	view
Load wheel dependencies (arm64, 13.0) / Metadata	✅ success	view
Prepare cache clean-up	❔ in_progress	view
Retrieve PR info	✅ success	view

⚠️ Required checks (3/6) — 3 missing — declared in .github/required-checks.yml for push

Required check	Status	Link
Build and test (amd64, llvm, openmpi) / Dev environment (Debug)	✅ success	view
Build and test (amd64, llvm, openmpi) / Dev environment (Python)	❌ failure	view
Build and test (arm64, llvm, openmpi) / Dev environment (Debug)	✅ success	view
Build and test (arm64, llvm, openmpi) / Dev environment (Python)	❌ failure	view
Build and test (amd64, gcc12, openmpi) / Dev environment (Debug)	✅ success	view
Build and test (amd64, gcc12, openmpi) / Dev environment (Python)	❌ failure	view

[schweitzpgi]

How do this differ from CircuitCheck?

[sacpis]

How do this differ from CircuitCheck?

This is a WIP. It is going to change. In short, CircuitCheck is the equivalence primitive, and the Validation Core is the safe optimization harness built on top of it. Basically CircuitCheck answers "are these two circuits equal?", whereas the Validation core answers "is this candidate a safe, non-regressing improvement?" and can't be fooled by an optimizer trying to game it.