qilisdk 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

qilisdk/utils/visualization/schedule_renderers.py

@@ -0,0 +1,161 @@
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# 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.
+
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import matplotlib.pyplot as plt
+
+if TYPE_CHECKING:
+    from qilisdk.analog.schedule import Schedule
+    from qilisdk.common.variables import Number
+
+from qilisdk.utils.visualization.style import ScheduleStyle
+
+
+class MatplotlibScheduleRenderer:
+    """Render a Schedule using matplotlib, with theme support."""
+
+    def __init__(self, schedule: Schedule, ax: plt.Axes | None = None, *, style: ScheduleStyle | None = None) -> None:
+        self.schedule = schedule
+        self.style = style or ScheduleStyle()
+        self.ax = ax or self._make_axes(self.style.dpi, self.style)
+
+    def plot(self, ax: plt.Axes | None = None) -> None:
+        """
+        Plot the schedule coefficients for each Hamiltonian over time.
+        Args:
+            ax (plt.Axes | None): The matplotlib axes to plot on. Default is None.
+        """
+        style = self.style
+        theme = style.theme
+        facecolor = theme.background
+        title_color = theme.on_background
+        label_color = theme.on_background
+        legend_facecolor = theme.surface
+        legend_edgecolor = theme.border
+        tick_color = theme.on_background
+
+        # Set axes and figure background to theme
+        self.ax.set_facecolor(facecolor)
+        if hasattr(ax, "figure"):
+            self.ax.figure.set_facecolor(facecolor)
+        plots: dict[str, list[Number]] = {}
+        T = self.schedule.T
+        dt = self.schedule.dt
+        hamiltonians = self.schedule.hamiltonians
+        times = [i * dt for i in range(int(T / dt))]
+        for h in hamiltonians:
+            plots[h] = []
+        for _t in range(int(T / dt)):
+            t = _t * dt
+            for h in hamiltonians:
+                plots[h].append(self.schedule.get_coefficient(t, h))
+
+        # Generate gradient colors between primary and accent
+        def hex_to_rgb(hex_color: str) -> tuple[int, ...]:
+            hex_color = hex_color.lstrip("#")
+            return tuple(int(hex_color[i : i + 2], 16) for i in (0, 2, 4))
+
+        def rgb_to_hex(rgb: tuple[int, ...]) -> str:
+            return "#{:02x}{:02x}{:02x}".format(*rgb)
+
+        def gradient_colors(start_hex: str, end_hex: str, n: int) -> list[str]:
+            start_rgb = hex_to_rgb(start_hex)
+            end_rgb = hex_to_rgb(end_hex)
+            colors = []
+            for i in range(n):
+                ratio = i / max(n - 1, 1)
+                rgb = tuple(int(start_rgb[j] + (end_rgb[j] - start_rgb[j]) * ratio) for j in range(3))
+                colors.append(rgb_to_hex(rgb))
+            return colors
+
+        n_hams = len(hamiltonians)
+        grad_colors = gradient_colors(theme.primary, theme.accent, n_hams)
+
+        for idx, h in enumerate(hamiltonians):
+            line_style = style.line_styles.get(h, style.default_line_style)
+            marker = style.marker
+            # If no color specified, use gradient color
+            if "color" not in line_style:
+                color = grad_colors[idx]
+                line_style = {**line_style, "color": color}
+            self.ax.plot(times, plots[h], label=h, marker=marker, markersize=style.marker_size, **line_style)
+        if style.grid:
+            grid_style = dict(style.grid_style)
+            if "color" not in grid_style:
+                grid_style["color"] = theme.surface_muted
+            self.ax.grid(**grid_style)
+        leg = self.ax.legend(
+            loc=style.legend_loc,
+            fontsize=style.legend_fontsize,
+            frameon=style.legend_frame,
+            facecolor=legend_facecolor,
+            edgecolor=legend_edgecolor,
+        )
+        # Set legend text color to match theme text color
+        if leg:
+            for text in leg.get_texts():
+                text.set_color(title_color)
+        self.ax.set_title(
+            self.style.title or "Schedule Plot",
+            fontsize=style.title_fontsize,
+            color=title_color,
+            fontweight=style.fontweight,
+            family=style.fontfamily,
+        )
+        self.ax.set_xlabel(
+            style.xlabel,
+            fontsize=style.label_fontsize,
+            color=label_color,
+            fontweight=style.fontweight,
+            family=style.fontfamily,
+        )
+        self.ax.set_ylabel(
+            style.ylabel,
+            fontsize=style.label_fontsize,
+            color=label_color,
+            fontweight=style.fontweight,
+            family=style.fontfamily,
+        )
+        self.ax.tick_params(axis="x", labelsize=style.xtick_fontsize, colors=tick_color)
+        self.ax.tick_params(axis="y", labelsize=style.ytick_fontsize, colors=tick_color)
+        if style.tight_layout:
+            plt.tight_layout()
+        plt.draw()
+
+    def save(self, filename: str) -> None:  # thin wrapper
+        """Save current figure to disk.
+
+        Args:
+            filename: Path to save the figure (e.g., 'circuit.png').
+        """
+
+        self.ax.figure.savefig(filename, bbox_inches="tight")  # type: ignore[union-attr]
+
+    @staticmethod
+    def _make_axes(dpi: int, style: ScheduleStyle) -> plt.Axes:
+        """
+        Create a new figure and axes with the given DPI.
+
+        Args:
+            style: Optional style configuration (for DPI).
+
+        Returns:
+            A newly created Matplotlib Axes.
+        """
+        _, ax = plt.subplots(figsize=style.figsize, dpi=style.dpi, facecolor=style.theme.background)
+        return ax

