[QAOA] Adds Built-In MaxCut Cost Hamiltonian #718

Lucaman99 · 2020-07-22T18:48:15Z

Context:

Part of the new PennyLane QAOA functionality.

Description of the Change:

Adds a built-in MaxCut cost Hamiltonian and tests.

Benefits:

Possible Drawbacks:

Related GitHub Issues:

codecov · 2020-07-22T18:50:49Z

Codecov Report

Merging #718 into master will increase coverage by 0.01%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##           master     #718      +/-   ##
==========================================
+ Coverage   95.47%   95.48%   +0.01%     
==========================================
  Files         109      110       +1     
  Lines        6813     6829      +16     
==========================================
+ Hits         6505     6521      +16     
  Misses        308      308

Impacted Files	Coverage Δ
pennylane/qaoa/__init__.py	`100.00% <100.00%> (ø)`
pennylane/qaoa/cost.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 485677c...e05b762. Read the comment docs.

ixfoduap

Looks great! Just missing usage details

ixfoduap · 2020-07-30T19:06:53Z

pennylane/qaoa/cost.py

+    find the cut of the graph such that the number of edges crossing the cut is maximized
+    (see `Cut (graph theory) <https://en.wikipedia.org/wiki/Cut_(graph_theory)>`__).
+
+    Recommended mixer Hamiltonian: ~.qaoa.x_mixer


I love this! Like a wine pairing in a restaurant menu 🍷 🍝

pennylane/qaoa/cost.py

josh146

Nice work @Lucaman99. My main suggestion is with regard to docstring improvements, but the code and tests look great!

josh146 · 2020-07-31T04:48:55Z

pennylane/qaoa/cost.py

+    r"""A method that builds a QAOA cost Hamiltonian corresponding to the MaxCut problem, for a given graph.
+
+    The goal of the MaxCut problem for a particular graph is to find a partition of nodes into two sets, such
+    that the number of edges in the graph with endpoints in different sets is maximized. Formally, we wish to
+    find the cut of the graph such that the number of edges crossing the cut is maximized
+    (see `Cut (graph theory) <https://en.wikipedia.org/wiki/Cut_(graph_theory)>`__).
+
+    The MaxCut Hamiltonian is defined as:
+
+    .. math:: H_C \ = \ \frac{1}{2} \displaystyle\sum_{(i, j) \in E(G)} Z_i Z_j \ - \ \mathbb{I}
+
+    where :math:`G` is some graph and :math:`Z_i` and :math:`Z_j` are the Pauli-Z operators on the :math:`i`-th and
+    :math:`j`-th wire respectively.
+
+    As one can check, the states :math:`|01\rangle` and
+    :math:`|10\rangle` (representing a cut) both have eigenvalues with respect to :math:`H_C` of :math:`-1`. One can
+    also see that :math:`|00\rangle` and :math:`|11\rangle`` (no cut) have eigenvalues of :math:`0`.
+    Thus, for a given basis state, with each entry of the state vector representing a node of the graph, and :math:`0` and
+    :math:`1` being the labels of the two partitioned sets, the MaxCut cost Hamiltonian effectively counts the number
+    of edges crossing the cut and multiplies it by :math:`-1`. Upon minimization, we are left with the basis
+    state that yields the maximum cut.
+
+    Recommended mixer Hamiltonian: ~.qaoa.x_mixer
+
+    Recommended initialization circuit: Even superposition over all basis states
+
+    Args:
+         graph (nx.Graph) A graph defining the pairs of wires on which each term of the Hamiltonian acts.
+
+    Returns:
+        ~.Hamiltonian:
+
+    .. UsageDetails::
+
+        The MaxCut cost Hamiltonian can be called as follows:
+
+        .. code-block:: python
+
+            from pennylane import qaoa
+            from networkx import Graph
+
+            graph = Graph([(0, 1), (1, 2)])
+            cost_h = qaoa.MaxCut(graph)
+
+        >>> print(cost_h)
+        (-0.5) [I0 I1] + (0.5) [Z0 Z1] + (-0.5) [I1 I2] + (0.5) [Z1 Z2]
+    """


@Lucaman99, the docstring might need some work, so that there is a better flow between essential details, examples, and technical details.

I suggest something similar to the following:

