Arch

Visualization helpers for :class:~bloqade.lanes.arch.spec.ArchSpec.

These used to live as methods on ArchSpec itself. They were extracted as part of #464 phase 1 so the core ArchSpec Python wrapper stays focused on architectural data and validation, keeping matplotlib out of its import surface.

The primary entry point is the :class:ArchVisualizer class, which caches bounds computations and provides plot / show methods. The ArchSpec shims (arch_spec.plot, .show, .x_bounds, .y_bounds, .path_bounds) create an ArchVisualizer via a @cached_property so existing call sites keep working.

ArchVisualizer

ArchVisualizer(arch_spec: ArchSpec)

Visualization facade for an :class:ArchSpec.

Construct once from an architecture spec; bounds are cached so repeated calls to plot or show don't recompute site positions.

Example::

viz = ArchVisualizer(arch_spec)
viz.plot(ax, show_words=[0, 1], show_word_bus=[0])
print(viz.x_bounds, viz.y_bounds)

Source code in .venv/lib/python3.12/site-packages/bloqade/lanes/visualize/arch.py

def __init__(self, arch_spec: ArchSpec) -> None:
    self.arch_spec = arch_spec

x_bounds cached property

x_bounds: tuple[float, float]

(x_min, x_max) across every site. Falls back to (-1.0, 1.0) when no sites are discoverable.

y_bounds cached property

y_bounds: tuple[float, float]

(y_min, y_max) across every site. Falls back to (-1.0, 1.0) when no sites are discoverable.

path_bounds

path_bounds() -> tuple[float, float, float, float]

(x_min, x_max, y_min, y_max) covering every site and every transport-path waypoint registered on the arch.

Source code in .venv/lib/python3.12/site-packages/bloqade/lanes/visualize/arch.py

def path_bounds(self) -> tuple[float, float, float, float]:
    """``(x_min, x_max, y_min, y_max)`` covering every site **and**
    every transport-path waypoint registered on the arch."""
    x_min, x_max = self.x_bounds
    y_min, y_max = self.y_bounds
    for path in self.arch_spec.paths.values():
        for x, y in path:
            x_min = min(x_min, x)
            x_max = max(x_max, x)
            y_min = min(y_min, y)
            y_max = max(y_max, y)
    return (x_min, x_max, y_min, y_max)

plot

plot(
    ax: Axes | None = None,
    show_words: Sequence[int] = (),
    show_site_bus: Sequence[int] = (),
    show_word_bus: Sequence[int] = (),
    **scatter_kwargs
) -> Axes

Render the architecture onto a matplotlib axes.

Returns the ax argument (or the auto-resolved current axes) so callers can chain or further customise the plot.

Source code in .venv/lib/python3.12/site-packages/bloqade/lanes/visualize/arch.py

def plot(
    self,
    ax: Axes | None = None,
    show_words: Sequence[int] = (),
    show_site_bus: Sequence[int] = (),
    show_word_bus: Sequence[int] = (),
    **scatter_kwargs,
) -> Axes:
    """Render the architecture onto a matplotlib axes.

    Returns the ``ax`` argument (or the auto-resolved current axes)
    so callers can chain or further customise the plot.
    """
    import matplotlib.pyplot as plt  # type: ignore[import-untyped]

    if ax is None:
        ax = plt.gca()

    arch = self.arch_spec
    for word_id in show_words:
        word = arch.words[word_id]
        positions: list[tuple[float, float]] = []
        for zone_id in range(len(arch.zones)):
            for site_id in range(len(word.site_indices)):
                pos = _location_position(arch, word_id, site_id, zone_id)
                if pos is not None:
                    positions.append(pos)
            if positions:
                break
        if positions:
            x_positions = [p[0] for p in positions]
            y_positions = [p[1] for p in positions]
            ax.scatter(x_positions, y_positions, **scatter_kwargs)

    for path in self.iter_site_bus_paths(show_words, show_site_bus):
        x_vals, y_vals = zip(*path)
        ax.plot(x_vals, y_vals, linestyle="--")

    for path in self.iter_word_bus_paths(show_word_bus):
        x_vals, y_vals = zip(*path)
        ax.plot(x_vals, y_vals, linestyle="-")
    return ax

show

show(
    ax: Axes | None = None,
    show_words: Sequence[int] = (),
    show_intra: Sequence[int] = (),
    show_inter: Sequence[int] = (),
    **scatter_kwargs
) -> None

Render and immediately call plt.show().

Convenience for interactive sessions; programmatic callers should prefer :meth:plot.

Source code in .venv/lib/python3.12/site-packages/bloqade/lanes/visualize/arch.py

def show(
    self,
    ax: Axes | None = None,
    show_words: Sequence[int] = (),
    show_intra: Sequence[int] = (),
    show_inter: Sequence[int] = (),
    **scatter_kwargs,
) -> None:
    """Render and immediately call ``plt.show()``.

    Convenience for interactive sessions; programmatic callers
    should prefer :meth:`plot`.
    """
    import matplotlib.pyplot as plt  # type: ignore[import-untyped]

    self.plot(
        ax,
        show_words=show_words,
        show_site_bus=show_intra,
        show_word_bus=show_inter,
        **scatter_kwargs,
    )
    plt.show()