QIR-EE

The QIR Execution Engine library provides interfaces for processing Quantum Intermediate Representation code using the LLVM execution engine.

Introduction

The Quantum Intermediate Representation Execution Engine (QIR-EE, pronounced 'cure-ee') is a tool designed to streamline the process of running quantum circuits and algorithms. One of our goals is to make your journey into quantum computing as seamless as possible. This implementation is associated to the paper A Cross-Platform Execution Engine for the Quantum Intermediate Representation published in the Journal of Supercomputing, Volume 81, 1521 (2025) and is maintained by the QIR-EE Developers.

This work represents the feasibility of a modular workflow at the lower end of the quantum software stack. We welcome feedback and ideas for collaborations.

Documentation

Most of the QIR-EE documentation is readable through the codebase through a combination of static RST documentation and Doxygen-markup comments in the source code itself. The full QIR-EE user documentation (including selected code documentation incorporated by Breathe) and the QIR-EE code documentation will be mirrored on our GitHub pages site. You can generate these yourself (if the necessary prerequisites are installed) by setting the option -DQIREE_BUILD_DOCS=ON running make doc (user) or make doxygen (developer).

Getting Started

Dependencies

There is a key dependency for QIR-EE to work properly. Please make sure to download and install the most current version of:

LLVM (we have tested versions 14 through 18).

There is an optional dependency for QIR-EE to run on hardware backends.

XACC: Here, we recommend setting option -DQIREE_MINIMAL_BUILD=ON during cmake for a faster build. Follow the XACC prerequisites page to ensure a smoother installation.

Requirements for Basic Runs

Ability to download and build this project with cmake.
A QIR file with the quantum program that you want to run (see examples folder).

(Optional) Credentials for Hardware and Specialized Simulator Runs

Access to a compatible quantum computing simulator or real quantum hardware.
Configuration files set up in your home folder that contain credentials to access vendor backends. This typically takes on the form .backend_config depending on the backends you have access to.

Installation

QIR-EE Setup in Command Line

Clone/download/unzip this repo.
Enter the repo folder.
mkdir build; cd build
cmake ..
make

By default, we have the following options. These can be adjusted in step 3.

-DQIREE_BUILD_TESTS=ON, -DQIREE_BUILD_DOCS=OFF, -DDQIREE_USE_XACC=ON, -DQIREE_USE_QSIM=ON

The resulting path to executable files can be exported as

export PATH=${YOUR-QIREE-INSTALL-DIR}/bin:$PATH

which would allow you to access the QIR-EE from anywhere in command line.

Executing Quantum Circuits

(via QIR-EE and QSIM)

Syntax For basic usage:

qir-qsim llvm-file-path -s num-shots

The default number of shots is 1 if you don't invoke that option.

Example:

qir-qsim $HOME/qiree/examples/teleport.ll -s 100

This command will execute the teleport algorithm described in teleport.ll with 100 shots using Google's qsim state simulator, which can handle mid-circuit measurements.

(via QIR-EE and XACC)

Check that your cmake prefixes for XACC are correct.
Typing echo $CMAKE_PREFIX_PATH should give you the path to your XACC installation.
If empty, then add it: export CMAKE_PREFIX_PATH=$HOME/.xacc or an equivalent path to your XACC installation.
Check your $PYTHONPATH for pointing to your XACC installation.
If empty, then add it: export PYTHONPATH=$PYTHONPATH:$HOME/.xacc or an equivalent path to your XACC installation.

Syntax For basic usage:

qir-xacc llvm-file-path --flag-name flag-value

qir-xacc may be replaced with an equivalent executable.
llvm-file-path is used to indicate path of the LLVM (*.ll) file that specifies the quantum program (required).
-a or --accelerator is the name of the quantum accelerator (hardware or simulator) that you wish to use (required).
-s or --shots is the number of shots (optional with default at 1024).

With XACC we have tested: aer, qpp, qsim, quantinuum:H1-1SC, quantinuum:H1-1E, quantinuum:H1-1, ionq, ionq:sim.harmony, ionq:sim.aria-1, ionq:qpu.harmony.

Note that the minimal build only includes aer and qpp for local simulators.

Example:

qir-xacc $HOME/qiree/examples/bell.ll --accelerator qpp

This command will execute the quantum Bell circuit described in bell.ll the (default) 1024 times using the "qpp" accelerator.

Understanding the Results

After execution, you will receive a summary of the quantum circuit's results. This may include a simple dictionary of counts for qubit strings or the xacc buffer output. Some example outputs from experiments can be found here: qiree-data.

Directory structure

| Directory | Description | | ------------- | --------------- | | app | Source code for installed executable applications | | cmake | Implementation code for CMake build configuration | | doc | Code documentation and manual | | examples | A collection of QIR examples | | scripts | Development and continuous integration helper scripts | | src | Library source code | | test | Unit tests |

Citation

This code was was made public on github on June 24, 2024 and released to DOE CODE on January 15, 2025.

@misc{qireerepo,
title = {{QIR-EE}},
author = {{QIR-EE Developers}},
url = {https://github.com/ORNL-QCI/qiree},
howpublished = {[Computer Software] \url{https://doi.org/10.11578/qiree/dc.20250114.1}},
year = {2025},
}

Qiree

Install / Use

README