Skip to main content

PennyLane-Lightning plugin

Project description

Linux x86_64 tests (branch) Windows tests (branch) Linux x86_64 wheel builds (branch) Codecov coverage CodeFactor Grade Read the Docs PyPI PyPI - Python Version

The Lightning plugin ecosystem provides fast state-vector 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.9 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.

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)

Linux x86

pip

pip

source

pip

source

source

Linux ARM

pip

source

pip

source

source

Linux PPC

pip

source

pip

source

source

MacOS x86

pip

pip

MacOS ARM

pip

pip

Windows

pip

Lightning-Qubit installation

PyPI wheels (pip)

Lightning plugins can be installed using pip as follows

$ pip install pennylane-lightning

The above command will install the Lightning-Qubit plugin (the default since it is most broadly supported). In order to install the Lightning-GPU and Lightning-Kokkos (OpenMP) backends, you can respectively use the following commands:

$ pip install pennylane-lightning[gpu]
$ pip install pennylane-lightning[kokkos]

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 or lightning_kokkos. 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 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-cu11, 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} pip install -e . -vv

Note that subsequent calls to pip install -e . will use cached binaries stored in the build folder. 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 . -vv

or with build_ext and the --define flag as follows:

$ python3 setup.py build_ext -i --define="ENABLE_OPENMP=OFF;ENABLE_BLAS=OFF"
$ python3 setup.py develop

where -D must not be included before ;-separated options.

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.

CMake support

One can also build the plugin using CMake:

$ cmake -S. -B build
$ cmake --build build

Supported options are

  • -DENABLE_WARNINGS:BOOL=ON

  • -DENABLE_NATIVE:BOOL=ON (for -march=native)

  • -DENABLE_BLAS:BOOL=ON

  • -DENABLE_OPENMP:BOOL=ON

  • -DENABLE_CLANG_TIDY:BOOL=ON

Testing

To test that a plugin is working correctly, test the Python code with:

$ make test-python device=${PL_DEVICE}

where ${PL_DEVICE} can be lightning.qubit (default), lightning.gpu or lightning.kokkos. These differ from ${PL_BACKEND} by replacing the underscore by a dot. The C++ code can be tested with

$ PL_BACKEND=${PL_BACKEND} make test-cpp

Lightning-GPU installation

Lightning-GPU can be installed using pip:

pip install pennylane-lightning[gpu]

Lightning-GPU requires the cuQuantum SDK (only the cuStateVec 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.

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:

git clone https://github.com/PennyLaneAI/pennylane-lightning.git
cd pennylane-lightning
pip install -r requirements.txt
PL_BACKEND="lightning_qubit" pip install -e . -vv

Then the cuStateVec library can be installed and set a CUQUANTUM_SDK environment variable.

python -m pip install wheel custatevec-cu11
export CUQUANTUM_SDK=$(python -c "import site; print( f'{site.getsitepackages()[0]}/cuquantum/lib')")

The Lightning-GPU can then be installed with pip:

PL_BACKEND="lightning_gpu" python -m pip install -e .

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-cu11), 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 with pip:

CMAKE_ARGS="-DENABLE_MPI=ON"  PL_BACKEND="lightning_gpu" python -m pip install -e .

Test L-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=<path to sdk>
cmake --build ./BuildTests --verbose
cd ./BuildTests
for file in *runner_mpi ; do mpirun -np 2 ./BuildTests/$file ; done;

Lightning-Kokkos installation

On linux systems, lightning.kokkos with the OpenMP backend can be installed by providing the optional [kokkos] tag:

$ pip install pennylane-lightning[kokkos]

Install Lightning-Kokkos from source

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.

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

cmake -S . -B build -G Ninja \
    -DCMAKE_BUILD_TYPE=RelWithDebugInfo \
    -DCMAKE_INSTALL_PREFIX=/opt/kokkos/4.1.00/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
echo export CMAKE_PREFIX_PATH=/opt/kokkos/4.1.00/AMPERE80:\$CMAKE_PREFIX_PATH

Next, append the install location to CMAKE_PREFIX_PATH. Note that the C++20 standard is required (-DCMAKE_CXX_STANDARD=20 option), and hence CUDA v12 is required for the CUDA backend. If an installation is not found, our builder will clone and install it during the build process.

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

