Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
39 commits
Select commit Hold shift + click to select a range
ea4e9e3
feat(statevector): add the host code that GPU backends share
rafaelha Nov 10, 2026
1c3a3d8
fix(statevector): bound the GPU noise tables, chunk sizes and shot-wo…
rafaelha Nov 10, 2026
44264cb
fix(statevector): draw noise of tiny probabilities from 48-bit skips
rafaelha Nov 10, 2026
0bff456
refactor(statevector): assert the tape dialects' chunk size
rafaelha Nov 11, 2026
710ddf2
refactor(statevector): drop rows.pieces
rafaelha Nov 11, 2026
df60b74
refactor(statevector): share the noise split and screen pass rate
rafaelha Nov 11, 2026
41503fd
refactor(statevector): share the tape kernel's glue and limits
rafaelha Nov 11, 2026
f25fcfc
refactor(statevector): share the GPU samplers' fork warning
rafaelha Nov 11, 2026
fd8beac
feat(statevector): sample on CUDA GPUs on the shared GPU host code
rafaelha Nov 10, 2026
bfa5063
fix(statevector): fix CUDA sampler issues found in review
rafaelha Nov 10, 2026
d832e66
refactor(cuda): pack whole shot words, without piece tables
rafaelha Nov 11, 2026
5b354f6
refactor(cuda): use the shared GPU helpers
rafaelha Nov 11, 2026
bce6606
refactor(cuda): let the CUDA package choose its sampler
rafaelha Nov 11, 2026
23841cd
refactor(cuda): name the thread counts and the counts words
rafaelha Nov 11, 2026
1d3b8ee
refactor(cuda): move the kernels' CUDA C++ to cuda/kernels.py
rafaelha Nov 11, 2026
e211b59
test(cuda): one parametrized comparison with cat5
rafaelha Nov 11, 2026
70e55b8
docs(cuda): shorten the changelog entry and the strategy docstrings
rafaelha Nov 11, 2026
8a7f4cf
Merge remote-tracking branch 'origin/main' into simplify/gpu-shared
rafaelha Nov 11, 2026
27b9806
Merge remote-tracking branch 'origin/feat/gpu-shared' into simplify/cuda
rafaelha Nov 11, 2026
f9d8591
Merge origin/main into the CUDA backend
rafaelha Nov 12, 2026
7562138
feat(cuda): sample with the device argument and Metal's fixes
rafaelha Nov 12, 2026
9371e02
docs: document the CUDA backend beside Metal
rafaelha Nov 12, 2026
86bd80b
perf(cuda): keep leading whole bytes a view of the rows; tie check ou…
rafaelha Nov 12, 2026
6f99566
Merge origin/main (1.1.0, #296) into the CUDA backend
rafaelha Nov 12, 2026
c34fb8c
fix(cuda): defer noise only where noise_kept can stage a block
rafaelha Nov 13, 2026
f96825b
fix(cuda): grow a call's host rows by the pass rate seen so far
rafaelha Nov 13, 2026
8a6e592
feat: device="auto" tries CUDA before Metal
rafaelha Nov 13, 2026
299f45a
fix(cuda): defer noise only where noise_kept fits shared memory
rafaelha Nov 13, 2026
67a4dfa
fix(cuda): free a chunk's device rows once its copy has landed
rafaelha Nov 13, 2026
9054c8f
ci: leave the CUDA package out of coverage, as Metal is
rafaelha Nov 13, 2026
2145b4d
docs(skills): cover the CUDA backend
rafaelha Nov 13, 2026
d65a109
refactor(gpu): drop the unused observable expectations
rafaelha Nov 13, 2026
bd8777d
refactor(cuda): gather rows with one kernel
rafaelha Nov 13, 2026
fccef75
refactor: keep the shared GPU code and Metal as on main
rafaelha Nov 13, 2026
ab1aa12
Merge branch 'main' into cuda/on-main
rafaelha Nov 17, 2026
ec27f8a
refactor(cuda): run a call's chunks as _start and _finish
rafaelha Nov 17, 2026
6107fd1
refactor(cuda): give each slot's streams and counts a _Slot
rafaelha Nov 17, 2026
cd656bd
perf(cuda): pass the counts array to the noise and tape kernels
rafaelha Nov 17, 2026
d140f3d
fix(cuda): fall back to the CPU when NVRTC cannot load
rafaelha Nov 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 29 additions & 7 deletions .claude/skills/benchmarking-tsim/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@ circuit k device shots/s kept compile shots/s vs ref (
inject_cultivate_d5_p0.001 6 cpu 13.9M 0.141 0.13 1.20x [1.19, 1.21] faster 0.96x same
```

- `device` is where the new side sampled (`cpu`, or a GPU backend such as `metal`).
A row that ends in `DEVICE: cpu -> metal` compares two devices: its ratio is not
- `device` is where the new side sampled (`cpu`, or a GPU backend: `metal` or `cuda`).
A row that ends in `DEVICE: cpu -> metal` (or `cuda`) compares two devices: its ratio is not
a code change.
- `kept` is the fraction of shots that survive postselection (`-` when there is none).
- `k` is the active width of the compiled sampler. With `--ref`, a row that ends in
Expand Down Expand Up @@ -82,7 +82,9 @@ uv run tsim-dev bench --side .:threads=4 --side origin/main:threads=4
- Compile time is compared too; when the sides differ only in threads, read the rate
column.

## Apple-silicon Macs (Metal)
## GPUs

### Apple-silicon Macs (Metal)

On a Mac with an M-series chip, the default strategy samples on the GPU through Metal
whenever every component has at most 11 active qubits (k_max <= 11). A plain `uv sync`
Expand All @@ -108,22 +110,42 @@ uv run tsim-dev bench --side .:device=gpu --side .:device=cpu,threads=10 # GPU
- `--device cpu` (the default) runs tsim-bench's worker through `dev/tsim_dev/on_device.py`,
which compiles with `device="cpu"`; `--device gpu` leaves Tsim's `device="auto"`.
- The GPU's rate depends on call size much more than the CPU's: each call pays a fixed cost
(setting up the launches, waiting for the GPU to finish), and each batch of up to 2^20 shots is one
launch. The bench calibrates calls to about 0.3 s, which is enough. A GPU rate measured
(setting up the launches, waiting for the GPU to finish), and each batch of up to 2^20 shots
(2^22 on CUDA) is one launch. The bench calibrates calls to about 0.3 s, which is enough. A GPU rate measured
with calls of 10^5 shots or fewer, or with a small `batch_size`, measures overhead, not
sampling; never report one. Leave `batch_size` unset on the GPU; it can only lower the
batch, and it changes a seed's GPU samples.
- A reference without the Metal backend samples on the CPU even with `--device gpu`; its
rows end in `DEVICE: cpu -> metal`, and the ratio compares devices, not code.
- Compare the GPU with all CPU cores (`--threads N`, from the `NOTE` line), not one.
- Say whether rates are bit-packed (the default) or `--bools`, above all on a GPU: booleans
cost it 2.3-3.2x on circuits with hundreds of detectors (surface_d7_r7: 757M packed,
237M booleans on an M4 Pro), against 1.0-1.8x on the CPU, so a boolean comparison
cost it 2.3-3.2x on Metal on circuits with hundreds of detectors (surface_d7_r7: 757M
packed, 237M booleans on an M4 Pro) and 7-8x on CUDA (surface_d7_r7: 1,168M packed, 159M
booleans on an RTX 5090), against 1.0-1.8x on the CPU, so a boolean comparison
understates the GPU's lead. Compare Tsim with other simulators on the same output format.
- The GPU's own time per kernel: set `tsim.statevector.metal.runtime.PROFILE = {}` before
a `sample` call, which then runs each dispatch alone and adds its GPU seconds under the
kernel's name (`noise`, `tape`, `gather_rows`, ...).

### NVIDIA GPUs (CUDA)

With CuPy installed (`uv sync --extra cuda`; CUDA 13, driver 580 or later), the default
strategy samples on an NVIDIA GPU under the same conditions as Metal, and `"auto"` tries CUDA
before Metal. A plain `uv sync` does not install CuPy, so check that the `device` column says
`cuda`. On an RTX 5090 the full corpus (k_max <= 11) ran at a median of 286x one CPU core,
bit-packed; end-to-end cultivation d=5 at about 1.6G shots/s.

Everything in the Metal section holds, with `cuda` for `metal`, except:

- `--ref` builds the reference with `uv sync --no-dev`, without CuPy, so its side samples on
the CPU and its rows end in `DEVICE: cpu -> cuda`. For a GPU A/B, check the reference out
in a worktree, `uv sync --extra cuda` there, and pass it as a side:
`--side .:device=gpu --side /path/to/ref-worktree:device=gpu`.
- With `--threads 1`, all of a circuit's workers are pinned to one core, so compiles of a
minute or more (distillation d17+, stability t100) can time out; pass `--timeout 3600`.
- For the GPU's own time per kernel, use Nsight Systems (`nsys profile`) or Nsight Compute;
the 5090 needs a 2025 or later release.

## What the command controls for you

- One thread, pinned to a core (`--threads N` to change; say so when you report).
Expand Down
23 changes: 13 additions & 10 deletions .claude/skills/profiling-tsim/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,23 +32,26 @@ Tsim is slow:
sampler its 10 measurements at 11.6M (Apple M4 Pro).
- **Output.** The harness times bit-packed rows, Tsim's own output. `--bools`
times `sample()`'s default boolean output, which adds a conversion: 1.6-1.8x on
surface_d7_r7 on the CPU, and 2.3-3.2x on a GPU for circuits with hundreds of
detectors (Metal on an M4 Pro: surface_d7_r7 3.2x, end2end_d3_dsurface15 2.8x,
hook_inject_T_d15_pd5 2.3x; under 1.3x for circuits with few detectors). A slow
surface_d7_r7 on the CPU, and on a GPU for circuits with hundreds of detectors
2.3-3.2x on Metal (M4 Pro: surface_d7_r7 3.2x, end2end_d3_dsurface15 2.8x,
hook_inject_T_d15_pd5 2.3x) and 7-8x on CUDA (RTX 5090: surface_d7_r7 7.3x,
end2end_d3_dsurface15 7.5x, hook_inject_T_d15_pd5 7.8x); under 1.3x for circuits
with few detectors. A slow
boolean rate next to a fast bit-packed one points at the conversion, not the
sampler.
- **Threads.** One pinned thread gives the rate per core. Tsim samples on all
performance cores by default (`numba.get_num_threads()`); the `NOTE` line says
how many. Quote all-core rates with `--threads N`.
- **Device.** The harness compiles with `device="cpu"`, so every side samples on
the CPU unless you pass `--device gpu` (or `--side REF:device=gpu`). On an
Apple-silicon Mac, Tsim samples on the GPU by default for k_max <= 11, 4-19x
faster than all CPU cores; there `--device gpu` measures what users get. The
Apple-silicon Mac, or with CuPy and an NVIDIA GPU, Tsim samples on the GPU by
default for k_max <= 11 (4-19x all cores on an M4 Pro, a median of about 290x one
core on an RTX 5090); there `--device gpu` measures what users get. The
`device` column says where each row sampled: under `device="auto"` a GPU falls
back to the CPU silently (components wider than 11, tiny rotations, noise beyond
its tables), and a row that ends in `DEVICE: cpu -> metal` compares a GPU with the
CPU. A slow GPU row with small calls or a small `batch_size` is launch overhead;
see "Apple-silicon Macs" in the `benchmarking-tsim` skill.
its tables), and a row that ends in `DEVICE: cpu -> metal` (or `cuda`) compares a
GPU with the CPU. A slow GPU row with small calls or a small `batch_size` is launch
overhead; see "GPUs" in the `benchmarking-tsim` skill.
- **Compile.** `compile` includes the first use of a backend in the process (about
0.1 s for Metal's PyObjC) but not the first call, whose kernel compilation goes
into `warmup_s` in the JSON.
Expand All @@ -67,8 +70,8 @@ uv run tsim-dev profile cultivation_d5 --seconds 5
The run is a fresh process, one pinned thread, warm numba cache, under a memory cap,
with bit-packed output on the CPU (`--threads`, `--device` and `--sampler` as in
step 2). py-spy sees the host only: on a GPU the sampling phase shows the wait for
the device. For Metal's time per kernel, see "Apple-silicon Macs" in the
`benchmarking-tsim` skill (`runtime.PROFILE`).
the device. For Metal's time per kernel, see "GPUs" in the `benchmarking-tsim`
skill (`runtime.PROFILE`); on CUDA use Nsight Systems or Nsight Compute.
The output splits samples by phase (`compile`, `sample`) and prints three tables:

- **innermost Tsim frame (kernel callers):** read this first. Jitted numba code has
Expand Down
2 changes: 1 addition & 1 deletion .claude/skills/shipping-tsim-changes/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ evidence.
| Any | `uv run tsim-dev check` prints PASS for lint and tests |
| Could affect compile or sampling cost (see below) | `uv run tsim-dev bench --ref origin/main`; any regression investigated and explained |
| Aims to make Tsim faster | the same with `--suite full`; see the `benchmarking-tsim` skill |
| Touches the GPU path (`statevector/gpu/`, `statevector/metal/`, or code they call) | on an Apple-silicon Mac, also `uv run tsim-dev bench --device gpu --ref origin/main` (the plain bench samples on the CPU only) |
| Touches the GPU path (`statevector/gpu/`, `statevector/metal/`, `statevector/cuda/`, or code they call) | on each GPU the change can reach (an Apple-silicon Mac, an NVIDIA GPU with CuPy), also `uv run tsim-dev bench --device gpu --ref origin/main` (the plain bench samples on the CPU only; for CUDA see "GPUs" in the `benchmarking-tsim` skill), and the GPU's tests (`test_metal_sampler.py`, `test_cuda_sampler.py`), which CI cannot run |
| Could change the active width (graph, simplification, scheduling, plan) | `uv run tsim-dev bench --width --ref origin/main`; any `wider` explained |
| Bug fix | the new test fails on `origin/main` and passes on the branch |
| User-visible | a `CHANGELOG.md` entry under `## [Unreleased]` |
Expand Down
6 changes: 3 additions & 3 deletions .claude/skills/testing-tsim-correctness/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,9 @@ handful of T gates; its memory grows exponentially.
test is a broken test.
- Stim merges consecutive identical instructions into one with several targets, so
write circuits that exercise both single- and multi-target paths.
- GPU tests: `test/conftest.py` keeps every test outside
`test/integration/test_metal_sampler.py` on the CPU. In the Metal tests compile the
GPU side with `device="metal"`, so a silent fallback cannot make the test pass on the
- GPU tests: `test/conftest.py` keeps every test outside `test/integration/test_metal_sampler.py`
and `test_cuda_sampler.py` on the CPU. In the GPU tests compile the GPU side with
`device="metal"` or `device="cuda"`, so a silent fallback cannot make the test pass on the
CPU, and the reference with `device="cpu"`; compare them with `assert_counts_match`
(GPU samples never equal CPU samples bit for bit).
- Keep circuits small (a few qubits, tens of thousands of shots) so the suite stays
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ more than a handful of T gates: their compile memory grows exponentially.
a reference. The reference-sample flags change only that.
- **Seeds:** with `active_statevector` on the CPU, a seed's samples do not depend on the
thread count or `batch_size`. Do not break this; noise blocks and per-shot draws are seeded
by call and shot index (`shots.py`). On a GPU (`statevector/metal/`) they depend on
by call and shot index (`shots.py`). On a GPU (`statevector/metal/`, `statevector/cuda/`) they depend on
`batch_size`, as documented, and differ from the CPU's.
- **Direct outputs stay direct:** outputs that depend on the noise alone never go through a
state vector. Most detectors of QEC circuits are direct, which is why the detector sampler is
Expand Down
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Added
- **NVIDIA GPU sampling.** With the new `cuda` extra
(`pip install "bloqade-tsim[cuda]"`, CUDA 13), Tsim samples on NVIDIA GPUs
through CuPy, as it does on Apple GPUs: every component must have at most 11
active qubits, `device="auto"` picks the GPU when it can run the circuit, and
`device="cuda"` raises an error explaining why it can't. On an RTX 5090,
end-to-end cultivation at d=5 samples about 1.6 billion shots per second,
postselected, in any output layout.
- The `jax-cuda12` and `jax-cuda13` extras, for the stabilizer-rank strategies
on NVIDIA GPUs with JAX. The `cuda12` and `cuda13` extras of Tsim 1.0 install
the same packages.

### Changed
- The stabilizer-rank strategies compile components of the same shape once, and
no longer run components with a single output without compiling them. A
Expand Down
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,10 @@ uv add bloqade-tsim
```

The default sampling strategy runs on the CPU, and on the GPU of an Apple-silicon Mac (no extra
needed). To run the stabilizer-rank strategies on an NVIDIA GPU, install the JAX CUDA extra:
needed). To sample on an NVIDIA GPU, install the extra of your strategy:
```bash
pip install "bloqade-tsim[cuda13]" # or bloqade-tsim[cuda12]
pip install "bloqade-tsim[cuda]" # the default strategy, "active_statevector" (CUDA 13)
pip install "bloqade-tsim[jax-cuda13]" # the stabilizer-rank strategies, with JAX (or jax-cuda12)
```

### Using Tsim with coding agents
Expand Down Expand Up @@ -82,7 +83,7 @@ Choose a strategy with the `strategy` argument of `compile_sampler` and `compile

| Strategy | Method | Runs on | Cost grows with | Use it for |
|---|---|---|---|---|
| `"active_statevector"` (default) | Dense state vector over the active qubits of each component, as in [Clifft](https://arxiv.org/abs/2604.27058) and [SymFT](https://arxiv.org/abs/2607.28600) | CPU (numba, multi-threaded), or an Apple GPU (Metal) | Number of active qubits (at most 30) | Most circuits, especially with postselection |
| `"active_statevector"` (default) | Dense state vector over the active qubits of each component, as in [Clifft](https://arxiv.org/abs/2604.27058) and [SymFT](https://arxiv.org/abs/2607.28600) | CPU (numba, multi-threaded), or an Apple GPU (Metal) or NVIDIA GPU (CUDA) | Number of active qubits (at most 30) | Most circuits, especially with postselection |
| `"cat5"`, `"bss"`, `"cutting"` | Stabilizer rank decomposition | CPU or GPU (JAX) | Number of non-Clifford gates | Few non-Clifford gates acting on many qubits; GPU throughput |

```python
Expand Down
5 changes: 3 additions & 2 deletions codecov.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# NOTE: the Metal executor needs an Apple GPU, which CI does not have; its tests
# run on Apple silicon only.
# NOTE: the GPU executors need a GPU, which CI does not have: the Metal tests run
# on Apple silicon only, and the CUDA tests on an NVIDIA GPU with CuPy installed.
ignore:
- "src/tsim/statevector/metal"
- "src/tsim/statevector/cuda"
6 changes: 3 additions & 3 deletions docs/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,10 @@ uv add bloqade-tsim
```

The default sampling strategy runs on the CPU, and on the GPU of an Apple-silicon Mac (no extra
needed). To run the stabilizer-rank strategies on an NVIDIA GPU, install the JAX CUDA extra:
needed). To sample on an NVIDIA GPU with the default strategy, install the `cuda` extra:

```bash
uv add "bloqade-tsim[cuda13]"
uv add "bloqade-tsim[cuda]"
```

See [Installation](/install) for more options.
Expand All @@ -55,7 +55,7 @@ Choose a strategy with the `strategy` argument of `compile_sampler` and `compile

| Strategy | Method | Runs on | Cost grows with | Use it for |
|---|---|---|---|---|
| `"active_statevector"` (default) | Dense state vector over the active qubits of each component, as in [Clifft](https://arxiv.org/abs/2604.27058) and [SymFT](https://arxiv.org/abs/2607.28600) | CPU (numba, multi-threaded), or an Apple GPU (Metal) | Number of active qubits (at most 30) | Most circuits, especially with postselection |
| `"active_statevector"` (default) | Dense state vector over the active qubits of each component, as in [Clifft](https://arxiv.org/abs/2604.27058) and [SymFT](https://arxiv.org/abs/2607.28600) | CPU (numba, multi-threaded), or an Apple GPU (Metal) or NVIDIA GPU (CUDA) | Number of active qubits (at most 30) | Most circuits, especially with postselection |
| `"cat5"`, `"bss"`, `"cutting"` | Stabilizer rank decomposition | CPU or GPU (JAX) | Number of non-Clifford gates | Few non-Clifford gates acting on many qubits; GPU throughput |

```python
Expand Down
49 changes: 27 additions & 22 deletions docs/install.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,55 +13,60 @@ We recommend using [`uv`](https://docs.astral.sh/uv/) for dependency management.
uv add bloqade-tsim
```

For GPU acceleration with CUDA:

```bash
# For CUDA 13
uv add "bloqade-tsim[cuda13]"

# For CUDA 12
uv add "bloqade-tsim[cuda12]"
```

## Using pip

```bash
pip install bloqade-tsim
```

For GPU acceleration with CUDA:
## GPUs

The default strategy (`"active_statevector"`) samples on an Apple GPU through Metal, or on an
NVIDIA GPU through CUDA. On an Apple-silicon Mac, the plain install includes PyObjC's Metal
bindings for it. For NVIDIA GPUs, install an extra; each sampling strategy has its own:

| Extra | Accelerates | Needs |
|---|---|---|
| `cuda` | `"active_statevector"` (the default), with CuPy | CUDA 13 (driver 580 or later) |
| `jax-cuda13` | `"cat5"`, `"bss"` and `"cutting"`, with JAX | CUDA 13 |
| `jax-cuda12` | `"cat5"`, `"bss"` and `"cutting"`, with JAX | CUDA 12 |

```bash
pip install "bloqade-tsim[cuda13]"
uv add "bloqade-tsim[cuda]"
# or, with both strategies on the GPU:
uv add "bloqade-tsim[cuda,jax-cuda13]"
```

## Apple GPUs
The `cuda12` and `cuda13` extras of Tsim 1.0 still install the JAX extras. JAX starts only
when a stabilizer-rank strategy samples, and then reserves 75% of the GPU's memory; to sample
with both strategies in one process, set `XLA_PYTHON_CLIENT_PREALLOCATE=false` before starting
Python.

On an Apple-silicon Mac, the default strategy (`"active_statevector"`) samples on the GPU
through Metal; the plain install includes PyObjC's Metal bindings for it. Where it samples is
the `device` argument of `compile_sampler` and `compile_detector_sampler`:
Where `"active_statevector"` samples is the `device` argument of `compile_sampler` and
`compile_detector_sampler`:

| `device` | Samples |
| --- | --- |
| `"auto"` (default) | On the GPU when it can run the circuit, else on the CPU, without a warning |
| `"auto"` (default) | On a GPU when it can run the circuit, else on the CPU, without a warning |
| `"cpu"` | On the CPU, in double precision |
| `"metal"` | On the GPU, or raises an error that says why it cannot |
| `"metal"` | On an Apple GPU, or raises an error that says why it cannot |
| `"cuda"` | On an NVIDIA GPU, or raises an error that says why it cannot |

```python
sampler = circuit.compile_detector_sampler(device="metal")
sampler = circuit.compile_detector_sampler(device="cuda")
```

The GPU runs circuits whose components have at most 11 active qubits. That includes Clifford
circuits, whose detectors depend on the noise alone: the GPU samples the noise as well as the
state vectors. Postselection runs on the GPU, so heavily postselected circuits gain the most.
A sampler's repr says where it samples (`samples on metal` or `samples on cpu`), and so does
`sampler.stats.device`.
A sampler's repr says where it samples (`samples on metal`, `samples on cuda` or
`samples on cpu`), and so does `sampler.stats.device`.

The GPU computes outcome probabilities in float32, so a sample follows the CPU's distribution
to within float32 rounding. Float32 cannot tell a measurement outcome of probability below
about 1e-11 from rounding error, so the GPU never draws one; a circuit with a rotation small
enough to make such an outcome (an angle within about 6e-5 π of a multiple of π/2) samples on
the CPU (or raises, with `device="metal"`).
the CPU (or raises, with `device="metal"` or `"cuda"`).

A seed's samples on the GPU differ from the CPU's and depend on `batch_size`, so with
`device="auto"` a seed reproduces its samples only on the same kind of machine. Use
Expand Down
6 changes: 6 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,12 @@ Repository = "https://github.com/QuEraComputing/tsim"
Issues = "https://github.com/QuEraComputing/tsim/issues"

[project.optional-dependencies]
# The default strategy, "active_statevector", on NVIDIA GPUs (CUDA 13).
cuda = ["cupy-cuda13x[ctk]>=14.0"]
# The stabilizer-rank strategies ("cat5", "bss", "cutting") on NVIDIA GPUs, with JAX.
jax-cuda12 = ["jax[cuda12]>=0.4.38"]
jax-cuda13 = ["jax[cuda13]>=0.7.0"]
# NOTE: the names of the JAX extras up to 1.0, kept so that they still install.
cuda12 = ["jax[cuda12]>=0.4.38"]
cuda13 = ["jax[cuda13]>=0.7.0"]

Expand Down
Loading
Loading