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: a fast state-vector simulator written in C++ with optional OpenMP additions and parallelized gate-level SIMD kernels.
• lightning.gpu: a state-vector simulator based on the NVIDIA cuQuantum SDK. It notably implements a distributed state-vector simulator based on MPI.
• lightning.kokkos: 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: a tensor network simulator based on the NVIDIA cuQuantum SDK. The supported methods are Matrix Product State (MPS) and Exact Tensor Network (TN).

If you're not sure what simulator to use, check out our PennyLane performance page.

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

	L-Qubit	L-GPU	L-GPU (MPI)	L-Kokkos (OMP)	L-Kokkos (CUDA)	L-Kokkos (HIP)	L-Tensor
Linux x86	pip	pip	source	pip	source	source	pip
Linux ARM	pip	pip		pip	source	source	pip
Linux PPC	pip	source		source	source	source
MacOS x86	pip			pip
MacOS ARM	pip			pip
Windows	pip

Lightning-Qubit installation

Standard installation

Lightning-Qubit comes pre-installed with PennyLane.

Please follow our installation instructions to install PennyLane.

Install from source

Note

The section below contains instructions for installing Lightning-Qubit from source. For most cases, this is not required and one can simply use the installation instructions at pennylane.ai/install. If those instructions do not work for you, or you have a more complex build environment that requires building from source, then consider reading on.

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. If installing Lightning-GPU, Lightning-Tensor, or Lightning-Kokkos, additional dependencies may be required. We recommend referring to the respective guides for Lightning-GPU installation, Lightning-Tensor installation, and Lightning-Kokkos installation.

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

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} differs from ${PL_BACKEND} by replacing the underscore with a period. Options for ${PL.DEVICE} are

• 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

Standard 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

Note

The section below contains instructions for installing Lightning-GPU from source. For most cases, this is not required and one can simply use the installation instructions at pennylane.ai/install. If those instructions do not work for you, or you have a more complex build environment that requires building from source, then consider reading on.

Since you will be installing PennyLane-Lightning from the master branch, it is recommended to install PennyLane from master:

pip install git+https://github.com/PennyLaneAI/pennylane.git@master

