mqt.qfr 1.11.1

A tool for Quantum Functionality Representation

MQT QFR - A Library for Quantum Functionality Representation Written in C++

A library for the representation of quantum functionality by the Institute for Integrated Circuits at the Johannes Kepler University Linz. If you have any questions feel free to contact us using [e-mail] or by creating an issue on GitHub.

Efficient Construction of Functional Representations for Quantum Algorithms

The QFR library provides the means for constructing the functionality of a given quantum circuit using decision diagrams in the form of the mqt.qfr Python package. It includes a traditional, sequential approach (qfr.ConstructionMethod.sequential) and the efficient, recursive method proposed in [1] (qfr.ConstructionMethod.recursive).

[1] L. Burgholzer, R. Raymond, I. Sengupta, and R. Wille. "Efficient Construction of Functional Representations for Quantum Algorithms". arXiv:2103.08281, 2021

In order to make the library as easy to use as possible (without compilation), we provide pre-built wheels for most common platforms (64-bit Linux, MacOS, Windows). These can be installed using

pip install mqt.qfr

However, in order to get the best performance out of the QFR, it is recommended to build it locally from the source distribution (see system requirements) via

pip install mqt.qfr --no-binary mqt.qfr

This enables platform specific compiler optimizations that cannot be enabled on portable wheels.

Once installed, in Python, the functionality of a given circuit (provided, e.g., as Qiskit QuantumCircuit) can be constructed with:

from mqt import qfr
from qiskit import QuantumCircuit

# create your quantum circuit
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)

# construct the functionality of the circuit
results = qfr.construct(qc)

# print the results
print(results)

The construct function additionally provides the options store_decision_diagram and store_matrix that allow to store the resulting decision diagram or matrix, respectively. Note that storing the resulting matrix takes considerable amounts of memory in comparison to the typical memory footprint incurred by the corresponding decision diagram. At least 2^(2n+1)*sizeof(float) byte are required for storing the matrix representing an n-qubit quantum circuit.

Special routines are available for constructing the functionality of the Quantum Fourier Transform (construct_qft(nqubits, ...)) or Grover's algorithm (construct_grover(nqubits, seed, ...)). For details on the method employed for Grover's search we refer to [1, Section 4.2].

MQT Toolset

The QFR library is the backbone of the quantum software tools in:

• MQT DDSIM: a decision diagram-based simulator for quantum circuits.
• MQT QMAP: a tool for mapping/compiling quantum circuits to real quantum architectures.
• MQT QCEC: a decision diagram-based equivalence checking tool for quantum circuits.
• MQT DDVis: a visualization tool for how decision diagrams are used in simulation and verification.
  • You can find an online instance of this tool at http://iic.jku.at/eda/research/quantum_dd/tool/

It acts as an intermediate representation and provides the facilitites to

• Obtain intermediate representations from circuit descriptions.

  Currently available file formats are:

  • OpenQASM (e.g. used by Qiskit)
  • Real (e.g. from RevLib)
  • GRCS Google Random Circuit Sampling Benchmarks (see GRCS)
  • TFC (e.g. from Reversible Logic Synthesis Benchmarks Page)
  • QC (e.g. from Feynman)

  Importing a circuit from a file in either of those formats is done via:

  std::string filename = "PATH_TO_FILE";
  qc::QuantumComputation qc(filename);
  

  or by calling

  qc.import(filename);
  

  which first resets the qc object before importing the new file.

