qiskit 2.1.0rc1__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/visualization/timeline/drawings.py

@@ -0,0 +1,260 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2020.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+Drawing objects for timeline drawer.
+
+Drawing objects play two important roles:
+    - Allowing unittests of visualization module. Usually it is hard for image files to be tested.
+    - Removing program parser from each plotter interface. We can easily add new plotter.
+
+This module is based on the structure of matplotlib as it is the primary plotter
+of the timeline drawer. However this interface is agnostic to the actual plotter.
+
+Design concept
+~~~~~~~~~~~~~~
+When we think about dynamically updating drawings, it will be most efficient to
+update only the changed properties of drawings rather than regenerating entirely from scratch.
+Thus the core :py:class:`~qiskit.visualization.timeline.core.DrawerCanvas` generates
+all possible drawings in the beginning and then the canvas instance manages
+visibility of each drawing according to the end-user request.
+
+Data key
+~~~~~~~~
+In the abstract class ``ElementaryData`` common attributes to represent a drawing are
+specified. In addition, drawings have the `data_key` property that returns an
+unique hash of the object for comparison.
+This key is generated from a data type, the location of the drawing in the canvas,
+and associated qubit or classical bit objects.
+See py:mod:`qiskit.visualization.timeline.types` for detail on the data type.
+If a data key cannot distinguish two independent objects, you need to add a new data type.
+The data key may be used in the plotter interface to identify the object.
+
+Drawing objects
+~~~~~~~~~~~~~~~
+To support not only `matplotlib` but also multiple plotters, those drawings should be
+universal and designed without strong dependency on modules in `matplotlib`.
+This means drawings that represent primitive geometries are preferred.
+It should be noted that there will be no unittest for each plotter API, which takes
+drawings and outputs image data, we should avoid adding a complicated geometry
+that has a context of the scheduled circuit program.
+
+For example, a two qubit scheduled gate may be drawn by two rectangles that represent
+time occupation of two quantum registers during the gate along with a line connecting
+these rectangles to identify the pair. This shape can be represented with
+two box-type objects with one line-type object instead of defining a new object dedicated
+to the two qubit gate. As many plotters don't support an API that visualizes such
+a linked-box shape, if we introduce such complex drawings and write a
+custom wrapper function on top of the existing API,
+it could be difficult to prevent bugs with the CI tools due to lack of
+the effective unittest for image data.
+
+Link between gates
+~~~~~~~~~~~~~~~~~~
+The ``GateLinkData`` is the special subclass of drawing that represents
+a link between bits. Usually objects are associated to the specific bit,
+but ``GateLinkData`` can be associated with multiple bits to illustrate relationship
+between quantum or classical bits during a gate operation.
+"""
+
+from abc import ABC
+from enum import Enum
+from typing import Optional, Dict, Any, List, Union
+
+import numpy as np
+
+from qiskit import circuit
+from qiskit.visualization.timeline import types
+from qiskit.visualization.exceptions import VisualizationError
+
+
+class ElementaryData(ABC):
+    """Base class of the scheduled circuit visualization object.
+
+    Note that drawings are mutable.
+    """
+
+    __hash__ = None
+
+    def __init__(
+        self,
+        data_type: Union[str, Enum],
+        xvals: Union[np.ndarray, List[types.Coordinate]],
+        yvals: Union[np.ndarray, List[types.Coordinate]],
+        bits: Optional[Union[types.Bits, List[types.Bits]]] = None,
+        meta: Optional[Dict[str, Any]] = None,
+        styles: Optional[Dict[str, Any]] = None,
+    ):
+        """Create new drawing.
+
+        Args:
+            data_type: String representation of this drawing.
+            xvals: Series of horizontal coordinate that the object is drawn.
+            yvals: Series of vertical coordinate that the object is drawn.
+            bits: Qubit or Clbit object bound to this drawing.
+            meta: Meta data dictionary of the object.
+            styles: Style keyword args of the object. This conforms to `matplotlib`.
+        """
+        if bits and isinstance(bits, (circuit.Qubit, circuit.Clbit)):
+            bits = [bits]
+
+        if isinstance(data_type, Enum):
+            data_type = data_type.value
+
+        self.data_type = str(data_type)
+        self.xvals = xvals
+        self.yvals = yvals
+        self.bits = bits
+        self.meta = meta
+        self.styles = styles
+
+    @property
+    def data_key(self):
+        """Return unique hash of this object."""
+        return str(
+            hash(
+                (
+                    self.__class__.__name__,
+                    self.data_type,
+                    tuple(self.bits),
+                    tuple(self.xvals),
+                    tuple(self.yvals),
+                )
+            )
+        )
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}(type={self.data_type}, key={self.data_key})"
+
+    def __eq__(self, other):
+        return isinstance(other, self.__class__) and self.data_key == other.data_key
+
+
+class LineData(ElementaryData):
+    """Drawing object that represents line shape."""
+
+    def __init__(
+        self,
+        data_type: Union[str, Enum],
+        xvals: Union[np.ndarray, List[types.Coordinate]],
+        yvals: Union[np.ndarray, List[types.Coordinate]],
+        bit: types.Bits,
+        meta: Dict[str, Any] = None,
+        styles: Dict[str, Any] = None,
+    ):
+        """Create new line.
+
+        Args:
+            data_type: String representation of this drawing.
+            xvals: Series of horizontal coordinate that the object is drawn.
+            yvals: Series of vertical coordinate that the object is drawn.
+            bit: Bit associated to this object.
+            meta: Meta data dictionary of the object.
+            styles: Style keyword args of the object. This conforms to `matplotlib`.
+        """
+        super().__init__(
+            data_type=data_type, xvals=xvals, yvals=yvals, bits=bit, meta=meta, styles=styles
+        )
+
+
+class BoxData(ElementaryData):
+    """Drawing object that represents box shape."""
+
+    def __init__(
+        self,
+        data_type: Union[str, Enum],
+        xvals: Union[np.ndarray, List[types.Coordinate]],
+        yvals: Union[np.ndarray, List[types.Coordinate]],
+        bit: types.Bits,
+        meta: Dict[str, Any] = None,
+        styles: Dict[str, Any] = None,
+    ):
+        """Create new box.
+
+        Args:
+            data_type: String representation of this drawing.
+            xvals: Left and right coordinate that the object is drawn.
+            yvals: Top and bottom coordinate that the object is drawn.
+            bit: Bit associated to this object.
+            meta: Meta data dictionary of the object.
+            styles: Style keyword args of the object. This conforms to `matplotlib`.
+
+        Raises:
+            VisualizationError: When number of data points are not equals to 2.
+        """
+        if len(xvals) != 2 or len(yvals) != 2:
+            raise VisualizationError("Length of data points are not equals to 2.")
+
+        super().__init__(
+            data_type=data_type, xvals=xvals, yvals=yvals, bits=bit, meta=meta, styles=styles
+        )
+
+
+class TextData(ElementaryData):
+    """Drawing object that represents a text on canvas."""
+
+    def __init__(
+        self,
+        data_type: Union[str, Enum],
+        xval: types.Coordinate,
+        yval: types.Coordinate,
+        bit: types.Bits,
+        text: str,
+        latex: Optional[str] = None,
+        meta: Dict[str, Any] = None,
+        styles: Dict[str, Any] = None,
+    ):
+        """Create new text.
+
+        Args:
+            data_type: String representation of this drawing.
+            xval: Horizontal coordinate that the object is drawn.
+            yval: Vertical coordinate that the object is drawn.
+            bit: Bit associated to this object.
+            text: A string to draw on the canvas.
+            latex: If set this string is used instead of `text`.
+            meta: Meta data dictionary of the object.
+            styles: Style keyword args of the object. This conforms to `matplotlib`.
+        """
+        self.text = text
+        self.latex = latex
+
+        super().__init__(
+            data_type=data_type, xvals=[xval], yvals=[yval], bits=bit, meta=meta, styles=styles
+        )
+
+
+class GateLinkData(ElementaryData):
+    """A special drawing data type that represents bit link of multi-bit gates.
+
+    Note this object takes multiple bits and dedicates them to the bit link.
+    This may appear as a line on the canvas.
+    """
+
+    def __init__(
+        self, xval: types.Coordinate, bits: List[types.Bits], styles: Dict[str, Any] = None
+    ):
+        """Create new bit link.
+
+        Args:
+            xval: Horizontal coordinate that the object is drawn.
+            bits: Bit associated to this object.
+            styles: Style keyword args of the object. This conforms to `matplotlib`.
+        """
+        super().__init__(
+            data_type=types.LineType.GATE_LINK,
+            xvals=[xval],
+            yvals=[0],
+            bits=bits,
+            meta=None,
+            styles=styles,
+        )