CMAKE_ARGS="-DKokkos_ENABLE_OPENMP=ON" PL_BACKEND="lightning_kokkos" python -m pip install .

To build the plugin directly with CMake as above:

cmake -B build -DKokkos_ENABLE_OPENMP=ON -DPL_BACKEND=lightning_kokkos -G Ninja
cmake --build build

The supported backend options are SERIAL, OPENMP, THREADS, HIP and CUDA and the corresponding build options are -DKokkos_ENABLE_XXX=ON, where XXX needs be replaced by the backend name, for instance OPENMP. One can activate simultaneously 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.

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 there is also a detailed description about PennyLane Docker support. 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 doing research using PennyLane and Lightning, please cite our paper:

Ville Bergholm, Josh Izaac, Maria Schuld, Christian Gogolin, M. Sohaib Alam, Shahnawaz Ahmed, Juan Miguel Arrazola, Carsten Blank, Alain Delgado, Soran Jahangiri, Keri McKiernan, Johannes Jakob Meyer, Zeyue Niu, Antal Száva, and Nathan Killoran. PennyLane: Automatic differentiation of hybrid quantum-classical computations. 2018. arXiv:1811.04968

Support

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 plugin makes 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:

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

PennyLane_Lightning_GPU-0.34.0.tar.gz (44.0 kB view details)

Uploaded Source

Built Distributions

PennyLane_Lightning_GPU-0.34.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (6.9 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

PennyLane_Lightning_GPU-0.34.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (6.9 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

PennyLane_Lightning_GPU-0.34.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (6.9 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

PennyLane_Lightning_GPU-0.34.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (6.9 MB view details)

Uploaded CPython 3.9manylinux: glibc 2.17+ x86-64

File details

Details for the file PennyLane_Lightning_GPU-0.34.0.tar.gz.

File metadata

File hashes

Hashes for PennyLane_Lightning_GPU-0.34.0.tar.gz
Algorithm Hash digest
SHA256 b6362cdc538ad8e504b13fcb39ea71112af9db4d1e0c4c810307a2f488088ca0
MD5 cd5a87b6d11c43a9006262ddc0c684f1
BLAKE2b-256 fd5ce6c0e8396de64de66680807a964027144527c9f756ae6b77043f43fcd026

See more details on using hashes here.

File details

Details for the file PennyLane_Lightning_GPU-0.34.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for PennyLane_Lightning_GPU-0.34.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 b1c96842961a92213766d761b5366ca4d2dfdea7529a675916ddd7f15ff390ba
MD5 6a7e86eee8d3a65b1f39e8452875f27c
BLAKE2b-256 454ad57191b52ad935a0defc387e8823f9ce2ae650950ae1185cef95d1939fbd

See more details on using hashes here.

File details

Details for the file PennyLane_Lightning_GPU-0.34.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for PennyLane_Lightning_GPU-0.34.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 21cc2ea6997f591426a23e8fdd15313532778997b75150a37f8b11b4292b837f
MD5 e29efc1b6f4cbb5efc4921b3126ccebe
BLAKE2b-256 854fc7b3151aed8101090b531f431a6ddd93671cd91241e83f36743cce68ef6d

See more details on using hashes here.

File details

Details for the file PennyLane_Lightning_GPU-0.34.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for PennyLane_Lightning_GPU-0.34.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 6a9df992d63ff5a39736e99224ed42114240d343fa14c6f012c14c9fbecb96df
MD5 9fae58e1709363d15c58baf5e7490701
BLAKE2b-256 b92b9acd1d4896abc9807a4eac7e43ade9afe55b68fee056dfbde701c90a034c

See more details on using hashes here.

File details

Details for the file PennyLane_Lightning_GPU-0.34.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for PennyLane_Lightning_GPU-0.34.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 65524ad6573c6b67c65085ec07036ac0453311d4517f8cdee1b9075cf86b5b05
MD5 2b7c4f046a5ae50dca6d70ba27d2f73b
BLAKE2b-256 808005d84ce53d8cd80eff76727092dab17111a311fb6f8f3b0740681ba7d777

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page