[docs] Correct Python docstrings and snippets that contradict the code

.github/pre-commit/spelling_allowlist.txt

@@ -315,6 +315,7 @@ cuTensor
 cudaq
 cudaqPulseRunCanonicalize
 cudm
+cx
 dataclass
 dataflow
 datagram
@@ -525,6 +526,7 @@ queryable
 qumode
 qumodes
 qvec
+qvector
 rabi
 reStructuredText
 realtime

docs/sphinx/specification/cudaq/algorithmic_primitives.rst

@@ -86,7 +86,7 @@ extract the result information in the following manner:
     counts.dump()
 
     # Fine-grained access to the bits and counts 
-    for bits, count in counts:
+    for bits, count in counts.items():
         print('Observed: {}, {}'.format(bits, count))
 
 
@@ -540,7 +540,7 @@ This return type can be used in the following way.
   .. code-block:: python 
 
     # I require the result with all generated data 
-    result = cudaq::observe(kernel, spinOp, *args)
+    result = cudaq.observe(kernel, spinOp, *args)
     expVal = result.expectation()
     X0X1Exp = result.expectation(x(0)*x(1))
     X0X1Data = result.counts(x(0)*x(1))
@@ -583,8 +583,8 @@ Here is an example of the utility of the :code:`cudaq::observe` function:
        ry(theta, q[1])
        x.ctrl(q[1], q[0])
 
-    h = 5.907 - 2.1433 * x(0) * x(1) - 2.1433 * y(0) * y(1) +
-                    .21829 * z(0) - 6.125 * z(1)
+    h = (5.907 - 2.1433 * x(0) * x(1) - 2.1433 * y(0) * y(1) +
+                    .21829 * z(0) - 6.125 * z(1))
     energy = cudaq.observe(ansatz, h, .59).expectation() 
     print('Energy is {}'.format(energy))
 

python/cudaq/kernel/kernel_builder.py

@@ -1145,14 +1145,14 @@ def __measure(self, opClass, target, regName):
     def mz(self, target, regName=None):
         """
         Measure the given qubit or qubits in the Z-basis. The optional
-        `register_name` may be used to retrieve results of this measurement
+        `regName` may be used to retrieve results of this measurement
         after execution on the QPU. If the measurement call is saved as a
         variable, it will return a :class:`QuakeValue` handle to the measurement
         instruction.
 
         Args:
         target (:class:`QuakeValue`): The qubit or qubits to measure.
-        register_name (Optional[:obj:`str`]): The optional name to provide the
+        `regName` (Optional[:obj:`str`]): The optional name to provide the
             results of the measurement. Defaults to ``None``, in which case
             no register name is attached to the measurement op.
 
@@ -1178,14 +1178,14 @@ def mz(self, target, regName=None):
     def mx(self, target, regName=None):
         """
         Measure the given qubit or qubits in the X-basis. The optional
-        `register_name` may be used to retrieve results of this measurement
+        `regName` may be used to retrieve results of this measurement
         after execution on the QPU. If the measurement call is saved as a
         variable, it will return a :class:`QuakeValue` handle to the measurement
         instruction.
 
         Args:
         target (:class:`QuakeValue`): The qubit or qubits to measure.
-        register_name (Optional[:obj:`str`]): The optional name to provide the
+        `regName` (Optional[:obj:`str`]): The optional name to provide the
             results of the measurement. Defaults to ``None``, in which case
             no register name is attached to the measurement op.
 
@@ -1210,14 +1210,14 @@ def mx(self, target, regName=None):
     def my(self, target, regName=None):
         """
         Measure the given qubit or qubits in the Y-basis. The optional
-        `register_name` may be used to retrieve results of this measurement
+        `regName` may be used to retrieve results of this measurement
         after execution on the QPU. If the measurement call is saved as a
         variable, it will return a :class:`QuakeValue` handle to the measurement
         instruction.
 
         Args:
         target (:class:`QuakeValue`): The qubit or qubits to measure.
-        register_name (Optional[:obj:`str`]): The optional name to provide the
+        `regName` (Optional[:obj:`str`]): The optional name to provide the
             results of the measurement. Defaults to ``None``, in which case
             no register name is attached to the measurement op.
 

python/cudaq/kernel/quake_value.py

@@ -127,20 +127,20 @@ def slice(self, startIdx, count):
             The underlying :class:`QuakeValue` must be a `list` or `veq`.
 
         Args:
-            start (int): The index to begin the slice from.
-            count (int): The number of elements to extract after the `start` index.
+            `startIdx` (int): The index to begin the slice from.
+            count (int): The number of elements to extract after the `startIdx` index.
         Returns:
             :class:`QuakeValue`: A new `QuakeValue` containing a slice of `self`
-            from the `start` element to the `start + count` element.
+            from the `startIdx` element to the `startIdx + count` element.
         """
         raise RuntimeError("QuakeValue.slice not implemented")
 
     def __neg__(self):
         """
         Return the negation of `self` (:class:`QuakeValue`).
 
-        Raises:
-            RuntimeError: if the underlying :class:`QuakeValue` type is not a float.
+        Note:
+            An integer :class:`QuakeValue` is promoted to floating point.
 
         .. code-block:: python
 
@@ -158,8 +158,8 @@ def __mul__(self, other):
         """
         Return the product of `self` (:class:`QuakeValue`) with `other` (float).
 
-        Raises:
-	        RuntimeError: if the underlying :class:`QuakeValue` type is not a float.
+        Note:
+	        `other` may be an `int`, a `float`, or another :class:`QuakeValue`.
 
         .. code-block:: python
 
