Graphs Visualization API

Visualization

graphcalc.graphs.viz.edges.draw_coloring(G: Graph, coloring: Dict[int, Iterable[Hashable]], *, layout: str = 'spring', pos: dict | None = None, seed: int = 42, palette: List[str] | None = None, node_size: int = 420, edge_color: str = 'lightgray', with_labels: bool = True, title: str | None = None, ax: Axes | None = None, show_legend: bool = True) → Tuple[Figure, Axes][source]

Visualize a proper coloring returned by optimal_proper_coloring.

Parameters:

G (networkx.Graph or SimpleGraph) – The graph to visualize.
coloring (dict[int, iterable]) – Mapping from color index to list of nodes assigned that color.
layout ({"spring","kamada_kawai","planar","circular","spectral"}, optional) – Layout algorithm (default “spring”).
pos (dict, optional) – Node positions; if None, computed by the chosen layout.
seed (int, optional) – Random seed for layouts with randomness (default 42).
palette (list of str, optional) – List of color strings for classes. If None, uses a default cycle (e.g., Matplotlib’s tab10 extended).
node_size (int, optional) – Size of nodes (default 420).
edge_color (str, optional) – Color for edges (default “lightgray”).
with_labels (bool, optional) – Whether to draw node labels (default True).
title (str, optional) – Figure title.
ax (matplotlib.axes.Axes, optional) – Existing axes to draw on. If None, a new figure is created.
show_legend (bool, optional) – Whether to draw a legend with color class labels (default True).

Returns:

fig (matplotlib.figure.Figure) – The figure.
ax (matplotlib.axes.Axes) – The axes.

Notes

Ignores empty color classes.
If there are more classes than palette entries, colors repeat.

Examples

>>> import graphcalc.graphs as gc
>>> from graphcalc.graphs.viz import draw_coloring
>>> G = gc.cycle_graph(6)
>>> C = gc.optimal_proper_coloring(G)
>>> fig, ax = draw_coloring(G, C, title=f"χ(G) = {len([v for v in C.values() if v])}")

graphcalc.graphs.viz.edges.draw_edge_set(G: Graph, edge_set: Iterable[Tuple[Hashable, Hashable]], *, layout: str = 'spring', pos: dict | None = None, seed: int = 42, width_selected: float = 2.8, width_other: float = 1.2, edge_color_selected: str = 'tab:red', edge_color_other: str = 'lightgray', node_color: str = 'lightblue', with_labels: bool = True, title: str | None = None, ax: Axes | None = None, legend: bool = True) → Tuple[Figure, Axes][source]

Visualize a distinguished set of edges in a graph.

This function highlights a subset of edges (e.g., a matching or cut) in a given graph \(G\). Selected edges are emphasized with distinct color and width, while the remaining edges are drawn in a muted style. Nodes are drawn uniformly.

Parameters:

G (networkx.Graph or graphcalc.SimpleGraph) – An undirected simple graph.
edge_set (iterable of tuple) – A collection of edges to highlight. Each edge must be a 2-tuple of hashable nodes present in \(G\).
layout ({"spring", "kamada_kawai", "planar", "circular", "spectral"}, optional) – Layout algorithm used to compute node positions. Ignored if pos is given (default is “spring”).
pos (dict, optional) – Precomputed node positions as a dictionary mapping nodes to coordinate pairs. If provided, layout is ignored.
seed (int, optional) – Random seed used by layout algorithms that are stochastic (default is 42).
width_selected (float, optional) – Line width for edges in edge_set (default is 2.8).
width_other (float, optional) – Line width for non-selected edges (default is 1.2).
edge_color_selected (str, optional) – Color for edges in edge_set (default is “tab:red”).
edge_color_other (str, optional) – Color for non-selected edges (default is “lightgray”).
node_color (str or list, optional) – Color(s) used for nodes (default is “lightblue”).
with_labels (bool, optional) – Whether to display node labels (default is True).
title (str, optional) – Title of the plot. If None, no title is shown (default is None).
ax (matplotlib.axes.Axes, optional) – Axes object to draw on. If None, a new figure and axes are created (default is None).
legend (bool, optional) – Whether to include a legend distinguishing selected and non-selected edges (default is True).

Returns:

fig (matplotlib.figure.Figure) – The matplotlib Figure object containing the plot.
ax (matplotlib.axes.Axes) – The matplotlib Axes object where the graph is drawn.

Examples

>>> import graphcalc.graphs as gc
>>> from graphcalc.graphs.viz import draw_edge_set
>>> G = gc.diamond_necklace(4)
>>> M = gc.maximum_matching(G)
>>> fig, ax = draw_edge_set(G, M,
...               edge_color_selected="tab:blue",
...               edge_color_other="gray",
...               node_color="lightyellow",
...               title="Maximum Matching")