Returns the QAOA cost Hamiltonian corresponding to the MaxCut problem, for a given graph. The goal of the MaxCut problem for a particular graph is to find a partition of nodes into two sets, such that the number of edges in the graph with endpoints in different sets is maximized. Formally, we wish to find the `cut of the graph <https://en.wikipedia.org/wiki/Cut_(graph_theory)>`__ such that the number of edges crossing the cut is maximized. The MaxCut Hamiltonian is defined as: .. math:: H_C \ = \ \frac{1}{2} \displaystyle\sum_{(i, j) \in E(G)} Z_i Z_j \ - \ \mathbb{I} where :math:`G` is some graph and :math:`Z_i` and :math:`Z_j` are the Pauli-Z operators on the :math:`i`-th and :math:`j`-th wire respectively. *Recommended mixer Hamiltonian:* :func:`~.qaoa.x_mixer` *Recommended initialization circuit:* Even superposition over all basis states Args: graph (nx.Graph): a graph defining the pairs of wires on which each term of the Hamiltonian acts Returns: .Hamiltonian: **Example** >>> graph = nx.Graph([(0, 1), (1, 2)]) >>> cost_h = qml.qaoa.MaxCut(graph) print(cost_h) (-0.5) [I0 I1] + (0.5) [Z0 Z1] + (-0.5) [I1 I2] + (0.5) [Z1 Z2] .. UsageDetails:: <For more advanced examples, advanced usage details, and additional technical details>

I based this on the documentation guidelines. Breaking this down part by part:

The docstring summary: 'A method that builds' is redundant, and likely to be confused with class methods. Better to just start with 'Returns ...' or 'Creates...'.

Rather than using '(see )', it flows a bit better to have the actual term ('cut of the graph') link to the resource. Think of how Wikipedia articles do it 🙂 Aside from this, the introduction and latex descpription are great.

The paragraph that begins 'As one can check, ..' is more of an aside, and not essential for the top level docstring. I would suggest moving this down into 'Usage details'.

To create links to code objects in general text, you need to use Sphinx domains, e.g.,

:class:`~.BaseQNode`, :func:`~.StronglyEntanglingLayers`

The only exception is on the left hand side of the colon in the Args: and Returns: sections.

~ is a formatting specifier for links (it instructs Sphinx to display only the name of the object in the link, not the full absolute path. E.g., .Hamiltonian would display as pennylane.Hamiltonian, whereas ~.Hamiltonian will display just as Hamiltonian. Since it is only for formatting, it shouldn't be used when specifying types on the left hand side of the colon in the Args: and Returns: sections.

All docstrings should include a top-level minimal example below Returns:. This example can assume standard imports (so no need to write import networkx as nx and import pennylane as qml), and should show a basic working use-case of the function. This example should always use Python console syntax, and not a .. code-block::.

Finally, the 'Usage Details' section is optional, but the place to put any more advanced technical details, usage details, and bigger examples. For example, a lot of the templates use the UsageDetails section to add more usage examples. This section is collapsed by default, leaving only the top-level example visible, to avoid overwhelming the user.

@josh146 I see! In that case, I think it should be Ok to just have an example and omit the "Usage Details"!

tests/test_qaoa.py

josh146 · 2020-07-31T05:01:06Z

pennylane/qaoa/cost.py

+
+    for node1, node2 in edges:
+
+        obs.append(qml.Identity(node1) @ qml.Identity(node2))


Something that just crossed my mind, is that if/when the Hamiltonian is being used as an observable (not for time evolution), the expectation value of these terms is simply <I>=1, and we don't even need to create a QNode for this term.

On the other hand, it will be needed for doing time evolution...

Yes, that's right, we thought it was worthwhile since the Hamiltonian may be used in both regards.

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

josh146

🔥 🏅

trbromley

Thanks @Lucaman99, looks good and have left some comments.

pennylane/qaoa/cost.py

tests/test_qaoa.py

trbromley · 2020-07-31T15:09:47Z

tests/test_qaoa.py

+        [
+            (
+                Graph([(0, 1), (1, 2)]),
+                qml.Hamiltonian(
+                    [-0.5, 0.5, -0.5, 0.5],
+                    [
+                        qml.Identity(0) @ qml.Identity(1),
+                        qml.PauliZ(0) @ qml.PauliZ(1),
+                        qml.Identity(1) @ qml.Identity(2),
+                        qml.PauliZ(1) @ qml.PauliZ(2),
+                    ],
+                ),
+            ),
+            (
+                Graph((np.array([0, 1]), np.array([1, 2]), np.array([0, 2]))),
+                qml.Hamiltonian(
+                    [-0.5, 0.5, -0.5, 0.5, -0.5, 0.5],
+                    [
+                        qml.Identity(0) @ qml.Identity(1),
+                        qml.PauliZ(0) @ qml.PauliZ(1),
+                        qml.Identity(0) @ qml.Identity(2),
+                        qml.PauliZ(0) @ qml.PauliZ(2),
+                        qml.Identity(1) @ qml.Identity(2),
+                        qml.PauliZ(1) @ qml.PauliZ(2),
+                    ],
+                ),
+            ),
+            (
+                graph,
+                qml.Hamiltonian(
+                    [-0.5, 0.5, -0.5, 0.5],
+                    [
+                        qml.Identity(0) @ qml.Identity(1),
+                        qml.PauliZ(0) @ qml.PauliZ(1),
+                        qml.Identity(1) @ qml.Identity(2),
+                        qml.PauliZ(1) @ qml.PauliZ(2),
+                    ],
+                ),
+            ),
+        ],
+    )


