Skip to content

io

io ¤

plot_region_graph(region_graph, out_path=None, orientation='vertical', region_node_shape='box', partition_node_shape='point', label_font='times italic bold', label_size='21pt', label_color='white', region_label=None, region_color='#607d8b', partition_label=None, partition_color='#ffbd2a') ¤

Plot the region graph using graphviz.

Parameters:

Name Type Description Default
region_graph RegionGraph

The region graph to plot.

 required
out_path str | PathLike[str] | None

The output path where the plot is saved. If it is None, the plot is not saved to a file. Defaults to None. The Output file format is deduced from the path. Possible formats are: {'jp2', 'plain-ext', 'sgi', 'x11', 'pic', 'jpeg', 'imap', 'psd', 'pct', 'json', 'jpe', 'tif', 'tga', 'gif', 'tk', 'xlib', 'vmlz', 'json0', 'vrml', 'gd', 'xdot', 'plain', 'cmap', 'canon', 'cgimage', 'fig', 'svg', 'dot_json', 'bmp', 'png', 'cmapx', 'pdf', 'webp', 'ico', 'xdot_json', 'gtk', 'svgz', 'xdot1.4', 'cmapx_np', 'dot', 'tiff', 'ps2', 'gd2', 'gv', 'ps', 'jpg', 'imap_np', 'wbmp', 'vml', 'eps', 'xdot1.2', 'pov', 'pict', 'ismap', 'exr'}. See https://graphviz.org/docs/outputs/ for more.

 None
orientation str

Orientation of the graph. "vertical" puts the root node at the top, "horizontal" at left. Defaults to "vertical".

 'vertical'
label_font str

Font used to render labels. Defaults to "times italic bold". See https://graphviz.org/faq/font/ for the available fonts.

 'times italic bold'
label_size str

Size of the font for labels in points. Defaults to "21pt".

 '21pt'
label_color str

Color for the labels in the nodes. Defaults to "white". See https://graphviz.org/docs/attr-types/color/ for supported color.

 'white'
region_label str | Callable[[RegionNode], str] | None

Either a string or a function. If a function is provided, then it must take as input a region node and returns a string that will be used as label. If None, it defaults to the string representation of the scope of the region node.

 None
region_color str | Callable[[RegionNode], str]

Either a string or a function. If a function is provided, then it must take as input a region node and returns a string that will be used as color for the region node. Defaults to "#607d8b".

 '#607d8b'
partition_label str | Callable[[PartitionNode], str] | None

Either a string or a function. If a function is provided, then it must take as input a partition node and returns a string that will be used as label. If None, it defaults to an empty string.

 None
partition_color str | Callable[[PartitionNode], str]

Either a string or a function. If a function is provided, then it must take as input a partition node and returns a string that will be used as color for the partition node. Defaults to "#ffbd2a".

 '#ffbd2a'

Raises:

Type Description
ValueError

The format is not among the supported ones.
ValueError

The direction is not among the supported ones.

Returns:

Type Description
Digraph

graphviz.Digraph: The graphviz object representing the region graph.
Source code in cirkit/templates/region_graph/io.py 
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
def plot_region_graph(
    region_graph: RegionGraph,
    out_path: str | PathLike[str] | None = None,
    orientation: str = "vertical",
    region_node_shape: str = "box",
    partition_node_shape: str = "point",
    label_font: str = "times italic bold",
    label_size: str = "21pt",
    label_color: str = "white",
    region_label: str | Callable[[RegionNode], str] | None = None,
    region_color: str | Callable[[RegionNode], str] = "#607d8b",
    partition_label: str | Callable[[PartitionNode], str] | None = None,
    partition_color: str | Callable[[PartitionNode], str] = "#ffbd2a",
) -> graphviz.Digraph:
    """Plot the region graph using graphviz.

    Args:
        region_graph: The region graph to plot.
        out_path: The output path where the plot is saved.
            If it is None, the plot is not saved to a file. Defaults to None.
            The Output file format is deduced from the path. Possible formats are:
            {'jp2', 'plain-ext', 'sgi', 'x11', 'pic', 'jpeg', 'imap', 'psd', 'pct',
             'json', 'jpe', 'tif', 'tga', 'gif', 'tk', 'xlib', 'vmlz', 'json0', 'vrml',
             'gd', 'xdot', 'plain', 'cmap', 'canon', 'cgimage', 'fig', 'svg', 'dot_json',
             'bmp', 'png', 'cmapx', 'pdf', 'webp', 'ico', 'xdot_json', 'gtk', 'svgz',
             'xdot1.4', 'cmapx_np', 'dot', 'tiff', 'ps2', 'gd2', 'gv', 'ps', 'jpg',
             'imap_np', 'wbmp', 'vml', 'eps', 'xdot1.2', 'pov', 'pict', 'ismap', 'exr'}.
             See https://graphviz.org/docs/outputs/ for more.
        orientation: Orientation of the graph. "vertical" puts the root
            node at the top, "horizontal" at left. Defaults to "vertical".
        label_font: Font used to render labels. Defaults to "times italic bold".
            See https://graphviz.org/faq/font/ for the available fonts.
        label_size: Size of the font for labels in points. Defaults to "21pt".
        label_color: Color for the labels in the nodes. Defaults to "white".
            See https://graphviz.org/docs/attr-types/color/ for supported color.
        region_label: Either a string or a function.
            If a function is provided, then it must take as input a region node and returns a string
            that will be used as label. If None, it defaults to the string representation of the
            scope of the region node.
        region_color: Either a string or a function.
            If a function is provided, then it must take as input a region node and returns a string
            that will be used as color for the region node. Defaults to "#607d8b".
        partition_label: Either a string or a
            function. If a function is provided, then it must take as input a partition node and
            returns a string that will be used as label. If None, it defaults to an empty string.
        partition_color: Either a string or a function.
            If a function is provided, then it must take as input a partition node and returns a
            string that will be used as color for the partition node. Defaults to "#ffbd2a".

    Raises:
        ValueError: The format is not among the supported ones.
        ValueError: The direction is not among the supported ones.

    Returns:
        graphviz.Digraph: The graphviz object representing the region graph.
    """
    fmt: str
    if out_path is None:
        fmt = "svg"
    else:
        fmt = Path(out_path).suffix.replace(".", "")
        if fmt not in graphviz.FORMATS:
            raise ValueError(f"Supported formats are {graphviz.FORMATS}.")

    if orientation not in ["vertical", "horizontal"]:
        raise ValueError("Supported graph directions are only 'vertical' and 'horizontal'.")

    def _default_region_label(rgn: RegionNode) -> str:
        return str(set(rgn.scope))

    def _default_partition_label(_: PartitionNode) -> str:
        return ""

    if region_label is None:
        region_label = _default_region_label
    if partition_label is None:
        partition_label = _default_partition_label

    dot: graphviz.Digraph = graphviz.Digraph(
        format=fmt,
        node_attr={
            "style": "filled",
            "fontcolor": label_color,
            "fontsize": label_size,
            "fontname": label_font,
        },
        engine="dot",
    )
    dot.graph_attr["rankdir"] = "BT" if orientation == "vertical" else "LR"

    for node in region_graph.nodes:
        match node:
            case RegionNode():
                dot.node(
                    str(id(node)),
                    region_label if isinstance(region_label, str) else region_label(node),
                    color=region_color if isinstance(region_color, str) else region_color(node),
                    shape=region_node_shape,
                )
            case PartitionNode():
                dot.node(
                    str(id(node)),
                    partition_label if isinstance(partition_label, str) else partition_label(node),
                    color=(
                        partition_color
                        if isinstance(partition_color, str)
                        else partition_color(node)
                    ),
                    shape=partition_node_shape,
                    width="0.2",
                )
        for node_in in region_graph.node_inputs(node):
            dot.edge(str(id(node_in)), str(id(node)))
    if out_path is not None:
        out_dir: Path = Path(out_path).with_suffix("")

        if fmt == "dot":
            with open(out_dir, "w", encoding="utf8") as f:
                f.write(dot.source)
        else:
            dot.format = fmt
            dot.render(out_dir, cleanup=True)

    return dot