Visualization

All visualization functionality is bundled in the sub-module mqt.qmap.visualization.

Search graph visualization

The recommended way to visualize search graphs of a mapping process is via a SearchVisualizer object, which can be passed to the mqt.qmap.compile() function to enable data logging during mapping, after which this data can be visualized by calling the method SearchVisualizer.visualize_search_graph().

Note

SearchVisualizer.visualize_search_graph() returns an IPython display object and therefore requires to be executed in a jupyter notebook or jupyter lab environment.

Note

Automatic layouting of architecture or search nodes requires Graphviz to be installed (except for the layouting method walker). If Graphviz is called without it being installed, it will ensue in an error such as:

FileNotFoundError: [Errno 2] "sfdp" not found in path.

Consequently, the only way to use SearchVisualizer.visualize_search_graph() without Graphviz is by passing explicit architecture node positions or hiding the architecture graph by passing show_layout=None.

class SearchVisualizer(data_logging_path=None)[source]

Handling data logging for a search process and providing methods to visualize that data.

__init__(data_logging_path=None)[source]

Handling data logging for a search process and providing methods to visualize that data.

Parameters:

data_logging_path (str | None) – Path to an empty directory, in which the search process should log all data. Defaults to None, in which case a temporary folder will be created.

close()[source]

Cleans up the data logging directory, if it is was temporarily created.

Return type:

None

visualize_search_graph(layer='interactive', architecture_node_positions=None, architecture_layout='sfdp', search_node_layout='walker', search_graph_border=0.05, architecture_border=0.05, swap_arrow_spacing=0.05, swap_arrow_offset=0.05, use3d=True, projection='perspective', width=1400, height=700, draw_search_edges=True, search_edges_width=0.5, search_edges_color='#888', search_edges_dash='solid', tapered_search_layer_heights=True, show_layout='hover', show_swaps=True, show_shared_swaps=True, show_only_solution_path=False, color_valid_mapping='green', color_final_node='red', search_node_color='total_cost', prioritize_search_node_color=False, search_node_color_scale='YlGnBu', search_node_invert_color_scale=True, search_node_colorbar_title=None, search_node_colorbar_spacing=0.06, search_node_height='total_cost', draw_stems=False, stems_width=0.7, stems_color='#444', stems_dash='solid', show_search_progression=True, search_progression_step=10, search_progression_speed=2, plotly_settings=None)[source]

Creates a widget to visualize the search graph.