qilisdk/utils/visualization/style.py

@@ -0,0 +1,154 @@
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# 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.
+
+from pathlib import Path
+from typing import Any, Literal, Optional
+
+import matplotlib.font_manager as fm
+from pydantic import BaseModel, Field
+
+from .themes import Theme, light
+
+_DEFAULT_FONT_PATH = Path(__file__).parent / "PlusJakartaSans-SemiBold.ttf"
+
+
+class Style(BaseModel):
+    # --- FontProperties-mapped fields (mirror matplotlib.font_manager.FontProperties) ---
+    # If `fontfname` exists, it takes precedence and loads the exact TTF.
+    theme: Theme = Field(default=light, description="Colour theme.")
+    fontfamily: str | list[str] | None = Field(
+        default=None, description="Font family name(s), e.g. 'Outfit' or ['Outfit', 'DejaVu Sans']."
+    )
+    fontstyle: Literal["normal", "italic", "oblique"] = Field(
+        default="normal", description="Font style: 'normal', 'italic', or 'oblique'."
+    )
+    fontvariant: Literal["normal", "small-caps"] = Field(
+        default="normal", description="Font variant: typically 'normal' or 'small-caps'."
+    )
+    fontweight: str | int = Field(
+        default="normal", description="Font weight: 'normal', 'bold', 'light', or numeric (100-900)."
+    )
+    fontstretch: str | int = Field(
+        default="normal", description="Width/condensation: 'ultra-condensed'..'ultra-expanded' or numeric."
+    )
+    fontsize: float | str = Field(
+        default=10, description="Font size in pt or keywords like 'small', 'medium', 'large'."
+    )
+    fontfname: str | None = Field(
+        default=str(_DEFAULT_FONT_PATH), description="Absolute path to the TTF/OTF file. If present, overrides family."
+    )
+    math_fontfamily: str | None = Field(default=None, description="Math text family, e.g. 'dejavusans', 'cm', or None.")
+    dpi: int = Field(default=150, description="Figure DPI.")
+    title: str | None = Field(default=None, description="Figure title.")
+
+    @property
+    def font(self) -> fm.FontProperties:
+        """
+        Construct a Matplotlib FontProperties from the configured fields.
+        If `fontfname` points to a real file, it is used (and overrides family).
+        """
+        return fm.FontProperties(
+            family=self.fontfamily,
+            style=self.fontstyle,
+            variant=self.fontvariant,
+            weight=self.fontweight,
+            stretch=self.fontstretch,
+            size=self.fontsize,
+            fname=self.fontfname,
+            math_fontfamily=self.math_fontfamily,
+        )
+
+
+class CircuitStyle(Style):
+    """All visual parameters controlling the appearance of a circuit plot."""
+
+    end_wire_ext: int = Field(default=2, description="Extra space after last layer.")
+    padding: float = Field(default=0.3, description="Padding around drawing (inches).")
+    gate_margin: float = Field(default=0.15, description="Left/right margin per gate.")
+    wire_sep: float = Field(default=0.5, description="Vertical separation of wires.")
+    layer_sep: float = Field(default=0.5, description="Horizontal separation of layers.")
+    gate_pad: float = Field(default=0.05, description="Padding around gate text.")
+    label_pad: float = Field(default=0.1, description="Padding before wire label.")
+    bulge: str = Field(default="round", description="Box-style for gate rectangles.")
+    align_layer: bool = Field(default=True, description="Align layers across wires.")
+
+    wire_label: list[Any] | None = Field(default=None, description="Custom wire labels.")
+    start_pad: float = Field(
+        default=0.1, description="Minimum spacing (inches) before the first layer so wire labels fit."
+    )
+    min_gate_h: float = Field(default=0.2, description="Minimum gate box height (inches).")
+    min_gate_w: float = Field(default=0.2, description="Minimum gate box width (inches).")
+    connector_r: float = Field(
+        default=0.01, description="Radius (inches) of small connector dots on multi-target gates."
+    )
+    target_r: float = Field(default=0.12, description="Radius (inches) of ⊕ target circle and SWAP half-width.")
+    control_r: float = Field(default=0.05, description="Radius (inches) of a filled control dot.")
+
+    layout: Literal["normal", "compact"] = Field(
+        default="normal",
+        description="If 'compact' minimizes the layers to highlight circuit depth, if 'normal' conserves the order of the circuit",
+    )
+
+
+class ScheduleStyle(Style):
+    """
+    Customization options for matplotlib schedule plots, with theme support.
+    """
+
+    # Figure and axes
+    figsize: Optional[tuple] = Field(default=(8, 5), description="Figure size in inches (width, height).")
+    grid: bool = Field(default=True, description="Whether to show grid lines on the plot.")
+    grid_style: dict[str, Any] = Field(
+        default_factory=lambda: {"linestyle": "--", "color": "#e0e0e0", "alpha": 0.7},
+        description="Style dictionary for grid lines (linestyle, color, alpha, etc.).",
+    )
+
+    # Title and labels
+    title_fontsize: int = Field(default=16, description="Font size for the plot title.")
+    xlabel: str = Field(default="time (dt)", description="Label for the x-axis.")
+    ylabel: str = Field(default="coefficient value", description="Label for the y-axis.")
+    label_fontsize: int = Field(default=14, description="Font size for axis labels.")
+
+    # Legend
+    legend_loc: str = Field(
+        default="best", description="Location of the legend (matplotlib string, e.g. 'best', 'upper right')."
+    )
+    legend_fontsize: int = Field(default=12, description="Font size for legend text.")
+    legend_frame: bool = Field(default=True, description="Whether to draw a frame around the legend.")
+
+    # Line style
+    line_styles: dict[str, dict[str, Any]] = Field(
+        default_factory=dict,
+        description="Custom line style dictionary for each Hamiltonian (e.g. {label: {color, linestyle, linewidth}}).",
+    )
+    default_line_style: dict[str, Any] = Field(
+        default_factory=lambda: {"linestyle": "-", "linewidth": 2},
+        description="Default line style for Hamiltonians not in line_styles.",
+    )
+
+    # Marker style
+    marker: Optional[str] = Field(
+        default=None, description="Matplotlib marker style for data points (e.g. 'o', 's', None for no marker)."
+    )
+    marker_size: int = Field(default=6, description="Size of markers if used.")
+
+    # Ticks
+    xtick_fontsize: int = Field(default=12, description="Font size for x-axis tick labels.")
+    ytick_fontsize: int = Field(default=12, description="Font size for y-axis tick labels.")
+    tick_color: Optional[str] = Field(
+        default=None, description="Color for tick labels (None uses theme.on_background)."
+    )
+
+    # Misc
+    tight_layout: bool = Field(default=True, description="Whether to use matplotlib's tight_layout for figure spacing.")

