Skip to content

feat(tableau): batch Clifford gates with combined bitmask ops - #51

Merged
Roger-luo merged 2 commits into
mainfrom
feat/batch-clifford-gates
Apr 12, 2026
Merged

Roger-luo merged 2 commits into
mainfrom
feat/batch-clifford-gates

Conversation

@Roger-luo

Copy link
Copy Markdown
Collaborator

Summary

  • Add optional neon feature flag with batch Clifford gate methods using combined bitmask operations
  • Single-qubit batches (sqrt_y_batch, sqrt_x_batch, etc.) merge N same-word gates into one mask swap/XOR + popcount parity — O(1) per word per row
  • CZ block pairs (cz_block_pairs, cz_block_pairs_cross_word) replace N constant-offset CZ calls with single word-level shift+XOR+popcount
  • New tableau-msd-fused benchmark demonstrating the batch API

MSD benchmark: 63.4µs vs 125.9µs = 49.6% faster (65% from original 181µs)

Key findings from the autotune experiment

  • LLVM auto-vectorizes [u64; 2] ops on aarch64 — explicit NEON intrinsics provide no benefit
  • Dynamic dispatch (match) in inner loops is catastrophic for branch prediction (3x slower)
  • Variable-address inner loops prevent compiler constant folding (1.7x slower)
  • Combined bitmask is the winning pattern: merge all same-word, same-type gates into a single mask, then apply once per word per row with popcount parity for phase
  • CZ with variable offsets cannot be combined without per-pair branches — only constant-offset CZ benefits from block pairs

Test plan

  • All 117 ppvm-tableau tests pass (with and without neon feature)
  • 10 new batch correctness tests verify batch methods match individual gate application
  • 7 new CZ block pairs tests (same-word, cross-word, edge cases)
  • Full workspace compilation clean (fmt, check, clippy)
  • Review that batch API design is ergonomic for integration into user code

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Apr 12, 2026 •

Copy link
Copy Markdown
PR Preview Action v1.8.1

QR code for preview link

🚀 View preview at
https://QuEraComputing.github.io/ppvm/pr-preview/pr-51/

Built to branch gh-pages at 2026-04-12 03:18 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

Add batch Clifford gate methods that use combined bitmask operations
for significant performance gains on circuits with many same-type gates.

## New APIs

### Combined bitmask single-qubit batches
- `sqrt_y_batch`, `sqrt_y_adj_batch`, `sqrt_x_batch`, `sqrt_x_adj_batch`, `h_batch`
- Merge N same-word, same-type gates into a single mask swap/XOR + popcount
  parity for phase — O(1) per word per row regardless of gate count

### CZ block pairs
- `cz_block_pairs(base, offset, count)` — constant-offset same-word CZ
- `cz_block_pairs_cross_word(word_c, bit_c, word_t, bit_t, count)` — cross-word CZ
- Replace N individual CZ calls with single word-level shift+XOR+popcount

### Benchmark
- `tableau-msd-fused` benchmark demonstrating batch API usage

## Performance

MSD benchmark: **62.9µs vs 122.5µs = 48.7% faster**
(From original pre-optimization 181µs: **65.3% total improvement**)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@Roger-luo
Roger-luo force-pushed the feat/batch-clifford-gates branch from b543197 to 00c67ea Compare April 12, 2026 03:10
Verifies that the full MSD circuit using batch methods (sqrt_y_batch,
cz_block_pairs, cz_block_pairs_cross_word) produces identical measurement
outcomes to the naive individual-gate version across 50 random seeds.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@Roger-luo
Roger-luo force-pushed the feat/batch-clifford-gates branch from 5fddef5 to 7d6489e Compare April 12, 2026 03:16
@Roger-luo
Roger-luo merged commit 406bcbe into main Apr 12, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant