Fix docstrings

docs/conf.py

@@ -300,7 +300,7 @@
 # Additional stuff for the LaTeX preamble.
 #####################################################
 # add LaTeX macros
-latex_elements['preamble'] = '\usepackage{amsmath}\n\usepackage{amssymb}\n'
+latex_elements['preamble'] = r'\usepackage{amsmath}\n\usepackage{amssymb}\n'
 
 with open('latex_macros.sty', "r") as f:
 

docs/simon.rst

@@ -33,7 +33,7 @@ The input qubits are prepared with the ancilla qubits into the state
 $$(H^{\\otimes n} \\otimes I^{\\otimes n})\\vert 0\\rangle^{\\otimes n}\\vert 0\\rangle^{\\otimes n} = \\vert +\\rangle^{\\otimes n}\\vert 0\\rangle^{\\otimes n}$$
 and sent through a blackbox gate \\(U_f\\). Then, the Hadamard-Walsh transform
 \\(H^{\\otimes n}\\) is applied to the \\(n\\) input qubits, resulting in the state given by
- $$(H^{\\otimes n} \\otimes I^{\\otimes n})U_f\\vert +\\rangle^{\\otimes n}\\vert 0\\rangle^{\\otimes n}$$
+$$(H^{\\otimes n} \\otimes I^{\\otimes n})U_f\\vert +\\rangle^{\\otimes n}\\vert 0\\rangle^{\\otimes n}$$
 
 It turns out the resulting \\(n\\) input qubits are in a uniform random state
 over the space killed by (modulo \\(2\\), bitwise) dot product with \\(s\\).

grove/alpha/deutsch_jozsa/deutsch_jozsa.py

@@ -11,17 +11,20 @@
 
 
 def oracle_function(unitary_funct, qubits, ancilla):
-    """
+    r"""
     Defines an oracle that performs the following unitary transformation:
-    |x>|y> -> |x>|f(x) xor y>
+
+    .. math::
+
+        \ket{x}\ket{y} \to \ket{x}\ket{f(x)\; \text{xor}\; y}
 
     Allocates one scratch bit.
 
     :param np.array unitary_funct: Matrix representation of the function f, i.e. the
-        unitary transformation that must be applied to a state |x> to put f(x) in qubit 0, where
-        f(x) returns either 0 or 1 for any n-bit string x
-    :param np.array qubits: List of qubits that enter as input |x>.
-    :param Qubit ancilla: Qubit to serve as input |y>.
+        unitary transformation that must be applied to a state :math:`\ket{x}` to put
+        f(x) in qubit 0, where f(x) returns either 0 or 1 for any n-bit string x
+    :param np.array qubits: List of qubits that enter as input :math:`\ket{x}`.
+    :param Qubit ancilla: Qubit to serve as input :math:`ket\{y}`.
     :return: A program that performs the above unitary transformation.
     :rtype: Program
     """
@@ -48,8 +51,8 @@ def deutsch_jozsa(oracle, qubits, ancilla):
     or balanced, provided that it is one of them.
 
     :param Program oracle: Program representing unitary application of function.
-    :param list qubits: List of qubits that enter as state |x>.
-    :param Qubit ancilla: Qubit to serve as input |y>.
+    :param list qubits: List of qubits that enter as state :math:`\\ket{x}`.
+    :param Qubit ancilla: Qubit to serve as input :math:`\\ket{y}`.
     :return: A program corresponding to the desired instance of the
              Deutsch-Jozsa Algorithm.
     :rtype: Program

grove/amplification/amplification.py

@@ -36,8 +36,8 @@ def amplification_circuit(algorithm, oracle, qubits, num_iter):
 
     :param Program algorithm: A program representing a measurement-less algorithm run on qubits.
     :param Program oracle: An oracle maps any basis vector ``|psi>`` to either ``+|psi>`` or
-    ``-|psi>`` depending on whether ``|psi>`` is in the desirable subspace or the undesirable
-    subspace.
+        ``-|psi>`` depending on whether ``|psi>`` is in the desirable subspace or the undesirable
+        subspace.
     :param Sequence qubits: the qubits to operate on
     :param int num_iter: number of iterations of amplifications to run
     :return: The amplified algorithm.
@@ -57,9 +57,10 @@ def amplification_circuit(algorithm, oracle, qubits, num_iter):
 
 
 def diffusion_program(qubits):
-    """Constructs the diffusion operator used in Grover's Algorithm, acted on both sides by an
-     a Hadamard gate on each qubit. Note that this means that the matrix representation of this
-     operator is diag(1, -1, ..., -1).
+    """
+    Constructs the diffusion operator used in Grover's Algorithm, acted on both sides by an
+    a Hadamard gate on each qubit. Note that this means that the matrix representation of this
+    operator is diag(1, -1, ..., -1).
 
     See C. Lavor, L.R.U. Manssur, and R. Portugal (2003) `Grover's Algorithm: Quantum Database
     Search`_ for more information.
@@ -68,7 +69,7 @@ def diffusion_program(qubits):
 
     :param qubits: A list of ints corresponding to the qubits to operate on.
                    The operator operates on bistrings of the form
-                   |qubits[0], ..., qubits[-1]>.
+                   ``|qubits[0], ..., qubits[-1]>``.
     """
     diffusion_program = pq.Program()
 

grove/amplification/grover.py

@@ -92,8 +92,8 @@ def find_bitstring(self, cxn, bitstring_map):
 
         :param JobConnection cxn: the connection to the Rigetti cloud to run pyQuil programs.
         :param bitstring_map: a mapping from bitstrings to the phases that the oracle should impart
