Update Lightning API documentation #131

mlxd · 2021-08-13T13:42:18Z

Context: This PR ensures all classes, methods and free functions in lightning are documented with doxygen-parseable docstrings. The C++ API is also now built alongside the docs and accessible on the website. This also adds 2 sample C4 architecture diagrams to the documentation, following the Container and Component (levels 2 and 3) processes of the model.

Description of the Change:

Updates and adds docstrings for all required code.
Builds and hosts C++ API along-side existing documentation
Adds C4 architecture diagrams to explain current design of Lightning relative to PennyLane ecosystem.
Moves bindings to anon namespace to selectively scope API generation.

Benefits: Enables a more accessible and usable code-base.

Possible Drawbacks: More updates with future changes.

* Update method signatures for bound class (#125) * Add utility to get qubit number * Define gate overloads to enable run-time generalised calls * Update method signatures * Update changelog * Fix column major data layout in bindings (#126) * Fix column major data layout bindings * Update changelog * increment version, update changelog, gitignore a build folder * no Python version 3.6 * changelog for removing Python 3.6 * Revert "Fix column major data layout in bindings (#126)" This reverts commit 14ea923. * resolve changelog conflict * Update .github/CHANGELOG.md * Revert "Revert "Fix column major data layout in bindings (#126)"" This reverts commit 1de97e6. Co-authored-by: Lee James O'Riordan <[email protected]> Co-authored-by: Antal Szava <[email protected]>

github-actions · 2021-08-13T13:43:31Z

Hello. You may have forgotten to update the changelog!
Please edit .github/CHANGELOG.md with:

A one-to-two sentence description of the change. You may include a small working example for new features.
A link back to this PR.
Your name (or GitHub username) in the contributors section.

github-actions · 2021-08-13T13:44:33Z

Test Report (C++) on Ubuntu

    1 files ±0     1 suites ±0 0s ⏱️ ±0s
164 tests ±0 164 ✔️ ±0 0 💤 ±0 0 ❌ ±0
694 runs ±0 694 ✔️ ±0 0 💤 ±0 0 ❌ ±0

Results for commit 54c071d. ± Comparison against base commit 54c071d.

♻️ This comment has been updated with latest results.

codecov · 2021-08-13T13:44:49Z

Codecov Report

Merging #131 (42a9ab7) into master (cd37eab) will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff            @@
##            master      #131   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            3         3           
  Lines           71        71           
=========================================
  Hits            71        71

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update cd37eab...42a9ab7. Read the comment docs.

…AI/pennylane-lightning into 7077-update-docstrings

trbromley

Thanks @mlxd, looks really cool in the built docs!

Wonder why the lines are so close together:

trbromley · 2021-08-17T17:15:21Z

doc/_static/arch/system_containers_components.svg

+entity gates--><rect fill="#85BBF0" height="122" style="stroke:#78A8D8;stroke-width:1.5;" width="194" x="421" y="520.0999"/><text fill="#000000" font-family="sans-serif" font-size="12" font-style="italic" lengthAdjust="spacing" textLength="75" x="480.5" y="543.3">«component»</text><text fill="#000000" font-family="sans-serif" font-size="16" font-weight="bold" lengthAdjust="spacing" textLength="44" x="496" y="561.164">Gates</text><text fill="#000000" font-family="sans-serif" font-size="12" font-style="italic" lengthAdjust="spacing" textLength="29" x="503.5" y="578.7001">[C++]</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="0" x="520" y="594.7061"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="166" x="435" y="611.506">const/constexpr numerical</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="154" x="441" y="628.3059">representations of gates</text><!--MD5=[e400456b7abe4aecb77e08736a9f47d8]
+entity bindings--><rect fill="#85BBF0" height="122" style="stroke:#78A8D8;stroke-width:1.5;" width="208" x="47" y="767.0999"/><text fill="#000000" font-family="sans-serif" font-size="12" font-style="italic" lengthAdjust="spacing" textLength="75" x="113.5" y="790.3">«component»</text><text fill="#000000" font-family="sans-serif" font-size="16" font-weight="bold" lengthAdjust="spacing" textLength="69" x="116.5" y="808.164">Bindings</text><text fill="#000000" font-family="sans-serif" font-size="12" font-style="italic" lengthAdjust="spacing" textLength="87" x="107.5" y="825.7001">[C++, Pybind11]</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="0" x="153" y="841.7061"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="179" x="61.5" y="858.506">Binds C++ classes, methods</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="188" x="57" y="875.3059">and functions to Python layer.</text><!--MD5=[23e4898078453906b079a6bea7d1245c]
+entity developer--><rect fill="#08427B" height="122.6002" style="stroke:#073B6F;stroke-width:1.5;" width="163" x="141.5" y="28.5999"/><text fill="#FFFFFF" font-family="sans-serif" font-size="12" font-style="italic" lengthAdjust="spacing" textLength="52" x="197" y="51.8">«person»</text><image height="48" width="48" x="199" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADAAAAAwCAIAAADYYG7QAAABuUlEQVR42u2Yv0oEMRDGp/QRfIR7BVs7Gx9AH0CwtrtKLNXSRsRSG8HCxkbQVrSykoOrzlILC9v4gwMRNptMMsnu3nHDFMcSLh/f/PsmsrY5HpTLUgHaOri8uHt+eJm8vs/wm8e38fn9aPekB0D7p7df3z+uxYC4sXfWEaD17SPIcAqDreqAQBMgpmnHV091ASm5+W8EtxYgQuCyDF7LA+JPXa5RieUBwbwzWHlAVLIFEB2rMKCk4rK0AC0gZzN9/S8soOnHpwWQvhtpATE4h5XUlrKnIKp06uxCS5poCzs6stvjzuF1XfmRVG4ZkihHMSp5SuXGJGG5LEAVPSIpb4qJfIQzQeF6OMORGXSHbCjLuAb1CYhti7whQHQ5PLrlcHh+kiAyN/RxFE0/9OYvH+dJw33gw/nB4bYa5Ltmokl4MTXqMi+sMFtSfFBEDWoD67bUkPSa+d/Gk3i7i6tvxE4LyLhgGOeu9ELPXzLFAVHJrkNrZreUFfN28S9l1x27upVSLwp5hlIYFqBm8a8ADRxQJIfszy72ZxrpeKxGR6xnltEbupkbXtkpbQsh6ozhV8kDCni1dcT8F2bsoAKLcdt7AAAAAElFTkSuQmCC" y="54.8"/><text fill="#FFFFFF" font-family="sans-serif" font-size="16" font-weight="bold" lengthAdjust="spacing" textLength="139" x="151.5" y="117.664">Quantum software</text><text fill="#FFFFFF" font-family="sans-serif" font-size="16" font-weight="bold" lengthAdjust="spacing" textLength="76" x="185" y="136.864">developer</text><!--MD5=[c15c44eddbde3698217cfa31d0e69e09]
+entity python--><rect fill="#1168BD" height="89" style="stroke:#3C7FC0;stroke-width:1.5;" width="100" x="434" y="45.5999"/><text fill="#FFFFFF" font-family="sans-serif" font-size="12" font-style="italic" lengthAdjust="spacing" textLength="52" x="458" y="68.8">«system»</text><text fill="#FFFFFF" font-family="sans-serif" font-size="16" font-weight="bold" lengthAdjust="spacing" textLength="55" x="456.5" y="86.664">Python</text><text fill="#FFFFFF" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="0" x="486" y="104.006"/><text fill="#FFFFFF" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="76" x="448" y="120.8059">Python 3.7+</text><!--MD5=[6b6aa52bae2e86a2b9fe7e5e53b309bd]


Minor point, but this seems like one spot we'll easily miss when updating to Python 3.8

This will be auto-generated from the .puml files.

trbromley · 2021-08-17T17:16:32Z

doc/_static/arch/system_containers_components.svg

+link statevector to utils--><path d="M511,889.2399 C511,910.6899 511,934.9899 511,957.0599 " fill="none" id="statevector-to-utils" style="stroke:#666666;stroke-width:1.0;"/><polygon fill="#666666" points="511,965.0799,514,957.0799,508,957.0799,511,965.0799" style="stroke:#666666;stroke-width:1.0;"/><text fill="#666666" font-family="sans-serif" font-size="12" font-weight="bold" lengthAdjust="spacing" textLength="30" x="512" y="931.2479">Uses</text><!--MD5=[86ee14325d8f20ef134eb46f3a45fd7b]
+link tests to statevector--><path d="M736.82,364.3199 C718.45,427.4599 680.66,547.0099 633,642.0999 C612.47,683.0499 584.65,725.9299 560.76,760.0799 " fill="none" id="tests-to-statevector" style="stroke:#666666;stroke-width:1.0;"/><polygon fill="#666666" points="556.04,766.7899,563.0953,761.9708,558.1869,758.52,556.04,766.7899" style="stroke:#666666;stroke-width:1.0;"/><text fill="#666666" font-family="sans-serif" font-size="12" font-weight="bold" lengthAdjust="spacing" textLength="30" x="710" y="585.2479">Uses</text><!--MD5=[d24df83077560457d840ca07cbc44928]
+link tests to gates--><path d="M691.51,364.1199 C680.29,373.5499 668.94,383.7899 659,394.0999 C623.65,430.7599 589.02,476.2499 562.93,513.0699 " fill="none" id="tests-to-gates" style="stroke:#666666;stroke-width:1.0;"/><polygon fill="#666666" points="558.16,519.8399,565.2153,515.0208,560.3069,511.57,558.16,519.8399" style="stroke:#666666;stroke-width:1.0;"/><text fill="#666666" font-family="sans-serif" font-size="12" font-weight="bold" lengthAdjust="spacing" textLength="30" x="660" y="422.2479">Uses</text><!--MD5=[a5e167f4b651f4e4770e13973728820e]
+link other to default_qubit--><path d="M386.83,319.5999 C349.44,319.5999 306.39,319.5999 267.37,319.5999 " fill="none" id="other-to-default_qubit" style="stroke:#666666;stroke-width:1.0;"/><polygon fill="#666666" points="259.12,319.5999,267.12,322.5999,267.12,316.5999,259.12,319.5999" style="stroke:#666666;stroke-width:1.0;"/><text fill="#666666" font-family="sans-serif" font-size="12" font-weight="bold" lengthAdjust="spacing" textLength="30" x="308" y="280.7479">Uses</text><text fill="#666666" font-family="sans-serif" font-size="12" font-style="italic" lengthAdjust="spacing" textLength="88" x="277.5" y="297.2001">[Quantum circuit</text><text fill="#666666" font-family="sans-serif" font-size="12" font-style="italic" lengthAdjust="spacing" textLength="56" x="296.5" y="313.4002">backends]</text><!--MD5=[d07d7441133a84b5b8107f0baf4f554f]


What about "Quantum device"

Sure, that should work.

trbromley · 2021-08-17T17:17:51Z

doc/_static/arch/system_containers_components.svg

+link python to other--><!--MD5=[5765bccd7314636ac8a75b927a991b7b]
+link python to other--><path d="M484,134.6999 C484,172.5999 484,227.5499 484,267.4999 " fill="none" id="python-to-other" style="stroke:#666666;stroke-width:1.0;"/><polygon fill="#666666" points="484,275.5399,487,267.5399,481,267.5399,484,275.5399" style="stroke:#666666;stroke-width:1.0;"/><text fill="#666666" font-family="sans-serif" font-size="12" font-weight="bold" lengthAdjust="spacing" textLength="30" x="485" y="193.7479">Uses</text><!--MD5=[fe122ec3631594ac4371c7e119759707]
+link developer to python--><path d="M304.51,90.0999 C343.7,90.0999 389.78,90.0999 425.44,90.0999 " fill="none" id="developer-to-python" style="stroke:#666666;stroke-width:1.0;"/><polygon fill="#666666" points="433.8,90.0999,425.8,87.0999,425.8,93.0999,433.8,90.0999" style="stroke:#666666;stroke-width:1.0;"/><text fill="#666666" font-family="sans-serif" font-size="12" font-weight="bold" lengthAdjust="spacing" textLength="30" x="354.25" y="67.2479">Uses</text><text fill="#666666" font-family="sans-serif" font-size="12" font-style="italic" lengthAdjust="spacing" textLength="93" x="322.75" y="83.7001">[Win/MacOS/Lnx]</text><!--MD5=[db00fa398594d0e602e6a4e604277272]
+link default_qubit to lightning_qubit--><path d="M151,363.7399 C151,403.9899 151,464.6899 151,511.5599 " fill="none" id="default_qubit-to-lightning_qubit" style="stroke:#666666;stroke-width:1.0;"/><polygon fill="#666666" points="151,519.8499,154,511.8499,148,511.8499,151,519.8499" style="stroke:#666666;stroke-width:1.0;"/><text fill="#666666" font-family="sans-serif" font-size="12" font-weight="bold" lengthAdjust="spacing" textLength="118" x="158.5" y="406.2479">Ops and data pointer</text><text fill="#666666" font-family="sans-serif" font-size="12" font-style="italic" lengthAdjust="spacing" textLength="91" x="170.5" y="422.7001">[Provides default</text><text fill="#666666" font-family="sans-serif" font-size="12" font-style="italic" lengthAdjust="spacing" textLength="128" x="155" y="438.9002">Python plugin methods]</text><!--MD5=[e74efe3d600ba974dbb7e83863c41cd6]


What do we mean by "Ops and data pointer"?

Good point --- "Operations and pointer to data". I should be more explicit on this

trbromley · 2021-08-17T17:26:31Z

doc/arch/arch_overview.rst

+
+   <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++.


Suggested change

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++.

Lightning Qubit'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 the PennyLane device API, as only the gate-application is offloaded to C++.

Nice! Though going forward will we still be following the philosophy of just offloading gate application to C++? E.g., if we override the whole execute method.

I think this is something to update as the architecture settles in. Maybe "our current design" to signify the existing implementation?

trbromley · 2021-08-17T17:30:45Z

doc/arch/system_context.puml

+title System-level component diagram for PennyLane using Lightning Qubit device
+
+Person(developer, "Quantum software developer")
+System(python, "Python", "Python 3.7+")


Now I know that these are autogenerated from an easily-searcheable script, maybe putting Python 3.7 isn't so bad here!

trbromley · 2021-08-17T17:32:45Z

doc/devices.rst

+    ~pennylane.CRot
+    ~pennylane.CRX
+    ~pennylane.CRY
+    ~pennylane.CRZ


In the long run, maybe we shouldn't even have this list of supported ops! Every op should be supported ⚡ (and saves us having to maintain this)

Sure --- do you think this entire list can be pulled? Or should we opt for that later?

trbromley · 2021-08-17T17:34:37Z

pennylane_lightning/src/Bindings.cpp

@@ -18,45 +18,65 @@
 #include "pybind11/pybind11.h"
 #include "pybind11/stl.h"

+/// @cond DEV


What does this bit do? 🤔

This is understood as a conditional option for Doxygen --- anything within the @cond LABELNAME regions will be excluded for generating API docs. We should be publishing the binding API with the C++ API, so this just ensures that entire region is ignored.

trbromley · 2021-08-17T17:37:11Z

pennylane_lightning/src/Bindings.cpp

+ * @param numpyArray Numpy data array.
+ * @return StateVector<fp_t> `%StateVector` object.
+ */
+template <class fp_t = double>


What is the relevance of fp_t?

I had thought of using fp_t as floating point type template type, with a default value of double. Happy to rename if you think something more relevant makes sense.

albi3ro and others added 10 commits August 11, 2021 16:34

Update documentation for Python bindings

25c6321

Add docstrings to gate matrix definitions

73da0a1

Add docstrings for all publically facing statevector methods

914683a

Fix incorrectly labelled gatecalls

ef86d85

Update doxygen comments to ignore anon namespaces

f00efe0

Move exc into namespace

4bf2050

Update missing gates

989c005

Enable build of C++ API with docs

54e249b

Add C++ API to docs

9facb8a

mlxd requested review from thisac and trbromley and removed request for thisac August 13, 2021 13:42

Merge branch 'master' into 7077-update-docstrings

a45c9bd

mlxd and others added 12 commits August 13, 2021 16:03

Add C4 arch diagrams for lightning

5a19738

Add sample C4 architecture for lightning using current design

1e9d898

Merge branch '7077-update-docstrings' of https://github.com/PennyLane…

619d99a

…AI/pennylane-lightning into 7077-update-docstrings

Merge branch 'master' into 7077-update-docstrings

87b7f2d

Fix missing packages

ca0be68

Merge branch '7077-update-docstrings' of https://github.com/PennyLane…

2dea5d3

…AI/pennylane-lightning into 7077-update-docstrings

Update documentation architecture

0c42811

Prevent bindings from generating API docs

50f7cd9

Merge branch 'v0.17.0-rc0' into 7077-update-docstrings

90a767e

Update changelog

32651c2

Merge branch 'master' into 7077-update-docstrings

c052cf3

Merge branch 'master' into 7077-update-docstrings

42a9ab7

trbromley approved these changes Aug 17, 2021

View reviewed changes

mlxd merged commit 54c071d into master Aug 20, 2021

mlxd deleted the 7077-update-docstrings branch August 20, 2021 17:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update Lightning API documentation #131

Update Lightning API documentation #131

mlxd commented Aug 13, 2021 •

edited

Loading

github-actions bot commented Aug 13, 2021

github-actions bot commented Aug 13, 2021 •

edited

Loading

codecov bot commented Aug 13, 2021 •

edited

Loading

trbromley left a comment

trbromley Aug 17, 2021

mlxd Aug 18, 2021

trbromley Aug 17, 2021

mlxd Aug 18, 2021

trbromley Aug 17, 2021

mlxd Aug 18, 2021

trbromley Aug 17, 2021

trbromley Aug 17, 2021

mlxd Aug 18, 2021

trbromley Aug 17, 2021

trbromley Aug 17, 2021

trbromley Aug 17, 2021

mlxd Aug 18, 2021

trbromley Aug 17, 2021

mlxd Aug 18, 2021

trbromley Aug 17, 2021

mlxd Aug 18, 2021


		<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++.

	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++.
	Lightning Qubit'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 the PennyLane device API, as only the gate-application is offloaded to C++.

Update Lightning API documentation #131

Update Lightning API documentation #131

Conversation

mlxd commented Aug 13, 2021 • edited Loading

github-actions bot commented Aug 13, 2021

github-actions bot commented Aug 13, 2021 • edited Loading

Test Report (C++) on Ubuntu

codecov bot commented Aug 13, 2021 • edited Loading

Codecov Report

trbromley left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mlxd commented Aug 13, 2021 •

edited

Loading

github-actions bot commented Aug 13, 2021 •

edited

Loading

codecov bot commented Aug 13, 2021 •

edited

Loading