• Generate circuit representations for important quantum algorithms.

  Currently available algorithms are:

  • Entanglement

    dd::QubitCount n = 2;
    qc::Entanglement entanglement(n); // generates bell circuit
    

    Generates the circuit for preparing an n qubit GHZ state. Primarily used as a simple test case.

  • Bernstein-Vazirani

    unsigned long long hiddenInteger = 16777215ull;
    qc::BernsteinVazirani bv(hiddenInteger); // generates Bernstein-Vazirani circuit for given hiddenInteger
    

    Generates the circuit for the Berstein-Vazirani algorithm using the provided hiddenInteger

  • Quantum Fourier Transform (QFT)

    dd::QubitCount n = 3;
    qc::QFT qft(n); // generates the QFT circuit for n qubits
    

    Generates the circuit for the n qubit Quantum Fourier Transform.

  • Grover's search algorithm

    dd::QubitCount n = 2;
    qc::Grover grover(n); // generates Grover's algorithm for a random n-bit oracle
    

    The algorithm performs ~ π/4 √2ⁿ Grover iterations. An optional unsigned int parameter controls the seed of the random number generation for the oracle generation.

  • (Iterative) Quantum Phase Estimation

    dd::QubitCount n = 3;
    bool exact = true; // whether to generate an exactly representable phase or not
    qc::QPE qpe(n, exact);
    qc::IQPE iqpe(n, exact);
    

    Generates a random bitstring of length n (n+1 in the inexact case) and constructs the corresponding (iterative) Quantum Phase Estimation algorithm using n+1 qubits. Alternatively, a specific phase and precision might be passed to the constructor.

• Generate circuit descriptions from intermediate representations.

  The library also supports the output of circuits in various formats by calling

  std::string filename = "PATH_TO_DESTINATION_FILE.qasm";
  qc.dump(filename);
  

  Currently available file formats are:

  • OpenQASM (.qasm)

Development

System Requirements

Building (and running) is continuously tested under Linux, MacOS, and Windows using the latest available system versions for GitHub Actions. However, the implementation should be compatible with any current C++ compiler supporting C++17 and a minimum CMake version of 3.19.

Disclaimer: We noticed some issues when compiling with Microsoft's MSVC compiler toolchain. If you are developing under Windows, consider using the clang compiler toolchain. A detailed description of how to set this up can be found here.

It is recommended (although not required) to have GraphViz installed for visualization purposes.

The QFR library also provides functionality to represent functionality of quantum circuits in the form of ZX-diagrams. At this point this feature is only used by MQT QCEC but is going to be extended further in future releases. If you want to use this feature it is recommended (although not strictly necessary) to have GMP installed in your system.

Configure, Build, and Install

To start off, clone this repository using

git clone --recurse-submodules -j8 https://github.com/cda-tum/qfr

Note the --recurse-submodules flag. It is required to also clone all the required submodules. If you happen to forget passing the flag on your initial clone, you can initialize all the submodules by executing git submodule update --init --recursive in the main project directory.

Our projects use CMake as the main build configuration tool. Building a project using CMake is a two-stage process. First, CMake needs to be configured by calling

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release

This tells CMake to search the current directory . (passed via -S) for a CMakeLists.txt file and process it into a directory build (passed via -B). The flag -DCMAKE_BUILD_TYPE=Release tells CMake to configure a Release build (as opposed to, e.g., a Debug build).

After configuring with CMake, the project can be built by calling

 cmake --build build --config Release

This tries to build the project in the build directory (passed via --build). Some operating systems and developer environments explicitly require a configuration to be set, which is why the --config flag is also passed to the build command. The flag --parallel <NUMBER_OF_THREADS> may be added to trigger a parallel build.

Building the project this way generates

• the core library libqfr.a (Unix) / qfr.lib (Windows) in the build/src folder
• the DD and ZX libraries libqfr_dd.a (Unix) / qfr_dd.lib (Windows) and libqfr_zx.a (Unix) / qfr_zx.lib (Windows) in the build/src/ folder
• test executables qfr_test, qfr_test_dd, and qfr_test_zx containing a small set of unit tests in the build/test folder

You can link against the library built by this project in other CMake project using the MQT::qfr target (or any of the other targets MQT::qfr_dd and MQT::qfr_zx).

Extending the Python Package

To extend the Python package you can locally install the package in edit mode, so that changes in the Python code are instantly available. The following example assumes you have a virtual environment set up and activated.

(venv) $ pip install cmake
(venv) $ pip install --editable .

If you change parts of the C++ code, you have to run the second line to make the changes visible in Python.