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 remains conservative: -O 0 -t native. Optimized conversion requires requesting optimization (for example, -O 1) and is supported only with -t x86-64; other optimized target combinations still fail fast to avoid known unstable LLVM 21 paths.

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

To keep untrusted entry-point metadata from driving effectively unbounded compiler allocations, validation and translation accept at most 65,535 statically declared qubits and 65,535 statically declared results. The Rust constants MAX_STATIC_QUBITS and MAX_STATIC_RESULTS expose these limits.

Platform Notes

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

• Optimized conversion on Windows is currently supported only when optimization is requested (for example, -O 1) with -t x86-64; other optimized target combinations fail fast instead of entering known unstable LLVM paths.
• 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