diff --git a/.github/CHANGELOG.md b/.github/CHANGELOG.md index 938238d4af..257cc96ff2 100644 --- a/.github/CHANGELOG.md +++ b/.github/CHANGELOG.md @@ -84,6 +84,9 @@ ### Documentation +* Add installation instructions and documentation for `lightning.tensor`. + [(#756)](https://github.com/PennyLaneAI/pennylane-lightning/pull/756) + ### Bug fixes * Fix random CI failures for `lightning.tensor` python unit tests and ignore `lightning_tensor` paths. diff --git a/.readthedocs.yml b/.readthedocs.yml index fe7c39df9b..fd7c32576b 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -30,4 +30,5 @@ build: post_install: - rm -rf ./build && export PATH=${READTHEDOCS_VIRTUALENV_PATH}/cuda-12.3/bin${PATH:+:${PATH}} && export LD_LIBRARY_PATH=${READTHEDOCS_VIRTUALENV_PATH}/cuda-12.3/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} && PL_BACKEND="lightning_gpu" python setup.py build_ext --define="PL_DISABLE_CUDA_SAFETY=1" && PL_BACKEND="lightning_gpu" python setup.py bdist_wheel - rm -rf ./build && PL_BACKEND="lightning_kokkos" python setup.py bdist_wheel + - rm -rf ./build && export PATH=${READTHEDOCS_VIRTUALENV_PATH}/cuda-12.3/bin${PATH:+:${PATH}} && export LD_LIBRARY_PATH=${READTHEDOCS_VIRTUALENV_PATH}/cuda-12.3/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} && PL_BACKEND="lightning_tensor" python setup.py build_ext --define="PL_DISABLE_CUDA_SAFETY=1" && PL_BACKEND="lightning_tensor" python setup.py bdist_wheel - python -m pip install ./dist/*.whl diff --git a/README.rst b/README.rst index d2df483c03..653407514b 100644 --- a/README.rst +++ b/README.rst @@ -49,26 +49,27 @@ 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). This device is designed to simulate large-scale quantum circuits using tensor networks. For small circuits, state-vector simulator plugins may be more suitable. The supported method is Matrix Product State (MPS). This device does not currently support finite shots. Currently, the supported measurement types are expectation values and the supported differentiation methods are ``parameter-shift`` and ``finite-diff``. Note that only 1,2-wire gates and gates that can be decomposed by PennyLane into 1,2-wire gates are supported. .. header-end-inclusion-marker-do-not-remove 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 | | | | | | -+-----------+---------+--------+-------------+----------------+-----------------+----------------+ ++-----------+---------+--------+-------------+----------------+-----------------+----------------+----------------+ +| | 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 | 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 | | | | | | | ++-----------+---------+--------+-------------+----------------+-----------------+----------------+----------------+ .. installation_LQubit-start-inclusion-marker-do-not-remove @@ -361,6 +362,41 @@ Note that ``THREADS`` backend is not recommended since `Kokkos does not guarante .. installation_LKokkos-end-inclusion-marker-do-not-remove +.. installation_LTensor-start-inclusion-marker-do-not-remove + +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. + +Install Lightning-Tensor from source +==================================== +Lightning-Qubit should be installed before Lightning-Tensor: + +.. code-block:: console + + git clone https://github.com/PennyLaneAI/pennylane-lightning.git + cd pennylane-lightning + pip install -r requirements.txt + PL_BACKEND="lightning_qubit" pip install . + +Then the `cutensornet`_ library can be installed and set a ``CUQUANTUM_SDK`` environment variable. + +.. code-block:: console + + pip install cutensornet-cu12 + export CUQUANTUM_SDK=$(python -c "import site; print( f'{site.getsitepackages()[0]}/cuquantum/lib')") + +The Lightning-Tensor can then be installed with ``pip``: + +.. code-block:: console + + PL_BACKEND="lightning_tensor" pip install -e . + +.. installation_LTensor-end-inclusion-marker-do-not-remove + + Please refer to the `plugin documentation `_ as well as to the `PennyLane documentation `_ for further reference. @@ -441,7 +477,7 @@ 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 +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. .. license-end-inclusion-marker-do-not-remove diff --git a/doc/code/__init__.rst b/doc/code/__init__.rst index 1e4eb7d3c8..e20adb95c7 100644 --- a/doc/code/__init__.rst +++ b/doc/code/__init__.rst @@ -28,6 +28,11 @@ This section contains the API documentation for the Lightning packages. :description: API documentation for the lightning_kokkos package :link: ../lightning_kokkos/package.html +.. title-card:: + :name: lightning_tensor + :description: API documentation for the lightning_tensor package + :link: ../lightning_tensor/package.html + .. raw:: html
@@ -39,3 +44,4 @@ This section contains the API documentation for the Lightning packages. ../lightning_qubit/package ../lightning_gpu/package ../lightning_kokkos/package + ../lightning_tensor/package diff --git a/doc/dev/installation.rst b/doc/dev/installation.rst index 639792896d..54ac4cb73e 100644 --- a/doc/dev/installation.rst +++ b/doc/dev/installation.rst @@ -18,6 +18,11 @@ Each device in the Lightning ecosystem is a separate Python package. Select the :description: Guidelines to installing and testing the Lightning Kokkos device :link: ../lightning_kokkos/installation.html +.. title-card:: + :name: Lightning Tensor + :description: Guidelines to installing and testing the Lightning Tensor device + :link: ../lightning_tensor/installation.html + .. raw:: html
@@ -29,3 +34,4 @@ Each device in the Lightning ecosystem is a separate Python package. Select the ../lightning_qubit/installation ../lightning_gpu/installation ../lightning_kokkos/installation + ../lightning_tensor/installation diff --git a/doc/index.rst b/doc/index.rst index fae9442113..d73ddad326 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -33,6 +33,11 @@ The Lightning ecosystem provides the following devices: :description: A heterogeneous backend state-vector simulator with Kokkos library support. :link: lightning_kokkos/device.html +.. title-card:: + :name: 'lightning.tensor' + :description: A heterogeneous backend tensor network simulator with NVIDIA cuQuantum library support. + :link: lightning_tensor/device.html + .. raw:: html
@@ -55,6 +60,7 @@ The Lightning ecosystem provides the following devices: lightning_qubit/device lightning_gpu/device lightning_kokkos/device + lightning_tensor/device .. toctree:: :maxdepth: 2 diff --git a/doc/lightning_tensor/device.rst b/doc/lightning_tensor/device.rst new file mode 100644 index 0000000000..109e909408 --- /dev/null +++ b/doc/lightning_tensor/device.rst @@ -0,0 +1,187 @@ +Lightning Tensor device +======================= + +The ``lightning.tensor`` device is a tensor network simulator device. The device is built on top of the `cutensornet `__ from the NVIDIA cuQuantum SDK, enabling GPU-accelerated simulation of quantum tensor network evolution. + +A ``lightning.tensor`` device can be loaded simply using: + +.. code-block:: python + + import pennylane as qml + dev = qml.device("lightning.tensor", wires=100) + +By default, the device represents the quantum state approximated as a Matrix Product State (MPS). +The default setup for the MPS tensor network approximation is: + - ``max_bond_dim`` (maximum bond dimension) defaults to ``128`` . + - ``cutoff`` (singular value truncation threshold) defaults to ``0`` . + - ``cutoff_mode`` (singular value truncation mode) defaults to ``abs`` , considering the absolute values of the singular values; Alternatively, users can opt to set ``cutoff_mode`` to ``rel`` to consider the relative values of the singular values. + +The ``lightning.tensor`` device dispatches all operations to be performed on a CUDA-capable GPU of generation SM 7.0 (Volta) +and greater. + +.. note:: + Given the inherent parallelism of GPUs, simulations with intensive parallel computation, such as those with larger maximum + bond dimensions, stand to gain the most from the computational power offered by GPU and those simulations can benifit from the + ``lightning.tensor`` device. It's worth noting that if the bond dimension used in the simulation is small, the ``lightning.tensor`` + device with ``MPS`` running a GPU may perform slower compared to a ``default.tensor`` device with ``MPS`` running on a CPU. For more details + on how bond dimension affects the simulation performance, please refer to the ``Approximate Tensor Network Methods`` section in the `cuQuantum SDK `__. + +Users also have the flexibility to customize these parameters according to their specific needs with: + +.. code-block:: python + + import pennylane as qml + import numpy as np + + num_qubits = 100 + + device_kwargs_mps = { + "max_bond_dim": 64, + "cutoff": 1e-10, + "cutoff_mode": "abs", + } + + dev = qml.device("lightning.tensor", wires=num_qubits, method="mps", **device_kwargs_mps) + +The ``lightning.tensor`` device allows users to get quantum circuit gradients using the ``parameter-shift`` method. This can be enabled at the PennyLane ``QNode`` level with: + +.. code-block:: python + + @qml.qnode(dev, diff_method="parameter-shift") + def circuit(params): + ... + +Check out the :doc:`/lightning_tensor/installation` guide for more information. + +.. seealso:: `DefaultTensor `__ for a CPU only tensor network simulator device. + +Operations and observables support +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The "lightning.tensor" supports 1- and 2-wire gate operations and all other operations that can be decomposed to that by PennyLane. + +**Supported operations:** + +.. raw:: html + +
+ +.. autosummary:: + :nosignatures: + + ~pennylane.BasisState + ~pennylane.BlockEncode + ~pennylane.CNOT + ~pennylane.ControlledPhaseShift + ~pennylane.ControlledQubitUnitary + ~pennylane.CRot + ~pennylane.CRX + ~pennylane.CRY + ~pennylane.CRZ + ~pennylane.CSWAP + ~pennylane.CY + ~pennylane.CZ + ~pennylane.DiagonalQubitUnitary + ~pennylane.DoubleExcitation + ~pennylane.ECR + ~pennylane.Hadamard + ~pennylane.Identity + ~pennylane.IsingXX + ~pennylane.IsingXY + ~pennylane.IsingYY + ~pennylane.IsingZZ + ~pennylane.ISWAP + ~pennylane.OrbitalRotation + ~pennylane.PauliX + ~pennylane.PauliY + ~pennylane.PauliZ + ~pennylane.PhaseShift + ~pennylane.PSWAP + ~pennylane.QFT + ~pennylane.QubitCarry + ~pennylane.QubitSum + ~pennylane.QubitUnitary + ~pennylane.Rot + ~pennylane.RX + ~pennylane.RY + ~pennylane.RZ + ~pennylane.S + ~pennylane.SingleExcitation + ~pennylane.SingleExcitationMinus + ~pennylane.SingleExcitationPlus + ~pennylane.SISWAP + ~pennylane.SQISW + ~pennylane.SWAP + ~pennylane.SX + ~pennylane.T + ~pennylane.Toffoli + +.. raw:: html + +
+ +**Unsupported operations:** + +.. raw:: html + +
+ +.. autosummary:: + :nosignatures: + + ~pennylane.StatePrep + ~pennylane.QubitStateVector + ~pennylane.DoubleExcitationMinus + ~pennylane.DoubleExcitationPlus + ~pennylane.GlobalPhase + +.. raw:: html + +
+ +**Supported observables:** + +The ``lightning.tensor`` supports all observables supported by the Lightning state-vector simulators, besides ``qml.SparseHamiltonian``, ``qml.Projector`` and limited support to ``qml.Hamiltonian``, ``qml.Prod``. + +Users can not create a ``Hamiltonian`` or ``Prod`` observable from ``Hamiltonian`` observables. + + + +.. raw:: html + +
+ +.. autosummary:: + :nosignatures: + + ~pennylane.ops.op_math.Exp + ~pennylane.Hadamard + ~pennylane.Hamiltonian + ~pennylane.Hermitian + ~pennylane.Identity + ~pennylane.PauliX + ~pennylane.PauliY + ~pennylane.PauliZ + ~pennylane.ops.op_math.Prod + ~pennylane.ops.op_math.SProd + ~pennylane.ops.op_math.Sum + +.. raw:: html + +
+ +**Unsupported observables:** + +.. raw:: html + +
+ +.. autosummary:: + :nosignatures: + + ~pennylane.SparseHamiltonian + ~pennylane.Projector + +.. raw:: html + +
\ No newline at end of file diff --git a/doc/lightning_tensor/installation.rst b/doc/lightning_tensor/installation.rst new file mode 100644 index 0000000000..6187f1c95a --- /dev/null +++ b/doc/lightning_tensor/installation.rst @@ -0,0 +1,3 @@ +.. include:: ../../README.rst + :start-after: installation_LTensor-start-inclusion-marker-do-not-remove + :end-before: installation_LTensor-end-inclusion-marker-do-not-remove \ No newline at end of file diff --git a/doc/lightning_tensor/package.rst b/doc/lightning_tensor/package.rst new file mode 100644 index 0000000000..b305892da7 --- /dev/null +++ b/doc/lightning_tensor/package.rst @@ -0,0 +1,19 @@ +lightning_tensor +================ + +.. automodapi:: pennylane_lightning.lightning_tensor + :no-heading: + :include-all-objects: + +.. raw:: html + +
+
+ +Directly importing the device class: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python3 + + from pennylane_lightning.lightning_tensor import LightningTensor + diff --git a/doc/requirements.txt b/doc/requirements.txt index 4887af0718..94b2a1df82 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -12,6 +12,7 @@ sphinxcontrib-htmlhelp==2.0.1 sphinxcontrib-serializinghtml==1.1.5 pennylane-sphinx-theme custatevec-cu12 +cutensornet-cu12 wheel sphinxext-opengraph -matplotlib \ No newline at end of file +matplotlib diff --git a/pennylane_lightning/core/_version.py b/pennylane_lightning/core/_version.py index deda380d36..ab1f98a20e 100644 --- a/pennylane_lightning/core/_version.py +++ b/pennylane_lightning/core/_version.py @@ -16,4 +16,4 @@ Version number (major.minor.patch[-label]) """ -__version__ = "0.37.0-dev35" +__version__ = "0.37.0-dev36" diff --git a/pennylane_lightning/lightning_tensor/lightning_tensor.py b/pennylane_lightning/lightning_tensor/lightning_tensor.py index b0db8f84b4..8862604677 100644 --- a/pennylane_lightning/lightning_tensor/lightning_tensor.py +++ b/pennylane_lightning/lightning_tensor/lightning_tensor.py @@ -200,10 +200,9 @@ class LightningTensor(Device): be described but the larger the memory requirements. Note that GPUs are ill-suited (i.e. less competitive compared with CPUs) for simulating circuits with low bond dimensions and/or circuit layers with a single or few gates because the arithmetic intensity is lower. - cutoff (float): The threshold used to truncate the singular values of the MPS tensors. Default is 0 - cutoff_mode (str): Singular value truncation mode. Options: ["rel", "abs"]. Default is "abs". + cutoff (float): The threshold used to truncate the singular values of the MPS tensors. The default is 0. + cutoff_mode (str): Singular value truncation mode. The options are ``"rel"`` and ``"abs"``. The default is ``"abs"``. backend (str): Supported backend. Currently, only ``cutensornet`` is supported. - method (str): Supported method. Currently, only ``mps`` is supported. **Example**