Skip to main content

Quantum circuit simulator for research

Project description

Qulacs

Ubuntu CI macOS CI Windows CI Wheel build Downloads

Qulacs is a Python/C++ library for fast simulation of large, noisy, or parametric quantum circuits. Qulacs is developed at QunaSys, Osaka University, NTT, and Fujitsu.

Qulacs is licensed under the MIT license.

Quick Install for Python

pip install qulacs

If your CPU is older than Intel Haswell architecture, the binary installed with the above command does not work. In this case, please install Qulacs with the following command. Even if your CPU is newer than Haswell, Qulacs installed with the below command shows better performance but takes a longer time. See "Install Python library from source" section for detail.

pip install git+https://github.com/qulacs/qulacs.git

If you have NVIDIA GPU and CUDA is installed, GPU-version can be installed with the following command:

pip install qulacs-gpu

Features

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

  • 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

The time for simulating random quantum circuits is compared with several quantum circuit simulators in November 2020.

See the benchmark repository and Section VI and VII of our paper for the detail of this benchmark.

Note that the plots with names ending with "opt" and "heavy opt" perform circuit optimization for fast simulation, where the time for optimization is included in the execution time.

Single-thread benchmark

single thread benchmark

Multi-thread benchmark

multi thread benchmark

GPU benchmark

GPU benchmark

Install Python library from source

To install Qulacs optimized for your system, we recommend the following install procedure for faster simulation of quantum circuits, while this requires a compiler and takes time for installation. In addition, you can enable or disable optimization features such as SIMD optimization, OpenMP parallelization, and GPU support.

A binary that is installed via pip command is optimized for Haswell architecture. Thus, Qulacs installed via pip command does not work with a CPU older than Haswell. If your CPU is newer than Haswell, Qualcs built from source shows the better performance.

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.9
  • CMake >= 3.5
  • 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

If you encounter some troubles, see troubleshooting.

How to install

Install with default options (Multi-thread without GPU):

pip install .

If AVX2 instructions are not supported, SIMD optimization is automatically disabled.

Install with GPU support (CUDA is required):

USE_GPU=Yes pip install .

Install single-thread Qulacs:

USE_OMP=No pip install .

The number of threads used in Qulacs installed with default options can be controlled via the environment variable OMP_NUM_THREADS or QULACS_NUM_THREADS. While OMP_NUM_THREADS affects the parallelization of other libraries, QULACS_NUM_THREADS controls only the parallelization of QULACS. Or, if you want to force only Qulacs to use a single thread, You can install single-thread Qulacs with the above command.

For development purpose, optional dependencies can be installed as follows.

# Install development tools
pip install .[dev]
# Install dependencies for document generation
pip install .[doc]

Uninstall Qulacs:

pip uninstall qulacs

Use Qulacs as C++ library

Build with GCC

Static libraries of Qulacs can be built with the following commands:

git clone https://github.com/qulacs/qulacs.git
cd qulacs
./script/build_gcc.sh

To build shared libraries, execute make shared at ./qulacs/build folder. When you want to build with GPU, use build_gcc_with_gpu.sh instead of build_gcc.sh.

Then, you can build your codes with the following gcc command:

g++ -O2 -I ./<qulacs_path>/include -L ./<qulacs_path>/lib <your_code>.cpp -lvqcsim_static -lcppsim_static -lcsim_static -fopenmp

If you want to run your codes with GPU, include cppsim/state_gpu.hpp and use QuantumStateGpu instead of QuantumState and build with the following command:

nvcc -O2 -I ./<qulacs_path>/include -L ./<qulacs_path>/lib <your_code>.cu -lvqcsim_static -lcppsim_static -lcsim_static -lgpusim_static -D _USE_GPU -lcublas -Xcompiler -fopenmp

Build with MSVC

Static libraries of Qulacs can be built with the following command:

git clone https://github.com/qulacs/qulacs.git
cd qulacs
script/build_msvc_2017.bat

