jkq.ddsim 1.9.1

JKQ DDSIM - A quantum simulator based on decision diagrams written in C++

JKQ DDSIM - A quantum circuit simulator based on decision diagrams written in C++

A tool for quantum circuit simulation by the Institute for Integrated Circuits at the Johannes Kepler University Linz and a part of the JKQ toolset.

The tool builds upon our quantum functionality representation (QFR) which in turns builds on our decision diagram (DD) package.

For more information, on our work on quantum circuit simulation please visit iic.jku.at/eda/research/quantum_simulation or, for more information on our work on noise-aware quantum circuit simulation, please visit iic.jku.at/eda/research/noise_aware_simulation.

If you have any questions, feel free to contact us via [e-mail] or by creating an issue on GitHub.

Table of contents

• Usage
• Using the Python Bindings / Backend for Qiskit
• System Requirements
• Build and Run
  • Library
  • Executable Simulator
  • Executable Noise-aware Simulator
• Running Tests
• Frequently Asked Questions
• References

Usage

This tool can be used for simulating quantum circuits provided in any of the following formats:

• Real from RevLib
  • Our set of circuits
  • RevLib
• OpenQASM used by IBM's Qiskit
  • Our set of circuits
  • OpenQASM Repo
  • QUEKO (focus on mapping though)
• GRCS
  • GRCS Repo
• TFC
  • Reversible Logic Synthesis Benchmarks Page
• Qiskit QuantumCircuits
  • As a backend for qiskit
  • "Standalone" by directly passing the quantum circuit

The format is automatically detected through the file extension.

The following additional algorithms are integrated in QFR and hence available in the simulator as well:

• Quantum Fourier Transformation
• Bernstein-Vazirani
• GHZ / Entanglement
• Grover's search (see --help for different call options)

For details on the available methods we refer to iic.jku.at/eda/research/quantum_simulation.

The simulator is based on the references listed below and can either be used as a standalone executable with command-line interface, or as a library for the incorporation in other projects.

Using the Python Bindings / Backend for Qiskit

The backend for Qiskit is available via PyPi as wheel for Linux, Windows and MacOS. 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). (We strongly recommend using a virtual environment.)

(venv) $ pip install jkq.ddsim

However, in order to get the best performance out of DDSIM, it is recommended to build it locally from the source distribution via

pip install --no-binary jkq.ddsim

The following code gives an example on the usage:

from qiskit import *
from jkq import ddsim

circ = QuantumCircuit(3)
circ.h(0)
circ.cx(0, 1)
circ.cx(0, 2)

print(circ.draw(fold=-1))

provider = ddsim.JKQProvider()

backend = provider.get_backend('qasm_simulator')

job = execute(circ, backend, shots=10000)
result = job.result()

counts = result.get_counts(circ)
print(counts)

The provider currently has five backends:

• qasm_simulator which simulates the circuit and returns the requested number of shots
• statevector_simulator which also simulates the circuit and returns the statevector along the requested number of shots
• hybrid_qasm_simulator which simulates the circuit in parallel using a hybrid Schrodinger-Feynman technique and returns the requested number of shots
• hybrid_statevector_simulator which also simulates the circuit in parallel using a hybrid Schrodinger-Feynman technique and returns the statevector
• unitary_simulator which constructs the unitary functionality of a circuit and returns the corresponding unitary matrix

A slightly more elaborate example can be found in the notebook ddsim.ipynb.

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.

OpenMP >= 4.0 is required for building the ddsim library. Additionally, boost/program_options >= 1.50 is required for building the commandline interface for ddsim_simple and ddsim_noise_aware. The ddsim_noise_aware simulator further requires Threads::Threads.

Clone, Build, and Run

The code uses quite a few submodules, which have to be initialized. There are two ways to do this:

1. While cloning the repository with the --recurse-submodules option to git clone. For HTTPS access: git clone --recurse-submodules https://github.com/iic-jku/ddsim/.
2. After cloning with git submodule update --init --recursive.

Library

For building the library alone the CMake target ddsim is available. In CMake from version 3.13 you can use the following commands:

$ cmake -DCMAKE_BUILD_TYPE=Release -S . -B build
$ cmake --build build --config Release --target ddsim

Windows users need to configure CMake by calling

$ cmake -A x64 -DCMAKE_BUILD_TYPE=Release -S . -B build
$ cmake --build build --config Release --target ddsim

instead.

The library can be used by including, for example, the QFRSimulator.hpp header file and

std::string file1 = "PATH_TO_FILE_1.EXT";
qc::QuantumComputation qc1(file1);

qc::SimpleSimulator sim(qc1);
sim.Simulate();
auto samples = sim.MeasureAllNonCollapsing(1000);
/* Use the results */

Executable Simulator

To build the executable simulator, build the ddsim_simple CMake target (which requires boost/program_options) and run the resulting executable with options according to your needs.

The standalone executable is launched in the following way, showing available options:

$ ./ddsim_simple --help
JKQ DDSIM by https://iic.jku.at/eda/ -- Allowed options:
-h [ --help ]                         produce help message
--seed arg (=0)                       seed for random number generator (default zero is possibly directly used as seed!)
--shots arg (=0)                      number of measurements (if the algorithm does not contain non-unitary gates, weak simulation is used)
--pv                                  display the state vector as list of pairs (real and imaginary parts)
--ps                                  print simulation stats (applied gates, sim. time, and maximal size of the DD)
--pm                                  print measurement results
--pcomplex                            print print additional statistics on complex numbers
--verbose                             Causes some simulators to print additional information to STDERR
--simulate_file arg                   simulate a quantum circuit given by file (detection by the file extension)
--simulate_file_hybrid arg            simulate a quantum circuit given by file (detection by the file extension) using the hybrid Schrodinger-Feynman simulator
--hybrid_mode arg                     mode used for hybrid Schrodinger-Feynman simulation (*amplitude*, dd)
--nthreads arg (=2)                   #threads used for hybrid simulation
--simulate_qft arg                    simulate Quantum Fourier Transform for given number of qubits
--simulate_ghz arg                    simulate state preparation of GHZ state for given number of qubits
--step_fidelity arg (=1)              target fidelity for each approximation run (>=1 = disable approximation)
--steps arg (=1)                      number of approximation steps
--simulate_grover arg                 simulate Grover's search for given number of qubits with random oracle
--simulate_grover_emulated arg        simulate Grover's search for given number of qubits with random oracle and emulation
--simulate_grover_oracle_emulated arg simulate Grover's search for given number of qubits with given oracle and emulation
--simulate_shor arg                   simulate Shor's algorithm factoring this number
--simulate_shor_coprime arg (=0)      coprime number to use with Shor's algorithm (zero randomly generates a coprime)
--simulate_shor_no_emulation          Force Shor simulator to do modular exponentiation instead of using emulation (you'll usually want emulation)
--simulate_fast_shor arg              simulate Shor's algorithm factoring this number with intermediate measurements
--simulate_fast_shor_coprime arg (=0) coprime number to use with Shor's algorithm (zero randomly generates a coprime)

The output is JSON-formatted as shown below (with hopefully intuitive naming).

$ cmake -DCMAKE_BUILD_TYPE=Release -S . -B build
$ cmake --build build --config Release --target ddsim_simple
$ ./build/ddsim_simple --simulate_ghz 4 --shots 1000 --ps --pm
{
  "measurement_results": {
    "0000": 484,
    "1111": 516
  },
  "statistics": {
    "applied_gates": 4,
    "approximation_runs": "0",
    "benchmark": "entanglement_4",
    "distinct_results": 2,
    "final_fidelity": "1.000000",
    "max_nodes": 9,
    "n_qubits": 4,
    "seed": "0",
    "shots": 1000,
    "simulation_time": 0.00013726699398830533,
    "single_shots": "1",
    "step_fidelity": "1.000000"
  }
}

Quickstart Guide

Execute the following lines to get the simulator running in no time:

$ git clone --recurse-submodules https://github.com/iic-jku/ddsim/
[...]

$ cd ddsim

ddsim/ $ cmake -S . -B build
-- Build files have been written to: /.../build

ddsim/ $ cmake --build build --config Release --target ddsim_simple
[...]
[100%] Built target ddsim_simple

ddsim/ $ build/ddsim_simple --help                            
JKQ DDSIM by https://iic.jku.at/eda/ -- Allowed options:
  -h [ --help ]                         produce help message
[...]

From here on you can start simulating quantum circuits or run the integrated algorithms.

Note that you have to have the Boost program_options library installed.

Executable Noise-aware Simulator

The tool also supports noise-aware quantum circuit simulation, based on a stochastic approach. It currently supports global decoherence and gate error noise effects. A detailed summary of the simulator is presented in [2]. Note that the simulator currently does not support simulating the integrated algorithms.

Building the simulator requires boost/program_options and Threads::Threads. It can be built by executing

$ cmake -DCMAKE_BUILD_TYPE=Release -S . -B build
$ cmake --build build --config Release --target ddsim_noise_aware

The simulator provides a help function which is called in the following way:

$ ./build/ddsim_noise_aware -h
JKQ DDSIM by https://iic.jku.at/eda/ -- Allowed options:
  -h [ --help ]                         produce help message
  --seed arg (=0)                       seed for random number generator (default zero is possibly directly used as seed!)
  --pm                                  print measurements
  --ps                                  print simulation stats (applied gates, sim. time, and maximal size of the DD)
  --verbose                             Causes some simulators to print additional information to STDERR
  --simulate_file arg                   simulate a quantum circuit given by file (detection by the file extension)
  --step_fidelity arg (=1)              target fidelity for each approximation run (>=1 = disable approximation)
  --steps arg (=1)                      number of approximation steps
  --noise_effects arg (=APD)            Noise effects (A (=amplitude damping),D (=depolarization),P (=phase flip)) in the form of a character string describing the noise effects
  --noise_prob arg (=0.001)             Probability for applying noise
  --confidence arg (=0.05)              Confidence in the error bound of the stochastic simulation
  --error_bound arg (=0.1)              Error bound of the stochastic simulation
  --stoch_runs arg (=0)                 Number of stochastic runs. When the value is 0 the value is calculated using the confidence, error_bound and number of tracked properties.
  --properties arg (=-3-1000)           Comma separated list of tracked properties. Note that -1 is the fidelity and "-" can be used to specify a range.

Process finished with exit code 0

An example run, with amplitude damping, phase flip, and depolarization error (each with a probability of 0.1% whenever a gate is applied) looks like this:

$ ./build/ddsim_noise_aware --ps --noise_effects APD --stoch_runs 10000 --noise_prob 0.001 --simulate_file adder4.qasm
{
  "statistics": {
    "applied_gates": 23,
    "approximation_runs": "0.000000",
    "benchmark": "stoch_APD_adder_n4",
    "final_fidelity": "0.937343",
    "max_nodes": 10,
    "mean_stoch_run_time": "0.015796",
    "n_qubits": 4,
    "parallel_instances": "28",
    "perfect_run_time": "0.000066",
    "seed": "0",
    "simulation_time": 5.911194324493408,
    "step_fidelity": "1.000000",
    "stoch_runs": 10000,
    "stoch_wall_time": "5.911118",
    "threads": 28
  }
}

Running Tests

The repository also includes some (rudimentary) unit tests (using GoogleTest), which aim to ensure the correct behavior of the tool. They can be built and executed in the following way:

$ cmake -DBUILD_DDSIM_TESTS=ON -DCMAKE_BUILD_TYPE=Release -S . -B build
$ cmake --build build/ --config Release
$ ./build/test/ddsim_test
[...]

Frequently Asked Questions

Why is target ddsim_simple unavailable when I try to build it?

To build the commandline interfaces such as ddsim_simple you require the Boost program_options library. If it is missing, you will see the following message in the CMake generation step

-- Did not find Boost! Commandline interface will not be an available target!

Under Ubuntu you can simply install libboost-program-options-dev.

Why does generation step of CMake fail?

If you see the following error message

$ cmake -S . -B <build target directory>
CMake Error at CMakeLists.txt:27 (message):
qfr was not found.  Please init/update submodules (git submodule update --init --recursive) and try again.

Please run git submodule update --init --recursive and try again.

Why do I get a linking error at the end of the build process?

If you are using gcc for building, and you get the error message

lto1: internal compiler error: Segmentation fault
Please submit a full bug report,
with preprocessed source if appropriate.
See <file:///usr/share/doc/gcc-9/README.Bugs> for instructions.
lto-wrapper: fatal error: /usr/bin/c++ returned 1 exit status
compilation terminated.
/usr/bin/ld: error: lto-wrapper failed
collect2: error: ld returned 1 exit status
make[2]: *** [test/CMakeFiles/ddsim_test.dir/build.make:166: test/ddsim_test] Error 1
make[1]: *** [CMakeFiles/Makefile2:464: test/CMakeFiles/ddsim_test.dir/all] Error 2

Configure the simulator again and add the parameter -DBINDINGS=ON

References

If you use our tool for your research, we will be thankful if you refer to it by citing the appropriate publication:

[1] A. Zulehner and R. Wille, “Advanced Simulation of Quantum Computations,” Transactions on CAD of Integrated Circuits and Systems (TCAD), vol. 38, no. 5, pp. 848–859, 2019

@article{zulehner2019advanced,
    title = {Advanced Simulation of Quantum Computations},
    author = {Zulehner, Alwin and Wille, Robert},
    journal = {Transactions on {CAD} of Integrated Circuits and Systems},
    volume = {38},
    number = {5},
    pages = {848--859},
    year = {2019},
    doi = {10.1109/TCAD.2018.2834427}
}

[2] S. Hillmich, I.L. Markov, and R. Wille, “Just Like the Real Thing: Fast Weak Simulation of Quantum Computation,” in Design Automation Conference (DAC), 2020

@inproceedings{DBLP:conf/dac/HillmichMW20,
  author    = {Stefan Hillmich and
               Igor L. Markov and
               Robert Wille},
  title     = {Just Like the Real Thing: {F}ast Weak Simulation of Quantum Computation},
  booktitle = {Design Automation Conference},
  publisher = {{IEEE}},
  year      = {2020}
}

[3] T. Grurl, R. Kueng, J. Fuß, and R. Wille, “Stochastic Quantum Circuit Simulation Using Decision Diagrams,” in Design, Automation and Test in Europe (DATE), 2021

@inproceedings{Grurl2020,
    author = {Grurl, Thomas and Kueng, Richard and Fu{\ss}, J{\"{u}}rgen and Wille, Robert},
    booktitle = {Design, Automation and Test in Europe (DATE)},
    title = {{Stochastic Quantum Circuit Simulation Using Decision Diagrams}},
    url = {http://arxiv.org/abs/2012.05620},
    year = {2021}
}

[4] S. Hillmich, R. Kueng, I. L. Markov, and R. Wille, "As Accurate as Needed, as Efficient as Possible: Approximations in DD-based Quantum Circuit Simulation," in Design, Automation and Test in Europe (DATE), 2021

@inproceedings{DBLP:conf/date/HillmichKMW21,
  author    = {Stefan Hillmich and
               Richard Kueng and
               Igor L. Markov and
               Robert Wille},
  title     = {As Accurate as Needed, as Efficient as Possible: Approximations in DD-based Quantum Circuit Simulation},
  booktitle = {Design, Automation and Test in Europe},
  year      = {2021}
}

[5] L. Burgholzer, H. Bauer, and R. Wille, "Hybrid Schrödinger-Feynman Simulation of Quantum Circuits With Decision Diagrams," arXiv:2105.07045, 2021

@misc{burgholzer2021hybrid,
      author={Lukas Burgholzer and
               Hartwig Bauer and
               Robert Wille},
      title={Hybrid Schrödinger-Feynman Simulation of Quantum Circuits With Decision Diagrams},
      year={2021},
      eprint={2105.07045},
      archivePrefix={arXiv},
      primaryClass={quant-ph}
}