graphcalc.graphs.viz.edges.draw_edges(G: Graph, classes: Iterable[Tuple[Hashable, Hashable]] | Mapping[int, Iterable[Tuple[Hashable, Hashable]]] | Sequence[Iterable[Tuple[Hashable, Hashable]]] | Mapping[Hashable, Hashable] | EdgeView, *, pos: dict | None = None, layout: str = 'spring', seed: int = 42, palette: List[str] | None = None, width: float = 2.8, node_color: str = 'white', with_labels: bool = True, title: str | None = None, ax: Axes | None = None, show_legend: bool = True, legend_labels: List[str] | None = None)[source]

Visualize edge partitions or highlighted sets in a graph.

This function generalizes edge visualization by supporting several input formats: a single edge set, a node-to-partner mapping (matchings), a dictionary encoding a k-edge-coloring, or multiple disjoint edge sets. Selected classes of edges are drawn with distinct colors, while all nodes are displayed uniformly.

Parameters:

G (networkx.Graph or graphcalc.SimpleGraph) – An undirected simple graph.
classes (iterable, mapping, or EdgeView) –
Specification of edge classes to highlight. Supported formats include:
- iterable of 2-tuples: A single edge set, automatically complemented by the rest of the edges.
- dict {node: partner}: A matching, where edges are inferred from the mapping.
- dict {color_index: iterable of edges}: A k-edge-coloring.
- sequence of iterables: Multiple edge sets to display.
- EdgeView: A subset of edges returned by G.edges(data=False).
pos (dict, optional) – Precomputed node positions as a dictionary mapping nodes to coordinate pairs. If None, positions are computed using the algorithm specified by layout.
layout ({"spring", "kamada_kawai", "planar", "circular", "spectral"}, optional) – Layout algorithm used to compute node positions (default is “spring”).
seed (int, optional) – Random seed for layout algorithms that are stochastic (default is 42).
palette (list of str, optional) – List of colors to cycle through for different edge classes. If None, a default matplotlib color cycle is used.
width (float, optional) – Line width for drawn edges (default is 2.8).
node_color (str or list, optional) – Color(s) used for nodes (default is “white”).
with_labels (bool, optional) – Whether to display node labels (default is True).
title (str, optional) – Title of the plot (default is None).
ax (matplotlib.axes.Axes, optional) – Axes object to draw on. If None, a new figure and axes are created (default is None).
show_legend (bool, optional) – Whether to include a legend distinguishing edge classes (default is True).
legend_labels (list of str, optional) – Custom labels for the legend. If None, labels are generated automatically as "class i".

Returns:

fig (matplotlib.figure.Figure) – The matplotlib Figure object containing the plot.
ax (matplotlib.axes.Axes) – The matplotlib Axes object where the graph is drawn.

Examples

Highlight a maximum matching:

>>> import graphcalc.graphs as gc
>>> from graphcalc.graphs.viz import draw_edges
>>> G = gc.diamond_necklace(5)
>>> M = gc.maximum_matching(G)
>>> _ = draw_edges(G, M,
...            palette=["tab:blue", "lightgray"],
...            legend_labels=["matching", "other edges"],
...            node_color="lightyellow",
...            title="Maximum Matching")

Visualize a 3-edge-coloring:

>>> coloring = {
...     0: [(0, 1), (2, 3)],
...     1: [(1, 2)],
...     2: [(3, 0)]
... }
>>> _ = draw_edges(G, coloring, palette=["red", "green", "blue"], title="3-edge-coloring")

graphcalc.graphs.viz.vertices.draw_vertex_set(G: Graph, subset: Iterable[Hashable], *, layout: str = 'spring', pos: dict | None = None, seed: int = 42, highlight_size: int = 500, base_size: int = 200, highlight_color: str = 'tab:red', other_color: str = 'lightgray', with_labels: bool = True, title: str | None = None, ax: Axes | None = None, legend: bool = True) → Tuple[Figure, Axes][source]

Visualize a distinguished subset of vertices in a graph.

This function highlights a specified subset of vertices (e.g., an independent set or dominating set) in a given graph \(G\). Highlighted nodes are drawn larger and in a distinct color, while all other nodes are rendered with a baseline size and muted color. Edges are drawn uniformly.

Parameters:

G (networkx.Graph or graphcalc.SimpleGraph) – An undirected simple graph.
subset (iterable of hashable) – A collection of nodes in \(G\) to highlight.
layout ({"spring", "kamada_kawai", "planar", "circular", "spectral"}, optional) – Layout algorithm used to compute node positions. Ignored if pos is given (default is “spring”).
pos (dict, optional) – Precomputed node positions as a dictionary mapping nodes to coordinate pairs. If provided, layout is ignored.
seed (int, optional) – Random seed used by layout algorithms that are stochastic (default is 42).
highlight_size (int, optional) – Size of nodes in subset (default is 500).
base_size (int, optional) – Size of nodes not in subset (default is 200).
highlight_color (str, optional) – Color used for nodes in subset (default is “tab:red”).
other_color (str, optional) – Color used for other nodes (default is “lightgray”).
with_labels (bool, optional) – Whether to display node labels (default is True).
title (str, optional) – Title of the plot. If None, no title is shown (default is None).
ax (matplotlib.axes.Axes, optional) – Axes object to draw on. If None, a new figure and axes are created (default is None).
legend (bool, optional) – Whether to include a legend distinguishing highlighted vs. other nodes (default is True).

Returns:

fig (matplotlib.figure.Figure) – The matplotlib Figure object containing the plot.
ax (matplotlib.axes.Axes) – The matplotlib Axes object where the graph is drawn.

Examples

Highlight a maximum independent set:

>>> import graphcalc.graphs as gc
>>> from graphcalc.graphs.viz import draw_vertex_set
>>> G = gc.cycle_graph(6)
>>> S = gc.maximum_independent_set(G)
>>> fig, ax = draw_vertex_set(G, S,
...                 highlight_color="tab:blue",
...                 other_color="lightgray",
...                 title="Maximum Independent Set")

graphcalc.graphs.viz.vertices.draw_vertices(G: Graph, classes: Iterable[Hashable] | Mapping[int, Iterable[Hashable]] | Sequence[Iterable[Hashable]], *, pos: dict | None = None, layout: str = 'spring', seed: int = 42, palette: List[str] | None = None, node_size: int = 420, edge_color: str = 'lightgray', with_labels: bool = True, title: str | None = None, ax: Axes | None = None, show_legend: bool = True, legend_labels: List[str] | None = None) → Tuple[Figure, Axes][source]

Visualize vertex partitions or highlighted subsets in a graph.

This function generalizes vertex visualization by supporting several input formats: a single subset (rendered as a 2-coloring), a dictionary encoding a k-coloring, or multiple disjoint subsets. Each class of vertices is drawn in a distinct color using either a provided palette or a default matplotlib cycle.

Parameters:

G (networkx.Graph or graphcalc.SimpleGraph) – An undirected simple graph.
classes (iterable, mapping, or sequence) –
Specification of vertex classes to highlight. Supported formats include:
- iterable of nodes: A single target subset, automatically complemented by the rest of the vertices (2-coloring).
- dict {color_index: iterable of nodes}: A k-coloring where each key corresponds to a color class.
- sequence of iterables: Multiple vertex subsets to display, assigned colors sequentially.
pos (dict, optional) – Precomputed node positions as a dictionary mapping nodes to coordinate pairs. If None, positions are computed using the algorithm specified by layout.
layout ({"spring", "kamada_kawai", "planar", "circular", "spectral"}, optional) – Layout algorithm used to compute node positions (default is “spring”).
seed (int, optional) – Random seed for layout algorithms that are stochastic (default is 42).
palette (list of str, optional) – List of colors to cycle through for different vertex classes. If None, a default matplotlib color cycle is used.
node_size (int, optional) – Size of nodes (default is 420).
edge_color (str, optional) – Color of edges (default is “lightgray”).
with_labels (bool, optional) – Whether to display node labels (default is True).
title (str, optional) – Title of the plot (default is None).
ax (matplotlib.axes.Axes, optional) – Axes object to draw on. If None, a new figure and axes are created (default is None).
show_legend (bool, optional) – Whether to include a legend distinguishing vertex classes (default is True).
legend_labels (list of str, optional) – Custom labels for the legend. If None, labels are generated automatically as "class i".

Returns:

fig (matplotlib.figure.Figure) – The matplotlib Figure object containing the plot.
ax (matplotlib.axes.Axes) – The matplotlib Axes object where the graph is drawn.

Examples

Highlight a maximum independent set as a 2-coloring:

>>> import graphcalc.graphs as gc
>>> from graphcalc.graphs.viz import draw_vertices
>>> G = gc.cycle_graph(6)
>>> S = gc.maximum_independent_set(G)
>>> _ = draw_vertices(G, S,
...               palette=["tab:blue", "lightgray"],
...               legend_labels=["independent set", "other vertices"],
...               title="Independent Set as 2-coloring")

Visualize an optimal proper coloring:

>>> coloring = gc.optimal_proper_coloring(G)
>>> _ = draw_vertices(G, coloring, title="Optimal Proper Coloring")