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.
Guppy can be installed via pip
. Requires Python >= 3.10.
pip install guppylang
See the Getting Started guide and the other examples.
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
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
.
Install the pre-commit hook by running:
uv run pre-commit install
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.
See the guppy-runner repository for in-progress work for compiling Guppy source programs and executing them.
This project is licensed under Apache License, Version 2.0 (LICENCE or http://www.apache.org/licenses/LICENSE-2.0).