Installation

QiliSDK and its optional extras are distributed via PyPI. Use pip to install the core package, plus any extra modules you need.

Base package

pip install qilisdk

Optional extras

Note

On macOS the default shell is zsh, which treats square brackets as a globbing pattern, so the extras must be quoted (pip install "qilisdk[cuda12]"). Select your operating system in the tabs below to get the right command.

  • CUDA acceleration (NVIDIA GPU support for QiliSim):

    pip install qilisdk[cuda12]

Note

Use the cuda13 extra instead if your drivers are on CUDA 13. Either way a CUDA accelerated GPU must be available on your system with proper drivers installed.

  • SpeQtrum (cloud submission via speqtrum):

    pip install qilisdk[speqtrum]

You can combine extras:

pip install qilisdk[cuda12,speqtrum]

Optional backends

CudaqBackend and QutipBackend run on third-party frameworks that QiliSDK does not distribute, so they are not covered by any extra. Install the framework yourself and the backend becomes available:

pip install "cuda-quantum-cu12>=0.14.0"       # or cuda-quantum-cu13, for CudaqBackend
pip install "qutip>=5.2.2" "qutip-qip>=0.4.0"  # for QutipBackend

QiliSDK checks the installed version when the backend is first used, and tells you what it found if it is too old.

Note

QiliSDK requires a python version 3.11 or higher.

Minimum OS requirements:

  • Linux: Ubuntu 22.04 or higher

  • Windows: Windows 11 or higher

  • MacOS: MacOS 14 or higher

Compiling From Source

The above method will install the pre-built binaries of QiliSDK of the most recent release. If you want to get the newest features (those that we’re still working on), you can compile the library from source, but be aware that this is not recommended for most users, and we make no promises that the latest code will be stable.

Support for Windows is limited, so we recommend using WSL, which can be installed as per this guide. With this you should then follow the Linux instructions below. If you must use pure Windows, the Windows instructions below should work, although they disable certain code features (notably some parallelized loops).

First, make sure you have Python, pip, git, cmake and a C++ compiler installed:

sudo apt update
sudo apt install python3 python3-pip git build-essential

Install uv globally with:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then, clone (i.e. download) and enter the repository:

git clone https://github.com/qilimanjaro-tech/qilisdk
cd qilisdk

Create a new virtual environment using uv:

uv venv

Then activate the environment:

source .venv/bin/activate

To then install QiliSDK into this new environment, run:

uv sync

If you want to install with extras, you can run the following, adjusting as needed:

uv sync --extra cuda13 --extra speqtrum --group backends

There are also a number of extra compile flags that can be set to enable/disable certain features:

Flag

What it does

-Ccmake.define.build_native=ON

Build for the architecture of the current machine for increased performance. Only recommended if you are building for your own machine.

-Ccmake.define.single_precision=ON

Use single precision (float) instead of double precision (double). Slightly faster, but less accurate.

-Ccmake.build-type=Debug

Enable a debug build (no optimizations, debug symbols).

-Ccmake.build-type=RelWithDebInfo

Enable an optimized debug build (optimizations plus debug symbols).

-Ccmake.build-type=Release

Enable a release build (optimizations, no debug symbols). This is the default.

-Ccmake.define.tidy=ON

Run clang-tidy on the code during compilation.

-Ccmake.define.verbose=ON

Enable (very) verbose output from the C++ code.

-Ccmake.define.tests=ON

Build the C++ test suite, which will then be available as a test_cpp executable in the tests directory.

-Ccmake.define.coverage=ON

Enable coverage instrumentation flags.

These can be passed to uv sync by simply appending to the build command, for example:

uv sync -Ccmake.define.build_native=ON -Ccmake.build-type=RelWithDebInfo

You then have an environment with the latest version of QiliSDK installed. If you want to install other things to the environment you’ll need to use pip with uv:

uv pip install <package_name>

And then to run a Python script within the environment, you can use:

uv run python3 <script_name.py>