Installation · Quick Example · Documentation · Rust · Citing

PECOS (Performance Estimator of Codes On Surfaces) is a framework/library for exploring, developing, and evaluating quantum error correction protocols and hybrid quantum-classical programs.

Quantum error correcting since 2014. Fast simulators, from stabilizer to GPU. User-friendly Python API. Blazingly fast Rust core. Supported by Quantinuum.

Installation

Python:

pip install quantum-pecos

Rust: Add to your Cargo.toml:

pecos = { version = "0.1", features = ["qasm"] }

For Julia or optional features (LLVM, CUDA), see the Getting Started Guide.

Quick Example

Simulate a distance-3 repetition code with syndrome extraction using Guppy, a pythonic quantum programming language:

from pecos import Guppy, sim, state_vector, depolarizing_noise
from guppylang import guppy
from guppylang.std.quantum import qubit, cx, measure
from guppylang.std.builtins import array, result


@guppy
def repetition_code() -> None:
    # 3 data qubits encode logical |0⟩ = |000⟩
    d0, d1, d2 = qubit(), qubit(), qubit()

    # 2 ancillas for syndrome extraction
    s0, s1 = qubit(), qubit()

    # Measure parity between adjacent data qubits
    cx(d0, s0)
    cx(d1, s0)
    cx(d1, s1)
    cx(d2, s1)

    # Extract syndromes as an array
    result("syndrome", array(measure(s0), measure(s1)))

    # Measure data qubits (required by Guppy)
    _ = measure(d0), measure(d1), measure(d2)


# Run 10 shots with 10% depolarizing noise
noise = depolarizing_noise().with_uniform_probability(0.1)
results = (
    sim(Guppy(repetition_code))
    .qubits(5)
    .quantum(state_vector())
    .noise(noise)
    .seed(42)
    .run(10)
)
print(results["syndrome"])
# [[1, 1], [0, 1], [0, 0], [1, 1], [0, 0], [0, 1], [1, 1], [0, 0], [0, 1], [0, 1]]

Non-trivial syndromes like [1, 0], [0, 1], [1, 1] indicate detected errors that a decoder would use to identify and correct faults.

For OpenQASM, PHIR, or other formats, see the documentation. For a Rust example, see For Rust Users below.

What Can You Do With PECOS?

• Simulate quantum circuits using fast simulators ideal for error correction research
• Study quantum error correction codes with tools for syndrome extraction, decoding, and analysis
• Run hybrid quantum-classical programs with support for classical control flow, conditionals, and Wasm
• Add realistic noise to understand how errors affect your circuits
• Choose your backend: stabilizer simulation, state vector, or GPU-accelerated options

Documentation

For tutorials, API reference, and advanced features:

• Getting Started Guide — Installation, first simulation, next steps
• Simulators Guide — Choosing the right backend
• Noise Model Builders — Adding realistic noise
• Decoders Guide — Quantum error correction decoding
• Full Documentation — Complete API reference

Versioning

Before version 1.0.0, breaking changes may occur between minor versions (e.g., 0.1.0 → 0.2.0). We recommend pinning to a specific version in production.

Citing

If you use PECOS in your research, please cite:

@misc{pecos,
 author={Ciar\'{a}n Ryan-Anderson},
 title={PECOS: Performance Estimator of Codes On Surfaces},
 howpublished={\url{https://github.com/PECOS-packages/PECOS}},
 year={2018}
}

For additional citation formats (PhD thesis, Zenodo DOI), see the full documentation.

License

Apache-2.0 — see LICENSE for details.

---

For Rust Users

The pecos crate is the main entry point—a metacrate that re-exports functionality from the underlying crates. Enable features for what you need:

[dependencies]
pecos = { version = "0.1", features = ["qasm", "phir"] }

Common features: qasm (OpenQASM support), phir (PHIR support), llvm (LLVM IR execution), cli (command-line tools). See docs.rs/pecos for the full list.

Each crate also works standalone—use just pecos-qsim for simulation or pecos-qec for error correction without the full framework. Trait-based design makes it easy to swap implementations or integrate into your own tools.

---

For Contributors

Repository Structure

• /python/quantum-pecos/ — Main Python package (imports as pecos)
• /python/pecos-rslib/ — Rust extensions for Python
• /crates/pecos/ — Main Rust metacrate (re-exports other crates)
• /crates/pecos-*/ — Individual Rust crates (simulators, engines, etc.)
• /julia/ — Experimental Julia bindings
• /docs/ — Documentation source

Both Rust and Python are designed to be modular. Extend or replace components without forking.

See the Development Guide to get started contributing.

---