Canopus (Canonical-Optimized Placement Utility Suite) is a qubit mapping/routing framework tailored to advanced quantum ISAs. 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.

If you make use of this code or the genAshN gate scheme in your work, please cite the following papers:

If you make sure of Canopus in your work, please cite the following paper:

@article{yang2025qubit,
  title={Qubit Mapping and Routing tailored to Advanced Quantum ISAs: Not as Costly as You Think},
  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}
}

canopus/ # Canopus implementation
├── __init__.py
├── backends.py # Backend related module
├── basics.py # Customized Qiskit CanonicalGate
├── mapping.py # CanopusMapping pass based on qiskit.transpiler.TransformationPass
├── synthesis.py # Synthesis passes (e.g., rebase to {Can, U3}, rebase to Clifford, rebase to SQiSW)
├── utils/ # Utilities module
│   ├── _accel.cpython-*.so # Rust-accelerated functions (compiled)
│   ├── _accel.pyi # Type stubs for Rust functions
│   └── _core.py # Python utilities (e.g., polytope coverage, circuit conversion)
└── decomposition/ # Gate decomposition module

src/ # Rust source code
└── lib.rs # PyO3 bindings for performance-critical functions

Prerequisites: Python 3.10+, Rust toolchain (for building from source)

pip install .

This will automatically compile the Rust extension and install the complete package.

First, install maturin and poethepoet:

pip install maturin poethepoet

Then use the following task commands:

Quick start for development:

poe dev  # Build Rust extension and install in editable mode

./examples/ contains some introductory examples:

• python route_demo.py to test the routing effect by Sabre and Canopus on a demo circuit
• python route_qft.py <n> to test the routing effect by Sabre and Canopus for the n-qubit QFT kernel
• python rebase_random_unitary.py to test the rebase passes for arbitrary ISAs

./experiments/ contains comprehensive evaluation scripts and data.

• ./experiments/eval_qft/ for case study on QFT kernel
• ./experiments/eval_qldpc/ for case study on QLDPC stabilizer circuit

Evaluation commands are holistically managed via ./experiments/Makefile. First, run

make

to prepare prerequisite files for evaluation (e.g., coupling files, coverage sets, logical-level optimized circuits).

• Run make canopus to evaluate Canopus
• Run make baselines to evaluate baseline compilers (Sabre, TOQM, BQSKit)
• Run make sum_result to summarize results once all routing evaluation are done
• Run make disp_result to show the summarized routing overheads across different compilers, topologies, and ISAs

You can also run bench_all.py, bench_all_toqm.py and so on to perform fine-grain evaluation.