paulistrings-rs

Library for simulating quantum circuits in the Pauli basis, built to scale across threads, processes and nodes. Pauli strings are stored as symplectic bitvectors, and terms are assigned to workers by a hash function that is linear over the bitfield. As a result, the library can efficiently parallelize the work and compute the communication patterns for a given circuit. Additionally, for standard gate and noise sets, the amount of communication remains bounded and no global synchronization or reduction is required.

Inspired by PauliStrings.jl.

Highlights

• Operator-basis Pauli propagation at scale — evolve the observable, not the wavefunction, in either the Schroedinger or Heisenberg picture.
• GF(2)-bucketed, write-disjoint parallel engine — layers are partitioned by a GF(2)-linear hash, so output buckets are statically predictable and never collide across threads.
• Partitioned across NUMA domains and MPI ranks — Support for scaling to arbitrary amount of nodes.
• CUDA backend — one GPU runs a saturated dense two-qubit layer about 10× faster than a 16-thread host, scaling to several devices in one process or one GPU per MPI rank, included in the Linux and Windows wheels (device= from Python).
• Open extension traits for research — plug in a custom Channel (gate or noise model) or TruncationPolicy without touching the engine.
• Rust core, Python front-end — Low-overhead efficient engine with a convenient interface.

Python quickstart

pip install paulistrings-rs        # or: uv add paulistrings-rs

Wheels cover Linux, macOS and Windows, with the CUDA backend included on Linux and Windows; Installation covers GPUs, MPI and building from source.

import math
from paulistrings import Circuit, PauliSum

# Observable: average X magnetization on 4 qubits.
observable = PauliSum.from_strings(
    {"XIII": 0.25, "IXII": 0.25, "IIXI": 0.25, "IIIX": 0.25}, num_qubits=4
)

circuit = Circuit(4)
circuit.rz(math.pi / 8, 0)
circuit.cnot(0, 1)
circuit.h(2)

evolved = observable.propagate(circuit, direction="heisenberg")
print(evolved.expectation("x+").real)

Showcase

A 2D transverse-field Ising quench, evolved by Heisenberg-propagating the average-X-magnetization observable through a Trotter circuit on a 6×6 lattice — a regime where exact diagonalization is already infeasible (2^36 amplitudes) but Pauli propagation with modest truncation finishes in seconds to minutes.

Walkthrough: Quenched time-evolution on the documentation site.

A larger Python examples & benchmarks suite lives under examples/: a 127-qubit heavy-hex kicked-Ising cross-check against PauliPropagation.jl and stim, operator-scrambling/OTOC diagnostics, noisy utility verification, operator-backpropagation depth reduction, and stabilizer-state preparation. Start at examples/README.md.

Documentation

• Documentation site — showcases, benchmarks and cross-engine comparisons, rebuilt on every push to main: lkdvos.github.io/paulistrings-rs. Source and local build instructions: docs/.
• Rust developer reference: docs.rs/paulistrings, or the rustdoc rendered alongside the site at lkdvos.github.io/paulistrings-rs/api/.

Repository layout

crates/
  paulistrings/         # core Rust library
    benches/            # criterion microbenchmarks
    examples/           # phase_breakdown measurement probe
    tests/              # cross-module and differential test nets
  paulistrings-py/      # PyO3 bindings (cdylib `_paulistrings`)
  membench/             # memory-bandwidth roofline probe
python/
  paulistrings/         # Python package; re-exports the extension module
examples/
  common/               # circuit builders, oracles, timing harness, report plots
  data/                 # checked-in, provenance-tagged inputs (127q coupling map, published observables)
  tests/                # showcase and example test suites
  b1_operator_scrambling/, b2_noisy_verification/, b5_operator_backpropagation/,
  b6_resource_probes/, b7_stabilizer_prep/  # one Part-B showcase per directory — see examples/README.md
  xxz_chain/            # Benchmark D — Part A's fourth benchmark lives here, not under benchmarks/
benchmarks/
  python/               # pytest-benchmark suites + cross-library comparisons (Part A benchmarks), tests/ alongside
  julia/                # subprocess-driven PauliPropagation.jl baseline
  results/              # raw benchmark output (gitignored)
docs/
  book/                 # mdBook source for the documentation site (showcases, benchmarks,
                        #   comparisons); rendered to docs/book/site/ (gitignored)
  figures/              # source figures the book's assets are synced from
  sync-assets.sh        # links the site's figures to the committed SVGs they came from
research/
  FINDINGS.md           # one entry per experiment: question, verdict, the number that matters
  HARDWARE.md           # measured host facts (bandwidth ceilings, roofline tables, node types)

Building from source and developing

Python is the user interface, documented on the documentation site. The Rust crate's rustdoc is a developer guide to the engine rather than a user API. CLAUDE.md lists the build, test and benchmark commands.

module load uv                    # Flatiron; elsewhere see https://docs.astral.sh/uv/
./scripts/setup.sh                # one-time: uv sync into .venv, builds the extension

cargo test                        # workspace tests (Rust toolchain pinned in rust-toolchain.toml)
cargo bench -p paulistrings        # criterion microbenchmarks (release-only)

uv run pytest python/paulistrings/tests   # rebuilds the extension first after any Rust change

License

Dual-licensed under the MIT License or Apache License 2.0, at your option.