qiskit 2.1.0rc1__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/visualization/timeline/plotters/matplotlib.py

@@ -0,0 +1,195 @@
+# 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.
+
+# pylint: disable=invalid-name
+
+"""Matplotlib plotter API."""
+
+from typing import Optional, Tuple
+
+import matplotlib
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.collections import PatchCollection
+from matplotlib.patches import Rectangle
+
+from qiskit.visualization.exceptions import VisualizationError
+from qiskit.visualization.timeline import core, types, drawings
+from qiskit.visualization.timeline.plotters.base_plotter import BasePlotter
+from qiskit.visualization.utils import matplotlib_close_if_inline
+
+
+class MplPlotter(BasePlotter):
+    """Matplotlib API for pulse drawer.
+
+    This plotter arranges bits along y axis of 2D canvas with vertical offset.
+    """
+
+    def __init__(self, canvas: core.DrawerCanvas, axis: Optional[plt.Axes] = None):
+        """Create new plotter.
+
+        Args:
+            canvas: Configured drawer canvas object. Canvas object should be updated
+                with `.update` method before initializing the plotter.
+            axis: Matplotlib axis object. When `axis` is provided, the plotter updates
+                given axis instead of creating and returning new matplotlib figure.
+        """
+        super().__init__(canvas=canvas)
+
+        if axis is None:
+            fig_height = self.canvas.vmax - self.canvas.vmin
+            fig_h = self.canvas.formatter["general.fig_unit_height"] * fig_height
+            fig_w = self.canvas.formatter["general.fig_width"]
+
+            self.figure = plt.figure(figsize=(fig_w, fig_h))
+            self.ax = self.figure.add_subplot(1, 1, 1)
+        else:
+            self.figure = axis.figure
+            self.ax = axis
+
+        self.initialize_canvas()
+
+    def initialize_canvas(self):
+        """Format appearance of matplotlib canvas."""
+        self.ax.set_facecolor(self.canvas.formatter["color.background"])
+
+        # axis lines
+        self.ax.spines["right"].set_color("none")
+        self.ax.spines["left"].set_color("none")
+        self.ax.spines["top"].set_color("none")
+
+        # axis labels
+        self.ax.set_yticks([])
+        axis_config = self.canvas.layout["time_axis_map"](time_window=self.canvas.time_range)
+
+        self.ax.set_xticks(list(axis_config.axis_map.keys()))
+        self.ax.set_xticklabels(
+            list(axis_config.axis_map.values()),
+            fontsize=self.canvas.formatter["text_size.axis_label"],
+        )
+        self.ax.set_xlabel(
+            axis_config.label, fontsize=self.canvas.formatter["text_size.axis_label"]
+        )
+
+        # boundary
+        self.ax.set_xlim(*self.canvas.time_range)
+        self.ax.set_ylim(self.canvas.vmin, self.canvas.vmax)
+
+    def draw(self):
+        """Output drawings stored in canvas object."""
+
+        for _, data in self.canvas.collections:
+            xvals = np.asarray(data.xvals, dtype=float)
+            yvals = np.asarray(data.yvals, dtype=float)
+            offsets = [self.canvas.assigned_coordinates[bit] for bit in data.bits]
+
+            if isinstance(data, drawings.BoxData):
+                # box data
+                if data.data_type in [
+                    str(types.BoxType.SCHED_GATE.value),
+                    str(types.BoxType.DELAY.value),
+                ]:
+                    # draw a smoothly rounded rectangle
+                    xs, ys1, ys2 = self._time_bucket_outline(xvals, yvals)
+                    self.ax.fill_between(
+                        x=xs, y1=ys1 + offsets[0], y2=ys2 + offsets[0], **data.styles
+                    )
+
+                else:
+                    # draw a rectangle
+                    x0, x1 = xvals
+                    y0, y1 = yvals + offsets[0]
+
+                    rect = Rectangle(xy=(x0, y0), width=x1 - x0, height=y1 - y0)
+                    pc = PatchCollection([rect], **data.styles)
+                    self.ax.add_collection(pc)
+
+            elif isinstance(data, drawings.LineData):
+                # line data
+                self.ax.plot(xvals, yvals + offsets[0], **data.styles)
+
+            elif isinstance(data, drawings.TextData):
+                # text data
+                if data.latex is not None:
+                    s = rf"${data.latex}$"
+                else:
+                    s = data.text
+
+                self.ax.text(x=xvals[0], y=yvals[0] + offsets[0], s=s, **data.styles)
+
+            elif isinstance(data, drawings.GateLinkData):
+                # gate link data
+                self.ax.plot(xvals.repeat(len(offsets)), offsets, **data.styles)
+
+            else:
+                raise VisualizationError(
+                    f"Data {data} is not supported by {self.__class__.__name__}"
+                )
+
+    def _time_bucket_outline(
+        self, xvals: np.ndarray, yvals: np.ndarray
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """Generate outline of time bucket. Edges are smoothly faded.
+
+        Args:
+            xvals: Left and right point coordinates.
+            yvals: Bottom and top point coordinates.
+
+        Returns:
+            Coordinate vectors of time bucket fringe.
+        """
+        x0, x1 = xvals
+        y0, y1 = yvals
+
+        width = x1 - x0
+        y_mid = 0.5 * (y0 + y1)
+
+        risefall = int(min(self.canvas.formatter["time_bucket.edge_dt"], max(width / 2 - 2, 0)))
+        edge = np.sin(np.pi / 2 * np.arange(0, risefall) / risefall)
+
+        xs = np.concatenate(
+            [
+                np.arange(x0, x0 + risefall),
+                [x0 + risefall, x1 - risefall],
+                np.arange(x1 - risefall + 1, x1 + 1),
+            ]
+        )
+
+        l1 = (y1 - y_mid) * np.concatenate([edge, [1, 1], edge[::-1]])
+        l2 = (y0 - y_mid) * np.concatenate([edge, [1, 1], edge[::-1]])
+
+        return xs, l1, l2
+
+    def save_file(self, filename: str):
+        """Save image to file.
+        Args:
+            filename: File path to output image data.
+        """
+        plt.savefig(filename, bbox_inches="tight", dpi=self.canvas.formatter["general.dpi"])
+
+    def get_image(self, interactive: bool = False) -> matplotlib.pyplot.Figure:
+        """Get image data to return.
+        Args:
+            interactive: When set `True` show the circuit in a new window.
+                This depends on the matplotlib backend being used supporting this.
+        Returns:
+            Matplotlib figure data.
+        """
+        matplotlib_close_if_inline(self.figure)
+
+        if self.figure and interactive:
+            self.figure.show()
+        try:
+            self.figure.tight_layout()
+        except AttributeError:
+            pass
+        return self.figure

qiskit/visualization/timeline/stylesheet.py

@@ -0,0 +1,301 @@
+# 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.
+
+"""
+Stylesheet for timeline drawer.
+
+# TODO merge this docstring with pulse drawer.
+
+The stylesheet `QiskitTimelineStyle` is initialized with the hard-corded default values in
+`default_style`.
+
+The `QiskitTimelineStyle` is a wrapper class of python dictionary with
+the nested keys written such as `<type>.<group>.<item>` to represent a specific item
+from many configuration options. This key representation is imitative of
+`rcParams` of `matplotlib`.  However, the `QiskitTimelineStyle` does not need to be compatible
+with the `rcParams` because the timeline stylesheet is heavily specialized to the context of
+the scheduled circuit visualization.
+
+Type of stylesheet is broadly separated into `formatter`, `generator` and `layout`.
+The formatter is a nested dictionary of drawing parameters to control the appearance of
+each visualization element. This data structure is similar to the `rcParams` of `matplotlib`.
+
+The generator is a list of callback functions that generates drawings from
+a given data source and the formatter. Each item can take multiple functions so that
+several drawing data, for example, box, text, etc..., are generated from the single data source.
+The layout is a callback function that determines the appearance of the output image.
+Because a single stylesheet doesn't generate multiple images with different appearance,
+only one layout function can be chosen for each stylesheet.
+"""
+
+from typing import Dict, Any, Mapping
+
+from qiskit.visualization.timeline import generators, layouts
+
+
+class QiskitTimelineStyle(dict):
+    """Stylesheet for pulse drawer."""
+
+    def __init__(self):
+        super().__init__()
+        # to inform which stylesheet is applied. some plotter may not support specific style.
+        self.stylesheet = None
+        self.update(default_style())
+
+    def update(self, __m: Mapping[str, Any], **kwargs) -> None:
+        super().update(__m, **kwargs)
+        for key, value in __m.items():
+            self.__setitem__(key, value)
+        self.stylesheet = __m.__class__.__name__
+
+    @property
+    def formatter(self):
+        """Return formatter field of style dictionary."""
+        sub_dict = {}
+        for key, value in self.items():
+            sub_keys = key.split(".")
+            if sub_keys[0] == "formatter":
+                sub_dict[".".join(sub_keys[1:])] = value
+        return sub_dict
+
+    @property
+    def generator(self):
+        """Return generator field of style dictionary."""
+        sub_dict = {}
+        for key, value in self.items():
+            sub_keys = key.split(".")
+            if sub_keys[0] == "generator":
+                sub_dict[".".join(sub_keys[1:])] = value
+        return sub_dict
+
+    @property
+    def layout(self):
+        """Return layout field of style dictionary."""
+        sub_dict = {}
+        for key, value in self.items():
+            sub_keys = key.split(".")
+            if sub_keys[0] == "layout":
+                sub_dict[".".join(sub_keys[1:])] = value
+        return sub_dict
+
+
+class IQXStandard(dict):
+    """Standard timeline stylesheet.
+
+    - Show time buckets.
+    - Show only operand name.
+    - Show bit name.
+    - Show barriers.
+    - Show idle timeline.
+    - Show gate link.
+    - Remove classical bits.
+    """
+
+    def __init__(self, **kwargs):
+        super().__init__()
+        style = {
+            "formatter.control.show_idle": True,
+            "formatter.control.show_clbits": False,
+            "formatter.control.show_barriers": True,
+            "formatter.control.show_delays": False,
+            "generator.gates": [generators.gen_sched_gate, generators.gen_short_gate_name],
+            "generator.bits": [generators.gen_bit_name, generators.gen_timeslot],
+            "generator.barriers": [generators.gen_barrier],
+            "generator.gate_links": [generators.gen_gate_link],
+            "layout.bit_arrange": layouts.qreg_creg_ascending,
+            "layout.time_axis_map": layouts.time_map_in_dt,
+        }
+        style.update(**kwargs)
+        self.update(style)
+
+    def __repr__(self):
+        return "Standard timeline style sheet."
+
+
+class IQXSimple(dict):
+    """Simple timeline stylesheet.
+
+    - Show time buckets.
+    - Show bit name.
+    - Show gate link.
+    - Remove idle timeline.
+    - Remove classical bits.
+    """
+
+    def __init__(self, **kwargs):
+        super().__init__()
+        style = {
+            "formatter.control.show_idle": False,
+            "formatter.control.show_clbits": False,
+            "formatter.control.show_barriers": False,
+            "formatter.control.show_delays": False,
+            "generator.gates": [generators.gen_sched_gate],
+            "generator.bits": [generators.gen_bit_name, generators.gen_timeslot],
+            "generator.barriers": [generators.gen_barrier],
+            "generator.gate_links": [generators.gen_gate_link],
+            "layout.bit_arrange": layouts.qreg_creg_ascending,
+            "layout.time_axis_map": layouts.time_map_in_dt,
+        }
+        style.update(**kwargs)
+        self.update(style)
+
+    def __repr__(self):
+        return "Simplified timeline style sheet."
+
+
+class IQXDebugging(dict):
+    """Timeline stylesheet for programmers. Show details of instructions.
+
+    - Show time buckets.
+    - Show operand name, qubits, and parameters.
+    - Show barriers.
+    - Show delays.
+    - Show idle timeline.
+    - Show bit name.
+    - Show gate link.
+    """
+
+    def __init__(self, **kwargs):
+        super().__init__()
+        style = {
+            "formatter.control.show_idle": True,
+            "formatter.control.show_clbits": True,
+            "formatter.control.show_barriers": True,
+            "formatter.control.show_delays": True,
+            "generator.gates": [generators.gen_sched_gate, generators.gen_full_gate_name],
+            "generator.bits": [generators.gen_bit_name, generators.gen_timeslot],
+            "generator.barriers": [generators.gen_barrier],
+            "generator.gate_links": [generators.gen_gate_link],
+            "layout.bit_arrange": layouts.qreg_creg_ascending,
+            "layout.time_axis_map": layouts.time_map_in_dt,
+        }
+        style.update(**kwargs)
+        self.update(style)
+
+    def __repr__(self):
+        return "Timeline style sheet for timeline programmers."
+
+
+def default_style() -> Dict[str, Any]:
+    """Define default values of the timeline stylesheet."""
+    return {
+        "formatter.general.fig_width": 14,
+        "formatter.general.fig_unit_height": 0.8,
+        "formatter.general.dpi": 150,
+        "formatter.margin.top": 0.5,
+        "formatter.margin.bottom": 0.5,
+        "formatter.margin.left_percent": 0.02,
+        "formatter.margin.right_percent": 0.02,
+        "formatter.margin.link_interval_percent": 0.01,
+        "formatter.margin.minimum_duration": 50,
+        "formatter.time_bucket.edge_dt": 10,
+        "formatter.color.background": "#FFFFFF",
+        "formatter.color.timeslot": "#DDDDDD",
+        "formatter.color.gate_name": "#000000",
+        "formatter.color.bit_name": "#000000",
+        "formatter.color.barrier": "#222222",
+        "formatter.color.gates": {
+            "u0": "#FA74A6",
+            "u1": "#000000",
+            "u2": "#FA74A6",
+            "u3": "#FA74A6",
+            "id": "#05BAB6",
+            "sx": "#FA74A6",
+            "sxdg": "#FA74A6",
+            "x": "#05BAB6",
+            "y": "#05BAB6",
+            "z": "#05BAB6",
+            "h": "#6FA4FF",
+            "cx": "#6FA4FF",
+            "cy": "#6FA4FF",
+            "cz": "#6FA4FF",
+            "swap": "#6FA4FF",
+            "s": "#6FA4FF",
+            "sdg": "#6FA4FF",
+            "dcx": "#6FA4FF",
+            "iswap": "#6FA4FF",
+            "t": "#BB8BFF",
+            "tdg": "#BB8BFF",
+            "r": "#BB8BFF",
+            "rx": "#BB8BFF",
+            "ry": "#BB8BFF",
+            "rz": "#000000",
+            "reset": "#808080",
+            "measure": "#808080",
+        },
+        "formatter.color.default_gate": "#BB8BFF",
+        "formatter.latex_symbol.gates": {
+            "u0": r"{\rm U}_0",
+            "u1": r"{\rm U}_1",
+            "u2": r"{\rm U}_2",
+            "u3": r"{\rm U}_3",
+            "id": r"{\rm Id}",
+            "x": r"{\rm X}",
+            "y": r"{\rm Y}",
+            "z": r"{\rm Z}",
+            "h": r"{\rm H}",
+            "cx": r"{\rm CX}",
+            "cy": r"{\rm CY}",
+            "cz": r"{\rm CZ}",
+            "swap": r"{\rm SWAP}",
+            "s": r"{\rm S}",
+            "sdg": r"{\rm S}^\dagger",
+            "sx": r"{\rm √X}",
+            "sxdg": r"{\rm √X}^\dagger",
+            "dcx": r"{\rm DCX}",
+            "iswap": r"{\rm iSWAP}",
+            "t": r"{\rm T}",
+            "tdg": r"{\rm T}^\dagger",
+            "r": r"{\rm R}",
+            "rx": r"{\rm R}_x",
+            "ry": r"{\rm R}_y",
+            "rz": r"{\rm R}_z",
+            "reset": r"|0\rangle",
+            "measure": r"{\rm Measure}",
+        },
+        "formatter.latex_symbol.frame_change": r"\circlearrowleft",
+        "formatter.unicode_symbol.frame_change": "\u21BA",
+        "formatter.box_height.gate": 0.5,
+        "formatter.box_height.timeslot": 0.6,
+        "formatter.layer.gate": 3,
+        "formatter.layer.timeslot": 0,
+        "formatter.layer.gate_name": 5,
+        "formatter.layer.bit_name": 5,
+        "formatter.layer.frame_change": 4,
+        "formatter.layer.barrier": 1,
+        "formatter.layer.gate_link": 2,
+        "formatter.alpha.gate": 1.0,
+        "formatter.alpha.timeslot": 0.7,
+        "formatter.alpha.barrier": 0.5,
+        "formatter.alpha.gate_link": 0.8,
+        "formatter.line_width.gate": 0,
+        "formatter.line_width.timeslot": 0,
+        "formatter.line_width.barrier": 3,
+        "formatter.line_width.gate_link": 3,
+        "formatter.line_style.barrier": "-",
+        "formatter.line_style.gate_link": "-",
+        "formatter.text_size.gate_name": 12,
+        "formatter.text_size.bit_name": 15,
+        "formatter.text_size.frame_change": 18,
+        "formatter.text_size.axis_label": 13,
+        "formatter.label_offset.frame_change": 0.25,
+        "formatter.control.show_idle": True,
+        "formatter.control.show_clbits": True,
+        "formatter.control.show_barriers": True,
+        "formatter.control.show_delays": True,
+        "generator.gates": [],
+        "generator.bits": [],
+        "generator.barriers": [],
+        "generator.gate_links": [],
+        "layout.bit_arrange": None,
+        "layout.time_axis_map": None,
+    }

qiskit/visualization/timeline/types.py

@@ -0,0 +1,148 @@
+# 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.
+
+"""
+Special data types.
+"""
+
+from enum import Enum
+from typing import NamedTuple, List, Union, NewType, Tuple, Dict
+
+from qiskit import circuit
+
+
+ScheduledGate = NamedTuple(
+    "ScheduledGate",
+    [
+        ("t0", int),
+        ("operand", circuit.Gate),
+        ("duration", int),
+        ("bits", List[Union[circuit.Qubit, circuit.Clbit]]),
+        ("bit_position", int),
+    ],
+)
+ScheduledGate.__doc__ = "A gate instruction with embedded time."
+ScheduledGate.t0.__doc__ = "Time when the instruction is issued."
+ScheduledGate.operand.__doc__ = "Gate object associated with the gate."
+ScheduledGate.duration.__doc__ = "Time duration of the instruction."
+ScheduledGate.bits.__doc__ = "List of bit associated with the gate."
+ScheduledGate.bit_position.__doc__ = "Position of bit associated with this drawing source."
+
+
+GateLink = NamedTuple(
+    "GateLink", [("t0", int), ("opname", str), ("bits", List[Union[circuit.Qubit, circuit.Clbit]])]
+)
+GateLink.__doc__ = "Dedicated object to represent a relationship between instructions."
+GateLink.t0.__doc__ = "A position where the link is placed."
+GateLink.opname.__doc__ = "Name of gate associated with this link."
+GateLink.bits.__doc__ = "List of bit associated with the instruction."
+
+
+Barrier = NamedTuple(
+    "Barrier",
+    [("t0", int), ("bits", List[Union[circuit.Qubit, circuit.Clbit]]), ("bit_position", int)],
+)
+Barrier.__doc__ = "Dedicated object to represent a barrier instruction."
+Barrier.t0.__doc__ = "A position where the barrier is placed."
+Barrier.bits.__doc__ = "List of bit associated with the instruction."
+Barrier.bit_position.__doc__ = "Position of bit associated with this drawing source."
+
+
+HorizontalAxis = NamedTuple(
+    "HorizontalAxis", [("window", Tuple[int, int]), ("axis_map", Dict[int, int]), ("label", str)]
+)
+HorizontalAxis.__doc__ = "Data to represent configuration of horizontal axis."
+HorizontalAxis.window.__doc__ = "Left and right edge of graph."
+HorizontalAxis.axis_map.__doc__ = "Mapping of apparent coordinate system and actual location."
+HorizontalAxis.label.__doc__ = "Label of horizontal axis."
+
+
+class BoxType(str, Enum):
+    """Box type.
+
+    SCHED_GATE: Box that represents occupation time by gate.
+    DELAY: Box associated with delay.
+    TIMELINE: Box that represents time slot of a bit.
+    """
+
+    SCHED_GATE = "Box.ScheduledGate"
+    DELAY = "Box.Delay"
+    TIMELINE = "Box.Timeline"
+
+
+class LineType(str, Enum):
+    """Line type.
+
+    BARRIER: Line that represents barrier instruction.
+    GATE_LINK: Line that represents a link among gates.
+    """
+
+    BARRIER = "Line.Barrier"
+    GATE_LINK = "Line.GateLink"
+
+
+class SymbolType(str, Enum):
+    """Symbol type.
+
+    FRAME: Symbol that represents zero time frame change (Rz) instruction.
+    """
+
+    FRAME = "Symbol.Frame"
+
+
+class LabelType(str, Enum):
+    """Label type.
+
+    GATE_NAME: Label that represents name of gate.
+    DELAY: Label associated with delay.
+    GATE_PARAM: Label that represents parameter of gate.
+    BIT_NAME: Label that represents name of bit.
+    """
+
+    GATE_NAME = "Label.Gate.Name"
+    DELAY = "Label.Delay"
+    GATE_PARAM = "Label.Gate.Param"
+    BIT_NAME = "Label.Bit.Name"
+
+
+class AbstractCoordinate(Enum):
+    """Abstract coordinate that the exact value depends on the user preference.
+
+    RIGHT: The horizontal coordinate at t0 shifted by the left margin.
+    LEFT: The horizontal coordinate at tf shifted by the right margin.
+    TOP: The vertical coordinate at the top of the canvas.
+    BOTTOM: The vertical coordinate at the bottom of the canvas.
+    """
+
+    RIGHT = "RIGHT"
+    LEFT = "LEFT"
+    TOP = "TOP"
+    BOTTOM = "BOTTOM"
+
+
+class Plotter(str, Enum):
+    """Name of timeline plotter APIs.
+
+    MPL: Matplotlib plotter interface. Show timeline in 2D canvas.
+    """
+
+    MPL = "mpl"
+
+
+# convenient type to represent union of drawing data
+DataTypes = NewType("DataType", Union[BoxType, LabelType, LineType, SymbolType])
+
+# convenient type to represent union of values to represent a coordinate
+Coordinate = NewType("Coordinate", Union[float, AbstractCoordinate])
+
+# Valid bit objects
+Bits = NewType("Bits", Union[circuit.Qubit, circuit.Clbit])