Guppy

Guppy is a quantum programming language that is fully embedded into Python. It allows you to write high-level hybrid quantum programs with classical control flow and mid-circuit measurements using Pythonic syntax:

from guppylang import guppy
from guppylang.prelude.quantum import cx, h, measure, qubit, x, z

@guppy
def teleport(src: qubit, tgt: qubit) -> qubit:
    """Teleports the state in `src` to `tgt`."""
    # Create ancilla and entangle it with src and tgt
    tmp = qubit()
    tmp, tgt = cx(h(tmp), tgt)
    src, tmp = cx(src, tmp)

    # Apply classical corrections
    if measure(h(src)):
        tgt = z(tgt)
    if measure(tmp):
        tgt = x(tgt)
    return tgt

guppy.compile_module()

More examples and tutorials are available here.

Install

Guppy can be installed via pip. Requires Python >= 3.10.

pip install guppylang

Usage

See the Getting Started guide and the other examples.

Development

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

• uv
• Rust >= 1.75.0 (only needed for tests)

Installing

Run the following to setup your virtual environment and install dependencies:

uv sync --extra execution
cargo build --release  # Builds the validator (optional)

Note that the --extra flag, and the cargo build line, are both optional, but enable some integration tests.

The validator allows the tests to validate that the hugrs guppy outputs are well formed, and the execution extra allows tests to compile these hugrs to native code using hugr-llvm to check the results are as expected. This requires llvm-14 as described in the hugr-llvm repo.

Consider using direnv to automate this when entering and leaving a directory.

To run a single command in the shell, just prefix it with uv run.

Pre-commit

Install the pre-commit hook by running:

uv run pre-commit install

Testing

Run tests using

uv run pytest [-v]  # -v just enables verbose test output

(If you have not built the validator, you can do uv run pytest --no_validation.)

You have to install extra dependencies to test automatic circuit conversion from pytket.

# Install extra dependencies
# Using `--inexact` to avoid removing the already installed extras.
uv sync --extra pytket --inexact
# Now rerun tests
uv run pytest -v

Integration test cases can be exported to a directory using

uv run pytest --export-test-cases=guppy-exports

which will create a directory ./guppy-exports populated with hugr modules serialised in JSON.

Experimental: Execution

See the guppy-runner repository for in-progress work for compiling Guppy source programs and executing them.

License

This project is licensed under Apache License, Version 2.0 (LICENCE or http://www.apache.org/licenses/LICENSE-2.0).