# PRISM-Q

> Open-source quantum circuit simulator written in Rust, with Python bindings.
> Nine CPU backends and four Clifford+T and Pauli-propagation engines behind one
> dispatcher, a multi-pass gate fusion pipeline, AVX2, FMA and BMI2 kernels
> (NEON on ARM64), an optional CUDA path and an optional MPI-distributed
> statevector. Input is OpenQASM 3.0 with backward-compatible 2.0 syntax, and
> circuits export back to OpenQASM 3.0.

PRISM-Q picks the state representation from the circuit. A Clifford circuit
runs on a stabilizer tableau, a Clifford+T circuit on a stabilizer-rank or
Pauli-propagation engine, a diagonal and permutation circuit on a map of basis
states, a low-entanglement circuit on matrix product states, a circuit that
splits into independent registers on per-block backends, and everything else on
a dense statevector. `BackendKind::Auto` is the default; every backend can also
be named, and the run metadata reports which one ran. The selection is a shape
rule, not a cost model.

Backend kinds: Statevector, Stabilizer, Sparse, Mps, ProductState,
TensorNetwork, Factored, FactoredStabilizer, DensityMatrix, and the Clifford+T
engines StabilizerRank, StochasticPauli, DeterministicPauli and PauliPath, plus
GPU variants (StatevectorGpu, StabilizerGpu, DensityMatrixGpu, AutoGpu) behind
the `gpu` feature and StatevectorDistributed behind the `distributed` feature.

Install: `cargo add prism-q` (Rust, crates.io) or `pip install prism-q`
(Python wheels for Linux x86_64 and aarch64, macOS arm64, Windows x64; Python
3.11 and newer). Feature flags: `parallel` (default, Rayon), `gpu` (CUDA 12.x),
`distributed`, `distributed-mpi`.

Status: pre-1.0, released on crates.io and PyPI with a changelog per release.
Licensed MIT or Apache-2.0. Source at https://github.com/AbeCoull/prism-q.

## Getting started

