prompt: You will be provided with a partial code base and an issue statement explaining a problem to resolve.
  <issue>
  Change order of technical description and list of functions in documentation
  Three modules, [`kernels`](https://pennylane.readthedocs.io/en/latest/code/qml_kernels.html), [`grouping`](https://pennylane.readthedocs.io/en/latest/code/qml_grouping.html), and [`qaoa`](https://pennylane.readthedocs.io/en/latest/code/qml_qaoa.html) have their module documentation ordered such that there is first a lengthy description of the theory, and the actual list of functions comes after. We should update the docs of these modules so that the functions appear *first*, and the technical details come afterwards (as was recently discussed in #1160). This will improve readability of the documentation and make it easier to find the details of a desired function.
  
  </issue>
  <code>
  [start of pennylane/qaoa/__init__.py]
  1 # Copyright 2018-2021 Xanadu Quantum Technologies Inc.
  2 
  3 # Licensed under the Apache License, Version 2.0 (the "License");
  4 # you may not use this file except in compliance with the License.
  5 # You may obtain a copy of the License at
  6 
  7 #     http://www.apache.org/licenses/LICENSE-2.0
  8 
  9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14 r"""
  15 This module contains functionality to construct QAOA workflows in PennyLane.
  16 """
  17 
  18 from .mixers import *
  19 from .cost import *
  20 from .layers import *
  21 import pennylane.qaoa.cycle
  22
  [end of pennylane/qaoa/__init__.py]
  [start of pennylane/kernels/__init__.py]
  1 # Copyright 2018-2021 Xanadu Quantum Technologies Inc.
  2 
  3 # Licensed under the Apache License, Version 2.0 (the "License");
  4 # you may not use this file except in compliance with the License.
  5 # You may obtain a copy of the License at
  6 
  7 #     http://www.apache.org/licenses/LICENSE-2.0
  8 
  9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14 r"""
  15 This subpackage defines functions that relate to quantum kernel methods.
  16 On one hand this includes functions to call a quantum kernel systematically
  17 on training and test datasets to obtain the *kernel matrix*.
  18 On the other hand it provides postprocessing methods for those kernel
  19 matrices which can be used to mitigate device noise and sampling errors.
  20 
  21 Given a kernel
  22 
  23 .. math ::
  24 
  25     k: \mathbb{R}^d \times \mathbb{R}^d \to \mathbb{R}, \quad
  26     (x_1, x_2)\mapsto k(x_1, x_2)
  27 
  28 the kernel matrix of :math:`k` on a training dataset
  29 :math:`\{(x_1, y_1),\cdots (x_n, y_n)\}` with :math:`x_i\in\mathbb{R}^d`
  30 and :math:`y_i\in\{-1, 1\}` is defined as
  31 
  32 .. math ::
  33 
  34     K_{ij} = k(x_i, x_j).
  35 
  36 For valid kernels, this is a real symmetric positive semi-definite matrix.
  37 We also define the *ideal kernel matrix* for the training dataset which
  38 perfectly predicts whether two points have identical labels or not:
  39 
  40 .. math ::
  41 
  42     K^\ast_{ij} = y_i y_j
  43 
  44 We can measure the similarity between :math:`K` and :math:`K^\ast`,
  45 through the *kernel polarity* which can be expressed as the Frobenius inner
  46 product between the two matrices:
  47 
  48 .. math ::
  49 
  50     \operatorname{P}(k) = \langle K^\ast, K \rangle_F = \sum_{i,j=1}^n y_i y_j k(x_i, x_j)
  51 
  52 Additionally, there is the *kernel-target alignment*, which is the normalized
  53 counterpart to the kernel polarity:
  54 
  55 .. math ::
  56 
  57     \operatorname{TA}(k) &= \frac{P(k)}{\lVert K^\ast \rVert_F\;\lVert K \rVert_F}\\
  58         \lVert K\rVert_F &= \sqrt{\sum_{i,j=1}^n k(x_i, x_j)^2}\\
  59    \lVert K^\ast\rVert_F &= \sqrt{\sum_{i,j=1}^n (y_iy_j)^2}
  60 
  61 For datasets with different numbers of training points per class the labels are rescaled
  62 by the number of datapoints in the respective class to avoid that kernel polarity and
  63 kernel-target alignment are dominated by the properties of the kernel for just a single class.
  64 
  65 Given a callable kernel function, all these quantities can readily be computed
  66 using the methods in this module.
  67 """
  68 from .cost_functions import (
  69     polarity,
  70     target_alignment,
  71 )
  72 from .postprocessing import (
  73     threshold_matrix,
  74     displace_matrix,
  75     flip_matrix,
  76     closest_psd_matrix,
  77     mitigate_depolarizing_noise,
  78 )
  79 from .utils import (
  80     kernel_matrix,
  81     square_kernel_matrix,
  82 )
  83
  [end of pennylane/kernels/__init__.py]
  </code>
  
  I need you to solve this issue by generating a single patch file that I can apply directly to this repository using git apply. Please respond with a single patch file in the following format.
  <patch>
  diff --git a/file.py b/file.py
  --- a/file.py
  +++ b/file.py
  @@ -1,27 +1,35 @@
   def euclidean(a, b):
  -    while b:
  -        a, b = b, a % b
  -    return a
  +    if b == 0:
  +        return a
  +    return euclidean(b, a % b)
   
   
   def bresenham(x0, y0, x1, y1):
       points = []
       dx = abs(x1 - x0)
       dy = abs(y1 - y0)
  -    sx = 1 if x0 < x1 else -1
  -    sy = 1 if y0 < y1 else -1
  -    err = dx - dy
  +    x, y = x0, y0
  +    sx = -1 if x0 > x1 else 1
  +    sy = -1 if y0 > y1 else 1
   
  -    while True:
  -        points.append((x0, y0))
  -        if x0 == x1 and y0 == y1:
  -            break
  -        e2 = 2 * err
  -        if e2 > -dy:
  -            err -= dy
  -            x0 += sx
  -        if e2 < dx:
  -            err += dx
  -            y0 += sy
  +    if dx > dy:
  +        err = dx / 2.0
  +        while x != x1:
  +            points.append((x, y))
  +            err -= dy
  +            if err < 0:
  +                y += sy
  +                err += dx
  +            x += sx
  +    else:
  +        err = dy / 2.0
  +        while y != y1:
  +            points.append((x, y))
  +            err -= dx
  +            if err < 0:
  +                x += sx
  +                err += dy
  +            y += sy
  +
  +    points.append((x, y))
       return points
  
  </patch>
golden_diff: diff --git a/pennylane/kernels/__init__.py b/pennylane/kernels/__init__.py
  --- a/pennylane/kernels/__init__.py
  +++ b/pennylane/kernels/__init__.py
  @@ -13,58 +13,8 @@
   # limitations under the License.
   r"""
   This subpackage defines functions that relate to quantum kernel methods.
  -On one hand this includes functions to call a quantum kernel systematically
  -on training and test datasets to obtain the *kernel matrix*.
  -On the other hand it provides postprocessing methods for those kernel
  -matrices which can be used to mitigate device noise and sampling errors.
  -
  -Given a kernel
  -
  -.. math ::
  -
  -    k: \mathbb{R}^d \times \mathbb{R}^d \to \mathbb{R}, \quad
  -    (x_1, x_2)\mapsto k(x_1, x_2)
  -
  -the kernel matrix of :math:`k` on a training dataset
  -:math:`\{(x_1, y_1),\cdots (x_n, y_n)\}` with :math:`x_i\in\mathbb{R}^d`
  -and :math:`y_i\in\{-1, 1\}` is defined as
  -
  -.. math ::
  -
  -    K_{ij} = k(x_i, x_j).
  -
  -For valid kernels, this is a real symmetric positive semi-definite matrix.
  -We also define the *ideal kernel matrix* for the training dataset which
  -perfectly predicts whether two points have identical labels or not:
  -
  -.. math ::
  -
  -    K^\ast_{ij} = y_i y_j
  -
  -We can measure the similarity between :math:`K` and :math:`K^\ast`,
  -through the *kernel polarity* which can be expressed as the Frobenius inner
  -product between the two matrices:
  -
  -.. math ::
  -
  -    \operatorname{P}(k) = \langle K^\ast, K \rangle_F = \sum_{i,j=1}^n y_i y_j k(x_i, x_j)
  -
  -Additionally, there is the *kernel-target alignment*, which is the normalized
  -counterpart to the kernel polarity:
  -
  -.. math ::
  -
  -    \operatorname{TA}(k) &= \frac{P(k)}{\lVert K^\ast \rVert_F\;\lVert K \rVert_F}\\
  -        \lVert K\rVert_F &= \sqrt{\sum_{i,j=1}^n k(x_i, x_j)^2}\\
  -   \lVert K^\ast\rVert_F &= \sqrt{\sum_{i,j=1}^n (y_iy_j)^2}
  -
  -For datasets with different numbers of training points per class the labels are rescaled
  -by the number of datapoints in the respective class to avoid that kernel polarity and
  -kernel-target alignment are dominated by the properties of the kernel for just a single class.
  -
  -Given a callable kernel function, all these quantities can readily be computed
  -using the methods in this module.
   """
  +
   from .cost_functions import (
       polarity,
       target_alignment,
  diff --git a/pennylane/qaoa/__init__.py b/pennylane/qaoa/__init__.py
  --- a/pennylane/qaoa/__init__.py
  +++ b/pennylane/qaoa/__init__.py
  @@ -12,10 +12,11 @@
   # See the License for the specific language governing permissions and
   # limitations under the License.
   r"""
  -This module contains functionality to construct QAOA workflows in PennyLane.
  +This module provides a collection of methods that help in the construction of
  +QAOA workflows.
   """
   
  +import pennylane.qaoa.cycle
   from .mixers import *
   from .cost import *
   from .layers import *
  -import pennylane.qaoa.cycle
  
verification_info: {"golden_diff": "diff --git a/pennylane/kernels/__init__.py b/pennylane/kernels/__init__.py\n--- a/pennylane/kernels/__init__.py\n+++ b/pennylane/kernels/__init__.py\n@@ -13,58 +13,8 @@\n # limitations under the License.\n r\"\"\"\n This subpackage defines functions that relate to quantum kernel methods.\n-On one hand this includes functions to call a quantum kernel systematically\n-on training and test datasets to obtain the *kernel matrix*.\n-On the other hand it provides postprocessing methods for those kernel\n-matrices which can be used to mitigate device noise and sampling errors.\n-\n-Given a kernel\n-\n-.. math ::\n-\n-    k: \\mathbb{R}^d \\times \\mathbb{R}^d \\to \\mathbb{R}, \\quad\n-    (x_1, x_2)\\mapsto k(x_1, x_2)\n-\n-the kernel matrix of :math:`k` on a training dataset\n-:math:`\\{(x_1, y_1),\\cdots (x_n, y_n)\\}` with :math:`x_i\\in\\mathbb{R}^d`\n-and :math:`y_i\\in\\{-1, 1\\}` is defined as\n-\n-.. math ::\n-\n-    K_{ij} = k(x_i, x_j).\n-\n-For valid kernels, this is a real symmetric positive semi-definite matrix.\n-We also define the *ideal kernel matrix* for the training dataset which\n-perfectly predicts whether two points have identical labels or not:\n-\n-.. math ::\n-\n-    K^\\ast_{ij} = y_i y_j\n-\n-We can measure the similarity between :math:`K` and :math:`K^\\ast`,\n-through the *kernel polarity* which can be expressed as the Frobenius inner\n-product between the two matrices:\n-\n-.. math ::\n-\n-    \\operatorname{P}(k) = \\langle K^\\ast, K \\rangle_F = \\sum_{i,j=1}^n y_i y_j k(x_i, x_j)\n-\n-Additionally, there is the *kernel-target alignment*, which is the normalized\n-counterpart to the kernel polarity:\n-\n-.. math ::\n-\n-    \\operatorname{TA}(k) &= \\frac{P(k)}{\\lVert K^\\ast \\rVert_F\\;\\lVert K \\rVert_F}\\\\\n-        \\lVert K\\rVert_F &= \\sqrt{\\sum_{i,j=1}^n k(x_i, x_j)^2}\\\\\n-   \\lVert K^\\ast\\rVert_F &= \\sqrt{\\sum_{i,j=1}^n (y_iy_j)^2}\n-\n-For datasets with different numbers of training points per class the labels are rescaled\n-by the number of datapoints in the respective class to avoid that kernel polarity and\n-kernel-target alignment are dominated by the properties of the kernel for just a single class.\n-\n-Given a callable kernel function, all these quantities can readily be computed\n-using the methods in this module.\n \"\"\"\n+\n from .cost_functions import (\n     polarity,\n     target_alignment,\ndiff --git a/pennylane/qaoa/__init__.py b/pennylane/qaoa/__init__.py\n--- a/pennylane/qaoa/__init__.py\n+++ b/pennylane/qaoa/__init__.py\n@@ -12,10 +12,11 @@\n # See the License for the specific language governing permissions and\n # limitations under the License.\n r\"\"\"\n-This module contains functionality to construct QAOA workflows in PennyLane.\n+This module provides a collection of methods that help in the construction of\n+QAOA workflows.\n \"\"\"\n \n+import pennylane.qaoa.cycle\n from .mixers import *\n from .cost import *\n from .layers import *\n-import pennylane.qaoa.cycle\n", "issue": "Change order of technical description and list of functions in documentation\nThree modules, [`kernels`](https://pennylane.readthedocs.io/en/latest/code/qml_kernels.html), [`grouping`](https://pennylane.readthedocs.io/en/latest/code/qml_grouping.html), and [`qaoa`](https://pennylane.readthedocs.io/en/latest/code/qml_qaoa.html) have their module documentation ordered such that there is first a lengthy description of the theory, and the actual list of functions comes after. We should update the docs of these modules so that the functions appear *first*, and the technical details come afterwards (as was recently discussed in #1160). This will improve readability of the documentation and make it easier to find the details of a desired function.\n", "before_files": [{"content": "# Copyright 2018-2021 Xanadu Quantum Technologies Inc.\n\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n\n#     http://www.apache.org/licenses/LICENSE-2.0\n\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\nr\"\"\"\nThis module contains functionality to construct QAOA workflows in PennyLane.\n\"\"\"\n\nfrom .mixers import *\nfrom .cost import *\nfrom .layers import *\nimport pennylane.qaoa.cycle\n", "path": "pennylane/qaoa/__init__.py"}, {"content": "# Copyright 2018-2021 Xanadu Quantum Technologies Inc.\n\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n\n#     http://www.apache.org/licenses/LICENSE-2.0\n\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\nr\"\"\"\nThis subpackage defines functions that relate to quantum kernel methods.\nOn one hand this includes functions to call a quantum kernel systematically\non training and test datasets to obtain the *kernel matrix*.\nOn the other hand it provides postprocessing methods for those kernel\nmatrices which can be used to mitigate device noise and sampling errors.\n\nGiven a kernel\n\n.. math ::\n\n    k: \\mathbb{R}^d \\times \\mathbb{R}^d \\to \\mathbb{R}, \\quad\n    (x_1, x_2)\\mapsto k(x_1, x_2)\n\nthe kernel matrix of :math:`k` on a training dataset\n:math:`\\{(x_1, y_1),\\cdots (x_n, y_n)\\}` with :math:`x_i\\in\\mathbb{R}^d`\nand :math:`y_i\\in\\{-1, 1\\}` is defined as\n\n.. math ::\n\n    K_{ij} = k(x_i, x_j).\n\nFor valid kernels, this is a real symmetric positive semi-definite matrix.\nWe also define the *ideal kernel matrix* for the training dataset which\nperfectly predicts whether two points have identical labels or not:\n\n.. math ::\n\n    K^\\ast_{ij} = y_i y_j\n\nWe can measure the similarity between :math:`K` and :math:`K^\\ast`,\nthrough the *kernel polarity* which can be expressed as the Frobenius inner\nproduct between the two matrices:\n\n.. math ::\n\n    \\operatorname{P}(k) = \\langle K^\\ast, K \\rangle_F = \\sum_{i,j=1}^n y_i y_j k(x_i, x_j)\n\nAdditionally, there is the *kernel-target alignment*, which is the normalized\ncounterpart to the kernel polarity:\n\n.. math ::\n\n    \\operatorname{TA}(k) &= \\frac{P(k)}{\\lVert K^\\ast \\rVert_F\\;\\lVert K \\rVert_F}\\\\\n        \\lVert K\\rVert_F &= \\sqrt{\\sum_{i,j=1}^n k(x_i, x_j)^2}\\\\\n   \\lVert K^\\ast\\rVert_F &= \\sqrt{\\sum_{i,j=1}^n (y_iy_j)^2}\n\nFor datasets with different numbers of training points per class the labels are rescaled\nby the number of datapoints in the respective class to avoid that kernel polarity and\nkernel-target alignment are dominated by the properties of the kernel for just a single class.\n\nGiven a callable kernel function, all these quantities can readily be computed\nusing the methods in this module.\n\"\"\"\nfrom .cost_functions import (\n    polarity,\n    target_alignment,\n)\nfrom .postprocessing import (\n    threshold_matrix,\n    displace_matrix,\n    flip_matrix,\n    closest_psd_matrix,\n    mitigate_depolarizing_noise,\n)\nfrom .utils import (\n    kernel_matrix,\n    square_kernel_matrix,\n)\n", "path": "pennylane/kernels/__init__.py"}]}