Metadata-Version: 2.4
Name: paulistrings-rs
Version: 0.1.2
Requires-Dist: numpy>=1.24
Requires-Dist: pytest-benchmark>=4 ; extra == 'bench'
Requires-Dist: qiskit ; extra == 'bench'
Requires-Dist: numpy ; extra == 'bench'
Requires-Dist: stim ; extra == 'bench'
Requires-Dist: pytest>=7 ; extra == 'dev'
Requires-Dist: pytest-benchmark>=4 ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'
Requires-Dist: maturin ; extra == 'dev'
Requires-Dist: matplotlib ; extra == 'examples'
Requires-Dist: stim ; extra == 'examples'
Requires-Dist: qiskit ; extra == 'examples'
Requires-Dist: qiskit-aer ; extra == 'examples'
Requires-Dist: numpy ; extra == 'examples'
Requires-Dist: mpi4py>=4,<5 ; extra == 'mpi'
Provides-Extra: bench
Provides-Extra: dev
Provides-Extra: examples
Provides-Extra: mpi
License-File: LICENSE-MIT
License-File: LICENSE-APACHE
Summary: Classical simulation of quantum circuits in the Pauli basis, with a parallel Rust engine
Author-email: Lukas Devos <ldevos@flatironinstitute.org>
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# paulistrings-rs

[![CI](https://github.com/lkdvos/paulistrings-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/lkdvos/paulistrings-rs/actions/workflows/ci.yml)
[![docs](https://github.com/lkdvos/paulistrings-rs/actions/workflows/docs.yml/badge.svg)](https://lkdvos.github.io/paulistrings-rs/)
[![license](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)](#license)

<!-- Pitch paragraph is single-sourced with crates/paulistrings/README.md — keep the two word-identical.
     The docs site pulls this same text in mechanically through the ANCHOR markers below
     (docs/book/src/index.md), so it cannot drift there; only these two files need syncing by hand. -->
<!-- ANCHOR: pitch -->
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.
<!-- ANCHOR_END: pitch -->

Inspired by [`PauliStrings.jl`](https://github.com/nicolasloizeau/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

```bash
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](https://lkdvos.github.io/paulistrings-rs/installation.html) covers GPUs, MPI and building from source.

```python
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.

![Average X magnetization vs time for a 6x6 periodic Ising quench, two field strengths h (color) and five TopN term caps each (opacity)](https://raw.githubusercontent.com/lkdvos/paulistrings-rs/main/docs/book/src/assets/ising-quench-convergence/quench_convergence.svg)

Walkthrough: [Quenched time-evolution](https://lkdvos.github.io/paulistrings-rs/#quenched-time-evolution) on the documentation site.

A larger Python examples & benchmarks suite lives under [`examples/`](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`](examples/README.md).

## Documentation

- Documentation site — showcases, benchmarks and cross-engine comparisons, rebuilt on every push to `main`: [lkdvos.github.io/paulistrings-rs](https://lkdvos.github.io/paulistrings-rs/).
  Source and local build instructions: [`docs/`](docs/README.md).
- Rust developer reference: [docs.rs/paulistrings](https://docs.rs/paulistrings), or the rustdoc rendered alongside the site at [lkdvos.github.io/paulistrings-rs/api/](https://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](https://lkdvos.github.io/paulistrings-rs/).
The Rust crate's rustdoc is a developer guide to the engine rather than a user API.
[`CLAUDE.md`](CLAUDE.md) lists the build, test and benchmark commands.

```bash
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](LICENSE-MIT) or
[Apache License 2.0](LICENSE-APACHE), at your option.

