Qulacs-Osaka

Qulacs-Osaka is a python/C++ library for fast simulation of large, noisy, or parametric quantum circuits. This project is (implicitly) forked from Qulacs and developed at Osaka University and NTT.

Qulacs-Osaka is licensed under the MIT license.

Relation to Qulacs

The commits in Qulacs are merged into Qulacs-Osaka up to the pull request corresponding to the commit 987474b31a6e60eba116d2e40ab538dcf8086038 (link to the corresponding commit in Qulacs and in Qulacs-Osaka). After that commit, this project is developed independently from Qulacs and has many new features that have not been available in Qulacs.

Note Qulacs-Osaka/qulacs-osaka will be integrated into the qulacs/qulacs. For more details, please refer to Information section.

Features

• Fast quantum circuit simulation with parallelized C/C++ backend
• Noisy quantum gate for simulation of NISQ devices
• Parametric quantum gates for variational methods
• Circuit compression for fast simulation
• GPU support for fast simulation
• Many utility functions for research

Performance

• Compared following libraries on March, 2020

Package	Version
Qulacs GPU	0.1.9
Cirq	0.6.0
Qiskit Aer	0.3.4
ProjectQ	0.4.2
qHiPSTER	latest master branch
Python interface of QuEST (PyQuest-cffi)	3.0.0
qsim	latest master branch

Test environment:

• Azure NC6s_v3 (6vcpu / Mem112GiB)
  • Intel(R) Xeon(R) CPU E5-2690 v4 @ 2.60GHz
  • Tesla V100 PCIE (driver 440.33.01)

What is Benchmarked

For each qubit number N:

• Apply simultaneous random single-qubit Pauli-X rotation

and then repeat:

• Apply CNOT(i,(i+1)%N) for all i in [0..N-1]
• Apply simultaneous random single-qubit Pauli-X rotation

for N times.

Note

• Execution time include time for creating quantum circuit
• Benchmark was done with float64 precision (qsim was done with float32)

Single thread benchmark

Multi thread / GPU benchmark

This benchmark was done with majour quantum circuit simulators with python interface.
Yao is quantum circuit simulator using Julia that is as fast as Qulacs.
Benchmark inculde Yao can be found here.

Requirements

• C++ compiler (gcc or VisualStudio)
  • gcc/g++ >= 7.0.0 (checked in Linux, MacOS, cygwin, MinGW, and WSL)
  • Microsoft VisualStudio C++ 2015 or later
• Boost >= 1.71.0 (Minimum version tested in CI)
• Python >= 3.7
• CMake >= 3.0
• git
• (option) CUDA >= 8.0
• (option) AVX2 support

If your system supports AVX2 instructions, SIMD optimization is automatically enabled. If you want to enable GPU simulator, install qulacs through qulacs-gpu package or build from source. Note that qulacs-gpu includes CPU simulator. You don't need to install both.

Qulacs is tested on the following systems.

• Ubuntu 20.04
• macOS Big Sur 11
• Windows Server 2019

Install via pip

You can install the Python package via pip.

pip install qulacs-osaka

Install from Source

If you encounter some troubles, see troubleshooting.

Install Python library from source

Install (Multi-thread without GPU)

python setup.py install

Install (Multi-thread with GPU. CUDA is required)

USE_GPU=Yes python setup.py install

Uninstall

pip uninstall qulacs

Build C++ library

GCC

git clone https://github.com/Qulacs-Osaka/qulacs-osaka.git
cd qulacs-osaka
./script/build_gcc.sh

When you want to build with GPU, use build_gcc_with_gpu.sh.

MSVC

git clone https://github.com/Qulacs-Osaka/qulacs-osaka.git
cd qulacs-osaka
./script/build_msvc_2017.bat

When you want to build with GPU, use build_msvc_2017_with_gpu.bat. If you use MSVC2015, replace "2017" in file names to "2015".

Tutorial and API document

See the following documents for more detail.

• Python Tutorial
• C++ Tutorial
• Examples
• API document

Sample code

Python

from qulacs import Observable, QuantumCircuit, QuantumState
from qulacs.gate import Y,CNOT,merge

state = QuantumState(3)
state.set_Haar_random_state()

circuit = QuantumCircuit(3)
circuit.add_X_gate(0)
merged_gate = merge(CNOT(0,1),Y(1))
circuit.add_gate(merged_gate)
circuit.add_RX_gate(1,0.5)
circuit.update_quantum_state(state)

observable = Observable(3)
observable.add_operator(2.0, "X 2 Y 1 Z 0")
observable.add_operator(-3.0, "Z 2")
value = observable.get_expectation_value(state)
print(value)

If you want to run it on GPU, install GPU-enabled qulacs and replace QuantumState in the above codes to QuantumStateGpu.

C++

#include <iostream>
#include <cppsim/state.hpp>
#include <cppsim/circuit.hpp>
#include <cppsim/observable.hpp>
#include <cppsim/gate_factory.hpp>
#include <cppsim/gate_merge.hpp>

int main(){
    QuantumState state(3);
    state.set_Haar_random_state();

    QuantumCircuit circuit(3);
    circuit.add_X_gate(0);
    auto merged_gate = gate::merge(gate::CNOT(0,1),gate::Y(1));
    circuit.add_gate(merged_gate);
    circuit.add_RX_gate(1,0.5);
    circuit.update_quantum_state(&state);

    Observable observable(3);
    observable.add_operator(2.0, "X 2 Y 1 Z 0");
    observable.add_operator(-3.0, "Z 2");
    auto value = observable.get_expectation_value(&state);
    std::cout << value << std::endl;
    return 0;
}

Build command for g++:

g++ -O2 -I ./include -L ./lib main.cpp -fopenmp -lcppsim_static -lcsim_static

If you want to run it on GPU, include cppsim/state_gpu.hpp and replace QuantumState with QuantumStateGpu.

How to cite

Please cite this arXiv paper: Qulacs: a fast and versatile quantum circuit simulator for research purpose

Information

Experimental new features of Qulacs that have been developed in the Osaka University repository Qulacs-Osaka/qulacs-osaka will be integrated into the original Qulacs. The following new features will be added!!!

Integration date

Scheduled around August 2022.

New features

The main new features are as follows

• Providing type hint files for Python
  • Configure tools such as mypy to take full advantage of type hint information.
  • mypy can detect the use of incorrect argument types in the qulacs API.
• Sending exceptions with detailed information
  • Makes it easier to understand the cause of the error.
  • (For Jupyter Notebook users) kernel is less likely to crash if incorrect input is given.
• Added backprop (gradient calculation by error back propagation method) to ParametricQuantumCircuit
  • It is faster than calculating gradients one by one.
• Gradient Calculator

Scope of impact

The existing functionality has not been changed, so the existing code using Qulacs will continue to work as is. However, since the implementation language of csim has been changed from C to C++, changes may be necessary if you have been using direct calls to csim. Due to the C++ change, all complex numbers are now handled by std::complex.

Add dependency libraries

This integration adds boost as a dependency library. There will be some changes in the installation procedure.