qilisdk/utils/visualization/themes.py

@@ -0,0 +1,76 @@
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# 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.
+
+from typing import Final
+
+from pydantic import BaseModel, ConfigDict, Field
+
+WHITE: Final[str] = "#FFFFFF"
+BLACK: Final[str] = "#000000"
+
+# Neutral ramp (light → dark)
+NEUTRAL_050: Final[str] = "#F0F0F0"
+NEUTRAL_100: Final[str] = "#DCDCDC"
+NEUTRAL_200: Final[str] = "#CACACA"
+NEUTRAL_600: Final[str] = "#7A7A7A"
+NEUTRAL_800: Final[str] = "#2F2F2F"
+NEUTRAL_900: Final[str] = "#1F1F1F"
+
+# Brand colours
+VIOLET: Final[str] = "#5E56A1"
+MAGENTA: Final[str] = "#AC115F"
+
+
+class Theme(BaseModel):
+    """Colour Theme."""
+
+    model_config = ConfigDict(frozen=True)
+
+    background: str = Field(description="Canvas background.")
+    on_background: str = Field(description="Default text/line color on background.")
+    surface: str = Field(description="Raised surface/panel fill.")
+    on_surface: str = Field(description="Text/line color on surface.")
+    surface_muted: str = Field(description="Muted lines on background (wires/grid).")
+    border: str = Field(description="Neutral stroke/border color.")
+    primary: str = Field(description="Primary/brand fill.")
+    on_primary: str = Field(description="Text/icons over primary.")
+    accent: str = Field(description="Accent/highlight color.")
+    on_accent: str = Field(description="Text/icons over accent.")
+
+
+light = Theme(
+    background=WHITE,
+    on_background=BLACK,
+    surface=NEUTRAL_100,
+    on_surface=BLACK,
+    surface_muted=NEUTRAL_050,
+    border=NEUTRAL_200,
+    primary=VIOLET,
+    on_primary=WHITE,
+    accent=MAGENTA,
+    on_accent=WHITE,
+)
+
+dark = Theme(
+    background=BLACK,
+    on_background=WHITE,
+    surface=NEUTRAL_800,
+    on_surface=BLACK,
+    surface_muted=NEUTRAL_900,
+    border=NEUTRAL_600,
+    primary=MAGENTA,
+    on_primary=WHITE,
+    accent=VIOLET,
+    on_accent=WHITE,
+)

