lightning.tensor mps docs (#756)

### Before submitting Please complete the following checklist when submitting a PR: - [ ] All new features must include a unit test. If you've fixed a bug or added code that should be tested, add a test to the [`tests`](../tests) directory! - [x] All new functions and code must be clearly commented and documented. If you do make documentation changes, make sure that the docs build and render correctly by running `make docs`. - [ ] Ensure that the test suite passes, by running `make test`. - [x] Add a new entry to the `.github/CHANGELOG.md` file, summarizing the change, and including a link back to the PR. - [x] Ensure that code is properly formatted by running `make format`. When all the above are checked, delete everything above the dashed line and fill in the pull request template. ------------------------------------------------------------------------------------------------------------ **Context:** Add `lightning.tensor` documentation. The requirement of this doc is `Basic documentation and developer-facing notes` [SC-62441] **Description of the Change:** **Benefits:** **Possible Drawbacks:** **Related GitHub Issues:** --------- Co-authored-by: ringo-but-quantum <[email protected]> Co-authored-by: Mudit Pandey <[email protected]> Co-authored-by: Vincent Michaud-Rioux <[email protected]> Co-authored-by: Ali Asadi <[email protected]> Co-authored-by: Vincent Michaud-Rioux <[email protected]> Co-authored-by: Amintor Dusko <[email protected]> Co-authored-by: Korbinian Kottmann <[email protected]> Co-authored-by: Pietropaolo Frisoni <[email protected]>
PennyLaneAI · Jun 14, 2024 · 52710ff · 52710ff
1 parent f15665c
commit 52710ff
Show file tree

Hide file tree

Showing 12 changed files with 288 additions and 21 deletions.
diff --git 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
@@ -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
@@ -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 <https://developer.nvidia.com/cuquantum-sdk>`_. It notably implements a distributed state-vector simulator based on MPI.
 * ``lightning.kokkos``: is a state-vector simulator written with `Kokkos <https://kokkos.github.io/kokkos-core-wiki/index.html>`_. It can exploit the inherent parallelism of modern processing units supporting the `OpenMP <https://www.openmp.org/>`_, `CUDA <https://developer.nvidia.com/cuda-toolkit>`_ or `HIP <https://docs.amd.com/projects/HIP/en/docs-5.3.0/index.html>`_ programming models.
+* ``lightning.tensor``: is a tensor network simulator based on the `NVIDIA cuQuantum SDK <https://developer.nvidia.com/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 <https://developer.nvidia.com/cuquantum-sdk>`_ (only the `cutensornet <https://docs.nvidia.com/cuda/cuquantum/latest/cutensornet/index.html>`_ 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 <https://developer.nvidia.com/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 <https://docs.pennylane.ai/projects/lightning/>`_ as
 well as to the `PennyLane documentation <https://docs.pennylane.ai/>`_ for further reference.
 
@@ -441,7 +477,7 @@ License
 
 The Lightning plugins are **free** and **open source**, released under
 the `Apache License, Version 2.0 <https://www.apache.org/licenses/LICENSE-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
@@ -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
 
         <div style='clear:both'></div>
@@ -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
@@ -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
 
         <div style='clear:both'></div>
@@ -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
@@ -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
 
     <div style='clear:both'></div>
@@ -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
@@ -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 <https://docs.nvidia.com/cuda/cuquantum/latest/cutensornet/index.html>`__ 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 <https://developer.nvidia.com/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 <https://docs.pennylane.ai/en/latest/code/api/pennylane.devices.default_tensor.DefaultTensor.html>`__ 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
+
+    <div class="summary-table">
+
+.. 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
+
+    </div>
+
+**Unsupported operations:**
+
+.. raw:: html
+
+    <div class="summary-table">
+
+.. autosummary::
+    :nosignatures:
+
+    ~pennylane.StatePrep
+    ~pennylane.QubitStateVector
+    ~pennylane.DoubleExcitationMinus
+    ~pennylane.DoubleExcitationPlus
+    ~pennylane.GlobalPhase
+
+.. raw:: html
+
+    </div>
+
+**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
+
+    <div class="summary-table">
+
+.. 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
+
+    </div>
+
+**Unsupported observables:**
+
+.. raw:: html
+
+    <div class="summary-table">
+
+.. autosummary::
+    :nosignatures:
+
+    ~pennylane.SparseHamiltonian
+    ~pennylane.Projector
+
+.. raw:: html
+
+    </div>
diff --git a/doc/lightning_tensor/installation.rst 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
diff --git a/doc/lightning_tensor/package.rst b/doc/lightning_tensor/package.rst
@@ -0,0 +1,19 @@
+lightning_tensor
+================
+
+.. automodapi:: pennylane_lightning.lightning_tensor
+    :no-heading:
+    :include-all-objects:
+
+.. raw:: html
+
+        <div style='clear:both'></div>
+        </br>
+
+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
@@ -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
+matplotlib
diff --git 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"