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 and Robert Wille.
If you have any questions feel free to contact us using [email protected] or by creating an issue on GitHub.
The package can be used for a multitude of tasks, as illustrated in the following:
-
Obtaining 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. -
Generating 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.
-
-
Constructing a functional representation of a given quantum computation.
Thereby we use our decision diagram (DD) package, which is included as a git-submodule in this project, in order to construct a DD representation from the individual gate descriptions.
For more information on decision diagrams for quantum computing, please visit iic.jku.at/eda/research/quantum_dd.
The following example shows how to construct the functionality of the three-qubit QFT from above.
auto dd = make_unique<dd::Package>(); // create an instance of the DD package auto functionality = qft.buildFunctionality(dd); // obtain DD representation
The matrix representation of the constructed functionality can be printed by calling
qft.printMatrix(dd, functionality, std::cout);
which results in the following output
Common Factor: √½ ½ 1 1 1 1 1 1 1 1 1 1 1 1 -1 -1 -1 -1 1 1 -1 -1 +i +i -i -i 1 1 -1 -1 -i -i +i +i 1 -1 +i -i √½(1+i) -√½(1+i) -√½(1-i) √½(1-i) 1 -1 +i -i -√½(1+i) √½(1+i) √½(1-i) -√½(1-i) 1 -1 -i +i -√½(1-i) √½(1-i) √½(1+i) -√½(1+i) 1 -1 -i +i √½(1-i) -√½(1-i) -√½(1+i) √½(1+i)
Note that matrix output factors in initial assignments as well as output permutations of the system (i.e.
initialLayout
andoutputPermutation
).The (much more compact) DD representation that was actually constructed can be visualized as a *.dot file (which is automatically converted to SVG if GraphViz is installed) by calling
dd::export2Dot(functionality, "functionality.dot");
which produces
See below for a description of the visualization options and their interpretation.
-
Basic support for DD-based simulation of quantum algorithms.
Only the calculation of a DD state vector representation is supported (without intermediate measurements). For a more powerful approach, see our dedicated simulator JKQ DDSIM.
The following example shows the simulation of Grover's algorithm from above (searching for the 2-bit string
00
). Note that00
is just an example here, as the oracle that is generated byGrover(n)
depends on a random seed.auto dd = make_unique<dd::Package>(); // create an instance of the DD package auto initial_state = dd->makeZeroState(n); // create initial state |0...0> auto state_vector = grover.simulate(initial_state, dd);
The vector representation of the resulting state vector can be printed by calling
grover.printVector(dd, state_vector, std::cout);
which results in the following output
Common Factor: -1 0: 1 1: 0 10: 0 11: 0 100: 0 101: 0 110: 0 111: 0
As expected, the probabilities for obtaining the state
|x00>
(the ancillary qubit x is ignored) sum up to 1.The (much more compact) DD representation, that was actually produced by the simulation, can again be visualized as SVG file by calling
dd::export2Dot(state_vector, "state_vector.dot", true);
which produces
-
Visualization and output of functional representations.
Quantum computations can be visualized by printing them to any given output stream, e.g.
std::cout << grover << std::endl;
yields
i: 0 1 2 1: X | | X 2: H H | | 3: H | H | 4: Z c c Z 5: H H | | 6: H | H | 7: X X | | 8: X | X | 9: H | H | 10: X c X | 11: H | H | 12: X | X | 13: X X | | 14: H | H | 15: H H | | 16: X | | X o: 0 1 2
As already demonstrated above, the function
dd::exportDD(...)
can be used to create visualizations of DDs representing vectors as well as matrices. To this end, the thickness of each edge indicates the edge weight's magnitude, while a color code indicates its phase. We use the HSV color wheel (at 50% lightness and 50% saturation) given belowFurthermore, the export function has several options to tune the look and feel of the resulting DDs, e.g., enabling/disabling color, enabling/disabling edge weights, enabling/disabling classic mode.
If you ever want to visually explore how decision diagrams are employed in quantum computing for tasks such as simulation and verification, check out our installation-free web-tool JKQ DDVis.
The library also supports the output of circuits in various formats by calling
std::string filename = "PATH_TO_DESTINATION_FILE.{qasm | py}";
qc.dump(filename);
Currently available file formats are:
* `OpenQASM` (.qasm)
* `Qiskit` (.py) Qiskit export generates a python file, which can be used to transpile a respective circuit to a suitable architecture using the Qiskit toolset (specifically Qiskit Terra 0.12.0).
-
Circuit transcription
The project also includes a small command line application
qfr_app
which can be used to transcribe circuits from one format into another format, e.g.qfr_app circuit.real circuit.py
can be used to transcribe a circuit from
real
format to a Qiskit realization
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.
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 thebuild/src
folder - a test executable
qfr_test
containing a small set of unit tests in thebuild/test
folder - a small demo example executable
qfr_example
in thebuild/test
directory. - the commandline transcription executable
qfr_app
in thebuild/apps
directory.
You can link against the library built by this project in other CMake project using the JKQ::qfr
target.