hugr-qir 0.0.27

Quantinuum's tool for converting HUGR to QIR

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.

Installation

You can install from pypi via pip install hugr-qir.

Usage

Python

Use the function hugr_to_qir from the hugr_to_qir module to convert hugr to qir. By default, some basic validity checks will be run on the generated QIR. These checks can be turned off 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:

1. 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())
   

2. Generate the hugr file with:

   python guppy_examples/general/quantum-classical-1.py > test-guppy.hugr
   

Guppy language support

✅ = full support, *️⃣ = partial support, ❌ = unsupported

Overview Data Types

Data Types	Support	Caveats
int	✅
bool	✅
nat	✅
struct	✅	Cannot contain arrays
float	*️⃣	Must be runtime constant, arithmetic comptime only
array	*️⃣	Comptime only
tuple	*️⃣	Unpacking with * returns array, so only at comptime

Arrays

• Only supported within comptime guppy
• Cannot use guppy builtins that use runtime arrays internally
• Cannot be used within structs
• Cannot be used as parameter to either @guppy or @guppy.comptime decorated functions

Array examples:

def py_function(arr: array[qubit]) -> None: # ✅ no need to fully qualify array type, will be treated as python list
   """This python function can be called from @guppy.comptime, but not @guppy
      Can do anything here that is allowed within @guppy.comptime
   """
    for q in arr:
       h(q)

@guppy.comptime
def guppy_comptime_function(arr: array[qubit, 4]) -> None: # ❌ no support for passing in arrays (even to guppy.comptime functions)
   for q in arr:
      h(q)

@guppy
def guppy_function(arr: array[qubit, 4]) -> None: # ❌ no support for passing in arrays
   for q in arr:
      h(q)

@guppy.comptime
def main() -> None:
    comptime_array = array(qubit() for _ in range(4)) # ✅: array initialization at comptime
    py_function(comptime_array)             # ✅: can call python function from comptime and pass in comptime array
    guppy_comptime_function(comptime_array) # ❌: parameters to guppy comptime functions are NOT comptime
    guppy_function(comptime_array)          # ❌: parameters to guppy functions are NOT comptime

@guppy
def main_noncomptime() -> None:
   array = array(qubit() for _ in range(4)) # ❌: non-comptime array initialization

Tuples

• Unpacking with * only supported at comptime (creates array)

Structs

• Cannot contain arrays

Overview Guppy Features

Features	Support	Remarks
if elif else constructs	✅
function overloading	✅
Generics (type_var/nat_var)	✅	nat_vars not really useful without runtime array support
First class/ Higher order functions	✅
Recursive functions/loops	*️⃣	Only if unrollable/serializable
measure_array/discard_array	❌	Use non-comptime arrays internally

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

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).