- [Overview](https://abecoull.github.io/prism-q/overview.html): what the library does and where to start.
- [Installation](https://abecoull.github.io/prism-q/getting-started/install.html): cargo and pip install, and the feature flags.
- [Your first circuit](https://abecoull.github.io/prism-q/getting-started/first-circuit.html): building a circuit in Rust, from the builder or from OpenQASM.
- [Shots and sampling](https://abecoull.github.io/prism-q/getting-started/shots.html): measurement records, shot counts, and seeding.
- [Choosing a backend](https://abecoull.github.io/prism-q/getting-started/choosing-a-backend.html): the automatic dispatch tree and when to override it.

## Tutorials

- [Tutorials](https://abecoull.github.io/prism-q/tutorials/index.html): task-shaped walkthroughs in Python with Rust equivalents, each tested in CI.
- [Simulate and sample](https://abecoull.github.io/prism-q/tutorials/simulate-and-sample.html): exact probabilities, shot counts, and choosing a backend.
- [Variational circuits and gradients](https://abecoull.github.io/prism-q/tutorials/variational.html): adjoint and parameter-shift gradients, `Parameters`, `PreparedCircuit`, and batched sweeps.
- [Noisy simulation](https://abecoull.github.io/prism-q/tutorials/noisy-simulation.html): `NoiseBuilder` rules, device calibrations, and exact density-matrix answers.
- [A QEC memory experiment](https://abecoull.github.io/prism-q/tutorials/qec-memory.html): a repetition code built with `QecProgram`, its detector error model, and union-find decoding.
- [Dynamic circuits](https://abecoull.github.io/prism-q/tutorials/dynamic-circuits.html): mid-circuit measurement, reset, and `if`/`else` from OpenQASM 3.
- [Large and structured circuits](https://abecoull.github.io/prism-q/tutorials/large-circuits.html): stabilizer, stabilizer rank, Pauli propagation, and MPS runs past the statevector limit, with `require_exact()` and result metadata.

## Guides

- [Python bindings](https://abecoull.github.io/prism-q/guides/python.html): the wheel surface, which Rust terminals it exposes, and numpy interop.
- [Backends deep dive](https://abecoull.github.io/prism-q/guides/backends.html): memory layout, gate support, and applicability per backend.
- [Capability and support matrix](https://abecoull.github.io/prism-q/guides/capabilities.html): which gates, channels, and terminals each backend answers, CPU and GPU.
- [Performance and SIMD](https://abecoull.github.io/prism-q/guides/performance.html): parallel thresholds, kernel dispatch, and the tuning knobs.
- [Benchmark methodology](https://abecoull.github.io/prism-q/guides/benchmarking.html): what the published timings include, the warmup and timing rules, the Criterion targets, and the controls for a fair comparison against another simulator.
- [OpenQASM support](https://abecoull.github.io/prism-q/guides/openqasm.html): the accepted subset, the Braket dialect, gate modifiers, and export.
- [Drawing circuits](https://abecoull.github.io/prism-q/guides/drawing.html): text diagrams, gate-density heatmaps, and SVG output from Rust.
- [Clifford+T simulation](https://abecoull.github.io/prism-q/guides/clifford-t.html): stabilizer rank, sparse Pauli propagation, and their exactness contracts.
- [Noise and QEC](https://abecoull.github.io/prism-q/guides/qec.html): noise channels, trajectory and exact mixture routes, detectors, and decoding.
- [GPU backend](https://abecoull.github.io/prism-q/guides/gpu.html): the CUDA path, what it accelerates, and how to enable it.
- [Distributed statevector and MPI](https://abecoull.github.io/prism-q/guides/distributed.html): the rank layout, qubit relabeling, launch scripts, and limits.

## Architecture

- [Overview and layered design](https://abecoull.github.io/prism-q/architecture/overview.html)
- [Parser and circuit IR](https://abecoull.github.io/prism-q/architecture/ir.html)
- [Fusion pipeline](https://abecoull.github.io/prism-q/architecture/fusion.html): the multi-pass gate fusion chain and its width thresholds.
- [Simulation engine and dispatch](https://abecoull.github.io/prism-q/architecture/engine.html): how `BackendKind::Auto` resolves a circuit to a backend.
- [Backends](https://abecoull.github.io/prism-q/architecture/backends.html): each backend's position in the design.
- [Compiled samplers](https://abecoull.github.io/prism-q/architecture/samplers.html)
- [Native QEC program IR](https://abecoull.github.io/prism-q/architecture/qec-ir.html)
- [QEC program execution](https://abecoull.github.io/prism-q/architecture/qec-programs.html)
- [Threading, SIMD, and memory layout](https://abecoull.github.io/prism-q/architecture/threading-simd.html)
- [Error model and public API](https://abecoull.github.io/prism-q/architecture/api-surface.html): the error type, the panic policy, and what is public surface.

## Reference

- [Benchmarks](https://abecoull.github.io/prism-q/benchmarks.html): wall-clock timings on a fixed circuit suite, with the command that reproduces them.
- [Comparative measurements](https://abecoull.github.io/prism-q/comparison.html): the same circuit families timed beside Qiskit Aer, qsim, QuEST, Spinoza and RustQIP on one host, with versions, settings, an equivalence check per row, and a committed harness that reproduces the table.
- [Circuit builders](https://abecoull.github.io/prism-q/reference/builders.html): the prebuilt circuit generators.
- [Glossary](https://abecoull.github.io/prism-q/glossary.html)

## Limitations

- OpenQASM 3.0 coverage is a practical subset; a construct outside it returns an
  `UnsupportedConstruct` error naming it. The OpenQASM guide lists the subset.
- The dense statevector is capped by host memory (half of physical memory by
  default, `PRISM_MAX_SV_QUBITS` overrides); past it, automatic dispatch falls
  back to sparse or MPS representations, which are exact only when the circuit
  fits them.
- The density matrix and distributed statevector backends are never selected
  automatically.
- A GPU context binds one device; there is no multi-GPU or distributed GPU
  execution. The stabilizer GPU path is experimental. ROCm is not implemented.
- The distributed backend is CPU only, needs a power-of-two rank count, and
  rejects noise models.
- Amplitudes are `f64` complex on every backend; there is no single-precision
  mode.
- Library only: no command-line tool, GUI, or hardware backend connectivity.

## Optional

- [API reference on docs.rs](https://docs.rs/prism-q): generated rustdoc for every public item.
- [Crate on crates.io](https://crates.io/crates/prism-q)
- [Package on PyPI](https://pypi.org/project/prism-q)
- [Changelog](https://github.com/AbeCoull/prism-q/blob/main/CHANGELOG.md)
- [Contributing guide](https://github.com/AbeCoull/prism-q/blob/main/CONTRIBUTING.md)
- [Citation metadata](https://github.com/AbeCoull/prism-q/blob/main/CITATION.cff)
