Update Lightning API documentation

.github/CHANGELOG.md

@@ -24,6 +24,12 @@
 
 ### Documentation
 
+* Added preliminary architecture diagram for package.
+  [(#131)](https://github.com/PennyLaneAI/pennylane-lightning/pull/131)
+
+* C++ API built as part of docs generation.
+  [(#131)](https://github.com/PennyLaneAI/pennylane-lightning/pull/131)
+
 ### Bug fixes
 
 * Column-major data in numpy is now correctly converted to row-major upon pass to the C++ layer.
@@ -104,7 +110,7 @@ Thomas Bromley, Lee James O'Riordan
 
 This release contains contributions from (in alphabetical order):
 
-Ali Asadi, Thomas Bromley, Lee James O'Riordan
+Ali Asadi, Christina Lee, Thomas Bromley, Lee James O'Riordan
 
 ---
 

doc/arch/arch_overview.rst

@@ -0,0 +1,34 @@
+Architecture overview
+=====================
+
+.. |br| raw:: html
+
+   <br />
+
+Lightning's purpose is to provide direct C++ kernels to manipulate the statevector data as created with PennyLane. Our design extends that of the "default.qubit" device in PennyLane, allowing direct access to the complex C-backed Numpy array data. This ensures we maintain all existing compatibility with PennyLane plugins, as only the gate-application is offloaded to C++.
+
+The following diagram represents the current architecture of Lightning using an adaption of the C4 container model.
+
+|br|
+
+.. image:: ../_static/arch/system_context.svg
+  :width: 600
+  :alt: Example of a tensor network.
+  :align: center
+
+|br|
+
+
+To understand the relationships between PennyLane, Lightning, and its components, we also present a component-level diagram. 
+
+|br|
+
+
+.. image:: ../_static/arch/system_containers_components.svg
+  :width: 600
+  :alt: Example of a tensor network.
+  :align: center
+
+|br|
+
+The interactions provided allow us to develop and extend functionality from PennyLane to Lightning, whilst providing a clear boundary between different parts of the system.

doc/arch/system_containers_components.puml

@@ -0,0 +1,50 @@
+@startuml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
+' uncomment the following line and comment the first to use locally
+' !include C4_Context.puml
+
+LAYOUT_TOP_DOWN()
+
+title Component-level diagram for PennyLane Lightning
+
+Person(developer, "Quantum software developer")
+System(python, "Python", "Python 3.7+")
+
+System(pennylane, "PennyLane", "PennyLane quantum simulation library")
+
+System_Boundary(pennylane, "PennyLane") {
+    Container(other, "Other", "Catch-all for rest of PennyLane library and tooling")
+    Container(default_qubit, "default.qubit", "PennyLane Python-only simulation device")
+
+    Container_Boundary(lightning, "lightning-qubit") {
+        Component(lightning_qubit, "lightning_qubit", "C++/Python", "Python module front-end for C++ operations")
+
+        Component(statevector, "StateVector", "C++", "C++ class for directly manipulating statevector data")
+        Component(utils, "Utils", "C++", "Helper utilities for C++ operations")
+        Component(gates, "Gates", "C++", "const/constexpr numerical representations of gates")
+        Component(bindings, "Bindings", "C++, Pybind11", "Binds C++ classes, methods and functions to Python layer.")
+    }
+}
+
+Rel(lightning_qubit, bindings, "Uses", "Bound methods wrapped to interface with PennyLane library")
+Rel_Neighbor(bindings, statevector, "Uses", "Wraps statevector to manipulate data using C++")
+Rel(statevector, utils, "Uses")
+
+System_Ext(tests, "Tests", "C++, CMake, Catch2")
+Rel(tests, statevector, "Uses")
+Rel(tests, gates, "Uses")
+
+Rel_Neighbor(other, default_qubit, "Uses", "Quantum circuit \n backends")
+Lay_L(other, default_qubit)
+
+Lay_D(python, other)
+
+Rel_Neighbor(developer, python, "Uses", "Win/MacOS/Lnx")
+
+Rel(python, other, "Uses")
+
+Rel(default_qubit, lightning_qubit, "Ops and data pointer", "Provides default \n Python plugin methods")
+
+@enduml

doc/arch/system_context.puml

@@ -0,0 +1,33 @@
+@startuml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+' uncomment the following line and comment the first to use locally
+' !include C4_Context.puml
+
+LAYOUT_TOP_DOWN()
+
+title System-level component diagram for PennyLane using Lightning Qubit device
+
+Person(developer, "Quantum software developer")
+System(python, "Python", "Python 3.7+")
+System(pennylane, "PennyLane", "PennyLane quantum simulation library")
+
+System_Boundary(pennylane, "PennyLane") {
+    Container(other, "Other", "Catch-all for rest of PennyLane library and tooling")
+    Container(default_qubit, "default.qubit", "PennyLane Python-only simulation device")
+
+    Container(lightning, "lightning.qubit", "PennyLane Lightning C++ simulation library ⚡")
+}
+
+System_Ext(tests, "Tests", "C++, CMake, Catch2")
+
+Rel_Neighbor(developer, python, "Uses", "Win/MacOS/Lnx")
+
+Rel_D(python, other, "Uses")
+
+Rel_Neighbor(default_qubit, other, "Catch-all for rest of PennyLane library and tools")
+Rel_D(default_qubit, lightning, "Ops and data pointer", "Provides default \n Python plugin methods")
+Rel(tests, lightning, "Uses", "Tests for C++ gate kernels")
+
+
+@enduml

doc/conf.py

@@ -11,7 +11,7 @@
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
-import sys, os, re
+import sys, os, re, inspect
 from unittest.mock import MagicMock
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -45,6 +45,8 @@ def __getattr__(cls, name):
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "breathe",
+    "exhale",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.todo",
@@ -65,6 +67,38 @@ def __getattr__(cls, name):
 automodapi_toctreedirnm = "code/api"
 automodsumm_inherited_members = True
 
+# Breathe extension
+breathe_projects = {"Lightning-Qubit": "./doxyoutput/xml"}
+breathe_default_project = "Lightning-Qubit"
+
+# Exhale extension
+# Setup the exhale extension
+exhale_args = {
+    # These arguments are required
+    "containmentFolder": "./api",
+    "rootFileName": "library_root.rst",
+    "rootFileTitle": "Overview",
+    "doxygenStripFromPath": "..",
+    # Suggested optional arguments
+    "createTreeView": True,
+    # TIP: if using the sphinx-bootstrap-theme, you need
+    # "treeViewIsBootstrap": True,
+    "exhaleExecutesDoxygen": True,
+    "exhaleDoxygenStdin": (
+        "INPUT = "
+        "../pennylane_lightning/src/Bindings.cpp "
+        "../pennylane_lightning/src/Gates.hpp "
+        "../pennylane_lightning/src/StateVector.hpp "
+        "../pennylane_lightning/src/Util.hpp"
+        "EXCLUDE_SYMBOLS = std::* "
+    ),
+    "afterTitleDescription": inspect.cleandoc(
+        """
+        The Pennylane Lightning C++ API is intended to be called from Python through Pybind11. Direct use of the C++ API is currently unsupported and is provided for reference only.
+        """
+    ),
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates', 'xanadu_theme']
 

doc/devices.rst

@@ -26,10 +26,16 @@ Supported operations and observables
 
     ~pennylane.BasisState
     ~pennylane.CNOT
+    ~pennylane.CRot
+    ~pennylane.CRX
+    ~pennylane.CRY
+    ~pennylane.CRZ
     ~pennylane.Hadamard
     ~pennylane.PauliX
     ~pennylane.PauliY
     ~pennylane.PauliZ
+    ~pennylane.PhaseShift
+    ~pennylane.ControlledPhaseShift
     ~pennylane.QubitStateVector
     ~pennylane.Rot
     ~pennylane.RX

doc/index.rst

@@ -29,6 +29,7 @@ PennyLane-Lightning provides the following device:
 
    installation
    support
+   Architecture <arch/arch_overview>
 
 .. toctree::
    :maxdepth: 2
@@ -43,3 +44,4 @@ PennyLane-Lightning provides the following device:
    :hidden:
 
    code/__init__
+   C++ API <api/library_root>

doc/requirements.txt

@@ -1,3 +1,6 @@
 docutils==0.16
 sphinx
 sphinx-automodapi
+breathe
+exhale
+pybind11