Source code for pennylane.core.queuing

# Copyright 2018-2021 Xanadu Quantum Technologies Inc.

# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at

#     http://www.apache.org/licenses/LICENSE-2.0

# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
r"""
This module contains the classes for placing objects into queues.

.. warning::

    Unless you are a PennyLane developer, you likely do not need
    to use these classes directly.

.. currentmodule:: pennylane.core.queuing

.. autosummary::
    :toctree: api

    ~QueuingManager
    ~AnnotatedQueue


Description
-----------

Users provide *quantum functions* which PennyLane needs to convert into a circuit representation capable
of being executed by a device. A quantum function is any callable that:

* accepts classical inputs
* constructs any number of quantum :class:`~.Operator` objects
* returns one or more :class:`~.MeasurementProcess` objects.

For example:

.. code-block:: python

    def qfunc(x, scale_value=1):
        qp.RX(x * scale_value, wires=0)
        if (1 != 2):
            qp.S(0)
        return qp.expval(qp.Z(0)), qp.expval(qp.X(1))

To convert from a quantum function to a representation of a circuit, we use queuing.

A *queuable object* is anything that can be placed into a queue. These will be :class:`~.Operator`,
:class:`~.MeasurementProcess`, and :class:`~.QuantumTape` objects. :class:`~.Operator` and
:class:`~.MeasurementProcess` objects achieve queuing via a :meth:`~.Operator.queue` method called upon construction.
Note that even though :class:`~.QuantumTape` is a queuable object, it does not have a ``queue`` method.

When an object is queued, it sends itself to the :class:`~.QueuingManager`. The :class:`~.QueuingManager`
is a global singleton class that facilitates placing objects in the queue. All of :class:`~.QueuingManager`'s methods
and properties are class methods and properties, so all instances will access the same information.

The :meth:`~.QueuingManager.active_context` is the queue where any new objects are placed.
The :class:`~.QueuingManager` is said to be *recording* if an active context exists.

Active contexts are :class:`~.AnnotatedQueue` instances. They are *context managers* where recording occurs
within a ``with`` block.

Let's take a look at an example. If we query the :class:`~.QueuingManager` outside of an
:class:`~.AnnotatedQueue`'s context, we can see that nothing is recording and no active context exists.

>>> print("Are we recording? ", qp.QueuingManager.recording())
Are we recording?  False
>>> print("What's the active context? ", qp.QueuingManager.active_context())
What's the active context?  None

Inside of a context, we can see the active recording context:

>>> with qp.queuing.AnnotatedQueue() as q:
...     print("Are we recording? ", qp.QueuingManager.recording())
...     print("Is q the active queue? ", q is qp.QueuingManager.active_context())
Are we recording?  True
Is q the active queue?  True

If we have nested :class:`~.AnnotatedQueue` contexts, only the innermost one will be recording.
Once the currently active queue exits, any outer queue will resume recording.

>>> with qp.queuing.AnnotatedQueue() as q1:
...     print("Is q1 recording? ", q1 is qp.QueuingManager.active_context())
...     with qp.queuing.AnnotatedQueue() as q2:
...         print("Is q1 recording? ", q1 is qp.QueuingManager.active_context())
...     print("Is q1 recording? ", q1 is qp.QueuingManager.active_context())
Is q1 recording?  True
Is q1 recording?  False
Is q1 recording?  True

If we construct an operator inside the recording context, we can see it is added to the queue:

>>> with qp.queuing.AnnotatedQueue() as q:
...     op = qp.X(0)
>>> q.queue
[X(0)]

If an operator is constructed outside of the context, we can manually add it to the queue by
calling the :meth:`~.Operator.queue` method. The :meth:`~.Operator.queue` method is automatically
called upon initialization, but it can also be manually called at a later time.

>>> op = qp.X(0)

.. code-block:: python

    with qp.queuing.AnnotatedQueue() as q:
        op.queue()

>>> q.queue
[X(0)]

An object can only exist up to *once* in the queue, so calling queue multiple times will
not do anything.

>>> op = qp.X(0)

.. code-block:: python

    with qp.queuing.AnnotatedQueue() as q:
        op.queue()
        op.queue()

>>> q.queue
[X(0)]

The :func:`~pennylane.apply` function allows a single object to be queued multiple times in a
circuit. The function queues a copy of the original object if it is already in the queue.

>>> op = qp.X(0)

.. code-block:: python

    with qp.queuing.AnnotatedQueue() as q:
        qp.apply(op)
        qp.apply(op)

>>> q.queue
[X(0), X(0)]
>>> q.queue[0] is q.queue[1]
False

In the case of operators composed of other operators, like with :class:`~.SymbolicOp` and
:class:`~.CompositeOp`, the new nested operation removes its constituents from the queue.
Only the operators that will end up in the circuit will remain.

>>> with qp.queuing.AnnotatedQueue() as q:
...     base = qp.X(0)
...     print(q.queue)
...     pow_op = base ** 1.5
...     print(q.queue)
[X(0)]
[X(0)**1.5]

Once the queue is constructed, the :meth:`~pennylane.tape.QuantumScript.from_queue` method converts it into the operations
and measurements in the final circuit. This step eliminates any object that has an owner.

.. code-block:: python

    with qp.queuing.AnnotatedQueue() as q:
        qp.StatePrep(np.array([1.0, 0]), wires=0)
        base = qp.X(0)
        pow_op = base ** 1.5
        qp.expval(qp.Z(0) @ qp.X(1))

>>> tape = qp.tape.QuantumScript.from_queue(q)
>>> tape.operations
[StatePrep(array([1., 0.]), wires=[0]), X(0)**1.5]
>>> tape.measurements
[expval(Z(0) @ X(1))]

In order to construct new operators within a recording, but without queuing them
use the :meth:`~.queuing.QueuingManager.stop_recording` context upon construction:

.. code-block:: python

    with qp.queuing.AnnotatedQueue() as q:
        with qp.QueuingManager.stop_recording():
            qp.Y(1)

>>> q.queue
[]

"""

