This repository is the "out-of-tree" components for the Intel Quantum Compiler. It interprets and processes the IR generated by the Intel Quantum Intrinsics and provides interfaces to integrate your own passes into the quantum compilation process.
The passes included in this repository lowers, schedules and prepares the generated IR from clang package with the Intel Quantum SDK to the point before the qISA is generated for Intel Quantum Backends via the Quantum Runtime. The code included with this repository cannot generate a binary. The final step of compilation to target a quantum binary will need to be generated using the compilation program included with the Intel Quantum SDK. See "Using This Repository with the SDK" for more information.
There are two different ways provided to use this repository. However, both require access to the Intel Quantum SDK for all features to be usable. To build the repository, you must also have access to cmake and either the ninja or make build systems.
The first step is the same for both.
git clone https://github.com/intel/quantum-passes.git
cd quantum-passes
mkdir build
cd build
This is the simplest and fastest way to get started. The Intel Quantum SDK has a packaged version of Clang and LLVM tools with quantum intrinsics in the iqc directory. In this case, the path to the SDK is needed.
cmake -G Ninja -DLT_INTEL_QUANTUM_SDK_LOC=<sdk_install_dir> ../
ninja
If the Ninja build system is not available, replace this option with -G "Unix Makefiles".
This is the more advanced option. In general, it will not be required by users of this repository. However, some potential uses may include:
- Enabling more detailed debug messages/stack traces
- Adding your own quantum intrinsics
- Adding your own functions to the header files
- Adding your own backend to compile quantum intrinsics to a binary structure separate from the qISA
You must first clone and build the Intel Quantum Intrinsics repository. You can find more in-depth instructions in that repository, but here as the basics:
mkdir build
cd build
cmake -G Ninja -S ../llvm -B . -DLLVM_INSTALL_UTILS=ON -DCMAKE_INSTALL_PREFIX=<iqc_install_dir> -DLLVM_ENABLE_PROJECTS="clang;lld" -DCMAKE_BUILD_TYPE=Release
ninja -C . install
Now, point to the Intel Quantum SDK and the built Quantum Intrinsics to build the passes from the build directory.
cmake -G Ninja -DLT_INTEL_QUANTUM_SDK_LOC=<sdk_install_dir> -DLT_LLVM_INSTALL_DIR=<iqc_install_dir> ../
ninja
If the Ninja build system is not available, replace this option with -G "Unix Makefiles".
Via the LLVM underpinnings, the Intel Quantum Compiler offers a mechanism for users to write and run their own passes on quantum code.
To do so, you must use the -E to specify a compile library of passes. Examples of these can be found in the ExamplePassLibraries directory. Then for each section passes are to be run, specify -e to denote when they are to be run. precondition runs the passes before the quantum module is validated and conditioned. prelower is run before the quantum module is lowered to native gates. presplit is run before the quantum modules and classical code are separated from one another. Then -a is used to denote which passes are to be run, from the LLVM library, the Intel Quantum Library of passes, or the user generated passes from the provided library. These are given in a comma-delimited list. Then -A can be used before each argument that needs to be passed to this instantiation of passes.
The following is an example of this invocation of the driver script. It runs the example-print-gates from a single pass library during the prelower and the presplit sections of compilation. The first runs with a default command line argument, and the other contains a command line argument.
./iqc-out-of-tree.sh -b iqc/build/bin -E build/lib/libExampleSinglePass.so -e prelower -a print-all-gates-example -e presplit -a print-all-gates-example -A -example-pass-opt -A testing <source_file>
This is an example of a multipass library that runs multiple passes.
./iqc-out-of-tree.sh -b <iqc_install_dir>/bin -E build/lib/libExampleMultiPass.so -e prelower -a print-all-gates,x-to-hzh,print-all-gates -A -example-pass-opt -A testing -e presplit -a print-all-gates-example -A -example-pass-opt -A testing <source_file>
The passes generated here can be used in conjunction with, or during the compilation flow included in the Intel Quantum SDK.
A compilation script is included with both the repository and the SDK. Both of these can pick up a generated IR file mid-compilation, detect the stage of compilation and continue the compilation as far as it can. This gives two possible ways to combine the two.
This is the simplest way to perform compilation. However, this script cannot make use of FLEQ, PCOAST optimization and some scheduling operations. This is a bare-bones compilation. It is likely best used for proofs of concept or for when more control over the compilation flow is desired. Simply use the included script in this repository, using the command line flags listed above. After compilation is complete, you will be left with a file named *_separated.ll. This file can be given to the compilation script included in the SDK, which will generate the binary program file.
This compilation requires one script. It uses the same command line flags as before, but for the usual steps of compilation will use the Intel Quantum SDK version. Any modifications made to the included passes will not be used. This process will automatically compile directly to a runnable program.
If you do need to specify the path to a modified version of LLVM and Clang, this can be done through the -b option.
The benefit of this strategy is the ability to integrate Intel Quantum SDK optimizations with your own optimizations.
There is an in-depth explanation of each pass and writing passes in the docs directory.