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, qubit, quantum

guppy.load(quantum)

# Teleports the state in `src` to `tgt`.
@guppy
def teleport(src: qubit, tgt: qubit) -> qubit:
   # 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

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

• Python >= 3.10
• Poetry
• Rust >= 1.75.0 (only needed for tests)

Installing

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

poetry install --with execution,validation

Note that the --with execution,validation flag is optional and only needed to run integration tests.

The validation flag allows the tests to validate that the hugrs guppy outputs are well formed, and the execution flag 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.

You can then activate the virtual environment and work within it with:

poetry shell

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

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

Pre-commit

Install the pre-commit hook by running:

poetry run pre-commit install

Testing

Run tests using

poetry run pytest -v

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

poetry install --with pytket
poetry run pytest -v  # Now rerun tests

Integration test cases can be exported to a directory using

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