Add module documentation for ops

doc/code/qml_ops_op_math.rst

@@ -0,0 +1,4 @@
+qml.ops.op_math
+===============
+
+.. automodule:: pennylane.ops.op_math

doc/index.rst

@@ -183,6 +183,7 @@ PennyLane is **free** and **open source**, released under the Apache License, Ve
    code/qml_grouping
    code/qml_kernels
    code/qml_math
+   code/qml_ops_op_math
    code/qml_qinfo
    code/qml_numpy
    code/qml_qaoa

doc/introduction/operations.rst

@@ -42,25 +42,45 @@ Operator functions
 ------------------
 
 Various functions and transforms are available for manipulating operators,
-and extracting information.
+and extracting information. These can be broken down into two main categories:
+
+Operator to Operator functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. autosummary::
 
     ~pennylane.adjoint
     ~pennylane.ctrl
     ~pennylane.cond
+    ~pennylane.op_sum
+    ~pennylane.prod
+    ~pennylane.s_prod
+    ~pennylane.generator
+
+These operator functions act on operators to produce new operators.
+
+>>> op = qml.prod(qml.PauliX(0), qml.PauliZ(1))
+>>> op = qml.op_sum(qml.Hadamard(0), op)
+>>> op = qml.s_prod(1.2, op)
+1.2*(Hadamard(wires=[0]) + PauliX(wires=[0]) @ PauliZ(wires=[1]))
+
+Operator to Other functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autosummary::
+
     ~pennylane.matrix
     ~pennylane.eigvals
-    ~pennylane.generator
 
-All operator functions can be used on instantiated operators,
+These operator functions act on operators and return other data types.
+All operator functions can be used on instantiated operators.
 
 >>> op = qml.RX(0.54, wires=0)
 >>> qml.matrix(op)
 [[0.9637709+0.j         0.       -0.26673144j]
 [0.       -0.26673144j 0.9637709+0.j        ]]
 
-Operator functions can also be used in a functional form:
+Some operator functions can also be used in a functional form:
 
 >>> x = torch.tensor(0.6, requires_grad=True)
 >>> matrix_fn = qml.matrix(qml.RX)
@@ -75,7 +95,7 @@ In the functional form, they are usually differentiable with respect to gate arg
 >>> x.grad
 tensor(-0.5910)
 
-Some operator transform can also act on multiple operators, by passing
+Some operator transforms can also act on multiple operators, by passing
 quantum functions, QNodes or tapes:
 
 >>> def circuit(theta):

pennylane/ops/functions/__init__.py

@@ -13,6 +13,17 @@
 # limitations under the License.
 """
 This module contains functions that act on operators and tapes.
+
+.. currentmodule:: pennylane
+
+.. autosummary::
+    :toctree: api
+
+    ~eigvals
+    ~generator
+    ~matrix
+    ~equal
+
 """
 from .eigvals import eigvals
 from .equal import equal

pennylane/ops/op_math/__init__.py

@@ -14,10 +14,38 @@
 """
 This module contains classes and functions for Operator arithmetic.
 
+Constructor Functions
+~~~~~~~~~~~~~~~~~~~~~
+
+.. currentmodule:: pennylane
+
+.. autosummary::
+    :toctree: api
+
+    ~adjoint
+    ~ctrl
+    ~op_sum
+    ~prod
+    ~s_prod
+
+Symbolic Classes
+~~~~~~~~~~~~~~~~
+
 .. currentmodule:: pennylane.ops.op_math
+
 .. autosummary::
     :toctree: api
 
+    ~Adjoint
+    ~ControlledOperation
+    ~Controlled
+    ~ControlledOp
+    ~Pow
+    ~Prod
+    ~Sum
+    ~SProd
+    ~SymbolicOp
+
 """
 
 from .adjoint_class import Adjoint

pennylane/ops/op_math/control.py

@@ -83,6 +83,13 @@ class ControlledOperation(Operation):
         control_wires: A wire or set of wires.
         control_values: An int or list of ints indicating the values each control wire should
             take.
