Implement unified docs for Lightning Qubit and Kokkos (#473)

* Create a new single repository structure and merge Lightning Qubit and Lightning Kokkos backends

* remove benchmarks CI actions for now

* update _version.py location on actions

* update changelog

* update version

* update action python version

* pleasing CodeFactor

* remove doc/code/api

* ignore doc/code/api

* update wheels build actions

* add coverage test

* add developer tools to check coverage

* update changelog

* fix broken actions

* update test linux

* update upload pypi action name

* update testing configuration strategy

* fix tests without binary

* fix tests without binary

* fix tests without binary

* build wheels for LKokkos but do not push to pypi

* expand QuantumScriptSerializer testing

* pin pennylane back to what should be

* now, really pinning pennylane back to what should be

* docs initial push

* pin pennylane back

* add lighning_qubit and lightning_kokkos packages to the automodapi

* unbreak my CIs... 🎶

* adjust test precision

* uninstall pennylane-lightning before testing LightningKokkos

* fix wheels

* change uninstall pennylane-lightning to install new pennylane-lightning without binaries

* fix if statement

* No longer in-place modify input to `apply` (#474)

* stop mutating input to apply

* changelog

* Reformat.

* include jax data type

* configure jax precision and test tolerance properly

* format

* update dev version

* update avx docs

* add Lightning image

* add Lightning image file

* update Plugin name to Lightning

* Fix merge

* more fixing to merge

* Auto update version

* fix bin files

* fix lightning kokkos docs

* install the lightning_kokkos backend

* remove about title

* Update Python on readthedocs action

* fix PYPI Readme rendering

* Auto update version

* Content and structural changes coming from review suggestions

* update lightning kokkos installation guidelines

* Update lists of 'Supported operations and observables' in device docs.

* Fix Exp Prod SProd Sum links in doc.

* review suggestions and some small fixes

* Fix couple formatting typos.

* Add changelog and more typo fixes

---------

Co-authored-by: Vincent Michaud-Rioux <[email protected]>
Co-authored-by: AmintorDusko <[email protected]>

.github/CHANGELOG.md

@@ -14,9 +14,13 @@
 ### Breaking changes
 
 ### Improvements
+
 * Merge Lightning Qubit and Lightning Kokkos backends in the new repository.
   [(#472)] (https://github.com/PennyLaneAI/pennylane-lightning/pull/472)
 
+* Integrated new unified docs for Lightning Kokkos and Lightning Qubit packages.
+  [(#473)] (https://github.com/PennyLaneAI/pennylane-lightning/pull/473)
+
 ### Documentation
 
 ### Bug fixes

.github/workflows/format.yml

@@ -40,7 +40,7 @@ jobs:
         uses: actions/checkout@v3
 
       - name: Run formatter
-        run: ./bin/format --check --cfversion 14 ./pennylane_lightning/src
+        run: ./bin/format --check --cfversion 14 ./pennylane_lightning/core/src
 
   build_and_cache_Kokkos:
     name: "Build and cache Kokkos"

.github/workflows/wheel_noarch.yml

@@ -83,4 +83,4 @@ jobs:
         with:
           user: __token__
           password: ${{ secrets.TEST_PYPI_API_TOKEN }}
-          repository-url: https://test.pypi.org/legacy/
+          repository-url: https://test.pypi.org/legacy/

.readthedocs.yml

@@ -15,7 +15,7 @@ python:
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.8"
+    python: "3.9"
   apt_packages:
     - cmake
     - build-essential
@@ -25,3 +25,5 @@ build:
   jobs:
     pre_install:
       - echo "setuptools~=66.0\npip~=22.0" >> ci_build_requirements.txt
+    post_install:
+      - PL_BACKEND="lightning_kokkos" pip install -e . -vv

Makefile

@@ -115,4 +115,11 @@ ifdef target
 	cmake --build ./BuildTidy $(VERBOSE) --target $(target)
 else
 	cmake --build ./BuildTidy $(VERBOSE)
-endif
+endif
+
+docs:
+	$(MAKE) -C doc html
+
+.PHONY : clean-docs
+clean-docs:
+	$(MAKE) -C doc clean

README.rst

@@ -1,5 +1,5 @@
-PennyLane-Lightning Plugin
-##########################
+Lightning Plugins
+#################
 
 .. image:: https://img.shields.io/github/actions/workflow/status/PennyLaneAI/pennylane-lightning/tests_linux.yml?branch=master&label=Test%20%28Linux%29&style=flat-square
     :alt: Linux x86_64 tests (branch)
@@ -35,33 +35,34 @@ PennyLane-Lightning Plugin
 
 .. header-start-inclusion-marker-do-not-remove
 
-The PennyLane-Lightning plugin provides fast state-vector simulators written in C++.
+The Lightning plugin ecosystem provides fast state-vector simulators written in C++.
 
 `PennyLane <https://docs.pennylane.ai>`_ 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.
 
 .. header-end-inclusion-marker-do-not-remove
 
 
 Features
 ========
 
-* Combine PennyLane-Lightning's high performance simulators with PennyLane's
+* Combine Lightning's high performance simulators with PennyLane's
   automatic differentiation and optimization.
 
-.. installation-start-inclusion-marker-do-not-remove
+.. installation_LQubit-start-inclusion-marker-do-not-remove
 
 
-Installation
-============
+Lightning Qubit installation
+============================
 
-PennyLane-Lightning requires Python version 3.9 and above. It can be installed using ``pip``:
+Lightning Qubit can be installed using ``pip``:
 
 .. code-block:: console
 
     $ pip install pennylane-lightning
 
-To build PennyLane-Lightning from source you can run
+To build Lightning from source you can run
 
 .. code-block:: console
 
@@ -109,18 +110,6 @@ or with ``build_ext`` and the ``--define`` flag as follows:
     $ python3 setup.py develop
 
 
-GPU support
------------
-
-For GPU support, `PennyLane-Lightning-GPU <https://github.com/PennyLaneAI/pennylane-lightning-gpu>`_
-can be installed by providing the optional ``[gpu]`` tag:
-
-.. code-block:: console
-
-    $ pip install pennylane-lightning[gpu]
-
-For more information, please refer to the PennyLane Lightning GPU `documentation <https://docs.pennylane.ai/projects/lightning-gpu>`_.
-
 Testing
 -------
 
@@ -168,7 +157,7 @@ Other supported options are
 Compile on Windows with MSVC
 ----------------------------
 
-You can also compile Pennylane-Lightning on Windows using
+You can also compile Lightning on Windows using
 `Microsoft Visual C++ <https://visualstudio.microsoft.com/vs/features/cplusplus/>`_ compiler.
 You need `cmake <https://cmake.org/download/>`_ and appropriate Python environment
 (e.g. using `Anaconda <https://www.anaconda.com/>`_).
@@ -193,16 +182,110 @@ Then a common command will work.
 Note that OpenMP and BLAS are disabled in this setting.
 
 
-.. installation-end-inclusion-marker-do-not-remove
+.. installation_LQubit-end-inclusion-marker-do-not-remove
+
+
+.. installation_LKokkos-start-inclusion-marker-do-not-remove
+
+Lightning Kokkos installation
+=============================
+
+We suggest first installing Kokkos with the wanted configuration following the instructions found in the `Kokkos documentation <https://kokkos.github.io/kokkos-core-wiki/building.html>`_.
+Next, append the install location to ``CMAKE_PREFIX_PATH``.
+If an installation is not found, our builder will install it from scratch nevertheless.
+
+The simplest way to install PennyLane-Lightning-Kokkos (OpenMP backend) is using ``pip``.
+
+.. code-block:: console
+
+   CMAKE_ARGS="-DKokkos_ENABLE_OPENMP=ON" PL_BACKEND="lightning_kokkos" python -m pip install .
+
+or for an editable ``pip`` installation with:
+
+.. code-block:: console
+
+   CMAKE_ARGS="-DKokkos_ENABLE_OPENMP=ON" PL_BACKEND="lightning_kokkos" python -m pip install -e .
+
+Alternatively, you can install the Python interface with:
+
+.. code-block:: console
+
+   CMAKE_ARGS="-DKokkos_ENABLE_OPENMP=ON" PL_BACKEND="lightning_kokkos" python setup.py build_ext
+   python setup.py bdist_wheel
+   pip install ./dist/PennyLane*.whl --force-reinstall
+
+To build the plugin directly with CMake:
+
+.. code-block:: console
+
+   cmake -B build -DKokkos_ENABLE_OPENMP=ON -DPLKOKKOS_BUILD_TESTS=ON -DPL_BACKEND=lightning_kokkos -G Ninja
+   cmake --build build
+
+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 <https://github.com/kokkos/kokkos/wiki/Macros#architectures>`_.
+Note that "THREADS" backend is not recommended since `Kokkos <https://github.com/kokkos/kokkos-core-wiki/blob/17f08a6483937c26e14ec3c93a2aa40e4ce081ce/docs/source/ProgrammingGuide/Initialization.md?plain=1#L67>`_ does not guarantee its safety.
 
 
+Testing
+=======
+
+To test with the ROCm stack using a manylinux2014 container we must first mount the repository into the container:
+
+.. code-block:: console
+
+    docker run -v `pwd`:/io -it quay.io/pypa/manylinux2014_x86_64 bash
+
+Next, within the container, we install the ROCm software stack:
+
+.. code-block:: console
+
+    yum install -y https://repo.radeon.com/amdgpu-install/21.40.2/rhel/7.9/amdgpu-install-21.40.2.40502-1.el7.noarch.rpm
+    amdgpu-install --usecase=hiplibsdk,rocm --no-dkms
+
+We next build the test suite, with a given AMD GPU target in mind, as listed `here <https://github.com/kokkos/kokkos/blob/master/Makefile.kokkos>`_.
+
+.. code-block:: console
+
+    cd /io
+    export PATH=$PATH:/opt/rocm/bin/
+    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/rocm/lib
+    export CXX=/opt/rocm/hip/bin/hipcc
+    cmake -B build -DCMAKE_CXX_COMPILER=/opt/rocm/hip/bin/hipcc -DKokkos_ENABLE_HIP=ON -DPLKOKKOS_BUILD_TESTS=ON -DKokkos_ARCH_VEGA90A=ON
+    cmake --build build --verbose
+
+We may now leave the container, and run the built test suite on a machine with access to the targeted GPU.
+
+For a system with access to the ROCm stack outside of a manylinux container, an editable ``pip`` installation can be built and installed as:
+
+.. code-block:: console
+
+   CMAKE_ARGS="-DKokkos_ENABLE_HIP=ON -DKokkos_ARCH_VEGA90A=ON" PL_BACKEND="lightning_kokkos" python -m pip install -e .
+
+.. installation_LKokkos-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.
 
 
+GPU support
+-----------
+
+For GPU support, `PennyLane-Lightning-GPU <https://github.com/PennyLaneAI/pennylane-lightning-gpu>`_
+can be installed by providing the optional ``[gpu]`` tag:
+
+.. code-block:: console
+
+    $ pip install pennylane-lightning[gpu]
+
+For more information, please refer to the PennyLane Lightning GPU `documentation <https://docs.pennylane.ai/projects/lightning-gpu>`_.
+
 Docker Support
 --------------
-One can also build the Pennylane-Lightning image using Docker:
+
+One can also build the Lightning image using Docker:
 
 .. code-block:: console
 
@@ -237,9 +320,9 @@ Please make your best effort to comply with `black` and `pylint` before using di
 Authors
 =======
 
-PennyLane-Lightning is the work of `many contributors <https://github.com/PennyLaneAI/pennylane-lightning/graphs/contributors>`_.
+Lightning is the work of `many contributors <https://github.com/PennyLaneAI/pennylane-lightning/graphs/contributors>`_.
 
-If you are doing research using PennyLane and PennyLane-Lightning, please cite `our paper <https://arxiv.org/abs/1811.04968>`_:
+If you are doing research using PennyLane and Lightning, please cite `our paper <https://arxiv.org/abs/1811.04968>`_:
 
     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,

bin/cpp-files

@@ -0,0 +1,34 @@
+#!/usr/bin/python3
+
+import argparse
+import json
+import sys
+
+from utils import get_cpp_files
+
+
+if __name__ == '__main__':
+    """
+    This program output a json list of all C++ source files.
+    """
+    parser = argparse.ArgumentParser(
+        description="Output C/C++ files in json list"
+    )
+    parser.add_argument(
+        "--header-only", action='store_true', dest='header_only', help="whether only include header files"
+    )
+    parser.add_argument(
+        "paths", nargs="+", metavar="DIR", help="paths to the root source directories"
+    )
+    parser.add_argument(
+        "--exclude-dirs", dest="exclude_dirs", nargs="*", metavar="DIR", help="paths exclude from"
+    )
+
+    args = parser.parse_args()
+
+    files = set(get_cpp_files(args.paths, header_only = args.header_only))
+    if args.exclude_dirs:
+        files_excludes = set(get_cpp_files(args.exclude_dirs, header_only = args.header_only))
+        files -= files_excludes
+
+    json.dump(list(files), sys.stdout)

bin/format

@@ -3,9 +3,10 @@
 import argparse
 import json
 import re
+import shutil
 import subprocess
 import sys
-from cpp_files import get_cpp_files
+from utils import get_cpp_files
 
 CLANG_FMT_BIN = "clang-format"
 CLANG_FMT_STYLE_CFG = {
@@ -125,4 +126,4 @@ if __name__ == "__main__":
     else:
         ret = fmt(args, cf_cmd)
 
-    sys.exit(int(ret > 0))
+    sys.exit(int(ret > 0))

bin/cpp_files.py → bin/utils.py

@@ -66,4 +66,4 @@ def get_cpp_files(paths, ignore_patterns=None, use_gitignore=True, header_only=F
     files = set()
     for path in paths:
         files |= get_cpp_files_from_path(path, ignore_patterns, use_gitignore, header_only)
-    return list(files)
+    return list(files)

doc/benchmark.rst

@@ -11,27 +11,27 @@ You can benchmark different gate implementations inside the project.
 Then you can benchmark all gate operations in all kernels by running the script.
 
 .. code-block:: console
-   
+
     $ ./benchmarks/benchmark_all.sh
 
 The results will be recorded in ``bench_result.json`` file.
-You can then plot the results for a specific gate with 
+You can then plot the results for a specific gate with
 
 .. code-block:: console
-   
+
     $ ./benchmarks/plot_gate_benchmark.py ./bench_result.json
 
 It will create a plot for each gate operation comparing performance of kernels and floating point types. The plots can be found in ``plots`` subdirectory.
 
 One can also choose a specific datatype by providing an option:
 
 .. code-block:: console
-   
+
     $ ./benchmarks/plot_gate_benchmark.py --precision float ./bench_result.json # Results for std::complex<float>
     $ ./benchmarks/plot_gate_benchmark.py --precision double ./bench_result.json # Results for std::complex<double>
 
 
-Currently, we have two different kernels in ``Pennylane-Lightning`` named ``PI`` and ``LM``. For difference between two kernels, see the documents :cpp:class:`Pennylane::Gates::GateImplementationsPI` and :cpp:class:`Pennylane::Gates::GateImplementationsLM`.
+Currently, we have two different kernels in ``Lightning Qubit`` named ``PI`` and ``LM``. For difference between two kernels, see the documents :cpp:class:`Pennylane::Gates::GateImplementationsPI` and :cpp:class:`Pennylane::Gates::GateImplementationsLM`.
 
 Here are some example plots: