Skip to content

perf(sampler): compile stabilizer-rank components of one shape once - #302

Merged
rafaelha merged 1 commit into
QuEraComputing:mainfrom
mehmetniyazikayi:perf/compile-components-once
Nov 17, 2026
Merged

rafaelha merged 1 commit into
QuEraComputing:mainfrom
mehmetniyazikayi:perf/compile-components-once

Conversation

@mehmetniyazikayi

@mehmetniyazikayi mehmetniyazikayi commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

With strategy="cat5" a pure Clifford circuit samples slower than the same circuit with 8 T gates: 55 ms against 14 ms at 20 qubits and 1000 shots. I ran into this while benchmarking and it took me a while to see why.

Without T gates the circuit falls apart into one component per measured qubit, each with one output, and sample_component runs those without jit, about 2.8 ms a piece.

My first try was to jit them anyway. That made it worse: the first sample(1000) went from 1.8 s to 6.9 s. Turns out output_indices is a static field of CompiledComponent, so it ends up in the jit cache key and every component compiles on its own, even though they all have the same shape. Sampling never reads that field.

So this hands the component to _sample_component_jit without it and drops the one-output special case. Components of the same shape then share one compilation. It is four lines in sample_component.

1000 shots, 16 cores of a Xeon Platinum 8468, every number from a fresh process:

circuit components (shapes) first call, main first call, here sample, main sample, here
1 qubit, Clifford 1 (1) 1.59 s 1.00 s 3.3 ms 0.9 ms
20 qubits, Clifford 20 (1) 1.76 s 1.12 s 55.1 ms 6.6 ms
80 qubits, Clifford 80 (1) 1.98 s 1.19 s 219 ms 23.0 ms
20 qubits, Clifford, depolarizing noise 20 (1) 1.70 s 1.03 s 56.7 ms 6.5 ms
8 noisy blocks of 3 qubits with 2 T gates each 18 (6) 5.15 s 3.98 s 38.7 ms 7.8 ms
d=3 surface code memory, 2 rounds, measurements 5 (2) 4.90 s 3.61 s 6.7 ms 6.9 ms
20 qubits, 8 T gates 1 (1) 18.7 s 19.1 s 14.3 ms 14.9 ms
20 qubits, 12 T gates 1 (1) 22.8 s 23.4 s 81.2 ms 79.3 ms

The last two rows have one big component and don't move beyond noise. For the 1-qubit circuit the first call on this branch took 2.2 s in one run and 1.0 s in the repeat; main took 1.6 s both times. Peak RSS for the circuits in the table moves by 22 MB at most. Across all my runs the biggest change was 173 MB less, at 100000 shots.

With a fixed seed I get the same samples as on main in every case I ran: the circuits above, a Clifford block next to a T block, a detector sampler, and batch sizes 1, 1000 and 100000.

I also tried sampling all one-output components in one jitted call. A bit faster per sample (4.4 ms at 20 qubits), but the compile grows with the number of components: 10.7 s for the first call at 80 qubits. Dropped.

What I ran:

  • coverage run -m pytest test passes. There is one new test; it fails on main (6 calls of _sample_component for 2 shapes) and passes here, and it checks the samples against the eager path.
  • isort, black, ruff, pyright src test dev, deptry: clean.

What I didn't:

  • I only timed cat5. bss and cutting go through the same function and the existing tests pass for them.
  • Linux on CPU with Python 3.12 only. No GPU, no macOS, no Windows.
  • tsim-dev bench: it times the default strategy, which doesn't go through this function.

I saw in AGENTS.md that the stabilizer-rank strategies are provisional. If they're on the way out and this isn't worth carrying, just close it, no hard feelings.

output_indices is a static field of CompiledComponent and so part of the jit cache key: every component compiled on its own, and the ones with a single output were run eagerly to avoid that. Sampling does not read the field. Without it components of the same shape share one compilation, and a 20-qubit Clifford circuit with cat5 samples in 6.6 ms instead of 55 ms. Seeded samples are unchanged.
@github-actions

Copy link
Copy Markdown
Contributor

👋 Thanks for opening your first pull request against Tsim!

A quick note on contribution terms: by submitting this PR you
agree that your contribution is licensed under the
Apache License 2.0
and that you accept the
Tsim Contributor License Agreement.
Please skim those before a maintainer reviews — opening this PR
counts as your acceptance.

A few things that will speed up review:

  • Read CONTRIBUTING.md
    for the workflow, commands, and style notes.
  • Run pre-commit run --all-files and uv run pytest locally;
    CI runs the same checks.
  • Use Conventional Commits
    for commit messages.

We'll get to your PR as soon as we can. Thanks for contributing!

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-13T22:08:37.086606Z dd0d160 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dd0d1602d1

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread src/tsim/sampler.py Resolved
@codecov

codecov Bot commented Nov 17, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@rafaelha

Copy link
Copy Markdown
Collaborator

Thanks for the contribution and improvement. I'll go ahead and merge this.

Yes - I am wondering if the stabilizer backend is really useful still or used in practice. I personally have not seen any cases practical cases where it performs better than the active statevector backend (from Clifft/SymFT). Do you have any usecases or opinion on whether the stabilizer rank backend is still needed?

On the other hand, I have been having some discussions on adding an approximate stabilizer decomposition backend, which could be promising for circuits with lots of small angle rotations.

@rafaelha
rafaelha merged commit d71d6a6 into QuEraComputing:main Nov 17, 2026
14 checks passed
@mehmetniyazikayi

Copy link
Copy Markdown
Contributor Author

Thanks for merging, and for the quick review 🙏

Honest answer: i don't have a case where it wins either. But i should say what that's based on, because it's less than it sounds. Everything i ran is bloqade-tsim 0.1.5, so cat5 only and without this PR. I haven't run strategy="active_statevector" from main yet, so i can't compare the two backends inside Tsim tbh 😅

What i can say is that on random Clifford+T circuits (20 to 100 qubits, up to 24 T gates, CPU) the stabilizer-rank path in 0.1.5 was slower than Clifft and SymFT at every T count i tried, and the gap grows quickly with the T count. Beyond 24 T gates i stopped running it.

That's a narrow set tho (few qubits active at once, T gates only, no GPU run of cat5), so i wouldn't read it as "never". My guess is it could still matter where many qubits are non-Clifford-active at the same time with few T gates in total, so a dense vector over the active qubits doesn't fit. Only a guess, i have no such circuit and no use of my own that needs it.

If it helps i can run main with active_statevector next to cat5 on those circuits, just say so 🫡

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.

2 participants