+
+    .. note::
+        Currently, the :func:`~.ctrl` tranform uses this class ``ControlledOperation``.  This class
+        wraps an entire :class:`pennylane.tape.QuantumTape`, and it is rarely supported for native device
+        execution.  See :class:`pennylane.ops.op_math.Controlled` for a more versatile controlled operation
+        that wraps a single target ``Operator``.
+
     """
 
     grad_method = None
@@ -197,6 +204,8 @@ def ctrl(fn, control, control_values=None):
         function: A new function that applies the controlled equivalent of ``fn``. The returned
         function takes the same input arguments as ``fn``.
 
+    .. seealso:: :class:`~.ControlledOperation`.
+
     **Example**
 
     .. code-block:: python3

pennylane/ops/op_math/controlled_class.py

@@ -17,6 +17,8 @@
 
 import warnings
 
+from inspect import signature
+
 import numpy as np
 from scipy import sparse
 
@@ -41,6 +43,17 @@ class Controlled(SymbolicOp):
             length as ``control_wires``. Defaults to ``True`` for all control wires.
         work_wires (Any): Any auxiliary wires that can be used in the decomposition
 
+    .. note::
+        This class, ``Controlled``, denotes a controlled version of any individual operation.
+        :class:`~.ControlledOp` adds :class:`~.Operation` specific methods and properties to the
+        more general ``Controlled`` class.
+
+        The :class:`~.ControlledOperation` currently constructed by the :func:`~.ctrl` transform wraps
+        an entire tape and does not provide as many representations and attributes as ``Controlled``,
+        but :class:`~.ControlledOperation` does decompose.
+
+    .. seealso:: :class:`~.ControlledOp` and ::class:`~.ControlledOperation`
+
     **Example**
 
     >>> base = qml.RX(1.234, 1)
@@ -99,6 +112,20 @@ class Controlled(SymbolicOp):
 
     """
 
+    # pylint: disable=no-self-argument
+    @operation.classproperty
+    def __signature__(cls):  # pragma: no cover
+        # this method is defined so inspect.signature returns __init__ signature
+        # instead of __new__ signature
+        # See PEP 362
+
+        # use __init__ signature instead of __new__ signature
+        sig = signature(cls.__init__)
+        # get rid of self from signature
+        new_parameters = tuple(sig.parameters.values())[1:]
+        new_sig = sig.replace(parameters=new_parameters)
+        return new_sig
+
     # pylint: disable=unused-argument
     def __new__(cls, base, *_, **__):
         """If base is an ``Operation``, then the a ``ControlledOp`` should be used instead."""
@@ -332,6 +359,8 @@ class ControlledOp(Controlled, operation.Operation):
 
     When we no longer rely on certain functionality through ``Operation``, we can get rid of this
     class.
+
+    .. seealso:: :class:`~.Controlled`
     """
 
     def __new__(cls, *_, **__):

pennylane/ops/op_math/prod.py

@@ -87,7 +87,7 @@ class Prod(Operator):
 
     .. note::
         When a Prod operator is applied in a circuit, its factors are applied in the reverse order.
-        (i.e ``Prod(op1, op2)`` corresponds to :math:`\hat{op}_{1} \dot \hat{op}_{2}` which indicates
+        (i.e ``Prod(op1, op2)`` corresponds to :math:`\hat{op}_{1}\dot\hat{op}_{2}` which indicates
         first applying :math:`\hat{op}_{2}` then :math:`\hat{op}_{1}` in the circuit. We can see this
         in the decomposition of the operator.
 

pennylane/ops/op_math/sprod.py

@@ -24,21 +24,20 @@
 
 def s_prod(scalar, operator, do_queue=True, id=None):
     r"""Construct an operator which is the scalar product of the
-     given scalar and operator provided.
+    given scalar and operator provided.
 
     Args:
         scalar (float or complex): the scale factor being multiplied to the operator.
         operator (~.operation.Operator): the operator which will get scaled.
 
     Keyword Args:
-        do_queue (bool): determines if the scalar product operator will be queued
-            (currently not supported). Default is True.
+        do_queue (bool): determines if the scalar product operator will be queued. Default is True.
         id (str or None): id for the scalar product operator. Default is None.
 
     Returns:
-        ~ops.op_math.SProd: the operator representing the scalar product.
+        ~ops.op_math.SProd: The operator representing the scalar product.
 
-    ..seealso:: :class:`~.ops.op_math.SProd`
+    .. seealso:: :class:`~.ops.op_math.SProd` and :class:`~.ops.op_math.SymbolicOp`
 
     **Example**
 
@@ -65,6 +64,11 @@ class SProd(SymbolicOp):
             (currently not supported). Default is True.
         id (str or None): id for the scalar product operator. Default is None.
 