from collections import OrderedDict
from contextlib import contextmanager
from threading import RLock
from typing import Optional

from pennylane import capture
from pennylane.capture.op_eqns import pop_op_eqns
from pennylane.exceptions import QueuingError


class WrappedObj:
    """Wraps an object to make its hash dependent on its identity"""

    def __init__(self, obj):
        self.obj = obj

    def __hash__(self):
        return id(self.obj)

    def __eq__(self, other):
        if not isinstance(other, WrappedObj):
            return False
        return id(self.obj) == id(other.obj)

    def __repr__(self):
        return f"Wrapped({self.obj.__repr__()})"


[docs] class QueuingManager: """Singleton global entry point for managing active recording contexts. This class consists purely of class methods. It both maintains a list of recording queues and allows communication with the currently active object. Queueable objects, like :class:`~.operation.Operator` and :class:`~.measurements.MeasurementProcess`, should use ``QueuingManager`` as an entry point for accessing the active queue. See also: :class:`~.AnnotatedQueue`, :class:`~.tape.QuantumTape`, :meth:`~.operation.Operator.queue`. Recording queues, such as :class:`~.AnnotatedQueue`, must define the following methods: * ``append``: define an action to perform when an object append request is made. * ``remove``: define an action to perform when an object removal request is made. * ``get_info``: retrieve the object's metadata * ``update_info``: Update an object's metadata if it is already queued. To start and end recording, the recording queue can use the :meth:`add_active_queue` and :meth:`remove_active_queue` methods. """ _active_contexts = [] """The stack of contexts that are currently active."""
[docs] @classmethod def add_active_queue(cls, queue): """Makes a queue the currently active recording context.""" cls._active_contexts.append(queue)
[docs] @classmethod def remove_active_queue(cls): """Ends recording on the currently active recording queue.""" return cls._active_contexts.pop()
[docs] @classmethod def recording(cls): """Whether a queuing context is active and recording operations""" return bool(cls._active_contexts)
[docs] @classmethod def active_context(cls) -> Optional["AnnotatedQueue"]: """Returns the currently active queuing context.""" return cls._active_contexts[-1] if cls.recording() else None
[docs] @classmethod @contextmanager def stop_recording(cls): """A context manager and decorator to ensure that contained logic is non-recordable or non-queueable within a QNode or quantum tape context. **Example:** Consider the function: >>> def list_of_ops(params, wires): ... return [ ... qp.RX(params[0], wires=wires), ... qp.RY(params[1], wires=wires), ... qp.RZ(params[2], wires=wires) ... ] If executed in a recording context, the operations constructed in the function will be queued: >>> dev = qp.device("default.qubit", wires=2) >>> @qp.qnode(dev) ... def circuit(params): ... ops = list_of_ops(params, wires=0) ... qp.apply(ops[-1]) # apply the last operation from the list again ... return qp.expval(qp.Z(0)) >>> print(qp.draw(circuit)([1, 2, 3])) 0: ──RX(1.00)──RY(2.00)──RZ(3.00)──RZ(3.00)─┤ <Z> Using the ``stop_recording`` context manager, all logic contained inside is not queued or recorded. >>> @qp.qnode(dev) ... def circuit(params): ... with qp.QueuingManager.stop_recording(): ... ops = list_of_ops(params, wires=0) ... qp.apply(ops[-1]) ... return qp.expval(qp.Z(0)) >>> print(qp.draw(circuit)([1, 2, 3])) 0: ──RZ(3.00)─┤ <Z> The context manager can also be used as a decorator on a function: >>> @qp.QueuingManager.stop_recording() ... def list_of_ops(params, wires): ... return [ ... qp.RX(params[0], wires=wires), ... qp.RY(params[1], wires=wires), ... qp.RZ(params[2], wires=wires) ... ] >>> @qp.qnode(dev) ... def circuit(params): ... ops = list_of_ops(params, wires=0) ... qp.apply(ops[-1]) ... return qp.expval(qp.Z(0)) >>> print(qp.draw(circuit)([1, 2, 3])) 0: ──RZ(3.00)─┤ <Z> """ previously_active_contexts = cls._active_contexts cls._active_contexts = [] try: yield finally: cls._active_contexts = previously_active_contexts
[docs] @classmethod def append(cls, obj, **kwargs): """Append an object to the queue(s). Args: obj: the object to be appended """ if cls.recording(): cls.active_context().append(obj, **kwargs)
[docs] @classmethod def remove(cls, obj): """Remove an object from the queue(s) if it is in the queue(s). Args: obj: the object to be removed """ if cls.recording(): cls.active_context().remove(obj)
[docs] @classmethod def update_info(cls, obj, **kwargs): """Updates information of an object in the active queue if it is already in the queue. Args: obj: the object with metadata to be updated """ if cls.recording(): cls.active_context().update_info(obj, **kwargs)
[docs] @classmethod def get_info(cls, obj): """Retrieves information of an object in the active queue. Args: obj: the object with metadata to be retrieved Returns: object metadata """ return cls.active_context().get_info(obj) if cls.recording() else None
[docs] class AnnotatedQueue(OrderedDict): """Lightweight class that maintains a basic queue of operations, in addition to metadata annotations.""" _lock = RLock() """threading.RLock: Used to synchronize appending to/popping from global QueueingContext.""" def __enter__(self): """Adds this instance to the global list of active contexts. Returns: AnnotatedQueue: this instance """ AnnotatedQueue._lock.acquire() QueuingManager.add_active_queue(self) return self def __exit__(self, exception_type, exception_value, traceback): """Remove this instance from the global list of active contexts.""" QueuingManager.remove_active_queue() AnnotatedQueue._lock.release()
[docs] def append(self, obj, **kwargs): """Append ``obj`` into the queue with ``kwargs`` metadata.""" obj = obj if isinstance(obj, WrappedObj) else WrappedObj(obj) self[obj] = kwargs
[docs] def remove(self, obj): """Remove ``obj`` from the queue. Passes silently if the object is not in the queue.""" obj = obj if isinstance(obj, WrappedObj) else WrappedObj(obj) if obj in self: del self[obj]
[docs] def update_info(self, obj, **kwargs): """Update ``obj``'s metadata with ``kwargs`` if it exists in the queue.""" obj = obj if isinstance(obj, WrappedObj) else WrappedObj(obj) if obj in self: self[obj].update(kwargs)
[docs] def get_info(self, obj): """Retrieve the metadata for ``obj``. Raises a ``QueuingError`` if obj is not in the queue.""" obj = obj if isinstance(obj, WrappedObj) else WrappedObj(obj) if obj not in self: raise QueuingError(f"Object {obj.obj} not in the queue.") return self[obj]
[docs] def items(self): return tuple((key.obj, value) for key, value in super().items())
@property def queue(self): """Returns a list of objects in the annotated queue""" return list(key.obj for key in self.keys()) def __setitem__(self, key, value): key = key if isinstance(key, WrappedObj) else WrappedObj(key) return super().__setitem__(key, value) def __getitem__(self, key): key = key if isinstance(key, WrappedObj) else WrappedObj(key) return super().__getitem__(key) def __contains__(self, key): key = key if isinstance(key, WrappedObj) else WrappedObj(key) return super().__contains__(key)
def remove_from_program(*ops): """Removes an operator from the captured/queued program.""" if QueuingManager.recording(): for op in ops: QueuingManager.remove(op) if capture.enabled(): pop_op_eqns(ops) __all__ = ["QueuingManager", "AnnotatedQueue", "remove_from_program"]