mirror of https://github.com/intel/intel-qs.git
233 lines
10 KiB
Markdown
233 lines
10 KiB
Markdown
|
|
/badge.svg)
|
|
[](https://github.com/iqusoft/intel-qs/blob/development/Dockerfile)
|
|
[](https://arxiv.org/abs/2001.10554)
|
|
[](https://arxiv.org/abs/1601.07195)
|
|
|
|
# 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](/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:
|
|
```bash
|
|
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.
|
|
```bash
|
|
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.
|
|
```bash
|
|
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:
|
|
```bash
|
|
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`](https://software.intel.com/en-us/cpp-compiler-developer-guide-and-reference-xhost-qxhost)
|
|
with Intel compilers and [`-march=native`](https://gcc.gnu.org/onlinedocs/gcc/x86-Options.html) 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](https://github.com/pybind/pybind11/issues/1628) 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](https://github.com/google/googletest).
|
|
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](https://software.intel.com/en-us/mkl)
|
|
and the [MPI-ICPC compiler](https://software.intel.com/en-us/node/528770).
|
|
|
|
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](https://www.nas.nasa.gov/hecc/support/kb/using-intel-openmp-thread-affinity-for-pinning_285.html).
|
|
|
|
|
|
----
|
|
## 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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](CONTRIBUTING.md) and also to the
|
|
[code of conduct](CODE_OF_CONDUCT.md).
|
|
For any bug, we use GitHub issues [GitHub issues](https://github.com/iqusoft/intel-qs/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](justin.w.hogaboam@intel.com),
|
|
[Gian Giacomo Guerreschi](gian.giacomo.guerreschi@intel.com), or to
|
|
[Fabio Baruffa](fabio.baruffa@intel.com).
|
|
|
|
----
|
|
## 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](https://arxiv.org/abs/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](https://arxiv.org/abs/1601.07195)
|