Minor comment:
It might be nice to build this up earlier in TestCostHamiltonians and then pass to parametrize(), e.g.,

Create graphs

Create hamiltonians

Create list of pairs

^ Just might help with readability.

pennylane/qaoa/cost.py

tests/test_qaoa.py

pennylane/qaoa/cost.py

Lucaman99 added 2 commits July 22, 2020 14:44

maxcut

fef9b5e

edits

984f4e4

changes

e1fe33e

ixfoduap self-requested a review July 23, 2020 21:34

Lucaman99 added 2 commits July 24, 2020 11:40

stuff

b042136

changes

9021d63

Lucaman99 mentioned this pull request Jul 24, 2020

[QAOA] Adds Cost and Mixer Layers #720

Merged

Lucaman99 added 3 commits July 27, 2020 13:48

wires

f99719f

revert

cb98868

changes

fba9635

ixfoduap reviewed Jul 30, 2020

View reviewed changes

Lucaman99 marked this pull request as ready for review July 30, 2020 20:02

Lucaman99 added 2 commits July 30, 2020 16:16

Merge branch 'master' into cost

0211564

docstring

2e39114

ixfoduap requested review from trbromley and josh146 July 30, 2020 21:09

josh146 requested changes Jul 31, 2020

View reviewed changes

Lucaman99 and others added 4 commits July 31, 2020 01:08

Update tests/test_qaoa.py

c9edaf0

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

Update tests/test_qaoa.py

8ca612b

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

changes

17ff0e6

Merge branch 'cost' of https://github.com/Lucaman99/pennylane into cost

d93a9c5

josh146 approved these changes Jul 31, 2020

View reviewed changes

re-run tests

3b3db10

trbromley reviewed Jul 31, 2020

View reviewed changes

Lucaman99 added 2 commits July 31, 2020 11:33

code review

7db95ab

edits

1b9f308

trbromley approved these changes Jul 31, 2020

View reviewed changes

pennylane/qaoa/cost.py Outdated Show resolved Hide resolved

tests/test_qaoa.py Outdated Show resolved Hide resolved

tests/test_qaoa.py Show resolved Hide resolved

changes

410e964

ixfoduap reviewed Jul 31, 2020

View reviewed changes

pennylane/qaoa/cost.py Outdated Show resolved Hide resolved

Update pennylane/qaoa/cost.py

e05b762

ixfoduap approved these changes Jul 31, 2020

View reviewed changes

ixfoduap merged commit 51dd8b4 into PennyLaneAI:master Jul 31, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[QAOA] Adds Built-In MaxCut Cost Hamiltonian #718

[QAOA] Adds Built-In MaxCut Cost Hamiltonian #718

Lucaman99 commented Jul 22, 2020 •

edited

Loading

codecov bot commented Jul 22, 2020 •

edited

Loading

ixfoduap left a comment

ixfoduap Jul 30, 2020

josh146 left a comment

josh146 Jul 31, 2020

Lucaman99 Jul 31, 2020

josh146 Jul 31, 2020 •

edited

Loading

Lucaman99 Jul 31, 2020

josh146 left a comment

trbromley left a comment

trbromley Jul 31, 2020


		for node1, node2 in edges:

		obs.append(qml.Identity(node1) @ qml.Identity(node2))

[QAOA] Adds Built-In MaxCut Cost Hamiltonian #718

[QAOA] Adds Built-In MaxCut Cost Hamiltonian #718

Conversation

Lucaman99 commented Jul 22, 2020 • edited Loading

codecov bot commented Jul 22, 2020 • edited Loading

Codecov Report

ixfoduap left a comment

Choose a reason for hiding this comment

ixfoduap Jul 30, 2020

Choose a reason for hiding this comment

josh146 left a comment

Choose a reason for hiding this comment

josh146 Jul 31, 2020

Choose a reason for hiding this comment

Lucaman99 Jul 31, 2020

Choose a reason for hiding this comment

josh146 Jul 31, 2020 • edited Loading

Choose a reason for hiding this comment

Lucaman99 Jul 31, 2020

Choose a reason for hiding this comment

josh146 left a comment

Choose a reason for hiding this comment

trbromley left a comment

Choose a reason for hiding this comment

trbromley Jul 31, 2020

Choose a reason for hiding this comment

Lucaman99 commented Jul 22, 2020 •

edited

Loading

codecov bot commented Jul 22, 2020 •

edited

Loading

josh146 Jul 31, 2020 •

edited

Loading