Add grouping module to docs #850

antalszava · 2020-10-14T22:00:57Z

Description of the Change:
Adds a description of the grouping subpackage to the Quantum operations page in the user-facing quickstart docs:

Added doc/code/qml_grouping.rst for subpackage description with modules
Added a short description and an example to doc/introduction/operations.rst
Renamed certain functions

Note: placed more mechanic updates of docstrings into #852 for ease of reviewing. That PR targets the branch of this PR. Therefore it can be worth considering that PR first.

codecov · 2020-10-14T22:38:56Z

Codecov Report

Merging #850 into master will increase coverage by 0.00%.
The diff coverage is 100.00%.

@@           Coverage Diff           @@
##           master     #850   +/-   ##
=======================================
  Coverage   97.79%   97.79%           
=======================================
  Files         136      137    +1     
  Lines        9201     9207    +6     
=======================================
+ Hits         8998     9004    +6     
  Misses        203      203

Impacted Files	Coverage Δ
pennylane/grouping/graph_colouring.py	`100.00% <ø> (ø)`
pennylane/grouping/__init__.py	`100.00% <100.00%> (ø)`
pennylane/grouping/group_observables.py	`100.00% <100.00%> (ø)`
pennylane/grouping/optimize_measurements.py	`92.30% <100.00%> (ø)`
pennylane/grouping/transformations.py	`100.00% <100.00%> (ø)`
pennylane/grouping/utils.py	`100.00% <100.00%> (ø)`

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 0119620...5ee57cb. Read the comment docs.

antalszava · 2020-10-16T00:47:36Z

doc/xanadu_theme/static/xanadu.css_t