@@ -177,8 +177,8 @@ def __rmul__(self, other):
         """
         Return the product of `other` (float) with `self` (:class:`QuakeValue`).
 
-        Raises:
-	        RuntimeError: if the underlying :class:`QuakeValue` type is not a float.
+        Note:
+	        `other` may be an `int`, a `float`, or another :class:`QuakeValue`.
 
         .. code-block:: python
 
@@ -196,8 +196,8 @@ def __truediv__(self, other):
         """
         Return the division of `self` (:class:`QuakeValue`) with `other` (float).
 
-        Raises:
-	        RuntimeError: if the underlying :class:`QuakeValue` type is not a float.
+        Note:
+	        `other` may be an `int`, a `float`, or another :class:`QuakeValue`.
 
         .. code-block:: python
 
@@ -218,8 +218,8 @@ def __rtruediv__(self, other):
         """
         Return the division of `other` (float) with `self` (:class:`QuakeValue`).
 
-        Raises:
-	        RuntimeError: if the underlying :class:`QuakeValue` type is not a float.
+        Note:
+	        `other` may be an `int`, a `float`, or another :class:`QuakeValue`.
 
         .. code-block:: python
 
@@ -240,8 +240,8 @@ def __add__(self, other):
         """
         Return the sum of `self` (:class:`QuakeValue`) and `other` (float).
 
-        Raises:
-	        RuntimeError: if the underlying :class:`QuakeValue` type is not a float.
+        Note:
+	        `other` may be an `int`, a `float`, or another :class:`QuakeValue`.
 
         .. code-block:: python
 
@@ -259,8 +259,8 @@ def __radd__(self, other):
         """
         Return the sum of `other` (float) and `self` (:class:`QuakeValue`).
 
-        Raises:
-	        RuntimeError: if the underlying :class:`QuakeValue` type is not a float.
+        Note:
+	        `other` may be an `int`, a `float`, or another :class:`QuakeValue`.
 
         .. code-block:: python
 
@@ -278,8 +278,8 @@ def __sub__(self, other):
         """
         Return the difference of `self` (:class:`QuakeValue`) and `other` (float).
 
-        Raises:
-	        RuntimeError: if the underlying :class:`QuakeValue` type is not a float.
+        Note:
+	        `other` may be an `int`, a `float`, or another :class:`QuakeValue`.
 
         .. code-block:: python
 
@@ -297,8 +297,8 @@ def __rsub__(self, other):
         """
         Return the difference of `other` (float) and `self` (:class:`QuakeValue`).
 
-        Raises:
-	        RuntimeError: if the underlying :class:`QuakeValue` type is not a float.
+        Note:
+	        `other` may be an `int`, a `float`, or another :class:`QuakeValue`.
 
         .. code-block:: python
 

python/cudaq/operators/custom/__init__.py

@@ -35,7 +35,7 @@ def define(id: str,
     function does not need to do this.
 
     Arguments:
-        op_id: A string that uniquely identifies the defined operator.
+        id: A string that uniquely identifies the defined operator.
         expected_dimensions: defines the number of levels, that is the dimension,
             for each degree of freedom in canonical (that is sorted) order. A
             negative or zero value for one (or more) of the expected dimensions
@@ -59,7 +59,7 @@ def instantiate(op_id: str,
     Instantiates a product operator containing a previously defined operator element.
 
     Arguments:
-        operator_id: The id of the operator element as specified when it was defined.
+        op_id: The id of the operator element as specified when it was defined.
         degrees: The degree(s) of freedom that the operator acts on.
     """
     if isinstance(degrees, int):

python/cudaq/runtime/translate.py

@@ -15,8 +15,8 @@
 @trace.traced
 def translate(kernel, *args, format="qir:0.1"):
     """
-    Return a `UTF-8` encoded string representing drawing of the execution path,
-    i.e., the trace, of the provided `kernel`.
+    Return a `UTF-8` encoded string containing the provided `kernel` translated
+    to the requested `format`.
 
     Args:
       format (`str`): format to translate to, <name[:version]>.
@@ -29,7 +29,8 @@ def translate(kernel, *args, format="qir:0.1"):
     Note: Translating functions with arguments to OpenQASM 2.0 is not supported.
 
     Returns:
-      The `UTF-8` encoded string of the circuit, without measurement operations.
+      The `UTF-8` encoded string of the circuit in the requested `format`,
+      including any measurement operations present in the `kernel`.
 
     # Example:
     import cudaq

python/cudaq/runtime/unitary.py

@@ -28,11 +28,11 @@ def get_unitary(kernel, *args):
       import cudaq
       @cudaq.kernel
       def bell():
-        `q = cudaq.qvector(2)`
+        q = cudaq.qvector(2)
         h(q[0])
-        `cx(q[0], q[1])`
+        cx(q[0], q[1])
       U = cudaq.get_unitary(bell)
-     print(U)
+      print(U)
     """
     if isa_kernel_decorator(kernel):
         decorator = kernel

python/runtime/common/py_SampleResult.cpp

@@ -123,7 +123,7 @@ terminal measurements.
 	bitstring (str): The binary string to return the measurement data of.
 
 Returns:
-	float: The number of times the given `bitstring` was measured
+	int: The number of times the given `bitstring` was measured
 	during the `shots_count` number of executions on the QPU.)#")
       .def(
           "__len__", [](sample_result &self) { return self.to_map().size(); },