When you want to build with GPU, use build_msvc_2017_with_gpu.bat. If you use MSVC with other versions, use build_msvc_2015.bat or edit the generator name in build_msvc_2017.bat.

Your C++ codes can be built with Qulacs with the following process:

  1. Create an empty project.
  2. Select "x64" as an active solution platform.
  3. Right Click your project name in Solution Explorer, and select "Properties".
  4. At "VC++ Directories" section, add the full path to ./qulacs/include to "Include Directories"
  5. At "VC++ Directories" section, add the full path to ./qulacs/lib to "Library Directories"
  6. At "C/C++ -> Code Generation" section, change "Runtime library" to "Multi-threaded (/MT)".
  7. At "Linker -> Input" section, add vqcsim_static.lib;cppsim_static.lib;csim_static.lib; to "Additional Dependencies".

Tutorial and API documents

See the following documents for tutorials.

Python sample code

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 with QuantumStateGpu.

C++ sample code

#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;
}

If you place the above codes in the root directory of this repository(e.g., qulacs/main.cpp), you can build your codes with the following command:

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

qulacs-0.6.12.tar.gz (804.6 kB view details)

Uploaded Source

Built Distributions

qulacs-0.6.12-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (969.7 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

qulacs-0.6.12-cp313-cp313-macosx_11_0_arm64.whl (680.9 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

qulacs-0.6.12-cp313-cp313-macosx_10_13_x86_64.whl (780.7 kB view details)

Uploaded CPython 3.13macOS 10.13+ x86-64

qulacs-0.6.12-cp312-cp312-win_amd64.whl (844.8 kB view details)

Uploaded CPython 3.12Windows x86-64

qulacs-0.6.12-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (969.6 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

qulacs-0.6.12-cp312-cp312-macosx_11_0_arm64.whl (681.0 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

qulacs-0.6.12-cp312-cp312-macosx_10_13_x86_64.whl (780.5 kB view details)

Uploaded CPython 3.12macOS 10.13+ x86-64

qulacs-0.6.12-cp311-cp311-win_amd64.whl (845.2 kB view details)

Uploaded CPython 3.11Windows x86-64

qulacs-0.6.12-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (969.6 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

qulacs-0.6.12-cp311-cp311-macosx_11_0_arm64.whl (679.5 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

qulacs-0.6.12-cp311-cp311-macosx_10_9_x86_64.whl (772.0 kB view details)

Uploaded CPython 3.11macOS 10.9+ x86-64

qulacs-0.6.12-cp310-cp310-win_amd64.whl (844.0 kB view details)

Uploaded CPython 3.10Windows x86-64

qulacs-0.6.12-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (968.4 kB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

qulacs-0.6.12-cp310-cp310-macosx_11_0_arm64.whl (677.9 kB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

qulacs-0.6.12-cp310-cp310-macosx_10_9_x86_64.whl (770.5 kB view details)

Uploaded CPython 3.10macOS 10.9+ x86-64

qulacs-0.6.12-cp39-cp39-win_amd64.whl (844.0 kB view details)

Uploaded CPython 3.9Windows x86-64

qulacs-0.6.12-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (968.7 kB view details)

Uploaded CPython 3.9manylinux: glibc 2.17+ x86-64

qulacs-0.6.12-cp39-cp39-macosx_11_0_arm64.whl (677.9 kB view details)

Uploaded CPython 3.9macOS 11.0+ ARM64

qulacs-0.6.12-cp39-cp39-macosx_10_9_x86_64.whl (770.6 kB view details)

Uploaded CPython 3.9macOS 10.9+ x86-64

File details

Details for the file qulacs-0.6.12.tar.gz.

File metadata

  • Download URL: qulacs-0.6.12.tar.gz
  • Upload date:
  • Size: 804.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.10.8

File hashes

Hashes for qulacs-0.6.12.tar.gz
Algorithm Hash digest
SHA256 ab62ec4244bc8fdf243b66cffec02e31ba4ec183f69aab6946d989fea4f89559
MD5 4a6e9080b56a90ff5f8cf7bff8e99b36
BLAKE2b-256 1c965dfdfc42281b4c110b1156d54f87df87a44f5d8625759e8d38a95a66a457

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for qulacs-0.6.12-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 19937ebb7b3c488da19b6e5e35b3a1dacec35fda1866af60d1a840d858727349
MD5 d00c5eaea1212b135019e3ebee57e0e2
BLAKE2b-256 05a02cfb4004efaf4b38b3d711fff739bca1615c32a9a85493ec85cf30e7038b

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for qulacs-0.6.12-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 831443d670a5aa715396a51b8904bf6365ad09b37e4f0f230fcda60fe184e891
MD5 9be70a78476295db5f8935084dd855a2
BLAKE2b-256 7290bd27f4c66e9d567f4c06fe3296445b70aaf4129c2e3bd110c04a44db42cb

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp313-cp313-macosx_10_13_x86_64.whl.

File metadata

File hashes

Hashes for qulacs-0.6.12-cp313-cp313-macosx_10_13_x86_64.whl
Algorithm Hash digest
SHA256 d31d7af9df9e4d57fe539f187069364df77e63e536a5a3f53a214b2541a0f3ef
MD5 f2ea323a4fcd3f833c440e31f2a888af
BLAKE2b-256 9161b068769cd042cb6f67700fdd24fe13036a381c4e9f2c8c7b80aa37498b1b

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: qulacs-0.6.12-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 844.8 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.10

File hashes

Hashes for qulacs-0.6.12-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 9c3ed2e32962c0dab62aac8a9505a08f23ff97316807e8c72600295e456aaf6a
MD5 51b989f692a568b3fdd206e674111cb9
BLAKE2b-256 15680c95587e1c70df95a2ee17744ecfa7c404af72f5010ac4053ca60ec3bed3

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for qulacs-0.6.12-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 2de6a3d97f0eb54f764ddf69a08874515752b750dc9bdfc56d165ac1b405b7ca
MD5 e1455a654d77149f0797bbe0c36019b4
BLAKE2b-256 b2cbb69c2f984e519cba36dcc2f4f22fe2e8c31252395b63332f9b6f6d22595b

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for qulacs-0.6.12-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 be1eeca7ff073fc0ad93160ee54b0a9228b6c8b0eb87e538ddb9894981eaaf76
MD5 a2506952eafc148d049753ad13e9f488
BLAKE2b-256 93a4781900269a04f90c83dae853bd4edf0207f7eda28a40dab0877b43c2dabe

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp312-cp312-macosx_10_13_x86_64.whl.

File metadata

File hashes

Hashes for qulacs-0.6.12-cp312-cp312-macosx_10_13_x86_64.whl
Algorithm Hash digest
SHA256 d7365f8886071f57183ba626c129b794e01f40e08e3e3c05f7979a3011444d16
MD5 4afee4b54e2a8b27c59da860b120062b
BLAKE2b-256 91552ddc10aa44dcbd96f389f5e626283376c946f365e7a93290176a14474482

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: qulacs-0.6.12-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 845.2 kB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.11.9

File hashes

Hashes for qulacs-0.6.12-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 68eac43b44ba866d81d15e0f31e16d6a2f7c8b7d9dca446e765a76891edceb41
MD5 974882edbdfc1674c6c5c155513f075c
BLAKE2b-256 60d20047f2f43fa4632f9aba2b9b5a6003fa34139d197911663e5b04e3d4b9dd

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for qulacs-0.6.12-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 792472cf55bdbb3524da68f299f99601643e6ec09b141b99533b114484e8e902
MD5 282caae5ba746c7d1dfff5f91ab7081b
BLAKE2b-256 8f2d9a0033ac4f62ca9564ec2a94a163b2ee3da16ae5e028b0d29296ccda8f0e

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for qulacs-0.6.12-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 41002d6ac2bdfae76e694afeb74d505df1f1afa8240788ebbdc988a2b0d54a3f
MD5 aa03de39212463ad33045ac33fa41d22
BLAKE2b-256 238d45756fe15035fbe0337c40df26dc8896ec9678e57070bd8e962c6039837a

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp311-cp311-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for qulacs-0.6.12-cp311-cp311-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 485719b553cd47712f73bfb7aa12709249564490aea6dbd0655287913214615a
MD5 aab501e269bcec995a82cbdabefc7c77
BLAKE2b-256 47f348a44c2b3ee87580e0d2a3b2e2aa01a841b179484ef4f19b6f536800666b

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: qulacs-0.6.12-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 844.0 kB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.10.11

File hashes

Hashes for qulacs-0.6.12-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 10fab56e6c8a4e84ea862af8e1bcf29931944e55624a38378d72294b3d0e33d9
MD5 f079f2e57f56db62a3e875204e3d0851
BLAKE2b-256 ed2f11a90946360e2074e9920d2de0a725f83b00b945d30f11f8f773a6027123

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for qulacs-0.6.12-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 3accffcbfb97521aa564c8aebd9cfd9ae02e96e95755c1cf85254693daf21d92
MD5 521df8be333a452d2df54f71dc967d6a
BLAKE2b-256 73bc0ba4989b2f03565ccffaceae96b9ba74de12c76badd8c73803fdcb7f9173

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for qulacs-0.6.12-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 bbd37b2b8fa387797f8f422a2eec90a3cb97005f6fd217edb09c792bfbd50d9d
MD5 58f9a6c3c8a186e421f10ab415925c94
BLAKE2b-256 51a2dc0c55582cbcd7023c782b905aa4bcff678c79d611c4d82c2a8460443653

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp310-cp310-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for qulacs-0.6.12-cp310-cp310-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 14ad56d23d5c619063bf507a5edc34970b94a3c6175da1a5c5c83d917d02b3bb
MD5 b9c8fa18a4ed7f2110093d51ab0bd34e
BLAKE2b-256 39009e92d99efc22d9d056f00fc3c628506ad8eaf8710e16e65e7bb22ebe319a

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp39-cp39-win_amd64.whl.

File metadata

  • Download URL: qulacs-0.6.12-cp39-cp39-win_amd64.whl
  • Upload date:
  • Size: 844.0 kB
  • Tags: CPython 3.9, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.9.13

File hashes

Hashes for qulacs-0.6.12-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 f7c3d2e2dc18f138c2914637d1ad6a394f878b10b4c949fbde1ac16a2ea4bbf8
MD5 48ea86eb5c610fcc153d5e4fbfaec3c6
BLAKE2b-256 7373a0529e085460659c0d5933d375f56b7f7d0da7cf77e8742f1af227855e30

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for qulacs-0.6.12-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ddb846813af11c9d743ce55e28a4ee2b486264d408409fe42744ce47e4aab2b8
MD5 97403c0034bb80aded570ff04988449b
BLAKE2b-256 1a43076d4cb8cec5fa3dd034a922a3a7836913d975a4c306819328f5a832dbc1

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp39-cp39-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for qulacs-0.6.12-cp39-cp39-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c604b92f10bf2c7b11c81ca79ff054c4986bc3160c3d8179867c021442ab55e6
MD5 673144b189fedef8b52f62828ba37e22
BLAKE2b-256 53e78e75d2f2b343c0783d607e6064e9d5133c2fb483ab13e25af7858ead5b9a

See more details on using hashes here.

File details

Details for the file qulacs-0.6.12-cp39-cp39-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for qulacs-0.6.12-cp39-cp39-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 1a53b9b57b2f21bf32fe98e0768acc3a56930a0c2e59f43a4516f2158f9c5884
MD5 37bf5db49e6de60863fa252c36cc28ff
BLAKE2b-256 b24afe9e2349a1d99e3baaf6fee87b045c091372e1867240b32ef586a1155b0c

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page