The Compiler for Qwerty, a Basis-Oriented Quantum Programming Language

This is the compiler (and examples) for Qwerty, a quantum programming language embedded in Python. It is licensed under the MIT license.

Documentation

The docs/ directory contains more documentation that doesn't fit in this README:

• docs/project-structure.md: An overview of the contents of this project (i.e., which files do what) and how the sections in the paper submission map to source files.
• docs/examples.md: A list of the example programs found in the examples/ directory in this directory.
• docs/testing.md: Details on our multi-faceted testing framework.
• docs/debugging.md: Guide for debugging the Qwerty compiler when it misbehaves.
• docs/qiree.md: Directions for building a copy of the Qwerty compiler/runtime that integrates with QIR-EE, an execution engine for QIR.
• docs/upgrading-llvm.md: Describes the semi-automated process for upgrading the version of LLVM used by the Qwerty compiler.

The rest of this README is dedicated to installation, basic testing, and troubleshooting.

Quick Start: Installing a Binary Build

If you are not doing development on the Qwerty compiler and you don't need the very latest compiler/runtime version, you can try installing a binary build.

1. Download the .whl corresponding to your platform of choice from the latest GitHub release
2. Install the wheel (binary) with pip:

   $ pip install *.whl
   

3. Download an example like bv_simple.py and test that it works:

   $ python3 bv_simple.py 1101
   1101
   

If you hit problems, please ask for help (aja@gatech.edu).

Building the Compiler on Your Own Machine

Step 1: Setting Up LLVM

LLVM is a heavy-duty compiler framework we use, along with its sub-project MLIR, in the Qwerty compiler. Qwerty currently requires LLVM 19.1.6. If you want to build the Qwerty compiler, you have two options to satisfy the LLVM dependency: (1) download pre-built LLVM libraries or (2) build LLVM yourself. We discuss both options below.

Option 1: Use a Pre-Built LLVM Tarball

You can download our builds of LLVM from here: https://github.com/gt-tinker/qwerty-llvm-builds/releases/tag/v19.1.6

macOS/Linux

You can extract it with something like:

$ export LLVM_INSTALL_DIR=~/bin/llvm19
$ mkdir -p "$LLVM_INSTALL_DIR"
$ tar -C "$(dirname "$LLVM_INSTALL_DIR")" -xJvf ~/Downloads/llvm_mlir_rel_v19_1_6_x86_linux.tar.xz
$ export PATH=$PATH:$LLVM_INSTALL_DIR/bin/
$ export MLIR_DIR=$LLVM_INSTALL_DIR/lib/cmake/mlir/

All three exports above should probably be in your ~/.bashrc (or your ~/.zshrc if you use zsh, e.g., if you are a macOS user).

Windows

Download the .zip above and put it somewhere like C:\qwerty\llvm19. (Avoid spaces in the path.) Then press Start and type in "environment variables" (either system or user should be fine). Set MLIR_DIR to C:\qwerty\llvm19\lib\cmake\mlir and add C:\qwerty\llvm19\bin to Path.

Option 2: Build LLVM Yourself

See docs/build-llvm.md.

Step 2: Building the Rest of the Qwerty Compiler

macOS/Linux

To test that LLVM was installed right in the last section, make sure the following commands produce the expected output:

