Munich Quantum Software Stack (MQSS)-Quantum Compilation Suite

This repository contains a collection of compiler passes integrated into the MQSS to optimize, transform, and lower quantum programs to instructions compliant with target Quantum devices. The passes in this suite operate on quantum circuits represented using the state-of-the-art Multi-Level Intermediate Representation (MLIR) framework.

The passes operate on either the quake MLIR dialect by Nvidia cudaq-quantum or catalyst-quantum dialect by pennlylane-catalyst.

[NOTE] : This Suite is still under active development. You can expect bugs.

Key features

1. Representation-Agnostic Optimizations: Apply the same passes across multiple MLIR dialects.

2. Cross-framework support: Works with ecosystems like cudaq-quantum and Catalyst.

3. Write once, reuse everywhere: Shared optimization logic across compiler representations.

4. Built to extend: Add new passes without redesigning the framework.

5. Native-IR interoperability: Connect frameworks without replacing their IRs/dialects.

6. Qubit Mapping: A representation-agnostic logical/algorithmic to physical qubit mapping pass that uses QDMI and MQT-QMAP

7. Transpilation: A transpilation pass to decompose to the native-gate set of target quantum devices (currently only for cudaq-quake).

Note: Please refer to the FAQs section for more details on the passes, MLIR, MQSS and other related questions.

Getting Started

System Requirements

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

Development Environment

• Docker
• VSCode
• VSCode Dev Containers extension

Major Dependencies

Note: These are automatically downloaded and installed by the build scripts

• LLVM : 22.1.0 toolchain
• CMake : 3.29...4.2
• cudaq-quantum toolchain : 0.15.0
• pennylane-catalyst toolchain: 0.14.1
• python : 3.11
• C++ : 17...20
• Compiler : gcc and g++ 11.4

For a full list of dependencies check .devcontainer/Dockerfile.

Prerequisites

Clone the project:

git clone https://github.com/Munich-Quantum-Software-Stack/MQSS-Quantum-Compilation-Suite.git \
       /workspaces/MQSS-Passes-Suite
cd /workspaces/MQSS-Passes-Suite
git checkout <branch-name>

branch-name could be develop or any other branch from this repository. 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

First, we need to configure the build via cmake 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

Next, we need to set paths to the directories where the executables are generated i.e. ~/.local/bin. RUN command:

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

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.

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/dialectsdirectory. There are a total of about 60 test cases currently, with more added regularly.

Contact

The development of this project is led by the QCT department at the LRZ and the QSI department at MQV gGmbH. You can also always reach us at mqss@munich-quantum-valley.de.

Please try to use the publicly accessible GitHub channels (issues, discussions, pull requests) to allow for a transparent and open discussion as much as possible.