# PECOS carries two version numbers, a 0.2 dev for Rust and a 0.11 dev for Python

> Performance Estimator of Codes On Surfaces is a quantum error-correction framework with a Rust core behind a Python API, spanning simulators, decoders, noise models and hybrid quantum-classical execution with WebAssembly. The workspace files document their own sharp edges, including dependency duplication that exists because of a specific packaging bug.

**PECOS-packages/PECOS** — Software for exploring, developing, and evaluating quantum error-correction protocols.

- Repository: https://github.com/PECOS-packages/PECOS
- Stars: 62 · Forks: 16
- Language: Rust
- License: Apache-2.0
- Published: 2026-08-21 · Updated: 2026-08-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/pecos-packages-pecos

## The Rust and Python workspaces carry different dev versions

The repository publishes one project under two version schemes, and nothing in the release tags suggests they are the same counter. The Python workspace declares its version as 0.11.0.dev0, and the three most recent releases are named with a py prefix followed by matching dev numbers, the newest being py-0.11.0.dev0. The Rust workspace declares 0.2.0-dev.0. So the Rust crates sit far behind the Python package in their own numbering, which is less a mistake than two lines of development that were never reconciled. The default branch is dev, not main, so a clone gives you the development tip of both. Anyone writing a requirements file alongside a Cargo manifest needs to record both numbers, because a PECOS version on its own does not tell you which half you have. The two install lines, as documented, are:

```bash
pip install quantum-pecos
```

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

## CUDA dependency lists are duplicated because groups do not propagate extras

The Python workspace file contains the longest explanatory comment in the repository, and it documents a packaging failure rather than a design preference. CUDA support is offered as one extra per toolkit major, so a sync command can request a specific CUDA major. The comment records that the original approach, pointing the group at another workspace member's extra, does not propagate that extra into the lock file, so the sync installed nothing at all. The fix was to list the packages themselves rather than reference them through another member, which means the same three packages are now written out twice, once per CUDA major. A script is responsible for keeping those two lists identical to the matching package extras, and the instruction is explicit: pick the extra matching your CUDA major and do not install both.

## Python bindings skip linking the interpreter library, because it breaks the test run

The Rust workspace file carries another comment explaining something that looks like an omission. Three settings that would normally be enabled for Python bindings are deliberately not turned on at the workspace level. The reason given is that they tell the build tool to skip linking the Python library at build time, which is correct when a maturin build produces the extension module but fatal for a plain test run. So each of the Rust extension crates gates those settings behind a feature of its own, and the Python build opts in through the Python workspace file instead. The result is that the same workspace builds two different ways depending on who is invoking it, and a contributor who enables the settings globally to tidy things up will find that the tests stop running.

## Six Selene plugins are workspace members, one per backend

The workspace lists a plugin package for each simulation backend rather than one plugin with backend switches, and the names make the enumeration clear: general noise, a matrix product state variant, a stabilizer variant, a state vector variant, plus a stabilizer plugin and a master plugin. Each appears as a member of both the Rust and Python workspaces, which is what lets a single build produce bindings for all of them. Alongside these sit the core extension crates for experimental work, the CUDA and LLVM variants, and the main Python package. The Rust workspace reaches further still, adding the synthesizer crate, a benchmarks crate, and three separate experimental directories including two zlup variants and a zluppy binding, so the split between stable crates and experiments is expressed as workspace membership rather than as a naming convention.

## The crate you install is a re-export, not an implementation

The published Rust crate is described as a metacrate that re-exports functionality from the underlying crates, which is why the feature list is about formats and backends rather than about capabilities. Enabling the OpenQASM and PHIR features turns on those two formats; the LLVM feature adds execution through the LLVM intermediate representation; the command-line feature adds tools. Because it is only a re-export, every underlying crate also works on its own, so you can take the simulator crate or the error-correction crate without the full framework. The stated reason is that the design is trait-based, which is what makes swapping an implementation or integrating into your own tooling possible. The cost of that flexibility is that a dependency declared as a single crate actually pulls a graph of them.

