9ccd34792e
|
||
|---|---|---|
| .github | ||
| benchmarks | ||
| cmake | ||
| docs | ||
| examples | ||
| include | ||
| interface | ||
| notebooks | ||
| pybind11 | ||
| src | ||
| tutorials | ||
| unit_test | ||
| util | ||
| .gitignore | ||
| CMakeLists.txt | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| Dockerfile | ||
| Jenkinsfile | ||
| LICENSE.md | ||
| README.md | ||
| docker_build | ||
README.md
/badge.svg){kind=icon}
Intel Quantum Simulator
Intel Quantum Simulator (Intel-QS), also known as qHiPSTER (The Quantum High Performance Software Testing Environment), is a simulator of quantum circuits optimized to take maximum advantage of multi-core and multi-nodes architectures. It is based on a complete representation of the qubit state, but avoids the explicit representation of gates and other quantum operations in terms of matrices. Intel-QS uses MPI (message-passing-interface) protocols to handle the communication between distributed resources that are used to store and manipulate the quantum state.
Build instructions
Intel-QS builds as a shared library which, once linked to the application program, allows to take advantage of the high-performance implementation of circuit simulations. The library can be built on a variety of different systems, from laptop to HPC server systems.
The directory structure of the repository can be found in intel-qs/docs/directory_structure.md.
The library object is: /builb/lib/libiqs.so
Requirements
The following packages are required by the installation:
- CMake tools version 3.12+
- MPICH3 library for enabling the distributed communication
- optional: MKL for distributed random number generation
- optional: PyBind11 (installed via conda, not pip) required by the Python bunding of Intel-QS
The first step is cloning the repository:
git clone https://github.com/iqusoft/intel-qs.git
cd intel-qs
Use Intel Parallel Studio compilers to build Intel-QS
If you wish to build Intel-QS using the latest Intel compiler technologies, then you need to configure your environment properly according to that tool's documentation. Assuming that you have installed Intel Parallel Studio in the standard location on your system, you should invoke the following scripts through the source command on Linux.
source /opt/intel/bin/compilervars.sh -arch intel64 -platform linux
source /opt/intel/compiler_and_libraries/linux/mpi/intel64/bin/mpivars.sh
Now, use CMake to generate the appropriate makefiles to use the Intel Parallel Studio compilers.
The installation follows the out-of-source building and requires the creation of the directory build.
This directory is used to collect all the files generated during the installation process.
mkdir build
cd build
CXX=mpiicpc cmake -DIqsMPI=ON -DIqsUtest=ON ..
make
By default, MKL is required when Intel compilers are used.
To re-build Intel-QS with different settings or options, we recommend to delete all content of the
build directory and then restart from the CMake command.
Use standard GNU tools to build Intel-QS
If you wish to build Intel-QS using only standard GNU compilers type:
mkdir build
cd build
CXX=g++ cmake -DIqsMPI=OFF ..
make
By default, MKL is not required when GNU compilers are used.
Optionally, MPI can be included by setting the option -DIqsMPI=ON instead. You must ensure
that you have at least version 3.1 of MPICH installed for the build to succeed.
https://www.mpich.org
Enable MPI protocol for distributed memory use
The above installation enables MPI functionalities to deploy Intel-QS on High Performance
Computing and Cloud Computing infrastructures. There is the option of disabling MPI:
simply set the CMake option selection to -DIqsMPI=OFF
(or just omit the option selection since MPI is disabled by default in the CMake build).
Enable Latest Vector Capability
To compile with the latest instruction set supported by your architecture, there is the option -DIqsNative.
Compiled with -DIqsNative=ON, the latest vector instructions available on your machine, e.g. AVX2, AVX512, are used.
By default, -DIqsNative=OFF.
If the machine you compile and the machine you run have different vector capabilities, turning on IqsNative=ON might cause run-time problems.
Underneath, this option uses -xhost
with Intel compilers and -march=native with GNU compilers.
Enable Python binding (only available without MPI)
By default, whenever MPI is disabled, the building process includes the Python binding for Intel-QS. The binding code uses the Pybind11 library which needs to be installed via 'conda' (and not simply with pip) to include the relevant information in CMake. See this page for more info on this issue.
To disable the Python wrap, even without MPI, set the CMake option selection to
-DIqsPython=OFF.
Unit test
By default, with MPI either enabled or disabled, the building process includes a suite
of unit tests written in the googletest framework.
Following the recommended integration, the CMake building process automatically downloads
the up-to-date repository of gtest and installs it in the build path.
To disable the unit tests, set the CMake option selection to -DIqsUtest=OFF.
To run the unit tests, from /build launch the executable ./bin/utest.
Recommended build for HPC.
The recommended building process requires Intel Math Kernel Library and the MPI-ICPC compiler.
When the program is run in hybrid configuration (OpenMP+MPI), we recommend to manage
the OpenMP affinity directly. Affinity settings can be set using the syntax:
KMP_AFFINITY=compact,1,0,granularity=fine.
A quick look at the options can be found at
this page.
Docker: build image and run/execute container
Dockerfile includes the instructions to build the docker image of an Ubuntu machine
with Intel-QS already installed. The image can be 'run' to create a container.
The container can be 'executed' to login into the machine.
For this, Three steps need to be followed to prepare containerirzed intelqs simulator.
- Create container
- Configure SSH tunneling
- Launch Jupyter notebook
Create container
Important: If user is not root,add sudo before each bash and docker command.
First command in below will build docker image for Intelqs named qhipster.One can choose other name too.
(if choosen name is other than qhipster, replace that name in all other commands as well).
Second command will create container while mapping 8080 port to the localhost.
Third command will enable conda env,execute cmake and make command, it will launch jupyter notebook
in the terminal. Copy and save the printed token from the terminal.
Example of a given token : http://127.0.0.1:8080/?token=6ee42173ee71353c1f1b33f8feb33132aed15f2a07960bc8.
Last command is optional,this can be executed to go inside container.
docker build -t qhipster .
docker run -d -t -p 8080:8080 qhipster
docker exec -i $(docker ps|grep -i qhipster|cut -d ' ' -f1) /bin/bash -c ". ~/.bashrc && . /opt/intel/mkl/bin/mklvars.sh intel64 ilp64 && . /opt/intel/bin/compilervars.sh -arch intel64 -platform linux && mkdir build && cd build && CXX=g++ cmake -DIqsMPI=OFF -DIqsUtest=ON -DIqsPython=ON .. && make && cd .. && jupyter notebook --ip 0.0.0.0 --port 8080 --no-browser --allow-root"
docker exec -it $(docker ps|grep -i qhipster|cut -d ' ' -f1) /bin/bash
If Docker is used on a Windows host machine, the last line should be substituted by:
winpty docker exec -it <container_id> //bin/bash.
Configure SSH tunneling
In local laptop, open Ubuntu emulator. This to allow the use of SSH protocol for port forwarding. For example if you use MobaxTerm tool,launch a session and type following command in the mobxterm shell:
ssh -L 8080:localhost:8080 user@domain.com
Launch Jupyter notebook
Now, paste the copied token(which we copied from 'Create Container' section) in your preffered web browser (most importantly, please clear your browser cache before pasting the token). Once you are seeing all folders and files in browser, follow below section to begin.
Getting started with Intel-QS
The simplest way of familiarize with the Intel Quantum Simulator is by exploring
the tutorials provided in the directory tutorials/.
In particular, the code tutorials/get_started_with_IQS.cpp provides step-by-step
description of the main commands to:
define a qubit register object, perform quantum gates, measure one or multiple qubits.
If the Python bindings were enabled, the same learning can be performed using the iPython
notebook tutorials/get_started_with_IQS.ipynb.
How to contribute
Thanks for your interest in the project! We welcome pull requests from developers of all skill levels. If you would like to contribute to Intel-QS, please take a look to our contributing policy and also to the code of conduct. For any bug, we use GitHub issues GitHub issues. Please submit your request there.
How to contact us
If you have a question or want to discuss something, feel free to send an email to Justin Hogaboam, Gian Giacomo Guerreschi, or to Fabio Baruffa.
How to cite
When using Intel Quantum Simulator for research projects, please cite:
Gian Giacomo Guerreschi, Justin Hogaboam, Fabio Baruffa, Nicolas P. D. Sawaya Intel Quantum Simulator: A cloud-ready high-performance simulator of quantum circuits arXiv:2001.10554
The original implementation is described here:
Mikhail Smelyanskiy, Nicolas P. D. Sawaya, Alán Aspuru-Guzik qHiPSTER: The Quantum High Performance Software Testing Environment arXiv:1601.07195