hugr-qir
A tool for converting Hierarchical Unified Graph Representation (HUGR, pronounced hugger) formatted quantum programs into QIR format.
[!NOTE] Not all Guppy/HUGR programs can be converted to QIR.
Documentation
Project documentation lives in docs/ and can be viewed online here.
- Getting started: docs/getting-started.md
- Examples: docs/examples/index.md
- Guppylang support: docs/guppy-for-h-series/index.md
- Python API: docs/python-api.md
- CLI: docs/cli.md
- WASM support: docs/wasm.md
- Development: docs/development.md
To build the documentation locally:
uv run --group docs sphinx-build -M html docs docs/_build
Then open docs/_build/html/index.html in a browser.
Installation
You can install from pypi via pip install hugr-qir.
Usage
Python
Use hugr_to_qir to convert a HUGR package or serialized HUGR bytes into QIR.
from hugr_qir.hugr_to_qir import hugr_to_qir
from hugr_qir.output import OutputFormat
qir = hugr_to_qir(
hugr_package,
validate_qir=False,
output_format=OutputFormat.LLVM_IR,
)
By default, basic validity checks are run on the generated QIR. These can be disabled by passing validate_qir=False.
You can find an example notebook at examples/submit-guppy-h2-via-qir.ipynb showing the conversion and the submission to Quantinuum System Model H2.
CLI
You can use the available CLI after installing the python package.
This will generate qir for a given hugr file:
hugr-qir test-file.hugr
Run hugr-qir --help to see the available options.
If you want to generate a HUGR file from Guppy, you can do this in two steps:
-
Add this to the end of your guppy file:
if __name__ == "__main__": sys.stdout.buffer.write(main.compile().to_bytes()) # Or to compile a non-main guppy function: sys.stdout.buffer.write(guppy_func.compile_function().to_bytes())
-
Generate the hugr file with:
python guppy_examples/general/quantum-classical-1.py > test-guppy.hugr
See docs/guppy-for-h-series/support-matrix.md for the current Guppylang support matrix and caveats.
Development
Setting up the development environment
The easiest way to set up the development environment is to use the provided
devenv.nix file. This will set up a development shell with all the
required dependencies.
To use this, you will need to install devenv. Once you have it running, open a shell with:
devenv shell
All the required dependencies should be available. You can automate loading the shell by setting up direnv.
Run tests
You can run the rust test with:
cargo test
You can run the Python test with:
uv run pytest -n auto
You can type-check the Python sources with:
uv run ty check
You can run the Python formatter and linter with:
uv run ruff format --check python guppy_examples
uv run ruff check python guppy_examples
You can run the configured Git hooks with:
uvx prek run --all-files
If you want to update the snapshots you can do that via:
uv run pytest --snapshot-update
License
This project is licensed under Apache License, Version 2.0 (LICENSE or http://www.apache.org/licenses/LICENSE-2.0).
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file hugr_qir-0.1.2.tar.gz.
File metadata
- Download URL: hugr_qir-0.1.2.tar.gz
- Upload date:
- Size: 1.4 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
maturin/1.14.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
68743144da1e14afe353726a847938a24465cdd3f5e800be1426f8e0b14258cb
|
|
| MD5 |
cecf02cafa43692f3f517702a62676e5
|
|
| BLAKE2b-256 |
c3f01a5384e8aae6458a0e77ca4143bc1f42bab0dfd9cddf992b7e9212cdbd2d
|
File details
Details for the file hugr_qir-0.1.2-cp310-abi3-win_amd64.whl.
File metadata
- Download URL: hugr_qir-0.1.2-cp310-abi3-win_amd64.whl
- Upload date:
- Size: 29.5 MB
- Tags: CPython 3.10+, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
maturin/1.14.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c4f1ff1dd795f502a646f739329c959b4132510f0f970f26ea0e80a32a4960bb
|
|
| MD5 |
8f3aaad04ac74c7e41eec1034b6c49fb
|
|
| BLAKE2b-256 |
3f3717ceaa619ef1616cacb12758aafafe008046c98f210552ab85d95ec464ef
|
File details
Details for the file hugr_qir-0.1.2-cp310-abi3-manylinux_2_34_x86_64.whl.
File metadata
- Download URL: hugr_qir-0.1.2-cp310-abi3-manylinux_2_34_x86_64.whl
- Upload date:
- Size: 34.5 MB
- Tags: CPython 3.10+, manylinux: glibc 2.34+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
maturin/1.14.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a88f209768753109c052984bac93cbf361e6e5974ea0c3b8ad7f901e3b0cedd4
|
|
| MD5 |
1164088fdb97c665e6714b9e7daa88d5
|
|
| BLAKE2b-256 |
ccd23c65f4cc266486f228dfad344f06014e0b21ece2a7eca9adcbe033ea6aed
|
File details
Details for the file hugr_qir-0.1.2-cp310-abi3-macosx_13_0_x86_64.whl.
File metadata
- Download URL: hugr_qir-0.1.2-cp310-abi3-macosx_13_0_x86_64.whl
- Upload date:
- Size: 32.5 MB
- Tags: CPython 3.10+, macOS 13.0+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
maturin/1.14.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5691040750a36362c5a90e82ab239d1a5f38dbc896d84ccc525e2bdf07dde575
|
|
| MD5 |
41174041b3ca0c17b95a3b90388825ba
|
|
| BLAKE2b-256 |
cd62a6ad673c19b8b49ea63350ddbec1f3bcdb8d5c83847ea236bd2bd01d7385
|
File details
Details for the file hugr_qir-0.1.2-cp310-abi3-macosx_13_0_arm64.whl.
File metadata
- Download URL: hugr_qir-0.1.2-cp310-abi3-macosx_13_0_arm64.whl
- Upload date:
- Size: 29.7 MB
- Tags: CPython 3.10+, macOS 13.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
maturin/1.14.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
83d9c045085866a20af67e56d6d8bd4840f8fbbd5d23b8f2deb2d45ba5b5e5fb
|
|
| MD5 |
fc92e088cf9bde1a4eaa98a0bb31b6db
|
|
| BLAKE2b-256 |
08884425d66adc688293d855a7149704a1986a6cd5878fd7e5d094c18ae12cb6
|