Parameters:

  • layer (int | Literal['interactive']) – Index of the circuit layer, of which the mapping should be visualized. Defaults to “interactive”, in which case a slider menu will be created.

  • architecture_node_positions (MutableMapping[int, tuple[float, float]] | None) – Mapping from physical qubits to (x, y) coordinates. Defaults to None, in which case architecture_layout will be used to generate a layout.

  • architecture_layout (Literal[ 'dot', 'neato', 'fdp', 'sfdp', 'circo', 'twopi', 'osage', 'patchwork' ]) – The method to use when layouting the qubit connectivity graph. Defaults to “sfdp”.

  • search_node_layout (Literal[ 'walker', 'dot', 'neato', 'fdp', 'sfdp', 'circo', 'twopi', 'osage', 'patchwork' ]) – The method to use when layouting the search graph. Defaults to “walker”.

  • search_graph_border (float) – Size of the border around the search graph. Defaults to 0.05.

  • architecture_border (float) – Size of the border around the qubit connectivity graph. Defaults to 0.05.

  • swap_arrow_spacing (float) – Lateral spacing between arrows indicating swaps on the qubit connectivity graph. Defaults to 0.05.

  • swap_arrow_offset (float) – Offset of heads and shaft of swap arrows from qubits they are pointing to/from. Defaults to 0.05.

  • use3d (bool) – If a 3D graph should be used for the search graph using the z-axis to plot data features. Defaults to True.

  • projection (Literal['orthographic', 'perspective']) – Projection type to use in 3D graphs. Defaults to “perspective”.

  • width (int) – Pixel width of the widget. Defaults to 1400.

  • height (int) – Pixel height of the widget. Defaults to 700.

  • draw_search_edges (bool) – If edges between search nodes should be drawn. Defaults to True.

  • search_edges_width (float) – Width of edges between search nodes. Defaults to 0.5.

  • search_edges_color (str) – Color of edges between search nodes (in CSS format, i.e. ‘#rrggbb’, ‘#rgb’, ‘colorname’, etc.). Defaults to “#888”.

  • search_edges_dash (str) – Dashing of search edges (in CSS format, i.e. ‘solid’, ‘dot’, ‘dash’, ‘longdash’, etc.). Defaults to “solid”.

  • tapered_search_layer_heights (bool) – If search graph tree should progressively reduce the height of each layer. Defaults to True.

  • show_layout (Literal['hover', 'click'] | None) – If the current qubit layout should be shown on the qubit connectivity graph, when clicking or hovering on a search node or not at all. Defaults to “hover”.

  • show_swaps (bool) – Showing swaps on the connectivity graph. Defaults to True.

  • show_shared_swaps (bool) – Indicate a shared swap by 1 arrow with 2 heads, otherwise 2 arrows in opposite direction are drawn for the 1 shared swap. Defaults to True.

  • show_only_solution_path (bool) – If only the final solution path should be shown. Defaults to False.

  • color_valid_mapping (str | None) – Color to use for search nodes containing a valid qubit layout (in CSS format). Defaults to “green”.

  • color_final_node (str | None) – Color to use for the final solution search node (in CSS format). Defaults to “red”.

  • search_node_color (str | Callable[[SearchNode], float] | list[str | Callable[[SearchNode], float]]) – Color to be used for search nodes. Either a static color (in CSS format) or function mapping a mqt.qmap.visualization.SearchNode to a float value, which in turn gets translated into a color by search_node_color_scale , or a preset data feature (‘total_cost’ | ‘fixed_cost’ | ‘heuristic_cost’ | ‘lookahead_penalty’). In case a 3D search graph is used with multiple points per search node, each point’s color can be controlled individually via a list. Defaults to “total_cost”.

  • prioritize_search_node_color (bool | list[ bool ]) – If search_node_color should be prioritized over color_valid_mapping and color_final_node. Defaults to False.

  • search_node_color_scale (str | list[str]) – Color scale to be used for converting float data features to search node colors. (See https://plotly.com/python/builtin-colorscales/ for valid values). Defaults to “YlGnBu”.

  • search_node_invert_color_scale (bool | list[bool]) – If the color scale should be inverted. Defaults to True.

  • search_node_colorbar_title (str | list[str | None] | None) – Title(s) to be shown next to the colorbar(s). Defaults to None.

  • search_node_colorbar_spacing (float) – Spacing between multiple colorbars. Defaults to 0.06.

  • search_node_height (str | Callable[[SearchNode], float] | list[str | Callable[[SearchNode], float]]) – Function mapping a mqt.qmap.visualization.SearchNode to a float value to be used as z-value in 3D search graphs or a preset data feature (‘total_cost’ | ‘fixed_cost’ | ‘heuristic_cost’ | ‘lookahead_penalty’). Or a list any of such functions/data features, to draw multiple points per search node. Defaults to “total_cost”.

  • draw_stems (bool) – If a vertical stem should be drawn in 3D search graphs to each search node. Defaults to False.

  • stems_width (float) – Width of stems in 3D search graphs. Defaults to 0.7.

  • stems_color (str) – Color of stems in 3D search graphs (in CSS format). Defaults to “#444”.

  • stems_dash (str) – Dashing of stems in 3D search graphs (in CSS format). Defaults to “solid”.

  • show_search_progression (bool) – If the search progression should be animated. Defaults to True.

  • search_progression_step (int) – Step size (in number of nodes added) of search progression animation. Defaults to 10.

  • search_progression_speed (float) – Speed of the search progression animation. Defaults to 2.

  • plotly_settings (MutableMapping[str, MutableMapping[str, any]] | None) – Plotly configuration dictionaries to be passed through. Defaults to None.

{
    "layout": settings for plotly.graph_objects.Layout (of subplots figure)
    "arrows": settings for plotly.graph_objects.layout.Annotation
    "stats_legend": settings for plotly.graph_objects.layout.Annotation
    "search_nodes": settings for plotly.graph_objects.Scatter resp. ...Scatter3d
    "search_edges": settings for plotly.graph_objects.Scatter resp. ...Scatter3d
    "architecture_nodes": settings for plotly.graph_objects.Scatter
    "architecture_edges": settings for plotly.graph_objects.Scatter
    "architecture_edge_labels": settings for plotly.graph_objects.Scatter
    "search_xaxis": settings for plotly.graph_objects.layout.XAxis resp. ...layout.scene.XAxis
    "search_yaxis": settings for plotly.graph_objects.layout.YAxis resp. ...layout.scene.YAxis
    "search_zaxis": settings for plotly.graph_objects.layout.scene.ZAxis
    "architecture_xaxis": settings for plotly.graph_objects.layout.XAxis
    "architecture_yaxis": settings for plotly.graph_objects.layout.YAxis
}
Raises:

TypeError – If any of the arguments are invalid.

Returns:

Widget – An interactive IPython widget to visualize the search graph.