From eade88c5b381b953b87140c8105d6eb34da4973c Mon Sep 17 00:00:00 2001 From: Amintor Dusko <87949283+AmintorDusko@users.noreply.github.com> Date: Thu, 24 Aug 2023 11:41:35 -0400 Subject: [PATCH] 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... :notes: * 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 Co-authored-by: AmintorDusko --- .github/CHANGELOG.md | 4 + .github/workflows/format.yml | 2 +- .github/workflows/wheel_noarch.yml | 2 +- .readthedocs.yml | 4 +- Makefile | 9 +- README.rst | 135 ++++++++++++++---- bin/cpp-files | 34 +++++ bin/format | 5 +- bin/{cpp_files.py => utils.py} | 2 +- doc/_static/pennylane_lightning.png | Bin 0 -> 115944 bytes doc/avx_kernels/build_system.rst | 21 --- doc/benchmark.rst | 10 +- doc/code/__init__.rst | 28 +++- doc/conf.py | 16 +-- doc/index.rst | 29 ++-- doc/installation.rst | 29 +++- doc/lightning_kokkos/device.rst | 116 +++++++++++++++ doc/lightning_kokkos/installation.rst | 3 + doc/lightning_kokkos/package.rst | 19 +++ .../development/add_gate_kernel.rst} | 13 +- .../development/avx_kernels/build_system.rst | 28 ++++ .../avx_kernels/implementation.rst | 35 +++-- .../development}/avx_kernels/index.rst | 0 doc/lightning_qubit/development/index.rst | 24 ++++ .../device.rst} | 49 ++++++- doc/lightning_qubit/installation.rst | 3 + doc/lightning_qubit/package.rst | 18 +++ pennylane_lightning/core/_version.py | 2 +- pennylane_lightning/core/lightning_base.py | 3 - .../core/src/bindings/BindingsBase.hpp | 4 - .../gates/GateFunctorsGenerator.hpp | 4 +- .../gates/GateFunctorsNonparam.hpp | 4 +- .../gates/GateFunctorsParam.hpp | 4 +- .../measurements/ExpValFunctors.hpp | 6 +- .../gates/OpToMemberFuncPtr.hpp | 2 + .../cpu_kernels/GateImplementationsLM.hpp | 2 + .../lightning_kokkos/__init__.py | 2 +- .../lightning_kokkos/lightning_kokkos.py | 9 +- .../lightning_qubit/__init__.py | 2 +- .../lightning_qubit/lightning_qubit.py | 3 +- setup.py | 2 +- 41 files changed, 558 insertions(+), 129 deletions(-) create mode 100755 bin/cpp-files rename bin/{cpp_files.py => utils.py} (98%) create mode 100644 doc/_static/pennylane_lightning.png delete mode 100644 doc/avx_kernels/build_system.rst create mode 100644 doc/lightning_kokkos/device.rst create mode 100644 doc/lightning_kokkos/installation.rst create mode 100644 doc/lightning_kokkos/package.rst rename doc/{add_kernel.rst => lightning_qubit/development/add_gate_kernel.rst} (92%) create mode 100644 doc/lightning_qubit/development/avx_kernels/build_system.rst rename doc/{ => lightning_qubit/development}/avx_kernels/implementation.rst (76%) rename doc/{ => lightning_qubit/development}/avx_kernels/index.rst (100%) create mode 100644 doc/lightning_qubit/development/index.rst rename doc/{devices.rst => lightning_qubit/device.rst} (76%) create mode 100644 doc/lightning_qubit/installation.rst create mode 100644 doc/lightning_qubit/package.rst diff --git a/.github/CHANGELOG.md b/.github/CHANGELOG.md index 32719b3aa8..3f20b70f67 100644 --- a/.github/CHANGELOG.md +++ b/.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 diff --git a/.github/workflows/format.yml b/.github/workflows/format.yml index 80427b35fd..6cbde05023 100644 --- a/.github/workflows/format.yml +++ b/.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" diff --git a/.github/workflows/wheel_noarch.yml b/.github/workflows/wheel_noarch.yml index 819fa64f52..9b3bcb57be 100644 --- a/.github/workflows/wheel_noarch.yml +++ b/.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/ \ No newline at end of file diff --git a/.readthedocs.yml b/.readthedocs.yml index c05c7e9005..b571acaade 100644 --- a/.readthedocs.yml +++ b/.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 diff --git a/Makefile b/Makefile index 2138be1e4e..6461b935e3 100644 --- a/Makefile +++ b/Makefile @@ -115,4 +115,11 @@ ifdef target cmake --build ./BuildTidy $(VERBOSE) --target $(target) else cmake --build ./BuildTidy $(VERBOSE) -endif \ No newline at end of file +endif + +docs: + $(MAKE) -C doc html + +.PHONY : clean-docs +clean-docs: + $(MAKE) -C doc clean diff --git a/README.rst b/README.rst index 9d484d0778..8b406fc103 100644 --- a/README.rst +++ b/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,10 +35,11 @@ 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 `_ 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 @@ -46,22 +47,22 @@ learning, automatic differentiation, and optimization of hybrid quantum-classica 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 `_ -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 `_. - 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++ `_ compiler. You need `cmake `_ and appropriate Python environment (e.g. using `Anaconda `_). @@ -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 `_. +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 `_. +Note that "THREADS" backend is not recommended since `Kokkos `_ 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 `_. + +.. 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 `_ as well as to the `PennyLane documentation `_ for further reference. +GPU support +----------- + +For GPU support, `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 `_. + 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 `_. +Lightning is the work of `many contributors `_. -If you are doing research using PennyLane and PennyLane-Lightning, please cite `our paper `_: +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, diff --git a/bin/cpp-files b/bin/cpp-files new file mode 100755 index 0000000000..28e7586cda --- /dev/null +++ b/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) \ No newline at end of file diff --git a/bin/format b/bin/format index 17357876f4..2564ad9763 100755 --- a/bin/format +++ b/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)) \ No newline at end of file diff --git a/bin/cpp_files.py b/bin/utils.py similarity index 98% rename from bin/cpp_files.py rename to bin/utils.py index f33bf6a159..01925a42f7 100644 --- a/bin/cpp_files.py +++ b/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) \ No newline at end of file diff --git a/doc/_static/pennylane_lightning.png b/doc/_static/pennylane_lightning.png new file mode 100644 index 0000000000000000000000000000000000000000..d852fa857a61180f6b3d68228b13e587cf8ce14d GIT binary patch literal 115944 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 $ ./benchmarks/plot_gate_benchmark.py --precision double ./bench_result.json # Results for std::complex -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: diff --git a/doc/code/__init__.rst b/doc/code/__init__.rst index 0f400b1850..bf68bf024a 100644 --- a/doc/code/__init__.rst +++ b/doc/code/__init__.rst @@ -1,7 +1,7 @@ pennylane_lightning =================== -This section contains the API documentation for the PennyLane-Lightning plugin. +This section contains the API documentation for the Lightning packages. .. warning:: @@ -9,10 +9,28 @@ This section contains the API documentation for the PennyLane-Lightning plugin. to use these classes and functions directly. See the :doc:`overview ` page for more - details on using PennyLane-Lightning. + details on using Lightning. .. currentmodule:: pennylane_lightning -.. automodapi:: pennylane_lightning - :no-heading: - :include-all-objects: +.. title-card:: + :name: lightning_qubit + :description: API documentation for the lightning_qubit package + :link: ../lightning_qubit/package.html + + +.. title-card:: + :name: lightning_kokkos + :description: API documentation for the lightning_kokkos package + :link: ../lightning_kokkos/package.html + +.. raw:: html + +
+
+ +.. toctree:: + :hidden: + + ../lightning_qubit/package + ../lightning_kokkos/package diff --git a/doc/conf.py b/doc/conf.py index 628270647c..b4468233a8 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- # -# PennyLane-Lightning documentation build configuration file. +# Lightning documentation build configuration file. # # This file is execfile()d with the current directory set to its # containing dir. @@ -24,11 +24,10 @@ sys.path.insert(0, os.path.abspath("_ext")) sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath("doc")), "doc")) - # For obtaining all relevant C++ source files currdir = Path(__file__).resolve().parent # PROJECT_SOURCE_DIR/docs PROJECT_SOURCE_DIR = currdir.parent -CPP_SOURCE_DIR = PROJECT_SOURCE_DIR.joinpath("pennylane_lightning/src") +CPP_SOURCE_DIR = PROJECT_SOURCE_DIR.joinpath("pennylane_lightning/core/src") CPP_EXCLUDE_DIRS = ["tests", "benchmarks"] # relative to CPP_SOURCE_DIR @@ -63,7 +62,8 @@ def __getattr__(cls, name): return MagicMock() -MOCK_MODULES = ["pennylane_lightning.lightning_qubit_ops"] +MOCK_MODULES = ["pennylane_lightning.lightning_qubit_ops", + "pennylane_lightning.lightning_qubit_ops.algorithms"] mock = Mock() for mod_name in MOCK_MODULES: @@ -143,7 +143,7 @@ def __getattr__(cls, name): master_doc = "index" # General information about the project. -project = "PennyLane-Lightning" +project = "Lightning" copyright = "2023, Xanadu Quantum Technologies" author = "Xanadu Inc." @@ -153,10 +153,10 @@ def __getattr__(cls, name): # |version| and |release|, also used in various other places throughout the # built documents. -import pennylane_lightning +from pennylane_lightning import lightning_qubit # The full version, including alpha/beta/rc tags. -release = pennylane_lightning.__version__ +release = lightning_qubit.__version__ # The short X.Y version. version = re.match(r"^(\d+\.\d+)", release).expand(r"\1") @@ -208,7 +208,7 @@ def __getattr__(cls, name): # html theme options (see theme.conf for more information) html_theme_options = { - "navbar_name": "PennyLane-Lightning", + "navbar_name": "Lightning", "navbar_active_link": 3, "google_analytics_tracking_id": "G-C480Z9JL0D", "extra_copyrights": [ diff --git a/doc/index.rst b/doc/index.rst index 101426090c..c9316bd782 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,21 +1,32 @@ -PennyLane-Lightning Plugin -########################## +Lightning plugins +################# :Release: |release| +.. image:: _static/pennylane_lightning.png + :align: left + :width: 210px + :target: javascript:void(0); + .. include:: ../README.rst :start-after: header-start-inclusion-marker-do-not-remove :end-before: header-end-inclusion-marker-do-not-remove + Devices -======= +------- -PennyLane-Lightning provides the following device: +The Lightning ecosystem provides the following devices: .. title-card:: :name: 'lightning.qubit' :description: A fast state-vector qubit simulator written in C++ - :link: devices.html + :link: lightning_qubit/device.html + +.. title-card:: + :name: 'lightning.kokkos' + :description: A heterogeneous backend state-vector simulator with Kokkos library support. + :link: lightning_kokkos/device.html .. raw:: html @@ -29,23 +40,21 @@ PennyLane-Lightning provides the following device: installation support - Architecture .. toctree:: :maxdepth: 2 :caption: Usage :hidden: - devices + lightning_qubit/device + lightning_kokkos/device .. toctree:: :maxdepth: 2 :caption: Development :hidden: - add_kernel - benchmark - avx_kernels/index + lightning_qubit/development/index .. toctree:: :maxdepth: 1 diff --git a/doc/installation.rst b/doc/installation.rst index 2c42946a12..d89f62a24c 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -1,3 +1,26 @@ -.. include:: ../README.rst - :start-after: installation-start-inclusion-marker-do-not-remove - :end-before: installation-end-inclusion-marker-do-not-remove \ No newline at end of file +Installation +############ + +Each device in the Lightning ecosystem is a separate Python package. Select the device below for installation instructions: + +.. title-card:: + :name: Lightning Qubit + :description: Guidelines to installing and testing the Lightning Qubit device. + :link: ./lightning_qubit/installation.html + + +.. title-card:: + :name: Lightning Kokkos + :description: Guidelines to installing and testing the Lightning Kokkos device + :link: ./lightning_kokkos/installation.html + +.. raw:: html + +
+
+ +.. toctree:: + :hidden: + + lightning_qubit/installation + lightning_kokkos/installation diff --git a/doc/lightning_kokkos/device.rst b/doc/lightning_kokkos/device.rst new file mode 100644 index 0000000000..3c13fe41aa --- /dev/null +++ b/doc/lightning_kokkos/device.rst @@ -0,0 +1,116 @@ +Lightning Kokkos device +======================= + +The ``lightning.kokkos`` device can run using a variety of HPC-focused backends, including GPUs, +enabling accelerated simulation of quantum state-vector evolution. + +A ``lightning.kokkos`` device can be loaded using: + +.. code-block:: python + + import pennylane as qml + dev = qml.device("lightning.kokkos", wires=2) + +The ``lightning.kokkos`` device also directly supports quantum circuit gradients using the adjoint differentiation method. This can be enabled at the PennyLane QNode level with: + +.. code-block:: python + + qml.qnode(dev, diff_method="adjoint") + def circuit(params): + ... + +Check out the :doc:`/lightning_kokkos/installation` guide for more information. + +Supported operations and observables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Supported operations:** + +.. raw:: html + +
+ +.. autosummary:: + :nosignatures: + + ~pennylane.BasisState + ~pennylane.CNOT + ~pennylane.ControlledPhaseShift + ~pennylane.ControlledQubitUnitary + ~pennylane.CPhase + ~pennylane.CRot + ~pennylane.CRX + ~pennylane.CRY + ~pennylane.CRZ + ~pennylane.CSWAP + ~pennylane.CY + ~pennylane.CZ + ~pennylane.DiagonalQubitUnitary + ~pennylane.DoubleExcitation + ~pennylane.DoubleExcitationMinus + ~pennylane.DoubleExcitationPlus + ~pennylane.ECR + ~pennylane.Hadamard + ~pennylane.Identity + ~pennylane.IsingXX + ~pennylane.IsingXY + ~pennylane.IsingYY + ~pennylane.IsingZZ + ~pennylane.ISWAP + ~pennylane.MultiControlledX + ~pennylane.MultiRZ + ~pennylane.OrbitalRotation + ~pennylane.PauliX + ~pennylane.PauliY + ~pennylane.PauliZ + ~pennylane.PhaseShift + ~pennylane.PSWAP + ~pennylane.QFT + ~pennylane.QubitCarry + ~pennylane.QubitStateVector + ~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 + +
+ +**Supported 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.SparseHamiltonian + ~pennylane.ops.op_math.SProd + ~pennylane.ops.op_math.Sum + +.. raw:: html + +
\ No newline at end of file diff --git a/doc/lightning_kokkos/installation.rst b/doc/lightning_kokkos/installation.rst new file mode 100644 index 0000000000..08519319fd --- /dev/null +++ b/doc/lightning_kokkos/installation.rst @@ -0,0 +1,3 @@ +.. include:: ../../README.rst + :start-after: installation_LKokkos-start-inclusion-marker-do-not-remove + :end-before: installation_LKokkos-end-inclusion-marker-do-not-remove \ No newline at end of file diff --git a/doc/lightning_kokkos/package.rst b/doc/lightning_kokkos/package.rst new file mode 100644 index 0000000000..16b5f8a75d --- /dev/null +++ b/doc/lightning_kokkos/package.rst @@ -0,0 +1,19 @@ +lightning_kokkos +================ + +.. automodapi:: pennylane_lightning.lightning_kokkos + :no-heading: + :include-all-objects: + +.. raw:: html + +
+
+ +Directly importing the device class: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python3 + + from pennylane_lightning.lightning_kokkos import LightningKokkos + diff --git a/doc/add_kernel.rst b/doc/lightning_qubit/development/add_gate_kernel.rst similarity index 92% rename from doc/add_kernel.rst rename to doc/lightning_qubit/development/add_gate_kernel.rst index 2b677321cc..c4785ed358 100644 --- a/doc/add_kernel.rst +++ b/doc/lightning_qubit/development/add_gate_kernel.rst @@ -3,7 +3,9 @@ Adding a gate implementation ############################ -We discuss how one can add another gate implementation in this document. Assume that you want to add a custom ``PauliX`` gate implementation in Pennylane-Lightning. In this case, you may first create a file and add a class: +We discuss how one can add another gate implementation in this document. +Assume that you want to add a custom ``PauliX`` gate implementation in Lightning Qubit. +In this case, you may first create a file and add a class: .. code-block:: cpp @@ -16,7 +18,7 @@ We discuss how one can add another gate implementation in this document. Assume constexpr static kernel_id = KernelType::MyKernel; // Will be discussed below constexpr static std::string_view = "MyGateImpl"; // Name of your kernel - /* This defines the required alignment for this kernel. If there is no special requirement, + /* This defines the required alignment for this kernel. If there is no special requirement, using std::alignment_of_v is sufficient. */ template constexpr static size_t required_alignment = std::alignment_of_v; @@ -31,7 +33,8 @@ We discuss how one can add another gate implementation in this document. Assume } }; -Then you can add your gate implementation to Pennylane-Lightning. This can be done by modifying two files as: +Then you can add your gate implementation to Lightning Qubit. +This can be done by modifying two files: .. code-block:: cpp @@ -43,7 +46,7 @@ Then you can add your gate implementation to Pennylane-Lightning. This can be do } // namespace Pennylane -and +and .. code-block:: cpp @@ -97,7 +100,7 @@ to will make your implementation as default kernel for ``PauliX`` gate (for all C++ calls as well as for the Python binding). -Gate generators can also be handled in the same way. Note that it is possible to assign the kernel only for specific memory model or +Gate generators can also be handled in the same way. Note that it is possible to assign the kernel only for specific memory models or threading operations. Check overloaded functions :cpp:func:`Pennylane::KernelMap::OperationKernelMap::assignKernelForOp` for details. Test your gate implementation diff --git a/doc/lightning_qubit/development/avx_kernels/build_system.rst b/doc/lightning_qubit/development/avx_kernels/build_system.rst new file mode 100644 index 0000000000..575d9c9795 --- /dev/null +++ b/doc/lightning_qubit/development/avx_kernels/build_system.rst @@ -0,0 +1,28 @@ +AVX2/512 kernel build system +############################ + + +In Lightning Qubit, a kernel is registered to :cpp:class:`Pennylane::LightningQubit::DynamicDispatcher` +when the library is loaded, and it is used at runtime when it is the most suitable kernel for the given input. + +To support AVX2 and AVX512 kernels, we always compile those kernels if the target system is UNIX on x86-64. +Specifically, we made separate C++ files for AVX2 and AVX512 kernels and build them as a static library with the corresponding compile options. This is handled by CMake. One can check ``gates/CMakeLists.txt`` file for details. + +One caveat is that we want to make sure that default kernels (``KernelType::PI`` and ``KernelType::LM``) are only instantiated once with specific compiler flags during the compile process. +This is important as the linker sometimes cannot choose the right instantiation when there are multiple instantiations of the same template class. +This problem does not arise when all instantiations are compiled with the same options, but with the AVX2/512 kernels, we use different compile options for each translation unit. We solve this problem by adding explicit instantiation declarations in the header files for these kernels +(:ref:`file_pennylane_lightning_core_src_simulators_lightning_qubit_gates_cpu_kernels_GateImplementationsLM.hpp` and +:ref:`file_pennylane_lightning_core_src_simulators_lightning_qubit_gates_cpu_kernels_GateImplementationsPI.hpp`) +and compile them as a separate static library. + +With this, the AVX2/512 kernels are always included in the binary when compiled for UNIX-compatible OSs on x86-64 architecture. +However, we register these kernels to :cpp:class:`Pennylane::LightningQubit::DynamicDispatcher` only when the runtime environment supports these architecture sets. + +.. literalinclude:: ../../../../pennylane_lightning/core/src/simulators/lightning_qubit/gates/RegisterKernels_x64.cpp + :lines: 26-52 + +Likewise, we also inform :cpp:class:`Pennylane::KernelMap::OperationKernelMap` to use AVX2/512 kernels when aligned memory is used. + +.. literalinclude:: ../../../../pennylane_lightning/core/src/simulators/lightning_qubit/gates/KernelMap_X64.cpp + :lines: 33-50 + diff --git a/doc/avx_kernels/implementation.rst b/doc/lightning_qubit/development/avx_kernels/implementation.rst similarity index 76% rename from doc/avx_kernels/implementation.rst rename to doc/lightning_qubit/development/avx_kernels/implementation.rst index ab39f37e0a..12bdf6f8e6 100644 --- a/doc/avx_kernels/implementation.rst +++ b/doc/lightning_qubit/development/avx_kernels/implementation.rst @@ -3,11 +3,11 @@ AVX2/512 kernel implementation AVX2 and AVX512 are extensions to the x86 instruction set providing multiple data processing within a single instruction (SIMD; single instruction, multiple data), supported by modern Intel and AMD CPUs. AVX2 (AVX512) works with 256-bit (512-bit) registers and naturally supports different integer types (4 or 8 bytes) as well as floating point types (single or double precision). -Those instructions are accessible within C++ using intrinsic functions provided by compilers (Intel/GCC/Clang) [#f1]_. +Those instructions are accessible within C++ using intrinsic functions provided by compilers (Intel/GCC/Clang) [#f1]_. As an introduction to AVX2/512 intrinsic is out of the scope of this document, we recommend e.g. `this website `_ for an introduction and `Intel intrinsics guide `_ for a reference. -We now discuss how we use SIMD to implement quantum gate operations in PennyLane-Lightning. -When using SIMD, it is natural to consider data as a list of packed arrays, i.e. two dimensional array where each row has ``packed_size`` numbers. +We now discuss how we use SIMD to implement quantum gate operations in Lightning Qubit. +When using SIMD, it is natural to consider data as a list of packed arrays, i.e. two-dimensional array where each row has ``packed_size`` numbers. For example, let us consider a four-qubit quantum state :math:`C` (which has 16 complex numbers) and ``packed_size=8`` (when we use AVX512 with a double precision floating point or AVX2 with a single precision floating point). In this case, we can write down the statevector (coefficients in the computational basis) as +----------------+----------------+----------------+----------------+----------------+----------------+----------------+----------------+ @@ -34,11 +34,11 @@ We now consider an implementation of a single qubit gate. For simplicity, we use where :math:`\neg 0 = 1` and :math:`\neg 1 = 0` is the bit negation operator. -We see that the gates (1) on the second and the last wires (:math:`X_2` and :math:`X_3`) act within a row (internally in a packed array) but (2) on the zeroth and the first wires (:math:`X_0` and :math:`X_1`) act between rows (externally). -Specifically, the Pauli-X gate just permute the elements within a row in the former case (1) whereas it swaps the whole two rows in the latter case (2). +We see that the gates (1) on the second and the last wires (:math:`X_2` and :math:`X_3`) act within a row (internally in a packed array) but (2) on the zeroth and the first wires (:math:`X_0` and :math:`X_1`) act between rows (externally). +Specifically, the Pauli-X gate just permutes the elements within a row in the former case (1) whereas it swaps the whole two rows in the latter case (2). This implies that we need two independent implementations of the same gate depending on where the gate applies to. -Following simple (C++ style) pseudocode shows how the algorithm is implemented. +The following simple (C++ style) pseudocode shows how the algorithm is implemented. .. code-block:: @@ -47,7 +47,7 @@ Following simple (C++ style) pseudocode shows how the algorithm is implemented. template void applyInternal(...) { // Within a row - permtation = compute a permutation within a row for a given wire + permutation = compute a permutation within a row for a given wire for every row index { row = load a row from the memory permute elements in row using permutation @@ -65,10 +65,12 @@ Following simple (C++ style) pseudocode shows how the algorithm is implemented. } } -Note that this is a general high level code and does not care details such as how many elements in a row. -However, one can translate it to C++ code without runtime overhead with modern techniques (``constexpr`` and ``template`` classes/functions). One tricky part is how we implement permutations efficiently, which can be found in :ref:`namespace_Pennylane__Gates__AVXCommon__Permutation`. -As some AVX2/512 permutation functions require its permutation data to be a compile-time constant, we require `wire` to be a compile-time parameter for ``applyInternal``. -The full implementation of the functions can be found in :cpp:class:`Pennylane::Gates::AVXCommon::ApplyPauliX`. +Note that this is a general high-level code and does not care about details such as how many elements are in a row. +However, one can translate it to C++ code without runtime overhead with modern techniques (``constexpr`` and ``template`` classes/functions). One tricky part is how we implement permutations efficiently, +which can be found in :ref:`namespace_Pennylane__LightningQubit__Gates__AVXCommon__Permutation`. +As some AVX2/512 permutation functions require its permutation data to be a compile-time constant, we require ``wire`` to be a compile-time parameter for ``applyInternal``. +The full implementation of the functions can be found in +:cpp:class:`Pennylane::LightningQubit::Gates::AVXCommon::ApplyPauliX`. Choosing an appropriate function @@ -77,7 +79,7 @@ Choosing an appropriate function When such a function is given, we can choose a proper function to call for a given statevector and a wire. For example, we can simply write as follows. .. code-block:: cpp - + void applyPauliX(num_qubits, wire, ...) { if (2**num_qubits < packed_size / 2) { // data size is smaller than the size of a row @@ -100,15 +102,18 @@ When such a function is given, we can choose a proper function to call for a giv Note that we used a switch-case statement for calling internal functions as the wire index must be a compile-time template parameter for ``applyInternal``. Since all single-qubit gate functions share the same structure, it might be beneficial to make a simple helper function that automatically finds a target function depending on the given information. -Two classes :cpp:class:`Pennylane::Gates::AVXCommon::SingleQubitGateWithParamHelper` and :cpp:class:`Pennylane::Gates::AVXCommon::SingleQubitGateWithoutParamHelper` provide such functionality for a single-qubit gate with and without parameters, respectively. +Two classes :cpp:class:`Pennylane::LightningQubit::Gates::AVXCommon::SingleQubitGateWithParamHelper` and :cpp:class:`Pennylane::LightningQubit::Gates::AVXCommon::SingleQubitGateWithoutParamHelper` provide such functionality for a single-qubit gate with and without parameters, respectively. Two-qubit gates --------------- -Two qubit gates are also implemented in the same way. It is slightly more involved as there are four different cases depending on the wires. So we implement 4 (or 3 when the gate acts symmetrically on the wires) functions. See :cpp:class:`Pennylane::Gates::AVXCommon::ApplyCNOT` for example. +Two qubit gates are also implemented in the same way. +It is slightly more involved as there are four different cases depending on the wires. +So we implement 4 (or 3 when the gate acts symmetrically on the wires) functions. +See :cpp:class:`Pennylane::LightningQubit::Gates::AVXCommon::ApplyCNOT` for example. .. rubric:: Footnotes -.. [#f1] Still, note that each intrinsic function does not necceassary be a single instruction after compiliation as the number of SIMD registers are limited. Thus compilers handle these optimizations. +.. [#f1] Still, note that each intrinsic function will not necessarily be a single instruction after compilation, as the number of SIMD registers is limited. Thus compilers handle these optimizations. diff --git a/doc/avx_kernels/index.rst b/doc/lightning_qubit/development/avx_kernels/index.rst similarity index 100% rename from doc/avx_kernels/index.rst rename to doc/lightning_qubit/development/avx_kernels/index.rst diff --git a/doc/lightning_qubit/development/index.rst b/doc/lightning_qubit/development/index.rst new file mode 100644 index 0000000000..7eb4a918e4 --- /dev/null +++ b/doc/lightning_qubit/development/index.rst @@ -0,0 +1,24 @@ +Lightning Qubit +############### + +.. title-card:: + :name: Adding gate implementations + :description: How to add additional gate implementations + :link: ./add_gate_kernel.html + + +.. title-card:: + :name: AVX2/512 kernels + :description: Development documentation for AVX2/512 Kernels + :link: ./avx_kernels/index.html + +.. raw:: html + +
+
+ +.. toctree:: + :hidden: + + avx_kernels/index + add_gate_kernel diff --git a/doc/devices.rst b/doc/lightning_qubit/device.rst similarity index 76% rename from doc/devices.rst rename to doc/lightning_qubit/device.rst index 10b6aab1c7..3aba8e5e64 100644 --- a/doc/devices.rst +++ b/doc/lightning_qubit/device.rst @@ -1,8 +1,7 @@ Lightning Qubit device ====================== -The ``lightning.qubit`` device is an extension of PennyLane's built-in ``default.qubit`` device. -It uses a custom-built backend to +The ``lightning.qubit`` device uses a custom-built backend to perform fast linear algebra calculations for simulating quantum state-vector evolution. A ``lightning.qubit`` device can be loaded using: @@ -12,6 +11,8 @@ A ``lightning.qubit`` device can be loaded using: import pennylane as qml dev = qml.device("lightning.qubit", wires=2) +Check out the :doc:`/lightning_qubit/installation` guide for more information. + Supported operations and observables ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -26,23 +27,55 @@ Supported operations and observables ~pennylane.BasisState ~pennylane.CNOT + ~pennylane.ControlledPhaseShift + ~pennylane.ControlledQubitUnitary + ~pennylane.CPhase ~pennylane.CRot ~pennylane.CRX ~pennylane.CRY ~pennylane.CRZ + ~pennylane.CSWAP + ~pennylane.CY + ~pennylane.CZ + ~pennylane.DiagonalQubitUnitary + ~pennylane.DoubleExcitation + ~pennylane.DoubleExcitationMinus + ~pennylane.DoubleExcitationPlus + ~pennylane.ECR ~pennylane.Hadamard + ~pennylane.Identity + ~pennylane.IsingXX + ~pennylane.IsingXY + ~pennylane.IsingYY + ~pennylane.IsingZZ + ~pennylane.ISWAP + ~pennylane.MultiControlledX + ~pennylane.MultiRZ + ~pennylane.OrbitalRotation ~pennylane.PauliX ~pennylane.PauliY ~pennylane.PauliZ ~pennylane.PhaseShift - ~pennylane.ControlledPhaseShift + ~pennylane.PSWAP + ~pennylane.QFT + ~pennylane.QubitCarry ~pennylane.QubitStateVector + ~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 @@ -57,11 +90,19 @@ Supported operations and observables .. 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.Projector + ~pennylane.SparseHamiltonian + ~pennylane.ops.op_math.SProd + ~pennylane.ops.op_math.Sum .. raw:: html @@ -112,7 +153,7 @@ The ``lightning.qubit`` device allows users to use the Markov Chain Monte Carlo import pennylane as qml dev = qml.device("lightning.qubit", wires=2, shots=1000, mcmc=True) -By default, the ``kernel_name`` is ``"Local"`` and ``num_burnin`` is ``100``. The local kernel conducts a bit-flip local transition between states. The local kernel generates a random qubit site and then generates a random number to determine the new bit at that qubit site. +By default, the ``kernel_name`` is ``"Local"`` and ``num_burnin`` is ``100``. The local kernel conducts a bit-flip local transition between states. The local kernel generates a random qubit site and then generates a random number to determine the new bit at that qubit site. The ``lightning.qubit`` device also supports a ``"NonZeroRandom"`` kernel. This kernel randomly transits between states that have nonzero probability. It can be enabled by initializing the device as: diff --git a/doc/lightning_qubit/installation.rst b/doc/lightning_qubit/installation.rst new file mode 100644 index 0000000000..e73525d5df --- /dev/null +++ b/doc/lightning_qubit/installation.rst @@ -0,0 +1,3 @@ +.. include:: ../../README.rst + :start-after: installation_LQubit-start-inclusion-marker-do-not-remove + :end-before: installation_LQubit-end-inclusion-marker-do-not-remove \ No newline at end of file diff --git a/doc/lightning_qubit/package.rst b/doc/lightning_qubit/package.rst new file mode 100644 index 0000000000..7c25d5428b --- /dev/null +++ b/doc/lightning_qubit/package.rst @@ -0,0 +1,18 @@ +lightning_qubit +=============== + +.. automodapi:: pennylane_lightning.lightning_qubit + :no-heading: + :include-all-objects: + +.. raw:: html + +
+
+ +Directly importing the device class: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python3 + + from pennylane_lightning.lightning_qubit import LightningQubit \ No newline at end of file diff --git a/pennylane_lightning/core/_version.py b/pennylane_lightning/core/_version.py index 3a4a0472e8..d750d3d2a1 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.32.0-dev10" +__version__ = "0.32.0-dev11" diff --git a/pennylane_lightning/core/lightning_base.py b/pennylane_lightning/core/lightning_base.py index ca1ef0b40d..a6d5650fe3 100644 --- a/pennylane_lightning/core/lightning_base.py +++ b/pennylane_lightning/core/lightning_base.py @@ -48,9 +48,6 @@ class LightningBase(QubitDevice): This intermediate base class provides device-agnostic functionalities. - Use of this device requires pre-built binaries or compilation from source. Check out the - :doc:`/installation` guide for more details. - Args: wires (int): the number of wires to initialize the device with c_dtype: Datatypes for statevector representation. Must be one of diff --git a/pennylane_lightning/core/src/bindings/BindingsBase.hpp b/pennylane_lightning/core/src/bindings/BindingsBase.hpp index 4f0e0357b2..eeb270d646 100644 --- a/pennylane_lightning/core/src/bindings/BindingsBase.hpp +++ b/pennylane_lightning/core/src/bindings/BindingsBase.hpp @@ -24,10 +24,6 @@ #include "ConstantUtil.hpp" // lookup #include "GateOperation.hpp" -/// @cond DEV -namespace {} // namespace -/// @endcond - namespace py = pybind11; namespace Pennylane::Bindings { diff --git a/pennylane_lightning/core/src/simulators/lightning_kokkos/gates/GateFunctorsGenerator.hpp b/pennylane_lightning/core/src/simulators/lightning_kokkos/gates/GateFunctorsGenerator.hpp index c2ce5e3f70..eea42d7937 100644 --- a/pennylane_lightning/core/src/simulators/lightning_kokkos/gates/GateFunctorsGenerator.hpp +++ b/pennylane_lightning/core/src/simulators/lightning_kokkos/gates/GateFunctorsGenerator.hpp @@ -18,10 +18,12 @@ #include "BitUtil.hpp" +/// @cond DEV namespace { using namespace Pennylane::Util; using Kokkos::Experimental::swap; } // namespace +/// @endcond namespace Pennylane::LightningKokkos::Functors { template @@ -970,4 +972,4 @@ template struct generatorMultiRZFunctor { 1 - 2 * int(Kokkos::Impl::bit_count(k & wires_parity) % 2)); } }; -} // namespace Pennylane::LightningKokkos::Functors +} // namespace Pennylane::LightningKokkos::Functors \ No newline at end of file diff --git a/pennylane_lightning/core/src/simulators/lightning_kokkos/gates/GateFunctorsNonparam.hpp b/pennylane_lightning/core/src/simulators/lightning_kokkos/gates/GateFunctorsNonparam.hpp index a9cfef33f6..0dd5a386a6 100644 --- a/pennylane_lightning/core/src/simulators/lightning_kokkos/gates/GateFunctorsNonparam.hpp +++ b/pennylane_lightning/core/src/simulators/lightning_kokkos/gates/GateFunctorsNonparam.hpp @@ -18,10 +18,12 @@ #include "BitUtil.hpp" +/// @cond DEV namespace { using namespace Pennylane::Util; using Kokkos::Experimental::swap; } // namespace +/// @endcond namespace Pennylane::LightningKokkos::Functors { template struct hadamardFunctor { @@ -524,4 +526,4 @@ template struct toffoliFunctor { } }; -} // namespace Pennylane::LightningKokkos::Functors +} // namespace Pennylane::LightningKokkos::Functors \ No newline at end of file diff --git a/pennylane_lightning/core/src/simulators/lightning_kokkos/gates/GateFunctorsParam.hpp b/pennylane_lightning/core/src/simulators/lightning_kokkos/gates/GateFunctorsParam.hpp index 32d25f9c17..727c96faa0 100644 --- a/pennylane_lightning/core/src/simulators/lightning_kokkos/gates/GateFunctorsParam.hpp +++ b/pennylane_lightning/core/src/simulators/lightning_kokkos/gates/GateFunctorsParam.hpp @@ -18,11 +18,13 @@ #include "BitUtil.hpp" +/// @cond DEV namespace { using namespace Pennylane::Util; using Kokkos::Experimental::swap; using std::size_t; } // namespace +/// @endcond namespace Pennylane::LightningKokkos::Functors { template struct singleQubitOpFunctor { @@ -1685,4 +1687,4 @@ template struct rotFunctor { } }; -} // namespace Pennylane::LightningKokkos::Functors +} // namespace Pennylane::LightningKokkos::Functors \ No newline at end of file diff --git a/pennylane_lightning/core/src/simulators/lightning_kokkos/measurements/ExpValFunctors.hpp b/pennylane_lightning/core/src/simulators/lightning_kokkos/measurements/ExpValFunctors.hpp index 3a16fb2b74..0526014f33 100644 --- a/pennylane_lightning/core/src/simulators/lightning_kokkos/measurements/ExpValFunctors.hpp +++ b/pennylane_lightning/core/src/simulators/lightning_kokkos/measurements/ExpValFunctors.hpp @@ -17,9 +17,11 @@ #include "BitUtil.hpp" +/// @cond DEV namespace { using namespace Pennylane::Util; -} +} // namespace +/// @endcond namespace Pennylane::LightningKokkos::Functors { template struct getExpectationValueIdentityFunctor { @@ -283,4 +285,4 @@ template struct getExpectationValueSparseFunctor { } }; -} // namespace Pennylane::LightningKokkos::Functors +} // namespace Pennylane::LightningKokkos::Functors \ No newline at end of file diff --git a/pennylane_lightning/core/src/simulators/lightning_qubit/gates/OpToMemberFuncPtr.hpp b/pennylane_lightning/core/src/simulators/lightning_qubit/gates/OpToMemberFuncPtr.hpp index 899b8e4131..60cd0c7746 100644 --- a/pennylane_lightning/core/src/simulators/lightning_qubit/gates/OpToMemberFuncPtr.hpp +++ b/pennylane_lightning/core/src/simulators/lightning_qubit/gates/OpToMemberFuncPtr.hpp @@ -26,10 +26,12 @@ #include "Error.hpp" #include "GateOperation.hpp" +/// @cond DEV namespace { using namespace Pennylane::Gates; using Pennylane::Gates::GateOperation; } // namespace +/// @endcond namespace Pennylane::LightningQubit::Gates { /** diff --git a/pennylane_lightning/core/src/simulators/lightning_qubit/gates/cpu_kernels/GateImplementationsLM.hpp b/pennylane_lightning/core/src/simulators/lightning_qubit/gates/cpu_kernels/GateImplementationsLM.hpp index 92ac289811..58cd4a98f8 100644 --- a/pennylane_lightning/core/src/simulators/lightning_qubit/gates/cpu_kernels/GateImplementationsLM.hpp +++ b/pennylane_lightning/core/src/simulators/lightning_qubit/gates/cpu_kernels/GateImplementationsLM.hpp @@ -30,11 +30,13 @@ #include "PauliGenerator.hpp" #include "Util.hpp" // exp2, INVSQRT2 +/// @cond DEV namespace { using namespace Pennylane::Gates; using Pennylane::Util::exp2; using Pennylane::Util::INVSQRT2; } // namespace +/// @endcond namespace Pennylane::LightningQubit::Gates { /** diff --git a/pennylane_lightning/lightning_kokkos/__init__.py b/pennylane_lightning/lightning_kokkos/__init__.py index e46250ec3f..73db3196de 100644 --- a/pennylane_lightning/lightning_kokkos/__init__.py +++ b/pennylane_lightning/lightning_kokkos/__init__.py @@ -11,7 +11,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -"""PennyLane lightning kokkos module.""" +"""PennyLane lightning_kokkos package.""" from pennylane_lightning.core import __version__ from .lightning_kokkos import LightningKokkos diff --git a/pennylane_lightning/lightning_kokkos/lightning_kokkos.py b/pennylane_lightning/lightning_kokkos/lightning_kokkos.py index f7ae13b619..724f60555e 100644 --- a/pennylane_lightning/lightning_kokkos/lightning_kokkos.py +++ b/pennylane_lightning/lightning_kokkos/lightning_kokkos.py @@ -16,6 +16,7 @@ This module contains the :class:`~.LightningQubit` class, a PennyLane simulator device that interfaces with C++ for fast linear algebra calculations. """ + from warnings import warn import numpy as np @@ -164,7 +165,7 @@ class LightningKokkos(LightningBase): A device that interfaces with C++ to perform fast linear algebra calculations. Use of this device requires pre-built binaries or compilation from source. Check out the - :doc:`/installation` guide for more details. + :doc:`/lightning_kokkos/installation` guide for more details. Args: wires (int): the number of wires to initialize the device with @@ -263,12 +264,12 @@ def sync_h2d(self, state_vector): **Example** + >>> dev = qml.device('lightning.kokkos', wires=3) >>> obs = qml.Identity(0) @ qml.PauliX(1) @ qml.PauliY(2) >>> obs1 = qml.Identity(1) >>> H = qml.Hamiltonian([1.0, 1.0], [obs1, obs]) - >>> state_vector = np.array([0.0 + 0.0j, 0.0 + 0.1j, 0.1 + 0.1j, 0.1 + 0.2j, - 0.2 + 0.2j, 0.3 + 0.3j, 0.3 + 0.4j, 0.4 + 0.5j,], dtype=np.complex64,) + >>> state_vector = np.array([0.0 + 0.0j, 0.0 + 0.1j, 0.1 + 0.1j, 0.1 + 0.2j, 0.2 + 0.2j, 0.3 + 0.3j, 0.3 + 0.4j, 0.4 + 0.5j,], dtype=np.complex64) >>> dev.sync_h2d(state_vector) >>> res = dev.expval(H) >>> print(res) @@ -285,6 +286,7 @@ def sync_d2h(self, state_vector): **Example** + >>> dev = qml.device('lightning.kokkos', wires=1) >>> dev.apply([qml.PauliX(wires=[0])]) >>> state_vector = np.zeros(2**dev.num_wires).astype(dev.C_DTYPE) @@ -317,6 +319,7 @@ def state(self): the data. **Example** + >>> dev = qml.device('lightning.kokkos', wires=1) >>> dev.apply([qml.PauliX(wires=[0])]) >>> print(dev.state) diff --git a/pennylane_lightning/lightning_qubit/__init__.py b/pennylane_lightning/lightning_qubit/__init__.py index 8bf59b036f..53e50cbf00 100644 --- a/pennylane_lightning/lightning_qubit/__init__.py +++ b/pennylane_lightning/lightning_qubit/__init__.py @@ -11,7 +11,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -"""PennyLane lightning qubit module.""" +"""PennyLane lightning_qubit package.""" from pennylane_lightning.core import __version__ from .lightning_qubit import LightningQubit diff --git a/pennylane_lightning/lightning_qubit/lightning_qubit.py b/pennylane_lightning/lightning_qubit/lightning_qubit.py index b7b6e475fc..0d5aff4b5e 100644 --- a/pennylane_lightning/lightning_qubit/lightning_qubit.py +++ b/pennylane_lightning/lightning_qubit/lightning_qubit.py @@ -16,6 +16,7 @@ This module contains the :class:`~.LightningQubit` class, a PennyLane simulator device that interfaces with C++ for fast linear algebra calculations. """ + from warnings import warn import numpy as np @@ -156,7 +157,7 @@ class LightningQubit(LightningBase): A device that interfaces with C++ to perform fast linear algebra calculations. Use of this device requires pre-built binaries or compilation from source. Check out the - :doc:`/installation` guide for more details. + :doc:`/lightning_qubit/installation` guide for more details. Args: wires (int): the number of wires to initialize the device with diff --git a/setup.py b/setup.py index 1337b8a6f2..2e39e430d8 100644 --- a/setup.py +++ b/setup.py @@ -197,7 +197,7 @@ def build_extension(self, ext: CMakeExtension): "entry_points": {"pennylane.plugins": pennylane_plugins}, "description": "PennyLane-Lightning plugin", "long_description": open("README.rst").read(), - "long_description_content_type": "text/markdown", + "long_description_content_type": "text/x-rst", "install_requires": requirements, "ext_modules": [] if os.environ.get("SKIP_COMPILATION", False)