@@ -109,6 +109,7 @@ h1 {
  /*border-bottom: 3px solid #D8E4EF;*/
  /*border-bottom: 3px solid #eee;*/
  padding-bottom: -29px;
+  word-wrap: break-word;


This is meant to wrap the long method/function names rendered in the docs

antalszava · 2020-10-16T00:49:17Z

pennylane/grouping/group_observables.py

@@ -17,10 +17,10 @@

 from pennylane.wires import Wires
 from pennylane.grouping.utils import (
-    convert_observables_to_binary_matrix,
+    observables_to_binary_matrix,


Sumarry of the renaming:
- diagonalize_qwc_grouping -> diagonalize_qwc_pauli_words
- obtain_qwc_post_rotations_and_diagonalized_groupings -> diagonalize_qwc_groupings
- convert_observables_to_binary_matrix -> observables_to_binary_matrix
- get_qwc_complement_adj_matrix -> qwc_complement_adj_matrix

Thanks @antalszava!

@co9olguy, for context as to why these were renamed: they include redundant terms (get, obtain, convert), and are too long - they were causing excessive horizontal scrolling and word wrapping in the documentation. The latter point wasn't evident until this PR, when they were added to the API documentation.

In particular, obtain_qwc_post_rotations_and_diagonalized_groupings was not displaying well in the documentation at all!

josh146

Thanks @antalszava! Since some of the functions are renamed, could you also update the changelog?

doc/code/qml_grouping.rst

josh146 · 2020-10-16T09:37:13Z

doc/introduction/operations.rst

+Grouping Pauli words
+^^^^^^^^^^^^^^^^^^^^
+
+Grouping Pauli words can be used for the optimizing the measurement of qubit
+Hamiltonians. Along with groups of observables, post measurement rotations can
+also be obtained using :func:`~.optimize_measurements`:
+
+.. code-block:: python
+
+    >>> obs = [qml.PauliY(0), qml.PauliX(0) @ qml.PauliX(1), qml.PauliZ(1)]
+    >>> coeffs = [1.43, 4.21, 0.97]
+    >>> post_rotations, diagonalized_groupings, grouped_coeffs = optimize_measurements(obs, coeffs)
+    >>> post_rotations
+    [[RY(-1.5707963267948966, wires=[0]), RY(-1.5707963267948966, wires=[1])],
+     [RX(1.5707963267948966, wires=[0])]]
+
+The post measurement rotations can be used to diagonalize the partitions of
+observables found.
+
+For further details on measurement optimization, graph coloring to be solved
+for grouping observables and auxiliary functions refer to the
+:doc:`/code/qml_grouping` subpackage.


👍 This looks great @antalszava. HIghlights that this functionality exists, but keeps it short, sweet, and succinct, which is how a quickstart should read (the quickstarts are reference guides, first and foremost, not tutorials).

If a user would like more information on the grouping functions, they can then refer to the qml.grouping module page.

doc/introduction/operations.rst

pennylane/grouping/group_observables.py

doc/code/qml_grouping.rst

josh146 · 2020-10-16T09:41:40Z

pennylane/grouping/group_observables.py

+        ValueError: if arguments specified for `grouping_type` or
+            `graph_colourer` are not recognized as elements of `GROUPING_TYPES` or
+            `GRAPH_COLOURING_METHODS` respectively


Note that GROUPING_TYPES and GRAPH_COLOURING_METHODS are not displayed in the documentation, so the user reading this will not know what the elements are. Perhaps they should be duplicated in the description of grouping_type and graph_colourer.

josh146 · 2020-10-16T09:42:11Z

pennylane/grouping/transformations.py

@@ -107,15 +107,15 @@ def diagonalize_pauli_word(pauli_word):
    return diag_term


-def diagonalize_qwc_grouping(qwc_grouping):
+def diagonalize_qwc_pauli_words(qwc_grouping):


👍 This definitely makes more sense after reading the first line of the docstring.

Co-authored-by: Josh Izaac <josh146@gmail.com>

pennylane/grouping/optimize_measurements.py

pennylane/grouping/__init__.py

doc/introduction/operations.rst

co9olguy · 2020-10-16T17:18:15Z

doc/introduction/operations.rst

+For further details on measurement optimization, graph coloring to be solved
+for grouping observables, and auxiliary functions, refer to the


The phrase "graph coloring to be solved for grouping observables" is a bit awkward (I wasn't sure what it meant). Suggest rephrasing (and using the Canadian spelling "colouring")

Good catch! Rephrased this part as For further details on measurement optimization, the minimum clique cover problem whose solution is used for grouping observables.

🤔 still seems to be a verb or something missing from the new phrasing

Had another go with it, let me know if it would be nice to further rephrase

doc/code/qml_grouping.rst

Co-authored-by: Nathan Killoran <co9olguy@users.noreply.github.com>

into grouping_in_docs

antalszava · 2020-10-16T18:23:10Z

@josh146 @co9olguy thank you so much for the many great suggestions! 🎊 Addressed them (maybe had one question for a minor suggestion).

antalszava · 2020-10-16T18:24:05Z

pennylane/grouping/group_observables.py

@@ -86,7 +90,7 @@ def __init__(self, observables, grouping_type="qwc", graph_colourer="rlf"):
        self.adj_matrix = None
        self.grouped_paulis = None

-    def obtain_binary_repr(self, n_qubits=None, wire_map=None):
+    def binary_repr(self, n_qubits=None, wire_map=None):


Removed obtain from the method names here for brevity

Co-authored-by: Nathan Killoran <co9olguy@users.noreply.github.com>

josh146

Looks great now @antalszava.

Note: I realized that the namespacing was a bit excessive (e.g., we didn't need qml.grouping.group_observables.group_observables). I fixed this in 42b4ba5 by importing all functions directly into grouping/__init__.py (with the exception of the graph_colouring functions, since the functions names are not descriptive enough).

Let me know what you think - if it looks okay, feel free to merge this in (as well as #852)

* New placements and renaming * Shorten names in example * Shorten names in example * Shorten names in example * Returns section indentation; no new line at the end of docstrings * Returns, raises formatting * Double back ticks * String options with double backticks * Double backticks in tests * Keyword args tidy * array[bool]->array[int] * scalar->float * Update pennylane/grouping/optimize_measurements.py Co-authored-by: Josh Izaac <josh146@gmail.com> * Indentation, double backticks * Minor updates * Class refs * Indentation * Update pennylane/grouping/graph_colouring.py Co-authored-by: Nathan Killoran <co9olguy@users.noreply.github.com> * Suggestion from code review Co-authored-by: Josh Izaac <josh146@gmail.com> Co-authored-by: Nathan Killoran <co9olguy@users.noreply.github.com>

antalszava added 3 commits October 14, 2020 17:59

Draft

a46fc25

Autosummary

da97aff

Adding rst for grouping subpackage

5b13c22

antalszava added 10 commits October 14, 2020 19:28

Further examples and description

5107c7e

Modification

861a2e3

Moving description to qml_grouping.rst

4f0db4d

Pruning description in quickstart doc

254aefa

Renaming diag functions

d4299d7

Further renaming

2fe0e9b

Mod ref

0ce9e4b

Module ref

de8a932

Add word wrap css for headers (h1)

82eccba

Rename functions in tests

464a9ac

antalszava commented Oct 16, 2020

View reviewed changes

arXiv links

7141b28

antalszava marked this pull request as ready for review October 16, 2020 01:10

antalszava requested review from josh146 and co9olguy October 16, 2020 01:12

antalszava mentioned this pull request Oct 16, 2020

Grouping subpackage docstring updates #852

Merged

josh146 reviewed Oct 16, 2020

View reviewed changes

antalszava and others added 8 commits October 16, 2020 13:01

Update doc/code/qml_grouping.rst

a736f7a

Co-authored-by: Josh Izaac <josh146@gmail.com>

Update doc/introduction/operations.rst

09eb5fe

Co-authored-by: Josh Izaac <josh146@gmail.com>

Update doc/code/qml_grouping.rst

23293d2

Co-authored-by: Josh Izaac <josh146@gmail.com>

Update doc/code/qml_grouping.rst

683f545

Co-authored-by: Josh Izaac <josh146@gmail.com>

Update doc/code/qml_grouping.rst

c153acc

Co-authored-by: Josh Izaac <josh146@gmail.com>

Update doc/code/qml_grouping.rst

c638fca

Co-authored-by: Josh Izaac <josh146@gmail.com>

Defining accepted grouping type and graph colourer; adjust docstring

10eece9

Renames for methods

fc8e660

co9olguy approved these changes Oct 16, 2020

View reviewed changes

antalszava and others added 9 commits October 16, 2020 13:32

Update pennylane/grouping/optimize_measurements.py

6afcbee

Co-authored-by: Nathan Killoran <co9olguy@users.noreply.github.com>

Hyphen

d0578db

Update doc/introduction/operations.rst

2b1a22b

Co-authored-by: Nathan Killoran <co9olguy@users.noreply.github.com>

Update doc/introduction/operations.rst

41e047c

Co-authored-by: Nathan Killoran <co9olguy@users.noreply.github.com>

Merge branch 'grouping_in_docs' of https://github.com/XanaduAI/pennylane

d718eb9

into grouping_in_docs

Use J for index set; rephrasing description

19c32c5

Suggested adjustments to docstrings

bd6e3d2

Shorten var names

58d8dda

Suggestions

cb63529

antalszava requested a review from thisac October 16, 2020 18:20

antalszava commented Oct 16, 2020

View reviewed changes

antalszava and others added 5 commits October 16, 2020 17:53

Update pennylane/grouping/__init__.py

b982895

Co-authored-by: Nathan Killoran <co9olguy@users.noreply.github.com>

Update doc/code/qml_grouping.rst

ff0a06f

Co-authored-by: Nathan Killoran <co9olguy@users.noreply.github.com>

Adding suggested dashes

ac63cc1

Adding suggested dashes in group_observables

5ee1d39

Update ref sentence

33d5494

antalszava requested a review from josh146 October 16, 2020 23:00

fixing namespacing

42b4ba5

josh146 approved these changes Oct 18, 2020

View reviewed changes

antalszava and others added 4 commits October 18, 2020 15:24

Merge branch 'master' into grouping_in_docs

035319c

Minor formatting updates

5ee57cb

update changelog

15492f3

josh146 merged commit 9d21ea4 into master Oct 19, 2020

josh146 deleted the grouping_in_docs branch October 19, 2020 05:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add grouping module to docs #850

Add grouping module to docs #850

antalszava commented Oct 14, 2020 •

edited

Loading

codecov bot commented Oct 14, 2020 •

edited

Loading

antalszava Oct 16, 2020

antalszava Oct 16, 2020

josh146 Oct 16, 2020 •

edited

Loading

josh146 left a comment

josh146 Oct 16, 2020

josh146 Oct 16, 2020

josh146 Oct 16, 2020

co9olguy Oct 16, 2020

antalszava Oct 16, 2020

co9olguy Oct 16, 2020

antalszava Oct 16, 2020

antalszava commented Oct 16, 2020

antalszava Oct 16, 2020 •

edited

Loading

josh146 left a comment

		For further details on measurement optimization, graph coloring to be solved
		for grouping observables, and auxiliary functions, refer to the

Add grouping module to docs #850

Add grouping module to docs #850

Conversation

antalszava commented Oct 14, 2020 • edited Loading

codecov bot commented Oct 14, 2020 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

josh146 Oct 16, 2020 • edited Loading

Choose a reason for hiding this comment

josh146 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

antalszava commented Oct 16, 2020

antalszava Oct 16, 2020 • edited Loading

Choose a reason for hiding this comment

josh146 left a comment

Choose a reason for hiding this comment

antalszava commented Oct 14, 2020 •

edited

Loading

codecov bot commented Oct 14, 2020 •

edited

Loading

josh146 Oct 16, 2020 •

edited

Loading

antalszava Oct 16, 2020 •

edited

Loading