Skip to main content

🧭 Canopus: Canonical-Optimized Placement Utility Suite for Quantum Compilation

PyPI License CI Python Slides Conference

Canopus (Canonical-Optimized Placement Utility Suite) is a unified qubit mapping/routing framework tailored to diverse quantum ISAs, i.e., the implementation of the paper "Unifying Qubit Routing Across Diverse Quantum ISAs via Canonical Representation". Its main function is to optimize the layout and routing of qubits on quantum hardware, handling optimal synthesis with diverse ISAs in a unified approach through two-qubit canonical gate representation, providing guidance for hardware-software co-design.

Canopus evokes the name of the second-brightest star in the sky, symbolizing its role as a "navigational" guide for routing qubits through the complex constraints of quantum hardware.

Canopus Architecture

Installation

Prerequisite: monodromy (+ lrslib)

Canopus depends on the monodromy library for Weyl-chamber coverage computation. monodromy is not on PyPI and must be installed manually before pip install canopus-quantum:

pip install git+https://github.com/Youngcius/monodromy

monodromy itself needs the lrs binary from lrslib. Platform-specific setup:

macOS
brew install gmp
cd lrslib-073 && make
sudo make install
Ubuntu / Debian
sudo apt update && sudo apt install -y build-essential libgmp-dev
cd lrslib-073 && make
sudo make install
Conda (any OS)
conda install -c conda-forge gmp
cd lrslib-073
make INCLUDEDIR="$CONDA_PREFIX/include" LIBDIR="$CONDA_PREFIX/lib"
make prefix=$HOME/.local install
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

From PyPI (recommended)

pip install canopus-quantum

Pre-compiled wheels are published for Linux and macOS on Python 3.10 – 3.13. No Rust toolchain is required for this path.

The distribution name on PyPI is canopus-quantum; the import name remains canopus:

import canopus

From source

git clone https://github.com/Youngcius/canopus.git
cd canopus
pip install .

pip install . runs the maturin build backend in an isolated environment, which:

  1. Compiles the Rust extension (canopus.utils._accel) for the active Python version,
  2. Packages the Python sources, and
  3. Installs the resulting wheel into the current environment.

Prerequisite for source builds: a working Rust toolchain. Install via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Usage

More end-to-end examples live under ./examples/:

  • routing.ipynb — Canopus routing in detail
  • rebasing.ipynb — Optimal ISA rebase (B gate, √iSWAP, arbitrary)
  • python route_demo.py to test the routing effect by Sabre and Canopus on a demo circuit
  • python route_qft.py <n> — Compare Canopus vs Sabre routing on an n-qubit QFT
  • python rebase_xxx.py to test the rebase passes for arbitrary ISAs

Package layout

canopus/                            # Python package
├── __init__.py
├── backends.py                     # Backend / ISA / cost-estimator definitions
├── basics.py                       # CanonicalGate, BGate, SQiSWGate
├── mapping.py                      # CanopusMapping & SabreMapping transpiler passes
├── synthesis.py                    # rebase_to_{canonical, sqisw, zzphase, custom, ...}
├── decomposition/                  # Two-qubit decomposition kernels
├── extensions/                     # Optional integrations (bqskit, ...)
└── utils/
    ├── _core.py                    # Pure-Python utilities
    ├── _accel.cpython-*.so         # Rust-compiled accelerator (built by maturin)
    └── _accel.pyi                  # Type stubs for the Rust extension

src/                                # Rust source for the accelerator
└── lib.rs                          # PyO3 bindings

Development

Install the dev extras and build the Rust extension in editable mode:

pip install -e ".[dev]"
poe dev          # equivalent to: maturin develop --release

Common tasks (defined in pyproject.toml):

Command Description
poe dev Build & install the Rust extension in editable mode
poe rebuild Clean and rebuild from scratch
poe build Build a redistributable wheel into ./target/wheels/
poe clean Remove every compiled artifact and cache
poe lint ruff check canopus
poe fmt ruff format canopus
poe fmt-check ruff format --check canopus
poe typecheck mypy canopus
poe test pytest
poe check Aggregate gate that CI runs: lint + fmt-check + test

See CONTRIBUTING.md for the full contribution workflow.

Evaluation artifact

./experiments/ contains the full evaluation suite that accompanies the paper.

Case studies

Benchmark suite

Evaluation commands are managed via ./experiments/Makefile. First prepare prerequisite files (coupling files, coverage sets, logical-level optimized circuits):

cd experiments && make

Then:

  • make canopus — evaluate Canopus
  • make baselines — evaluate baseline compilers (Sabre, TOQM, BQSKit)
  • make sum_result — summarize results once routing evaluation completes
  • make disp_result — display summarized routing overheads across compilers, topologies, and ISAs

For fine-grained evaluation, you may also run bench_all.py, bench_all_toqm.py, etc. directly.

Citation

If you use Canopus in your work, please cite:

@article{yang2025unifying,
  title   = {Unifying Qubit Routing Across Diverse Quantum ISAs via Canonical Representation},
  author  = {Yang, Zhaohui and Zhang, Kai and Tian, Xinyang and Ren, Xiangyu and
             Liu, Yingjian and Li, Yunfeng and Ding, Dawei and Chen, Jianxin and Xie, Yuan},
  journal = {arXiv preprint arXiv:2511.04608},
  year    = {2025}
}

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

