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

A JKQ library for the representation of quantum functionality by the Institute for Integrated Circuits at the Johannes Kepler University Linz. This package is part of the JKQ toolset.

Developers: Lukas Burgholzer, Hartwig Bauer, Stefan Hillmich, Thomas Grurl and Robert Wille.

If you have any questions feel free to contact us using iic-quantum@jku.at 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 jkq.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 start using it, install the package using

pip install jkq.qfr

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

from jkq import qfr
from qiskit import QuantumCircuit

# create your quantum circuit
qc = <...>

# 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].

JKQ Toolset

The QFR library is the backbone of the quantum software tools in JKQ: JKU Tools for Quantum Computing:

• JKQ DDSIM: a decision diagram-based simulator for quantum circuits.
• JKQ QMAP: a tool for mapping/compiling quantum circuits to real quantum architectures.
• JKQ QCEC: a decision diagram-based equivalence checking tool for quantum circuits.
• JKQ 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

    unsigned short 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)

    unsigned short 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

    unsigned short 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.

• 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.14.

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

Configure, Build, and Install

To start off, clone this repository using

git clone --recurse-submodules -j8 https://github.com/iic-jku/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 library libqfr.a (Unix) / qfr.lib (Windows) in the build/src folder
• a test executable qfr_test containing a small set of unit tests in the build/test folder
• a small demo example executable qfr_example in the build/test directory.

You can link against the library built by this project in other CMake project using the JKQ::qfr target.

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.