[bachase-agent]

Summary

Eligible leakage/loss requests previously needed a private binding to use fixed execution. Route public noncomp.sample through an owned prepared program so existing measurement workflows automatically use scalar or packed fixed execution, with general trajectories as the fallback. Refs #573; follows merged #609.

program = noncomp.compile(circuit, model)
print(program.explain())
result = program.sample(shots=100_000, seed=42, collect_stats=True)

• Add noncomp.compile, NonComputationalProgram, and optional NonComputationalStats. Programs own their inputs and selected strategy; each sampling call owns workers and RNG. The convenience function repeats preparation without a cross-call cache.
• Support execution="auto", "fixed", and "trajectory". Reuse the existing fixed eligibility rules and batch policy. Explicit packing rejects a trajectory selection, including zero-shot requests. Invalid circuit/model contracts propagate instead of becoming fallback reasons.
• Format explanations lazily from compact rejection metadata, existing source locations, and known resource estimates. Stats distinguish preparation attempts, trajectory starting-plan compilations, post-trap continuation compilations, and actual executed scalar/packed/trajectory work. Compilation counters sit at compilation sites; counting does not alter RNG streams.
• Update tutorials, API reference, CPU-control guidance, and the benchmark to use the public prepared API. The benchmark explicitly forces its trajectory reference and requests matching detailed-status outputs.

Breaking change

noncomp.sample now defaults to final_status=False, returning None for that field. Add final_status=True when consuming detailed QubitStatus values. Existing positional arguments, measurement/detector/observable/herald semantics, symbols(), and three-array unpacking remain supported.

This PR does not expand fixed eligibility. Timing-based tune, broader channel coverage, GPU support, and noncomputational survivor/importance sampling remain follow-ups.

Test plan

• Assertion-enabled GCC 13 Release CTest: all 1,191 cases passed, including expensive cases; no compiler warnings.
• Full Python suite: 8,811 passed, 1,304 skipped, one pre-existing failure. test_cpu_replay_rejects_non_boolean_values[0] accepts the string "0" in an untouched GPU-reference binding on this local Python 3.14 environment. The same isolated failure reproduces with the pre-PR installed build; the other six values pass. Tracked separately in Reject string record entries in the CPU replay binding #611. No GPU-reference code is changed here.
• New public API tests cover independent dense-model joint distributions, actual scalar/packed selection, Bell-pair detailed-status correlations, restoration, explicit trajectory replay against the legacy binding, zero/empty outputs, input ownership and concurrent reuse, optional reporting, validation versus fallback, and a rejected fixed-width candidate whose optimized trajectory fits.
• Review follow-ups: all 1,214 noncomputational Python tests pass, including 128 public API cases, positional compatibility, and actual continuation-compilation assertions for loss/leakage under both damping policies. The native program copy/move lifetime test passes for both selected strategies (41 assertions); a Python smoke check confirms both forced-strategy explanations.
• Existing shared noncomputational assertions now run through automatic convenience calls, reusable programs, and forced trajectories with one/two workers and their existing full-status contract. These API configurations can fall back to trajectories; dedicated tests assert actual fixed/packed selection. Fixed-versus-trajectory reference tests explicitly force and verify the trajectory path, with 40 joint-law cases covering both worker counts and scalar/packed fixed execution without redundant API permutations.
• Executable documentation: 53 passed, 8 skipped. Strict MkDocs build passes. After the guide reorganization, all nine executable examples across the affected pages pass and the strict site build passes again. Benchmark smoke checks cover scalar fixed, packed fixed, and trajectory reporting for Clifford/single-T circuits through public APIs.
• Pre-commit checks, including formatting and mypy, pass.

Public prepared benchmark checks used surface d3/d5, three rounds, leakage probability 0.003, Clifford/single-T variants, 1,000 shots, one worker, three alternating repetitions. Packed medians were 1.74-1.89 ms at d3 and 5.60-6.01 ms at d5, approximately 2.9-3.3x faster than scalar fixed sampling. Preparation is reported separately; these are matched-output local checks, not deltakit-stim parity claims.

A separate d7/r7 single-T, 10,000-shot check alternated stats off/on for six repetitions: medians were 303/306 ms, with overlapping run-to-run variation. No timing assertions are added to tests.

Contributor agreement

