Development Guide¶

Ready to contribute to the Quantum Compilation Suite of the MQSS? This guide will help you get started.

Development Environment¶

It is recommended to use a docker container to ensure consistent, stable development environment.
The required DockerFile and devcontainer.json are provided in .devcontainer directory. Build and RUN the docker container using the following commands:

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

Building the tool¶

The driver is the Makefile within the project root.
The Makefile invokes build scripts within scripts/. build.sh: Main script for configuring the build for all targets including mqss-opt
The ``make` commands to build the targets remain the same as in the README. Ensure the sequence of commands is followed.

Project structure (for Current Release)¶

MQSS-Quantum-Compilation-Suite/
├── cmake/                      # Find*.cmake modules: CUDAQ, Catalyst, QDMI, MQT-QMAP, MQT-QCEC, etc.
├── docs/                       # Sphinx documentation source (this page included)
├── include/
│   ├── Passes/
│   │   ├── Analysis/
│   │   │   ├── CatalystExtractor.h
│   │   │   ├── DialectAnalysisSelector.h
│   │   │   ├── Extractor.h
│   │   │   └── QuakeExtractor.h
│   │   ├── CodeGen/
│   │   │   ├── BasisConversionPatterns.h
│   │   │   ├── CMakeLists.txt
│   │   │   ├── CodeGenPasses.h
│   │   │   ├── CodeGenPasses.td
│   │   │   ├── Patterns.h
│   │   │   └── StaticAllocas.h
│   │   ├── Transforms/
│   │   │   ├── CMakeLists.txt
│   │   │   ├── Decomposition.h
│   │   │   ├── Dialects.h
│   │   │   ├── MappingPassUtils.h
│   │   │   ├── PassIncludes.h
│   │   │   ├── PassUtils.h
│   │   │   ├── Pipelines.h
│   │   │   ├── Transforms.h
│   │   │   ├── Transforms.td
│   │   │   └── TranspilationPassUtils.h
│   │   └── CMakeLists.txt
│   ├── Utils/
│   │   ├── debug_utils.h
│   │   ├── dialectutils.h
│   │   └── Error.h
│   └── CMakeLists.txt
├── lib/
│   ├── Dialects/
│   │   ├── CMakeLists.txt
│   │   └── Dialects.cpp
│   ├── Passes/
│   │   ├── CodeGen/
│   │   │   ├── BasisConversionPass.cpp
│   │   │   ├── CMakeLists.txt
│   │   │   ├── ConversionPatterns.cpp
│   │   │   ├── GlobalizeArrayValuesPass.cpp
│   │   │   ├── LLVMDialectToLLVMIRPass.cpp
│   │   │   ├── QuakeToQASM2Pass.cpp
│   │   │   ├── QuantumToLLVMDialectPass.cpp
│   │   │   └── StaticAllocas.cpp
│   │   ├── Transforms/
│   │   │   ├── CMakeLists.txt
│   │   │   ├── CommonCNOTReversalPass.cpp
│   │   │   ├── CommonCommuteAndSwitchPass.cpp
│   │   │   ├── CommonDecompositionPass.cpp
│   │   │   ├── CommonGateCancellationPass.cpp
│   │   │   ├── CommonGateCommutationPass.cpp
│   │   │   ├── CommonMappingPass.cpp
│   │   │   ├── CommonNormalizeArgAnglePass.cpp
│   │   │   ├── CommonPatternReductionPass.cpp
│   │   │   └── Pipeline.cpp
│   │   └── CMakeLists.txt
│   └── CMakeLists.txt
├── scripts/                    # build.sh, mqss-cc wrapper, front-end toolchain download scripts
├── tests/                      # tests/dialects (lit + FileCheck) and tests/code (end-to-end)
├── CMakeLists.txt
└── mqss-cc.cpp

Dialect registration lives in lib/Dialects. Dialect-agnostic MLIR optimization passes (namespace mqss::mqssci::opt) live in lib/Passes/Transforms. Code-generation/lowering passes (namespace mqss::mqssci::codegen) live in lib/Passes/CodeGen.
CUDAQ and Catalyst are included as external dependencies and are downloaded and installed as cmake modules. Following targets are built for each of these modules:
- CUDAQ: QuakeDialect CCDialect QECDialect OptimBuilder OptCodeGen
- Catalyst : MLIRMBQC MLIRQRef MLIRQuantum These targets incorporate all dialect related headers and API implementations.

CMakeLists.txt¶

The pass library is built as three separate CMake targets, one per directory under lib/, each with its own CMakeLists.txt declaring exactly the external dependencies (CUDAQ, Catalyst, QDMI, MQT-QMAP, MLIR conversion libraries, etc.) that its own sources actually need:

lib/Dialects/CMakeLists.txt — builds MQSSSupportedDialects (dialect registration).
lib/Passes/CodeGen/CMakeLists.txt — builds MQSSCICodeGenPasses (code-generation/lowering passes), linking MQSSSupportedDialects PUBLIC.
lib/Passes/Transforms/CMakeLists.txt — builds MQSSCIPasses (dialect-agnostic optimization passes), linking MQSSCICodeGenPasses PUBLIC.

Because each dependency is declared PUBLIC at the target that actually needs it, everything propagates transitively up the chain. root/CMakeLists.txt only has to link the final executable against the top of that chain plus MLIR’s own driver library:

target_link_libraries(mqss-opt PUBLIC MLIROptLib MQSSCIPasses)

Note: this transitive propagation is convenient, but it isn’t a substitute for checking what a given .cpp file’s callees actually require. If a source file (or a library it calls into, such as CUDAQ::CodeGen) needs a specific MLIR conversion library, link it explicitly at the target that contains that source file — don’t assume it will arrive transitively from another target further down the chain.

Testing¶

We use python-lit along-with ninja and FileCheck to perform dialect-level (input: MLIR dialect; output: MLIR dialect) and optionally end-to-end (input:c++/python code; output: MLIR dialect) testing. In the end, what is tested for correctness is the output optimized/transformed MLIR dialect. In a select few cases, especially the CodeGen passes, the backend exchange formats e.g. QIR or OpenQasm2 are tested for correctness.
The tests can be found in directories : tests/dialects and tests/code.
Dialect-level testing
1. The input dialect is annotated with the RUN command, for e.g.:
// RUN: %mqss-opt %s --CommonCommutePass=mode=CX-X 2>&1 | FileCheck %s which runs the target/executable mqss-opt along-with the pass CommonCommutePass. FileCheck looks for strings to match, specified using the CHECK: keyword, for e.g.
```
// CHECK: %out_qubits = quantum.custom "PauliX"() %2 : !quantum.bit
// CHECK: %out_qubits_0:2 = quantum.custom "CNOT"() %1, %2 : !quantum.bit, !quantum.bit
```
If an exact match is found in the output dialect, the test succeeds, otherwise the test fails.
1. End-to-End testing (Optional) In this testing, the input is a c++/python code, which is then translated to the input MLIR dialect. The testing then proceeds as in (1). The emphasis here is on testing the front-end translation pipeline as well as the transformed dialects. A wrapper script mqss-cc is used to invoke the necessary tools to translate the c++/python code to the input quake or catalyst-quantum dialect. If the input code to MLIR dialect translation fails, then the test itself will fail. An example test file performing such a test is shown below:
```
 // RUN: %mqss-cc %S/../CommuteCNotRxPass.cpp --passes=CommonCommutePass=mode=CX-RX | FileCheck %s

 // CHECK: quake.rx (%cst_1) %4 : (f64, !quake.ref) -> ()
 // CHECK-NEXT: quake.x [%1] %2 : (!quake.ref, !quake.ref) -> ()
```
The test proceeds as follows:
1. mqss-cc parses the command-line arguments %S/../CommuteCNotRxPass.cpp --passes=CommonCommutePass=mode=CX-RX
2. Since, a c++ code is the input, it is assumed that the code contains a quantum circuit defined using cudaq (will be updated in the future).
3. The c++ to quake dialect translation pipeline is invoked via the tool cudaq-quake
4. Once the input dialect is generated, mqss-opt tool is used to apply MQSS optimization/translation passes defined using the --passes flag.
5. Finally, the optimized/transformed dialect is emitted which is checked by FileCheck.
Note: Make sure that the path to cudaq-quake and mqss-opt are appended to the $PATH environment variable of your shell via the command : eval "$(make set-target-paths)".

Enabling Pass Debug Information¶

The Pass debug information can be enabled by passing in the flag --debug to the DEBUG_FLAG variable within the Makefile. Simply remove the flag if no debug information is needed.