Python API

Main functions

The Python layer centers on python/hugr_qir/hugr_to_qir.py.

hugr_to_qir

hugr_qir.hugr_to_qir.hugr_to_qir(hugr: Package | bytes, *, validate_qir: bool = True, validate_hugr: bool = False, target: str = 'quantinuum-hardware', opt_level: str = 'aggressive', max_loop_unroll: int = 800, output_format: OutputFormat = OutputFormat.BASE64, wasm_file: Path | None = None) → str | bytes[source]

A function for converting hugr to qir (llvm bitcode)

Parameters:

  • hugr (Package | bytes) – HUGR in binary format

  • validate_qir (bool) – Whether to validate the created QIR

  • validate_hugr (bool) – Whether to validate the input hugr before and after each internal pass

  • target (str) – LLVM compilation target, same options as cli, run hugr-qir –help to see available options and default

  • opt_level (str) – LLVM optimization level, same options as cli, run hugr-qir –help to see available options and default

  • max_loop_unroll (int) – Maximum statically-known loop trip count to fully unroll before QIR emission

  • output_format (OutputFormat) – Output format, see OutputFormat enum for available options

  • wasm_file (Path | None) – Optional path to WASM binary file

Return type:

str | bytes

Returns:

QIR corresponding to the HUGR input in format given by output_format

Example:

from hugr_qir.hugr_to_qir import hugr_to_qir
from hugr_qir.output import OutputFormat

bitcode = hugr_to_qir(hugr_package, output_format=OutputFormat.BITCODE)

Key parameters:

  • hugr: either a hugr.package.Package or serialized HUGR bytes

  • validate_qir: run QIR validation after code generation

  • validate_hugr: validate the input HUGR before and during compilation

  • target: compilation target passed through to the Rust backend

  • opt_level: LLVM optimization level

  • max_loop_unroll: maximum static loop trip count to fully unroll (default: 800)

  • output_format: LLVM_IR, BITCODE, or BASE64

  • wasm_file: optional path to a Wasm module used by the Wasm extension

Convenience helpers

hugr_qir.hugr_to_qir.to_qir_str(hugr: Package | bytes, *, validate_qir: bool = True, max_loop_unroll: int = 800) → str[source]

Converts hugr package to qir str

Uses hugr_to_qir internally with default settings and llvm_ir output format.

Parameters:

  • hugr (Package) – hugr package

  • validate_qir (bool) – Whether to validate the created QIR

  • max_loop_unroll (int) – Maximum statically-known loop trip count to fully unroll

Returns:

QIR corresponding to the HUGR input as str

Return type:

str

hugr_qir.hugr_to_qir.to_qir_bytes(hugr: Package | bytes, *, validate_qir: bool = True, max_loop_unroll: int = 800) → bytes[source]

Converts hugr package to qir bytes.

Uses hugr_to_qir internally with default settings and bitcode output format.

Parameters:

  • hugr (Package) – hugr package

  • validate_qir (bool) – Whether to validate the created QIR

  • max_loop_unroll (int) – Maximum statically-known loop trip count to fully unroll

Returns:

QIR corresponding to the HUGR input as bytes

Return type:

bytes

Result conversion

hugr_qir.h_series_helpers.results.backendresult_to_qsysresult(backres: BackendResult) → QsysResult[source]

This function can generate a qsys result from a given pytket result. When hugr-qir >= 0.3.0 was used for the generation of the submitted qir the register names in the pytket BackendResult contain the type of the value recorded. This information is used to map each guppy output tag to the appropriate type in the QsysResult data If this type information is missing in the register name or is incomplete, each register will be interpreted as a 64 bit signed integer. If any registers are not 64 bits, the results are either not from a hugr-qir converted program or corrupted, and conversion will fail

Parameters:

backres (BackendResult)

Return type:

QsysResult

Output formats

The output format enum lives in python/hugr_qir/output.py.

  • OutputFormat.LLVM_IR

  • OutputFormat.BITCODE

  • OutputFormat.BASE64