Package: qulacs
QulacsQulacs 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 theMIT license.Quick Install for Pythonpip install qulacsIf 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.gitIf you have NVIDIA GPU and CUDA is installed, GPU-version can be installed with the following command:pip install qulacs-gpuFeaturesNoteQulacs-Osaka/qulacs-osaka was integrated into the qulacs/qulacs. For more details, please refer toInformationsection.Fast quantum circuit simulation with parallelized C/C++ backendNoisy quantum gate for simulation of NISQ devicesParametric quantum gates for variational methodsCircuit compression for fast simulationGPU support for fast simulationMany utility functions for researchPerformanceThe time for simulating random quantum circuits is compared with several quantum circuit simulators in November 2020.Seethe benchmark repositoryandSection VI and VII of our paperfor 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 benchmarkMulti-thread benchmarkGPU benchmarkInstall Python library from sourceTo 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.RequirementsC++ compiler (gcc or VisualStudio)gcc/g++ >= 7.0.0 (checked in Linux, MacOS, cygwin, MinGW, and WSL)Microsoft VisualStudio C++ 2015 or laterBoost>= 1.71.0 (Minimum version tested in CI)Python >= 3.7CMake >= 3.0git(option) CUDA >= 8.0(option) AVX2 supportIf your system supports AVX2 instructions, SIMD optimization is automatically enabled.
If you want to enable GPU simulator, install qulacs throughqulacs-gpupackage or build from source.
Note thatqulacs-gpuincludes CPU simulator. You don't need to install both.Qulacs is tested on the following systems.Ubuntu 20.04macOS Big Sur 11Windows Server 2019If you encounter some troubles, seetroubleshooting.How to installInstall 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 variableOMP_NUM_THREADSorQULACS_NUM_THREADS.
WhileOMP_NUM_THREADSaffects the parallelization of other libraries,QULACS_NUM_THREADScontrols 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 qulacsUse Qulacs as C++ libraryBuild with GCCStatic libraries of Qulacs can be built with the following commands:git clone https://github.com/qulacs/qulacs.git
cd qulacs
./script/build_gcc.shTo build shared libraries, executemake sharedat./qulacs/buildfolder.
When you want to build with GPU, usebuild_gcc_with_gpu.shinstead ofbuild_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-fopenmpIf you want to run your codes with GPU, includecppsim/state_gpu.hppand useQuantumStateGpuinstead ofQuantumStateand 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 -fopenmpBuild with MSVCStatic libraries of Qulacs can be built with the following command:git clone https://github.com/qulacs/qulacs.git
cd qulacs
script/build_msvc_2017.batWhen you want to build with GPU, usebuild_msvc_2017_with_gpu.bat.
If you use MSVC with other versions, usebuild_msvc_2015.bator edit the generator name inbuild_msvc_2017.bat.Your C++ codes can be built with Qulacs with the following process:Create an empty project.Select "x64" as an active solution platform.Right Click your project name in Solution Explorer, and select "Properties".At "VC++ Directories" section, add the full path to./qulacs/includeto "Include Directories"At "VC++ Directories" section, add the full path to./qulacs/libto "Library Directories"At "C/C++ -> Code Generation" section, change "Runtime library" to "Multi-threaded (/MT)".At "Linker -> Input" section, addvqcsim_static.lib;cppsim_static.lib;csim_static.lib;to "Additional Dependencies".Tutorial and API documentsSee the following documents for tutorials.Python TutorialC++ TutorialManualExamplesPython sample codefromqulacsimportObservable,QuantumCircuit,QuantumStatefromqulacs.gateimportY,CNOT,mergestate=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 replaceQuantumStatein the above codes withQuantumStateGpu.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>intmain(){QuantumStatestate(3);state.set_Haar_random_state();QuantumCircuitcircuit(3);circuit.add_X_gate(0);automerged_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);Observableobservable(3);observable.add_operator(2.0,"X 2 Y 1 Z 0");observable.add_operator(-3.0,"Z 2");autovalue=observable.get_expectation_value(&state);std::cout<<value<<std::endl;return0;}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_staticIf you want to run it on GPU, includecppsim/state_gpu.hppand replaceQuantumStatewithQuantumStateGpu.How to citePlease cite this arXiv paper:Qulacs: a fast and versatile quantum circuit simulator for research purposeInformationExperimental new features of Qulacs that have been developed in the Osaka University repositoryQulacs-Osaka/qulacs-osakawill be integrated into the originalQulacs. The following new features will be added!!!Integration dateScheduled around August 2022.New featuresThe main new features are as followsProviding type hint files for PythonConfigure 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 informationMakes 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 ParametricQuantumCircuitIt is faster than calculating gradients one by one.Gradient CalculatorScope of impactThe 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 bystd::complex.Add dependency librariesThis integration adds boost as a dependency library.
There will be some changes in the installation procedure.