Lightning Plugins

The Lightning plugin ecosystem provides fast state-vector and tensor network simulators written in C++.

PennyLane is a cross-platform Python library for quantum machine learning, automatic differentiation, and optimization of hybrid quantum-classical computations. PennyLane supports Python 3.10 and above.

Features

PennyLane-Lightning high performance simulators include the following backends:

• lightning.qubit: is a fast state-vector simulator written in C++.
• lightning.gpu: is a state-vector simulator based on the NVIDIA cuQuantum SDK. It notably implements a distributed state-vector simulator based on MPI.
• lightning.kokkos: is a state-vector simulator written with Kokkos. It can exploit the inherent parallelism of modern processing units supporting the OpenMP, CUDA or HIP programming models.
• lightning.tensor: is a tensor network simulator based on the NVIDIA cuQuantum SDK (requires NVIDIA GPUs with SM 7.0 or greater). The supported method is Matrix Product State (MPS).

The following table summarizes the supported platforms and the primary installation mode:

Lightning-Qubit installation

Lightning-Qubit comes pre-installed with PennyLane. Please follow our installation instructions to install PennyLane.

Install from source

To build Lightning plugins from source you can run

PL_BACKEND=${PL_BACKEND} pip install pybind11 pennylane-lightning --no-binary :all:

where ${PL_BACKEND} can be lightning_qubit (default), lightning_gpu, lightning_kokkos, or lightning_tensor. The pybind11 library is required to bind the C++ functionality to Python.

A C++ compiler such as g++, clang++, or MSVC is required. On Debian-based systems, this can be installed via apt:

sudo apt -y update && sudo apt install -y g++ libomp-dev

where libomp-dev is included to also install OpenMP. On MacOS, we recommend using the latest version of clang++ and libomp:

brew install llvm libomp

The Lightning-GPU backend has several dependencies (e.g. CUDA, custatevec-cu12, etc.), and hence we recommend referring to Lightning-GPU installation section. Similarly, for Lightning-Kokkos it is recommended to configure and install Kokkos independently as prescribed in the Lightning-Kokkos installation section.

Development installation

For development and testing, you can install by cloning the repository:

git clone https://github.com/PennyLaneAI/pennylane-lightning.git
cd pennylane-lightning
pip install -r requirements.txt
PL_BACKEND=${PL_BACKEND} python scripts/configure_pyproject_toml.py
pip install -e . --config-settings editable_mode=compat -vv

Note that subsequent calls to pip install -e . will use cached binaries stored in the build folder, and the pyproject.toml file defined by the configuration script. Run make clean if you would like to recompile from scratch.

You can also pass cmake options with CMAKE_ARGS as follows:

CMAKE_ARGS="-DENABLE_OPENMP=OFF -DENABLE_BLAS=OFF" pip install -e . --config-settings editable_mode=compat -vv

Supported options are -DENABLE_WARNINGS, -DENABLE_NATIVE (for -march=native) -DENABLE_BLAS, -DENABLE_OPENMP, and -DENABLE_CLANG_TIDY.

Compile MSVC (Windows)

Lightning-Qubit can be compiled on Windows using the Microsoft Visual C++ compiler. You need cmake and appropriate Python environment (e.g. using Anaconda).

We recommend using [x64 (or x86)] Native Tools Command Prompt for VS [version] to compile the library. Be sure that cmake and python can be called within the prompt.

cmake --version
python --version

Then a common command will work.

pip install -r requirements.txt
pip install -e . 

Note that OpenMP and BLAS are disabled on this platform.

Testing

To test that a plugin is working correctly, one can check both Python and C++ unit tests for each device.

Python Test

Test the Python code with:

make test-python device=${PL.DEVICE}

where ${PL.DEVICE} differ from ${PL_BACKEND} by replacing the underscore by a dot. And can be

• lightning.qubit (default)
• lightning.gpu
• lightning.kokkos
• lightning.tensor

C++ Test

The C++ code can be tested with

PL_BACKEND=${PL_BACKEND} make test-cpp

Lightning-GPU installation

For the majority of cases, Lightning-GPU can be installed by following our installation instructions at pennylane.ai/install.

Install Lightning-GPU from source

To install Lightning-GPU from the package sources using the direct SDK path, Lightning-Qubit should be install before Lightning-GPU (compilation is not necessary):

git clone https://github.com/PennyLaneAI/pennylane-lightning.git
cd pennylane-lightning
pip install -r requirements.txt
pip install custatevec-cu12
PL_BACKEND="lightning_qubit" python scripts/configure_pyproject_toml.py
SKIP_COMPILATION=True pip install -e . --config-settings editable_mode=compat -vv

Then a CUQUANTUM_SDK environment variable can be set:

export CUQUANTUM_SDK=$(python -c "import site; print( f'{site.getsitepackages()[0]}/cuquantum')")

The Lightning-GPU can then be installed with pip:

PL_BACKEND="lightning_gpu" python scripts/configure_pyproject_toml.py
python -m pip install -e . --config-settings editable_mode=compat -vv

To simplify the build, we recommend using the containerized build process described in Docker support section.

Install Lightning-GPU with MPI

Building Lightning-GPU with MPI also requires the NVIDIA cuQuantum SDK (currently supported version: custatevec-cu12), mpi4py and CUDA-aware MPI (Message Passing Interface). CUDA-aware MPI allows data exchange between GPU memory spaces of different nodes without the need for CPU-mediated transfers. Both the MPICH and OpenMPI libraries are supported, provided they are compiled with CUDA support. The path to libmpi.so should be found in LD_LIBRARY_PATH. It is recommended to install the NVIDIA cuQuantum SDK and mpi4py Python package within pip or conda inside a virtual environment. Please consult the cuQuantum SDK , mpi4py, MPICH, or OpenMPI install guide for more information.

Before installing Lightning-GPU with MPI support using the direct SDK path, please ensure Lightning-Qubit, CUDA-aware MPI and custatevec are installed and the environment variable CUQUANTUM_SDK is set properly. Then Lightning-GPU with MPI support can then be installed in the editable mode:

PL_BACKEND="lightning_gpu" python scripts/configure_pyproject_toml.py
CMAKE_ARGS="-DENABLE_MPI=ON" python -m pip install -e . --config-settings editable_mode=compat -vv

Test Lightning-GPU with MPI

You may test the Python layer of the MPI enabled plugin as follows:

mpirun -np 2 python -m pytest mpitests --tb=short

The C++ code is tested with

rm -rf ./BuildTests
cmake . -BBuildTests -DBUILD_TESTS=1 -DBUILD_TESTS=1 -DENABLE_MPI=ON -DCUQUANTUM_SDK=