-         on them. If the oracle should "look" for a bitstring, it should have a ``-1``, otherwise
-          it should have a ``1``.
+            on them. If the oracle should "look" for a bitstring, it should have a ``-1``, otherwise
+            it should have a ``1``.
         :type bitstring_map: Dict[String, Int]
         :return: Returns the bitstring resulting from measurement after Grover's Algorithm.
         :rtype: str
@@ -104,14 +104,14 @@ def find_bitstring(self, cxn, bitstring_map):
 
     @staticmethod
     def oracle_grover(oracle, qubits, num_iter=None):
-        """Implementation of Grover's Algorithm for a given oracle.
+        r"""Implementation of Grover's Algorithm for a given oracle.
 
-        :param Program oracle: An oracle defined as a Program. It should send |x> to (-1)^f(x)|x>,
-         where the range of f is {0, 1}.
+        :param Program oracle: An oracle defined as a Program. It should send :math:`\ket{x}`
+            to :math:`(-1)^{f(x)}\ket{x}`, where the range of f is {0, 1}.
         :param qubits: List of qubits for Grover's Algorithm.
         :type qubits: list[int or Qubit]
         :param int num_iter: The number of iterations to repeat the algorithm for.
-                             The default is the integer closest to :math:`\\frac{\\pi}{4}\sqrt{N}`,
+                             The default is the integer closest to :math:`\frac{\pi}{4}\sqrt{N}`,
                              where :math:`N` is the size of the domain.
         :return: A program corresponding to the desired instance of Grover's Algorithm.
         :rtype: Program

grove/bernstein_vazirani/bernstein_vazirani.py

@@ -48,10 +48,10 @@ def create_bv_bitmap(dot_product_vector, dot_product_bias):
            (\\mathbf{a}\\in\\{0,1\\}^n, b\\in\\{0,1\\})
 
     :param String dot_product_vector: a string of 0's and 1's that represents the dot-product
-    partner in :math:`f`
+        partner in :math:`f`
     :param String dot_product_bias: 0 or 1 as a string representing the bias term in :math:`f`
     :return: A dictionary containing all possible bitstring of length equal to :math:`a` and the
-    function value :math:`f`
+        function value :math:`f`
     :rtype: Dict[String, String]
     """
     n_bits = len(dot_product_vector)
@@ -165,7 +165,7 @@ def run(self, cxn, bitstring_map):
 
         :param Connection cxn: connection to the QPU or QVM
         :param Dict[String, String] bitstring_map: a truth table describing the boolean function,
-        whose dot-product vector and bias is to be found
+            whose dot-product vector and bias is to be found
         :rtype: BernsteinVazirani
         """
 

grove/pyqaoa/maxcut_qaoa.py

@@ -37,27 +37,18 @@ def maxcut_qaoa(graph, steps=1, rand_seed=None, connection=None, samples=None,
     Max cut set up method
 
     :param graph: Graph definition. Either networkx or list of tuples
-    :param steps: (Optional. Default=1) Trotterization order for the
-                  QAOA algorithm.
-    :param rand_seed: (Optional. Default=None) random seed when beta and
-                      gamma angles are not provided.
+    :param steps: (Optional. Default=1) Trotterization order for the QAOA algorithm.
+    :param rand_seed: (Optional. Default=None) random seed when beta and gamma angles
+        are not provided.
     :param connection: (Optional) connection to the QVM. Default is None.
     :param samples: (Optional. Default=None) VQE option. Number of samples
-                    (circuit preparation and measurement) to use in operator
-                    averaging.
-    :param initial_beta: (Optional. Default=None) Initial guess for beta
-                         parameters.
-    :param initial_gamma: (Optional. Default=None) Initial guess for gamma
-                          parameters.
-    :param minimizer_kwargs: (Optional. Default=None). Minimizer optional
-                             arguments.  If None set to
-                             {'method': 'Nelder-Mead',
-                             'options': {'ftol': 1.0e-2, 'xtol': 1.0e-2,
-                                        'disp': False}
-    :param vqe_option: (Optional. Default=None). VQE optional
-                             arguments.  If None set to
-                       vqe_option = {'disp': print_fun, 'return_all': True,
-                       'samples': samples}
+        (circuit preparation and measurement) to use in operator averaging.
+    :param initial_beta: (Optional. Default=None) Initial guess for beta parameters.
+    :param initial_gamma: (Optional. Default=None) Initial guess for gamma parameters.
+    :param minimizer_kwargs: (Optional. Default=None). Minimizer optional arguments.  If None set to
+        ``{'method': 'Nelder-Mead', 'options': {'ftol': 1.0e-2, 'xtol': 1.0e-2, 'disp': False}``
+    :param vqe_option: (Optional. Default=None). VQE optional arguments.  If None set to
+        ``vqe_option = {'disp': print_fun, 'return_all': True, 'samples': samples}``
 
     """
     if not isinstance(graph, nx.Graph) and isinstance(graph, list):

grove/simon/simon.py

@@ -61,7 +61,7 @@ def create_1to1_bitmap(mask):
 
     :param String mask: binary mask as a string of 0's and 1's
     :return: dictionary containing a mapping of all possible bit strings of the same length as the
-    mask's string and their mapped bit-string value
+        mask's string and their mapped bit-string value
     :rtype: Dict[String, String]
     """
     n_bits = len(mask)
@@ -230,10 +230,10 @@ def find_mask(self, cxn, bitstring_map):
 
         :param JobConnection cxn: the connection to the Rigetti cloud to run pyQuil programs
         :param Dict[String, String] bitstring_map: a truth table describing the boolean function,
-        whose period is  to be found.
+            whose period is  to be found.
 
         :return: Returns the mask of the bitstring map or raises an Exception if the mask cannot be
-        found.
+            found.
         :rtype: String
         """
         self._init_attr(bitstring_map)