Metadata-Version: 2.4
Name: selene-hugr-qis-compiler
Version: 0.5.1
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Quantum Computing
Classifier: Topic :: Software Development :: Compilers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Dist: hugr~=0.18.8
Requires-Dist: typing-extensions>=4.5
Summary: A Python frontend for compiling HUGR to Quantinuum's QIS.
Author-email: Seyon Sivarajah <seyon.sivarajah@quantinuum.com>, TKET development team <tket-support@quantinuum.com>
Maintainer-email: Seyon Sivarajah <seyon.sivarajah@quantinuum.com>, TKET development team <tket-support@quantinuum.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: repository, https://github.com/quantinuum/tket2/tree/main/tket/qis-compiler

# The HUGR-QIS compiler for Selene

This package provides compilation from HUGR to LLVM adhering
to the Quantinuum QIS.

## Usage

Guppy can produce a HUGR Envelope with:
```python
from guppylang.decorator import guppy

@guppy
def main() -> None:
    # ...

package = main.compile()
```

This can then be compiled to LLVM IR or bitcode using this package:

```python
from selene_hugr_qis_compiler import EmulatorState

state = EmulatorState.from_python(package)

# Compile to LLVM IR for the host system
# and receive it as a string
ir = state.compile_to_llvm_ir()

# Compile to LLVM bitcode for the host system
# and receive it as a bytes object
bitcode = state.compile_to_bitcode()
```

Use `EmulatorState.from_bytes(hugr_envelope)` when loading a serialized HUGR
package.

If you wish to target a specific architecture or platform,
you can pass the triple as an argument to the compilation functions:

```python
state = EmulatorState.from_python(hugr.package, platform="helios")

# Compile to LLVM IR for Apple Silicon
ir_apple_silicon = state.compile_to_llvm_ir(
    target_triple="aarch64-apple-darwin",
)
# Compile to LLVM bitcode for x86_64 MSVC
bitcode_x86_64_windows = state.compile_to_bitcode(
    target_triple="x86_64-windows-msvc",
)
```

## Development

### Snapshot testing
This package uses snapshot testing for its compiler output.
Sample programs are defined using guppy in the script `python/tests/generate_hugrs.py`.
To add a new test case add a new function to generate the desired HUGR program and
call it from the `if __name__ == "__main__":` block.

The script has self contained dependencies with a pinned guppy version
defined in comments at the top of the file. `uv` will create a virtual environment
and install the dependencies when you run the script with `uv run python
tests/generate_hugrs.py`. This can also be done using `just regenerate` in the
`python/tests` directory.

HUGR regeneration should not be done in conjunction with other changes to the compiler,
to isolate possible changes to the snapshots. It should only be required if guppylang
updates are required for testing the compiler.