qilisdk/yaml.py

@@ -16,11 +16,33 @@
 
 import base64
 import types
+from collections import defaultdict
 
 import numpy as np
 from dill import dumps, loads
 from pydantic import BaseModel
 from ruamel.yaml import YAML
+from scipy import sparse
+
+
+def csr_representer(representer, data: sparse.csr_matrix):
+    """Representer for CSR matrix."""
+    value = {
+        "data": data.data.tolist(),
+        "indices": data.indices.tolist(),
+        "indptr": data.indptr.tolist(),
+        "shape": data.shape,
+    }
+    return representer.represent_mapping("!csr_matrix", value)
+
+
+def csr_constructor(constructor, node):
+    """Constructor for CSR matrix."""
+    mapping = constructor.construct_mapping(node, deep=True)
+    return sparse.csr_matrix(
+        (mapping["data"], mapping["indices"], mapping["indptr"]),
+        shape=tuple(mapping["shape"]),
+    )
 
 
 def ndarray_representer(representer, data):
@@ -38,6 +60,49 @@ def ndarray_constructor(constructor, node):
     return np.array(data, dtype=dtype).reshape(shape)
 
 
+def np_scalar_representer(representer, data: np.generic):
+    """Represent any NumPy scalar (e.g. np.int64, np.float32)."""
+    return representer.represent_mapping(
+        "!np_scalar",
+        {"dtype": str(data.dtype), "value": data.item()},
+    )
+
+
+def np_scalar_constructor(constructor, node):
+    """Reconstruct a NumPy scalar."""
+    mapping = constructor.construct_mapping(node, deep=True)
+    dtype = np.dtype(mapping["dtype"])
+    return dtype.type(mapping["value"])
+
+
+def defaultdict_representer(representer, data: defaultdict):
+    """
+    Represent a defaultdict by serializing its default_factory
+    (as module+qualname) plus its items dict.
+    """
+    factory = data.default_factory
+    factory_name = None if factory is None else f"{factory.__module__}.{factory.__qualname__}"
+    return representer.represent_mapping(
+        "!defaultdict",
+        {"default_factory": factory_name, "items": dict(data)},
+    )
+
+
+def defaultdict_constructor(constructor, node):
+    """Reconstruct a defaultdict, restoring its factory and contents."""
+    mapping = constructor.construct_mapping(node, deep=True)
+    fname = mapping["default_factory"]
+    if fname is None:
+        factory = None
+    else:
+        module, qual = fname.rsplit(".", 1)
+        mod = __import__(module, fromlist=[qual])
+        factory = getattr(mod, qual)
+    dd = defaultdict(factory)
+    dd.update(mapping["items"])
+    return dd
+
+
 def function_representer(representer, data):
     """Represent a non-lambda function by serializing it."""
     serialized_function = base64.b64encode(dumps(data, recurse=True)).decode("utf-8")
