Installation instructions
Operating systems support
In the table below we summarize the status of pre-compiled binaries distributed with pypi for the packages listed above.
Operating System |
qibo |
qibojit |
qibotf |
tensorflow |
---|---|---|---|---|
Linux x86 |
Yes |
Yes |
Yes |
Yes |
MacOS >= 10.15 |
Yes |
Yes |
Yes |
Yes |
Windows |
Yes |
Yes |
No |
Yes |
Note
All packages are supported for Python >= 3.7.
Backend installation
qibo
The qibo
is the base required package which includes the language API and a
lightweight cross-platform simulator based on numpy
. In order to accelerate
simulation please consider specialized backends listed in
Simulation backends.
Installing with pip
The installation using pip
is the recommended approach to install Qibo.
Make sure you have Python 3.7 or greater, then use pip
to install qibo
with:
pip install qibo
The pip
program will download and install all the required
dependencies for Qibo.
Installing with conda
We provide conda packages for qibo
through the conda-forge channel.
To install the package with conda run:
conda install -c conda-forge qibo
Installing from source
The installation procedure presented in this section is useful when you have to develop the code from source.
In order to install Qibo from source, you can simply clone the GitHub repository with
git clone https://github.com/qiboteam/qibo.git
cd qibo
pip install .
qibojit
The qibojit
package contains a simulator implementation based on
just-in-time (JIT) custom kernels using numba
and cupy. We also provide another implementation based
on cuQuantum primitives available
when running Qibo on GPU.
This backend is used by default, however, if needed, in order to switch to the
qibojit
backend please do:
import qibo
qibo.set_backend("qibojit")
Custom cupy kernels will be used by default if a GPU is available and
custom numba kernels if a GPU is not available.
If a GPU is available it is possible to switch to the cuQuantum implementation
using the platform
argument, for example:
import qibo
# switch to the cuquantum implementation
qibo.set_backend("qibojit", platform="cuquantum")
# switch to custom numba kernels (even if a GPU is available)
qibo.set_backend("qibojit", platform="numba")
Installing with pip
The installation using pip
is the recommended approach to install
qibojit
.
In order to install the package use the following command:
pip install qibojit
Note
The pip
program will download and install all the required
dependencies except cupy and/or
cuQuantum
which are required for GPU acceleration.
The cuQuantum dependency is optional, as it is required only for
the cuquantum
platform. Please install cupy by following the
instructions from the official website for your GPU hardware.
The installation instructions for cuQuantum
are available in the official documentation.
Installing with conda
We provide conda packages for qibo
and qibojit
through the conda-forge channel.
To install both packages with conda run:
conda install -c conda-forge qibojit
Note
The conda
program will download and install all the required
dependencies except cupy and/or
cuQuantum
which are required for GPU acceleration.
The cuQuantum dependency is optional, as it is required only for
the cuquantum
platform. Please install cupy by following the
instructions from the official website for your GPU hardware.
The installation instructions for cuQuantum
are available in the official documentation.
Installing from source
The installation procedure presented in this section is useful if you have to develop the code from source.
In order to install the package perform the following steps:
git clone https://github.com/qiboteam/qibojit.git
cd qibojit
Then proceed with the qibojit
installation using pip
pip install .
qibotf
The qibotf
package contains a custom simulator implementation based on
TensorFlow and custom operators in CUDA/C++.
If needed, in order to switch to the qibotf
backend please do:
import qibo
qibo.set_backend("qibotf")
Installing with pip
The installation using pip
is the recommended approach to install
qibotf
. We provide precompiled packages for linux x86/64 and macosx 10.15 or
greater for Python 3.7, 3.8 and 3.9.
In order to install the package use the following command:
pip install qibo qibotf
The pip
program will download and install all the required
dependencies.
Note
The pip
packages for linux are compiled with CUDA support, so if your
system has a NVIDIA GPU, Qibo will perform calculations on GPU. Note that
qibotf
uses TensorFlow for GPU management, if your system has a NVIDIA
GPU, make sure TensorFlow runs on GPU, please refer to the official
documentation.
Installing from source
The installation procedure presented in this section is useful if the pre-compiled binary packages for your operating system is not available or if you have to develop the code from source.
In order to install the package perform the following steps:
git clone https://github.com/qiboteam/qibotf.git
cd qibotf
then proceed with the installation of requirements with:
pip install -r requirements.txt
Make sure your system has a GNU g++ >= 4
compiler. If you are working on
macosx make sure the command c++
is clang >= 11
and install the libomp
library with brew install libomp
command.
Optionally, you can use the CXX
environment variable to set then compiler
path. Similarly, the PYTHON
environment variable sets the python interpreter
path.
Note
If your system has a NVIDIA GPU, make sure TensorFlow is installed properly and runs on GPU, please refer to the official documentation.
In that case, you can activate GPU support for Qibo by:
installing the NVCC compiler matching the TensorFlow CUDA version, see the CUDA documentation.
exporting the
CUDA_PATH
variable with the CUDA installation path containing the cuda compiler.make sure the NVCC compiler is available from
CUDA_PATH/bin/nvcc
, otherwise the compilation may fail. You can locate it withwhereis nvcc
and eventually link/copy to yourCUDA_PATH/bin
folder.
For example, TensorFlow 2.5.0 supports CUDA 11.2. After installing
TensorFlow proceed with the NVCC 11.2 installation. On linux the
installation path usually is /usr/local/cuda-11.2/
.
Before installing Qibo do export CUDA_PATH=/usr/local/cuda-11.2
.
Note that Qibo will not enable GPU support if points 1 and 2 are not performed.
Then proceed with the qibotf
installation using pip
pip install .
or if you prefer to manually execute all installation steps:
# builds binaries
python setup.py build
# installs the Qibo packages
python setup.py install # or python setup.py develop
tensorflow
If the TensorFlow package is installed Qibo
will detect and provide to the user the possibility to use tensorflow
backend.
This backend is used by default if qibotf
is not installed, however, if
needed, in order to switch to the tensorflow
backend please do:
import qibo
qibo.set_backend("tensorflow")
In order to install the package, we recommend the installation using:
pip install qibo tensorflow
Note
TensorFlow can be installed following its documentation.
numpy
The qibo
base package is distributed with a lightweight quantum simulator
shipped with the qibo base package. No extra packages are required.
This backend is used by default if qibotf
or tensorflow
are not
installed, however, if needed, in order to switch to the numpy
backend
please do:
import qibo
qibo.set_backend("numpy")
Using the code with docker
We provide docker images for tag release of the code using GitHub Packages. The docker images contain a pre-configured linux environment with the Qibo framework installed with the specific tag version.
Please refer to the download and authentication instructions from the Qibo GitHub Packages.
In order to start the docker image in interactive mode please use docker standard syntax, for example:
docker run -it ghcr.io/qiboteam/qibo:<tag_version> bash
This will open a bash shell with the Qibo environment already activated, with all binaries and scripts from the Qibo framework.
Note
The docker image contains the basic qibo
package with the lightweight
numpy
backend for simulation.