$ mlir-opt --version
LLVM (http://llvm.org/):
  LLVM version 19.1.6
  Optimized build with assertions.
$ llvm-config --version
19.1.6

Next, you need to install Rust (for qir-runner), python3-venv (to make a virtual environment), python3-dev (Python C API headers for the Python C extension), and libffi-dev and libxml2-dev (apparently required by qir-runner, possibly transitively), libzstd-dev (an LLVM dependency).

Finally, to build, run the following in a cloned copy of this repository (the first two commands are a one-time thing):

$ git submodule update --init tpls/tweedledum tpls/qir-runner tpls/googletest
$ python3 -m venv venv
$ . venv/bin/activate
$ pip install -v .

(Warning: the CMakeCache generated by skbuild might cause bizarre build errors under unusual circumstances (such as upgrading LLVM), so try deleting _skbuild/ if you are seeing weird build issues.)

Now, to test everything is working, try running one of the examples:

$ python3 examples/dj.py
Constant test:
Classical: constant
Quantum: constant

Balanced test:
Classical: balanced
Quantum: balanced

For a more comprehensive test, you can run the following if you built with the environment variable QWERTY_BUILD_TESTS=true (e.g., if you ran QWERTY_BUILD_TESTS=true pip install -v .):

$ test/run-tests.sh
[...voluminous output...]
100% tests passed, 0 tests failed out of 1

[...voluminous output...]
Ran 41 tests in 10.390s

OK

Windows

First, install Visual Studio, Rust and Python 3.

Then, open a Command Prompt (i.e., cmd, not PowerShell) and make sure that LLVM is installed correctly from the previous section:

> mlir-opt --version
LLVM (http://llvm.org/):
  LLVM version 19.1.6
  Optimized build with assertions.
> llvm-config --version
19.1.6

Still inside of cmd (not PowerShell), run the following commands inside a cloned copy of this repository (setup-env.bat configures Visual Studio to build an amd64 binary and tells CMake to use ninja instead of msbuild, both avoiding very strange errors — treat setup-env.bat as an extension of activate.bat in that you'll need to run it in every fresh terminal you build in):

> git submodule update --init tpls\tweedledum tpls\qir-runner tpls\googletest
> python -m venv venv
> ci\build-windows\setup-env.bat
> venv\Scripts\activate.bat
> pip install -v .

Now try one of the examples:

> python examples\dj.py
Constant test:
Classical: constant
Quantum: constant

Balanced test:
Classical: balanced
Quantum: balanced

To run the test suite, rebuild with tests included:

> set QWERTY_BUILD_TESTS=1
> pip install -v .

And then try running the tests:

> test\run-tests.bat
[...voluminous output...]
100% tests passed, 0 tests failed out of 1

[...voluminous output...]
Ran 41 tests in 10.390s

OK

Troubleshooting

If your compilation process keeps getting sniped by the OOM killer, as seen below:

c++: fatal error: Killed signal terminated program cc1plus
  compilation terminated.

Then a potential fix is to add the following code near the top of your CMakeLists.txt both in / and /tpls/tweedledum:

set_property(GLOBAL APPEND PROPERTY JOB_POOLS link_job_pool=1)
set(CMAKE_JOB_POOL_LINK link_job_pool)
set_property(GLOBAL APPEND PROPERTY JOB_POOLS compile_job_pool=1)
set(CMAKE_JOB_POOL_COMPILE compile_job_pool)

This tells CMake to tell Ninja to limit the number of linking and compilation jobs done in parallel to just 1 each, although this can be changed by changing the above parameters.

Citation

To cite the Qwerty compiler, you can cite our paper in CGO '25:

Austin J. Adams, Sharjeel Khan, Arjun S. Bhamra, Ryan R. Abusaada, Anthony M. Cabrera, Cameron C. Hoechst, Travis S. Humble, Jeffrey S. Young, and Thomas M. Conte. "Asdf: A Compiler for Qwerty, a Basis-Oriented Quantum Programming Language." To appear in 2025 IEEE/ACM International Symposium on Code Generation and Optimization (CGO '25). March 2025.

BibTeX citation:

@inproceedings{adams_asdf_2025,
    title = {{Asdf}: {A} {Compiler} for {Qwerty}, a {Basis-Oriented} {Quantum} {Programming} {Language}},
    booktitle = {2025 {IEEE}/{ACM} {International} {Symposium} on {Code} {Generation} and {Optimization} ({CGO})},
    author = {Adams, Austin J. and Khan, Sharjeel and Bhamra, Arjun S. and Abusaada, Ryan R. and Cabrera, Anthony M. and Hoechst, Cameron C. and Humble, Travis S. and Young, Jeffrey S. and  Conte, Thomas M.},
    month = mar,
    year = {2025}
}

The evaluation for the CGO '25 paper uses additional code not on the main branch of this repository. You can find that evaluation code in the Zenodo artifact or on the cgo25-artifact branch.