To install Lightning-GPU from the package sources using the direct SDK path first install Lightning-Qubit (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

Note that custatevec-cu12 is a requirement for Lightning-GPU, and is installed by pip separately. After custatevec-cu12 is installed, the CUQUANTUM_SDK environment variable should be set to enable discovery during installation:

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

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

Lightning-GPU also requires additional NVIDIA libraries including nvJitLink, cuSPARSE, cuBLAS, and CUDA runtime. These can be installed through the CUDA Toolkit or from pip.

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

Install Lightning-GPU with MPI

Note

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. 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 that:

Note

• Lightning-Qubit, CUDA-aware MPI and custatevec-cu12 are installed.
• The environment variable CUQUANTUM_SDK is set properly.
• path/to/libmpi.so is added to LD_LIBRARY_PATH.

Then Lightning-GPU with MPI support can 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 can test the Python layer of the MPI enabled plugin as follows:

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

The C++ code can be tested with:

PL_BACKEND="lightning_gpu" make test-cpp-mpi

Lightning-Kokkos installation

Standard installation

On most Linux systems,

Lightning-Kokkos can be installed via Spack or Docker by following our installation instructions at pennylane.ai/install.

Install Lightning-Kokkos from source

Note

The section below contains instructions for installing Lightning-Kokkos from source. For most cases, one can install Lightning-Kokkos via Spack or Docker by the installation instructions at pennylane.ai/install. If those instructions do not work for you, or you have a more complex build environment that requires building from source, then consider reading on.

As Kokkos enables support for many different HPC-targeted hardware platforms, lightning.kokkos can be built to support any of these platforms when building from source.

Install Kokkos (Optional)

We suggest first installing Kokkos with the wanted configuration following the instructions found in the Kokkos documentation. For example, the following will build Kokkos for NVIDIA A100 cards

Download the Kokkos code. Lightning-Kokkos was tested with Kokkos version <= 4.5.0

# Replace x, y, and z by the correct version
wget https://github.com/kokkos/kokkos/archive/refs/tags/4.x.yz.tar.gz
tar -xvf 4.x.y.z.tar.gz
cd kokkos-4.x.y.z

Build Kokkos for NVIDIA A100 cards (SM80 architecture), and append the install location to CMAKE_PREFIX_PATH.

cmake -S . -B build -G Ninja \
    -DCMAKE_BUILD_TYPE=RelWithDebugInfo \
    -DCMAKE_INSTALL_PREFIX=/opt/kokkos/4.x.y.z/AMPERE80 \
    -DCMAKE_CXX_STANDARD=20 \
    -DBUILD_SHARED_LIBS:BOOL=ON \
    -DBUILD_TESTING:BOOL=OFF \
    -DKokkos_ENABLE_SERIAL:BOOL=ON \
    -DKokkos_ENABLE_CUDA:BOOL=ON \
    -DKokkos_ARCH_AMPERE80:BOOL=ON \
    -DKokkos_ENABLE_EXAMPLES:BOOL=OFF \
    -DKokkos_ENABLE_TESTS:BOOL=OFF \
    -DKokkos_ENABLE_LIBDL:BOOL=OFF
cmake --build build && cmake --install build
export CMAKE_PREFIX_PATH=/opt/kokkos/4.x.y.z/AMPERE80:$CMAKE_PREFIX_PATH

Note that the C++20 standard is required (enabled via the -DCMAKE_CXX_STANDARD=20 option), hence CUDA 12 is required for the CUDA backend.

Install Lightning-Kokkos

If an installation of Kokkos is not found, then our builder will automatically clone and install it during the build process. Lightning-Qubit needs to be 'installed' by pip before Lightning-Kokkos (compilation is not necessary).

The simplest way to install Lightning-Kokkos (OpenMP backend) through pip.

git clone https://github.com/PennyLaneAI/pennylane-lightning.git
cd pennylane-lightning
PL_BACKEND="lightning_qubit" python scripts/configure_pyproject_toml.py
SKIP_COMPILATION=True pip install -e . --config-settings editable_mode=compat
PL_BACKEND="lightning_kokkos" python scripts/configure_pyproject_toml.py
CMAKE_ARGS="-DKokkos_ENABLE_OPENMP=ON" python -m pip install -e . --config-settings editable_mode=compat -vv

The supported backend options are

SERIAL

OPENMP

THREADS

HIP

CUDA

and the corresponding build options are -DKokkos_ENABLE_XYZ=ON, where XYZ needs be replaced by the backend name, for instance OPENMP.

One can simutaneously activate one serial, one parallel CPU host (e.g. OPENMP, THREADS) and one parallel GPU device backend (e.g. HIP, CUDA), but not two of any category at the same time. For HIP and CUDA, the appropriate software stacks are required to enable compilation and subsequent use. Similarly, the CMake option -DKokkos_ARCH_{...}=ON must also be specified to target a given architecture. A list of the architectures is found on the Kokkos wiki. Note that THREADS backend is not recommended since Kokkos does not guarantee its safety.

Lightning-Tensor installation

Lightning-Tensor requires CUDA 12 and the cuQuantum SDK (only the cutensornet library is required). The SDK may be installed within the Python environment site-packages directory using pip or conda or the SDK library path appended to the LD_LIBRARY_PATH environment variable. Please see the cuQuantum SDK install guide for more information.

Standard installation

For the majority of cases,

Lightning-Tensor can be installed by following our installation instructions at pennylane.ai/install.

Install Lightning-Tensor from source

Note

The section below contains instructions for installing Lightning-Tensor from source. For most cases, this is not required and one can simply use the installation instructions at pennylane.ai/install. If those instructions do not work for you, or you have a more complex build environment that requires building from source, then consider reading on.

Lightning-Qubit needs to be 'installed' by pip before Lightning-Tensor (compilation is not necessary):

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

Note that cutensornet-cu12 is a requirement for Lightning-Tensor, and is installed by pip separately. After cutensornet-cu12 is installed, the CUQUANTUM_SDK environment variable should be set to enable discovery during installation:

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

The Lightning-Tensor can then be installed with pip:

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

Lightning-Tensor also requires additional NVIDIA libraries including nvJitLink, cuSOLVER, cuSPARSE, cuBLAS, and CUDA runtime. These can be installed through the CUDA Toolkit or from pip.

Please refer to the plugin documentation as well as to the PennyLane documentation for further reference.

Docker support

Docker images for the various backends are found on the PennyLane Docker Hub page, where a detailed description about PennyLane Docker support can be found. Briefly, one can build the Docker Lightning images using:

git clone https://github.com/PennyLaneAI/pennylane-lightning.git
cd pennylane-lightning
docker build -f docker/Dockerfile --target ${TARGET} .

where ${TARGET} is one of the following

• wheel-lightning-qubit
• wheel-lightning-gpu
• wheel-lightning-kokkos-openmp
• wheel-lightning-kokkos-cuda
• wheel-lightning-kokkos-rocm

Contributing

We welcome contributions - simply fork the repository of this plugin, and then make a pull request containing your contribution. All contributors to this plugin will be listed as authors on the releases.

We also encourage bug reports, suggestions for new features and enhancements, and even links to cool projects or applications built on PennyLane.

Black & Pylint

If you contribute to the Python code, please mind the following. The Python code is formatted with the PEP 8 compliant opinionated formatter Black (black==23.7.0). We set a line width of a 100 characters. The Python code is statically analyzed with Pylint. We set up a pre-commit hook (see Git hooks) to run both of these on git commit. Please make your best effort to comply with black and pylint before using disabling pragmas (e.g. # pylint: disable=missing-function-docstring).

Authors

Lightning is the work of many contributors.

If you are using Lightning for research, please cite:

@misc{
    asadi2024,
    title={{Hybrid quantum programming with PennyLane Lightning on HPC platforms}},
    author={Ali Asadi and Amintor Dusko and Chae-Yeun Park and Vincent Michaud-Rioux and Isidor Schoch and Shuli Shu and Trevor Vincent and Lee James O'Riordan},
    year={2024},
    eprint={2403.02512},
    archivePrefix={arXiv},
    primaryClass={quant-ph},
    url={https://arxiv.org/abs/2403.02512},
}

Support

• Source Code: https://github.com/PennyLaneAI/pennylane-lightning
• Issue Tracker: https://github.com/PennyLaneAI/pennylane-lightning/issues
• PennyLane Forum: https://discuss.pennylane.ai

If you are having issues, please let us know by posting the issue on our Github issue tracker, or by asking a question in the forum.

License

The Lightning plugins are free and open source, released under the Apache License, Version 2.0. The Lightning-GPU and Lightning-Tensor plugins make use of the NVIDIA cuQuantum SDK headers to enable the device bindings to PennyLane, which are held to their own respective license.

Acknowledgements

PennyLane Lightning makes use of the following libraries and tools, which are under their own respective licenses:

• pybind11: https://github.com/pybind/pybind11
• Kokkos Core: https://github.com/kokkos/kokkos
• NVIDIA cuQuantum: https://developer.nvidia.com/cuquantum-sdk
• scipy-openblas32: https://pypi.org/project/scipy-openblas32/
• Xanadu JET: https://github.com/XanaduAI/jet