• I confirm this contribution is my original work (or I have the right to submit it) and I license it under this project's Apache-2.0 license.
• Human review of the AI-assisted changes is pending. The commit includes the Codex Assisted-by: trailer.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-26 15:35 UTC

[github-actions]

🐤 Performance Canary

No material performance changes detected. All 22 benchmarks remained within 5% of the base.

View 22 benchmark results

Benchmark	Base	PR	Runtime change	Assessment
Squeeze 8192 T gates	28.1 us	28.1 us	+0.0%	No material change
Phase pass, 4,096 measurement barriers	4.98 ms	5.00 ms	+0.5%	No material change
Phase pass, 4,096 Clifford regions	7.92 ms	7.93 ms	+0.1%	No material change
Phase pass, 32,000 rank-limited rotations	24.6 ms	24.7 ms	+0.2%	No material change
Phase pass, 4,096 postselected lookahead regions	4.97 ms	4.91 ms	-1.2%	No material change
Compile/plan cultivation d5	15.3 ms	15.2 ms	-0.3%	No material change
Compile+schedule+plan, coherent QEC d5/r5	14.7 ms	14.8 ms	+0.2%	No material change
Schedule pass, coherent QEC d5/r5	11.4 ms	11.3 ms	-0.0%	No material change
Schedule pass, cultivation d5	4.92 ms	4.91 ms	-0.3%	No material change
Schedule dependence build, surface code d7/r7	2.06 ms	2.06 ms	-0.1%	No material change
QV-10, 100 shots	6.90 ms	6.88 ms	-0.3%	No material change
Cultivation d5, 1,000 shots	25.9 ms	26.0 ms	+0.4%	No material change
Early rejection with noisy suffix, 1,000 shots	1.20 ms	1.21 ms	+0.5%	No material change
Coherent QEC d5/r5, width 13, 100 shots	103 ms	103 ms	-0.3%	No material change
Surface code d7/r7, 10,000 shots	14.4 ms	14.3 ms	-0.2%	No material change
Surface code d5/r5 high noise, 10,000 shots	29.4 ms	29.4 ms	+0.0%	No material change
Surface code d11/r11, 1,000 shots	5.31 ms	5.26 ms	-0.9%	No material change
EXP_VAL 20q/200 probes, 100,000 shots	50.1 ms	49.3 ms	-1.7%	No material change
external_inputs_nonclifford_packed_256_shots	159 us	159 us	-0.1%	No material change
external_inputs_nonclifford_scalar_256_shots	547 us	543 us	-0.7%	No material change
external_inputs_surface_d7_packed_256_shots	227 us	225 us	-1.0%	No material change
external_inputs_surface_d7_scalar_256_shots	16.8 ms	16.8 ms	+0.0%	No material change

_{Compared main (e16fa40) with this PR (e12a6b8) on the same runner using workload-local A/B/B/A ordering. Positive changes are slower. Changes under 5% are reported as no material change; changes of at least 5% but under 10% are notable; changes of at least 10% are possible regressions or improvements. Material changes that do not repeat in both pairs with low noise are inconclusive.}

Environment and method

• Runner CPU: AMD EPYC 7763 64-Core Processor
• Pinned logical CPU: 0
• ISA: AVX2 runtime backend (forced)
• Compiler: clang version 22.1.8
• Build: Release, x86-64-v2, ThinLTO, lld, and OpenMP enabled.
• Each pass warms every workload for at least 0.2 seconds, then runs 3 Google Benchmark repetitions with at least 0.5 seconds of measured CPU time each.
• One unreported full-suite process per revision runs before the measured pairs.
• Displayed timings are the geometric mean of the two drift-balanced pass medians.
• Material changes must repeat in both pairs with under 5% within-pass relative standard deviation; otherwise they are inconclusive.
• Results apply only to this runner and are intended to detect large regressions, not establish release performance.

View workflow run

[bachase]

This class and its description (alongside the c++ ones) are a bit confusing. What value is it providing? Is it worth keeping?

[bachase]

I'd ionly keep the brief "final_status" = true detail. We don't expect seeded samples to keep rows across releases.

[bachase]

Rather then "for the exactness argument" say "for details on which circuits and noise combinations are eligible for fixed sampling" or similar.

[bachase]

This section is a bit confusing after just coming after the fixed sampling section added above. Should it better open with something like "When a circuit is ineliglbe for a fixed smapler, the prpared trajcetory may still compile ..." ?

Stepping back, is the flow of this page still good with these new sections?