## The install names differ three ways between Python and Rust

The names are worth lining up before you start, because none of them match each other. On the Python side the distribution you install is quantum-pecos, and the name you import is shorter than that. On the Rust side the crate is pecos, matching the import rather than the distribution. The Python package version and the Rust crate version are also unrelated, as covered earlier. The optional surface is a fourth axis: a getting started guide exists specifically for Julia and for the optional features, which is a signal that those paths are supported but not the default path. Julia bindings are described as experimental and live in their own directory, and the workspace file includes a dedicated crate for them alongside the Python extensions.

## Breaking changes are expected between minor versions until 1.0.0

The versioning policy is stated in one sentence and it is unambiguous: before 1.0.0, breaking changes may occur between minor versions, with a jump from 0.1.0 to 0.2.0 given as the example, and pinning to a specific version is recommended for production use. That is the conventional pre-1.0 contract, but here it interacts badly with the two-version scheme, because a Python minor bump and a Rust minor bump are not the same event and there is no single number to pin against. The repository does carry the tooling for disciplined releases: a Justfile for task running, a releasing document, a deny configuration for dependency licensing, a vulnerability scanner configuration, a lock file, a pre-commit configuration and separate lint configuration for the Python and Markdown sides. The citations block records the project as dating from 2018, and the description claims the underlying work goes back to 2014.

## The example files name the experiments rather than the features

Look at the examples directory and you get a better sense of what the framework is actually used for than the documentation gives you. The notebooks are named after questions: dusting off a colour code, a repeated single-flag Steane code, translating a Steane code into Guppy, surface codes with selective local reconstruction, autodetection, measurement throughput benchmarking, and a cluster of surface-code experiments covering noisy decoding, a Selene demonstration, threshold exploration and more threshold exploration. The non-notebook examples are equally specific, with a Rust engine selection file, a Guppy builder demonstration, an integration example, an LLVM file and a QASM directory. A filename like dusting off color code is not something a feature list would contain, and it is a fair signal of what a user arrives wanting to do.

## Conclusion

Use PECOS if you are prototyping quantum error-correction protocols and want one framework spanning circuit simulation, syndrome extraction, decoding and noise models rather than stitching those together yourself, since the Rust core and the Python API cover the same surface. Do not assume the version numbers line up: the Rust workspace and the Python workspace carry separate dev versions, and the default branch is dev rather than main. Pin both if you depend on either. Before enabling the CUDA path, read the packaging note in the Python workspace file and install only the extra matching your CUDA major, because the lists are duplicated on purpose and a script enforces that they stay identical.

## FAQ

### How do I install PECOS?

For Python, install the quantum-pecos package with pip. For Rust, add the pecos crate to your manifest with the features you need, such as qasm or phir. A getting started guide covers Julia and the optional LLVM and CUDA features.

### What is the PECOS Rust crate?

It is a metacrate that re-exports functionality from the underlying crates, with features for OpenQASM, PHIR, LLVM IR execution and command-line tools. Each underlying crate also works standalone, such as the simulator crate or the error-correction crate.

### Which Python versions does PECOS support?

Python 3.12, 3.13 and 3.14, with the Python workspace declaring 3.12 or newer as the requirement.

### How do I install the PECOS CUDA support?

Pick the extra matching your CUDA major, either cuda12 or cuda13, and do not install both. The package lists are written out twice rather than referenced through a workspace member's extra, because a group referencing another member's extra does not propagate into the lock file and installs nothing.

### Can I rely on PECOS minor version upgrades?

Not before 1.0.0. Breaking changes may occur between minor versions, such as from 0.1.0 to 0.2.0, and pinning to a specific version is recommended for production. The Python and Rust workspaces also carry separate version numbers.

## Sources

- [Official README](https://github.com/PECOS-packages/PECOS#readme)
- [Project repository](https://github.com/PECOS-packages/PECOS)
- [Release notes](https://github.com/PECOS-packages/PECOS/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pecos-packages-pecos