@@ -90,14 +155,75 @@ def complex_constructor(constructor, node):
     return complex(mapping["real"], mapping["imag"])
 
 
+def tuple_representer(representer, data: tuple):
+    """Representer for built-in Python tuple."""
+    # Emit a tuple as a YAML sequence with tag !tuple
+    return representer.represent_sequence("!tuple", list(data))
+
+
+def tuple_constructor(constructor, node):
+    """Constructor for built-in Python tuple."""
+    seq = constructor.construct_sequence(node, deep=True)
+    return tuple(seq)
+
+
+def type_representer(representer, data: type):
+    """
+    Represent any Python class/type by its import path.
+    E.g. datetime.datetime → 'datetime.datetime'
+    """
+    path = f"{data.__module__}.{data.__qualname__}"
+    # emit as a simple scalar under !type
+    return representer.represent_scalar("!type", path)
+
+
+def type_constructor(constructor, node):
+    """
+    Reconstruct a class/type from its import path.
+    """
+    path = node.value  # e.g. "datetime.datetime"
+    module_name, qualname = path.rsplit(".", 1)
+    mod = __import__(module_name, fromlist=[qualname])
+    return getattr(mod, qualname)
+
+
+# Create YAML handler and register all custom types
 yaml = YAML(typ="unsafe")
+
+# SciPy CSR
+yaml.representer.add_representer(sparse.csr_matrix, csr_representer)
+yaml.constructor.add_constructor("!csr_matrix", csr_constructor)
+
+# NumPy scalars
+yaml.representer.add_multi_representer(np.generic, np_scalar_representer)
+yaml.constructor.add_constructor("!np_scalar", np_scalar_constructor)
+
+# defaultdict
+yaml.representer.add_representer(defaultdict, defaultdict_representer)
+yaml.constructor.add_constructor("!defaultdict", defaultdict_constructor)
+
+# NumPy arrays
 yaml.representer.add_representer(np.ndarray, ndarray_representer)
 yaml.constructor.add_constructor("!ndarray", ndarray_constructor)
+
+# Python functions and lambdas
 yaml.representer.add_representer(types.FunctionType, function_representer)
 yaml.constructor.add_constructor("!function", function_constructor)
 yaml.representer.add_representer(types.LambdaType, lambda_representer)
 yaml.constructor.add_constructor("!lambda", lambda_constructor)
+
+# Pydantic models
 yaml.representer.add_representer(BaseModel, pydantic_model_representer)
 yaml.constructor.add_constructor("!PydanticModel", pydantic_model_constructor)
+
+# Built-in complex numbers
 yaml.representer.add_representer(complex, complex_representer)
 yaml.constructor.add_constructor("!complex", complex_constructor)
+
+# Built-in tuples
+yaml.representer.add_representer(tuple, tuple_representer)
+yaml.constructor.add_constructor("!tuple", tuple_constructor)
+
+# Built-in type
+yaml.representer.add_multi_representer(type, type_representer)
+yaml.constructor.add_constructor("!type", type_constructor)