qir-qis 0.1.6

QIR to Quantinuum QIS (Quantum Instruction Set) compiler

QIR-QIS

A compiler that validates and translates QIR (Quantum Intermediate Representation) to Quantinuum QIS (Quantum Instruction Set). This tool enables quantum programs written in QIR to run on Quantinuum's quantum computing systems.

Features

• QIR Validation: Validates QIR bitcode for correctness and spec compliance
• QIS Translation: Compiles QIR to Quantinuum's native QIS instruction set
• Python & Rust API: Use as a Rust library or Python package
• CLI Tool: Command-line interface for quick compilation

See qtm-qir-reference.md for details on supported QIR features and their mapping to Quantinuum QIS.

Installation

From Source (Rust)

Requirements:

• Rust >= 1.91.0
• LLVM 21

# Point llvm-sys to your LLVM 21 installation
export LLVM_SYS_211_PREFIX=/path/to/llvm21

cargo build --release

The compiled binary will be available at target/release/qir-qis.

Python Package

Requirements:

• Python >= 3.10, < 3.15
• uv (recommended) or pip

Available pre-built wheels:

• Linux: x86_64 (manylinux_2_28), aarch64 (manylinux_2_28)
• macOS: x86_64, arm64 (Apple Silicon)
• Windows: x86_64

All wheels support Python 3.10+ using the stable ABI (abi3).

# Using uv (recommended)
uv pip install qir-qis

# Using pip
pip install qir-qis

Usage

Command Line

Compile a QIR LLVM IR file to QIS bitcode:

# Basic usage
qir-qis input.ll

# With custom optimization level
qir-qis -O 3 input.ll

# Specify target architecture
qir-qis -t x86-64 input.ll

# Or using cargo
cargo run -- input.ll

This generates input.qis.bc containing the compiled QIS bitcode.

On Windows, the default mode is conservative: -O 0 -t native. Optimized conversion paths remain temporarily disabled there because the current LLVM 21 integration can crash in those modes.

Python API

See examples/python_api.py for a complete working example.

uv run examples/python_api.py

For a more comprehensive example with quantum simulation, see main.py.

Rust API

See examples/rust_api.rs for a complete working example.

cargo run --example rust_api

Platform Notes

Windows support is functional, but a few LLVM integration paths still differ from Linux and macOS:

• Optimized conversion currently fails fast on Windows with a clear error instead of entering the known unstable LLVM path.
• LLVM verifier failures return a generic error on Windows instead of the full verifier message.
• Native target codegen on Windows uses conservative CPU settings instead of host CPU feature detection.
• -O0 optimization on Windows is a validation-only fast path and does not rewrite the module triple.

These limitations are implementation details of the current LLVM/Inkwell integration rather than QIR feature differences.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for:

• How to report issues and submit pull requests
• Coding standards and commit message format
• Development workflow and testing requirements

Development setup, test commands, and LLVM upgrade guidance live in DEVELOPMENT.md. Release notes are available in CHANGELOG.md.

License

Apache-2.0

Copyright Quantinuum