canopus_quantum-0.2.0.tar.gz (12.9 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

canopus_quantum-0.2.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (280.9 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

canopus_quantum-0.2.0-cp313-cp313-macosx_11_0_arm64.whl (250.8 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

canopus_quantum-0.2.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (280.9 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

canopus_quantum-0.2.0-cp312-cp312-macosx_11_0_arm64.whl (250.8 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

canopus_quantum-0.2.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (281.0 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

canopus_quantum-0.2.0-cp311-cp311-macosx_11_0_arm64.whl (253.3 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

canopus_quantum-0.2.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (281.1 kB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

canopus_quantum-0.2.0-cp310-cp310-macosx_11_0_arm64.whl (253.3 kB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

Details for the file canopus_quantum-0.2.0.tar.gz.

File metadata

  • Download URL: canopus_quantum-0.2.0.tar.gz
  • Upload date:
  • Size: 12.9 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for canopus_quantum-0.2.0.tar.gz
Algorithm Hash digest
SHA256 56b5e75e531f473cfe854a88c94bec767ae0dbc8f6d98100d1acd81194ea8fd3
MD5 a4288d560d82be000881e3f792f58e3c
BLAKE2b-256 ef2bb80d8342abbd3b5f1ffe092cc34a3cfc04321577eddb42f22a4623686eeb

See more details on using hashes here.

Provenance

The following attestation bundles were made for canopus_quantum-0.2.0.tar.gz:

Publisher: release.yml on Youngcius/canopus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file canopus_quantum-0.2.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for canopus_quantum-0.2.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 c096c5c37096c47ce7a5fecc238a0a736cd02bd0789a0cfe5043070c68b9066b
MD5 035670bd61c484551c792a118fcdf3bd
BLAKE2b-256 94b860dd22b5c44dae82bb93bea60954ff1f8d4e734508b155d5e601747badda

See more details on using hashes here.

Provenance

The following attestation bundles were made for canopus_quantum-0.2.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on Youngcius/canopus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file canopus_quantum-0.2.0-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for canopus_quantum-0.2.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 b7a51e9d14cca80e0f503edaf5ccb9d083edc400f3ed25416de45850d6407320
MD5 6ea54e80f8a8837d12b8f89f04285466
BLAKE2b-256 a6c8774b882ce9808620370123eefa32073ed35909c092a05a30a2917b0a505a

See more details on using hashes here.

Provenance

The following attestation bundles were made for canopus_quantum-0.2.0-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: release.yml on Youngcius/canopus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file canopus_quantum-0.2.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for canopus_quantum-0.2.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 148e64c07a0572b63c59002dc3b305fda7043852563e9314c5915f243f656f1c
MD5 e1d1a970052297bb18d38d1b098d232e
BLAKE2b-256 975120b377919fec480aec5dfa2fc53bce01be3bb81052fc3af3d00ab427dbf7

See more details on using hashes here.

Provenance

The following attestation bundles were made for canopus_quantum-0.2.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on Youngcius/canopus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file canopus_quantum-0.2.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for canopus_quantum-0.2.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 90958ee51b148141852e13f2da25954afbd3e98937c316af507877f0668f8665
MD5 b1ea72ef9c47f3de51c9c8cd70324789
BLAKE2b-256 96bf1193f320871e5ed6e40f805a51f2001f977ff2c8c5556a6a0f60a6168827

See more details on using hashes here.

Provenance

The following attestation bundles were made for canopus_quantum-0.2.0-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: release.yml on Youngcius/canopus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file canopus_quantum-0.2.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for canopus_quantum-0.2.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 67118bbe720dfa79516ffbe7534853f58e11fc820610b7f062f97598aad8bdfb
MD5 da55b8024455781d03dd5b3f88a68158
BLAKE2b-256 65f69cc34e59e1990ffbe27ce4764584a6119a90b2b7b1570fd4f377298ea9f1

See more details on using hashes here.

Provenance

The following attestation bundles were made for canopus_quantum-0.2.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on Youngcius/canopus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file canopus_quantum-0.2.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for canopus_quantum-0.2.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0d8224ce9d1244c7e40ea7440dbcc9fe06c695fd8276d00dc069273728f761be
MD5 8635c7c856ef913bb38d35439ac8352a
BLAKE2b-256 559540915164ed44cd340f42b8a18349844aed34a8f9a806899fd928c7e35edb

See more details on using hashes here.

Provenance

The following attestation bundles were made for canopus_quantum-0.2.0-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: release.yml on Youngcius/canopus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file canopus_quantum-0.2.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for canopus_quantum-0.2.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 97efcb2cefc23e6a95a7637a6cce34a8a99b40fd747fa9fdd763a6369c1c0025
MD5 a8b0df5d7d492afbfe5b368af985bf5e
BLAKE2b-256 048ae7ef2c8dfbfd13eae5f24138301b57ef67801db001f3380ac7c23061c73f

See more details on using hashes here.

Provenance

The following attestation bundles were made for canopus_quantum-0.2.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on Youngcius/canopus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file canopus_quantum-0.2.0-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for canopus_quantum-0.2.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 dd4e2cde4030e4520e160cfadb289041ff41e53255a0bcc050c642c83cdb1fa4
MD5 51283470adb7acb3d46ec332b3e91442
BLAKE2b-256 47ebd37d91cb85e0073980c809351139c0f2a70c0c1dd4bd267111fdc18974f7

See more details on using hashes here.

Provenance

The following attestation bundles were made for canopus_quantum-0.2.0-cp310-cp310-macosx_11_0_arm64.whl:

Publisher: release.yml on Youngcius/canopus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.0 This release

9 files

0.1.4

9 files

0.1.3

9 files

0.1.2

9 files

0.1.1

9 files

0.1.0

9 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page