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).
Release files for hugr-qir 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| hugr_qir-0.2.0.tar.gz | 1.3 MB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| hugr_qir-0.2.0-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details |
| hugr_qir-0.2.0-cp310-abi3-manylinux_2_34_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.34+ x86-64 | Details |
| hugr_qir-0.2.0-cp310-abi3-macosx_13_0_x86_64.whl | CPython 3.10 | abi3 | macOS 13.0+ x86-64 | Details |
| hugr_qir-0.2.0-cp310-abi3-macosx_13_0_arm64.whl | CPython 3.10 | abi3 | macOS 13.0+ ARM64 | Details |
Total release size: 111.4 MB
Release files / hugr_qir-0.2.0.tar.gz
| Download URL | hugr_qir-0.2.0.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
97c950794e184fba5f09d8cc21ea4a62373f1ce5153787a7ccf36252a46a1d82
|
|
BLAKE2b-256 checksum How to use checksums |
55a5afe51b8c1e6bfede9de4b160b6fd2469a02359686f0d4e092e4c0cdda55d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / hugr_qir-0.2.0-cp310-abi3-win_amd64.whl
| Download URL | hugr_qir-0.2.0-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 24.6 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
3902c6359bbb78c2b986809be84ded5473b8e9d7b57bb7e4e5fac4234f0c3562
|
|
BLAKE2b-256 checksum How to use checksums |
b0046500cf12d5f8afda6d856d33b4a4c57a785830afda722fa4230eeef147bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / hugr_qir-0.2.0-cp310-abi3-manylinux_2_34_x86_64.whl
| Download URL | hugr_qir-0.2.0-cp310-abi3-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 34.7 MB |
| Tags | CPython 3.10 Linux glibc 2.34+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
4ec68c346324049e3b980dae31ec026cffc55d05faeba8a708cfafb4759a44d9
|
|
BLAKE2b-256 checksum How to use checksums |
932899cac0974a021d8e8f17a83eab7f54a6cc8930c09d31d7c1981db6085096
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / hugr_qir-0.2.0-cp310-abi3-macosx_13_0_x86_64.whl
| Download URL | hugr_qir-0.2.0-cp310-abi3-macosx_13_0_x86_64.whl |
|---|---|
| Size | 26.1 MB |
| Tags | CPython 3.10 abi3 macOS 13.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
8cc34e0efedca3d6d831328915b0425144da1f20f7b670d6ff38912650f87424
|
|
BLAKE2b-256 checksum How to use checksums |
8eb16e24c2108eace73196635165f06fa1b11038c5572dcb99527871b104a30c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / hugr_qir-0.2.0-cp310-abi3-macosx_13_0_arm64.whl
| Download URL | hugr_qir-0.2.0-cp310-abi3-macosx_13_0_arm64.whl |
|---|---|
| Size | 24.7 MB |
| Tags | CPython 3.10 abi3 macOS 13.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
d6e5cb91cc0ff943ae70f0f09ea207d68ef0604af9b0cdd0f36617ff197ca023
|
|
BLAKE2b-256 checksum How to use checksums |
8f1a6e75ad679a03ce6e88ddfddb16a29a89eb8123fb1cbddf44dcdce613f839
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
