Getting Started¶

Note: It is highly recommended to use docker container to build and install the project.

System Requirements¶

OS : Linux (tested on Ubuntu 22.04)
Architecture : aarch64, X86

Development Environment¶

Docker
VSCode
VSCode Dev Containers extension

Dependencies¶

A list of major packages/toolchains required is mentioned in dependencies
For packages required for the development environment, please refer to the DockerFile.

Prerequisites¶

Clone the project:

git clone https://github.com/akshay9594/MQSS-Passes-Suite.git \
       /workspaces/MQSS-Passes-Suite
cd /workspaces/MQSS-Passes-Suite
git checkout <branch-name or commit hash>

If using docker, RUN the commands:

docker build -t mqss-pass-dev -f .devcontainer/Dockerfile .
docker run --rm -it \
  -v "$PWD":/workspaces/MQSS-Passes-Suite \
  -w /workspaces/MQSS-Passes-Suite \
  mqss-pass-dev \
  bash

Note: The project root is at /workspaces/MQSS-Passes-Suite

Building and Installing the project¶

The first thing to do is to setup a virtual environment and install python3.11 into it. We also need to install cmake. RUN:

make setup-env

Next, we need to set paths to the directories where the executables are placed i.e. ~/.local/bin as well as path to cudaq tools. RUN command:

eval "$(make set-target-paths)"

Then, configure the build by running the command:

make build

This invokes the scripts scripts/build.sh which downloads and installs all the required dependencies for building the target mqss-opt. This script contains the required cmake commands to configure the project.

Finally, build the targets by running:

make target

This builds the targets using the ninja build system and if the build succeeds, generates the executable mqss-opt. You can change the installation directory by modifying the INSTALL_DIR variable within the MakeFile.

If you make any changes to the source code i.e. to the C++ files within lib/*, then just rerun the make target command.
If any changes are made to the build script i.e. build.sh or to the CMakeLists or to the files within include/ then do make build first and then make target.

Enabling Pass Debug Information¶

To enable pass debug information, set the following flag within Makefile:

DEBUG_FLAG =  # --debug (if you want pass debug info)

By default the debug information is enabled i.e. DEBUG_FLAG = --debug. To disable the debug info, just remove the ---debug value.

Testing the installation¶

After the build is successful, use the following commands to test the installation.

For mlir dialect-level testing (faster), RUN:

make test-dialects

This command will run all the available test cases in the tests/dialects directory. There are a total of 60 test cases currently, with more added regularly.

Source-level Compilation¶

If C++/Python i.e. Source level compilation and testing is intended follow the following steps:

Downloading front-end dependencies¶

Run the following command

make frontend

This will setup a python virtual environment, after which, the script download_toolchains.sh is executed. This script downloads and installs: CUDA-Q and Catalyst toolchains. We need cudaq-quake (translates C++ to Quake) and the Catalyst-qjit (translates python to catalyst-quantum) tools. After the installation is complete, RUN the COMMAND:

eval "$(make front-end-paths)"

This will activate the virtual environment and add cudaq-quake to the $PATH environment variable. Check using:

which cudaq-quake

Testing the Front-end Compilation pipeline¶

The testing for the frontend involves the script mqss-cc. Check that is also on the $PATH environment variable. After this, RUN the command:

make test-all

This runs the test-cases within tests/code.