Performance and SIMD
Performance is the primary product requirement. This guide explains the mechanisms that make PRISM-Q fast and the knobs you can turn. The internals live in the architecture reference under Fusion Pipeline and Threading, SIMD, and Memory Layout.
The three levers
- Fusion collapses many small gate passes into fewer, larger ones before execution, reducing memory traffic over the statevector. It is qubit-count gated and zero-cost when it does not apply.
- Cache-resident tiling keeps batched gates (
MultiFused,Multi2q) operating on L2/L3-sized tiles so repeated passes reuse hot data. - SIMD vectorizes the inner complex-arithmetic loop with AVX2+FMA, FMA, and BMI2, with a scalar fallback on non-x86_64.
The levers are ordered, and lever 3 comes with a prior question: can the arithmetic be removed rather than issued faster? A kernel whose operations an algebraic identity or an operator structure deletes is bounded by its memory floor; vectorizing what remains is bounded by the complex-arithmetic issue ceiling, near 23% of FMA peak in the interleaved layout.
Threading
Rayon parallel kernels engage at ≥14 qubits (below that, thread-pool overhead
dominates), with MIN_PAR_ELEMS = 4096 per task. The pool defaults to all logical cores.
Set RAYON_NUM_THREADS to cap parallelism. Hyperthreading helps at 24+ qubits by hiding
memory latency, but on a contended host it adds noise to benchmarks.
An application that already owns the process-wide Rayon pool can keep it: build a
ThreadPool::with_threads(n) and run simulations inside install. The global pool is
left unbuilt on that path.
Determinism
Deterministic partitioning makes unitary evolution and seeded terminal sampling on the dense backends bitwise reproducible at any thread count. Parallel reductions (norms, collapse probabilities, expectation values) are stable to about 1e-12 but not bitwise, and the batched compiled sampler seeds one RNG stream per worker, so its shots reproduce only at a fixed thread count. The per-path contract is in Threading, SIMD, and Memory Layout.
Tuning environment variables
| Variable | Effect |
|---|---|
PRISM_MAX_SV_QUBITS | Override the statevector memory cap |
RAYON_NUM_THREADS | Cap Rayon thread count |
PRISM_NO_AVX2_2Q | Force the 128-bit FMA 2q kernel (A/B comparison) |
PRISM_NO_REORDER | Disable disjoint Fused2q tier grouping |
PRISM_GPU_MIN_QUBITS | GPU crossover qubit count (with the gpu feature) |
Benchmarking
Always run benchmarks with --features parallel. The baselines were taken with Rayon
enabled; without it, large circuits run single-threaded and are not comparable. Never run
two cargo bench processes at once: competing Rayon pools cause large swings.
cargo bench --bench circuits --features parallel # circuit macrobenchmarks
cargo bench --bench bench_driver --features parallel # gate microbenchmarks
For current wall-clock numbers across the circuit suite, see the Benchmarks page.