+    .. note::
+        Currently this operator can not be queued in a circuit as an operation, only measured terminally.
+
+    .. seealso:: :func:`~.ops.op_math.s_prod`
+
     **Example**
 
     >>> sprod_op = SProd(1.23, qml.PauliX(0))
@@ -75,6 +79,26 @@ class SProd(SymbolicOp):
            [1.23, 0.  ]])
     >>> sprod_op.terms()
     ([1.23], [PauliX(wires=[0]])
+
+    .. details::
+        :title: Usage Details
+
+        The SProd operation can also be measured inside a qnode as an observable.
+        If the circuit is parameterized, then we can also differentiate through the observable.
+
+        .. code-block:: python
+
+            dev = qml.device("default.qubit", wires=1)
+
+            @qml.qnode(dev, grad_method="best")
+            def circuit(scalar, theta):
+                qml.RX(theta, wires=0)
+                return qml.expval(qml.s_prod(scalar, qml.Hadamard(wires=0)))
+
+        >>> scalar, theta = (1.2, 3.4)
+        >>> qml.grad(circuit, argnum=[0,1])(scalar, theta)
+        (array(-0.68362956), array(0.21683382))
+
     """
     _name = "SProd"
 

pennylane/ops/op_math/sum.py

@@ -29,17 +29,17 @@ def op_sum(*summands, do_queue=True, id=None):
     r"""Construct an operator which is the sum of the given operators.
 
     Args:
-        *summands (tuple[~.operation.Operator]): the operators we want to sum together.
+        summands (tuple[~.operation.Operator]): the operators we want to sum together.
 
     Keyword Args:
         do_queue (bool): determines if the sum operator will be queued (currently not supported).
             Default is True.
-        id (str or None): id for the sum operator. Default is None.
+        id (str or None): id for the Sum operator. Default is None.
 
     Returns:
-        ~ops.op_math.Sum: the operator representing the sum of summands.
+        ~ops.op_math.Sum: The operator representing the sum of summands.
 
-    ..seealso:: :class:`~.ops.op_math.Sum`
+    .. seealso:: :class:`~.ops.op_math.Sum`
 
     **Example**
 
@@ -57,7 +57,7 @@ def _sum(mats_gen, dtype=None, cast_like=None):
     r"""Private method to compute the sum of matrices.
 
     Args:
-        mats_gen (Generator): a python generator which produces the matricies which
+        mats_gen (Generator): a python generator which produces the matrices which
             will be summed together.
 
     Keyword Args:
@@ -85,10 +85,14 @@ class Sum(Operator):
         summands (tuple[~.operation.Operator]): a tuple of operators which will be summed together.
 
     Keyword Args:
-        do_queue (bool): determines if the sum operator will be queued (currently not supported).
-            Default is True.
+        do_queue (bool): determines if the sum operator will be queued. Default is True.
         id (str or None): id for the sum operator. Default is None.
 
+    .. note::
+        Currently this operator can not be queued in a circuit as an operation, only measured terminally.
+
+    .. seealso:: :func:`~.ops.op_math.op_sum`
+
     **Example**
 
     >>> summed_op = Sum(qml.PauliX(0), qml.PauliZ(0))
@@ -116,7 +120,28 @@ class Sum(Operator):
                 1.81677345+0.57695852j, 0.        +0.j        ],
                [0.        +0.j        , 0.        +0.j        ,
                 0.        +0.j        , 1.81677345+0.57695852j]])
-    """
+
+        The Sum operation can also be measured inside a qnode as an observable.
+        If the circuit is parameterized, then we can also differentiate through the
+        sum observable.
+
+        .. code-block:: python
+
+            sum_op = Sum(qml.PauliX(0), qml.PauliZ(1))
+            dev = qml.device("default.qubit", wires=2)
+
+            @qml.qnode(dev, grad_method="best")
+            def circuit(weights):
+                qml.RX(weights[0], wires=0)
+                qml.RY(weights[1], wires=1)
+                qml.CNOT(wires=[0, 1])
+                qml.RX(weights[2], wires=1)
+                return qml.expval(sum_op)
+
+        >>> weights = qnp.array([0.1, 0.2, 0.3], requires_grad=True)
+        >>> qml.grad(circuit)(weights)
+        tensor([-0.09347337, -0.18884787, -0.28818254], requires_grad=True)
+        """
 
     _eigs = {}  # cache eigen vectors and values like in qml.Hermitian