Visualization Utilities

Visualization Utilities#

System Graph Visualizer#

Graphviz-based system graph visualization utilities.

This module renders SysSimX systems as Graphviz directed graphs with:

  • grouped component clusters,

  • port-aware record labels,

  • event connections styled distinctly,

  • algebraic loop connections highlighted, and

  • optional unit labels on edges.

syssimx.viz.system_graph_visualizer._auto_color_for_group(group_name, base_saturation=0.35, base_lightness=0.85)[source]#

Generate a deterministic pastel color for a group name.

Parameters:

  • group_name (str) – Name of the group to color.

  • base_saturation (float) – Base saturation for the generated color.

  • base_lightness (float) – Base lightness for the generated color.

Returns:

Hex color string (e.g., “#aabbcc”).

Return type:

str

syssimx.viz.system_graph_visualizer._build_palette(system)[source]#

Build a group color palette for the system.

Parameters:

system (System) – System whose groups are inspected.

Returns:

Mapping of group name to hex color.

Return type:

dict[str, str]

syssimx.viz.system_graph_visualizer._is_event_port(port)[source]#

Return True if a port is an event-type port.

Parameters:

port (PortSpec) – Port specification to inspect.

Returns:

True if the port is not a real-valued port.

Return type:

bool

syssimx.viz.system_graph_visualizer._format_port_label(port_name, color=None)[source]#

Format a port label with optional color emphasis.

Parameters:

  • port_name (str) – Port name to render.

  • color (str | None) – Optional hex color for the label.

Returns:

HTML fragment for the port label.

Return type:

str

syssimx.viz.system_graph_visualizer._build_ports_column(port_names, event_ports, feedthrough_ports=None)[source]#

Build an HTML table cell for a port column.

Parameters:

  • port_names (Iterable[str]) – Iterable of port names in display order.

  • event_ports (set[str]) – Set of event port names.

  • feedthrough_ports (set[str] | None) – Optional set of direct-feedthrough output ports.

Returns:

HTML fragment for the column cell.

Return type:

str

syssimx.viz.system_graph_visualizer._record_label_for_component(comp, execution_idx=-1)[source]#

Build an HTML-like record label for a component.

The label includes input and output port columns with explicit anchors. Output ports with direct feedthrough are highlighted in red; event ports are highlighted in blue.

Parameters:

  • comp (CoSimComponent) – Component to render.

  • execution_idx (int) – Optional execution order index to display.

Returns:

Graphviz HTML-like label string.

Return type:

str

syssimx.viz.system_graph_visualizer._edge_unit_label(system, conn)[source]#

Return unit label from the destination port specification.

Parameters:

  • system (System) – System containing the destination component.

  • conn (Connection) – Connection whose destination port is inspected.

Returns:

Unit label string if present, otherwise None.

Return type:

str | None

syssimx.viz.system_graph_visualizer._is_zero_delay_connection(system, conn, active_outputs)[source]#

Check if a connection participates in zero-delay direct feedthrough.

Parameters:

  • system (System) – System containing the components.

  • conn (Connection) – Connection to evaluate.

  • active_outputs (dict[str, set[str]]) – Mapping of components to output ports used by connections.

Returns:

True if this connection contributes to the zero-delay dependency graph.

Return type:

bool

syssimx.viz.system_graph_visualizer._is_direct_feedthrough_output(comp, port_name)[source]#

Return True if the given output port is direct-feedthrough.

Parameters:

  • comp (CoSimComponent) – Component to inspect.

  • port_name (str) – Output port name on the component.

Returns:

True if the output port has direct-feedthrough dependencies.

Return type:

bool

syssimx.viz.system_graph_visualizer._is_direct_feedthrough_input(comp, port_name)[source]#

Return True if the given input port feeds any direct-feedthrough output.

Parameters:

  • comp (CoSimComponent) – Component to inspect.

  • port_name (str) – Input port name on the component.

Returns:

True if the input port appears in any direct-feedthrough dependency list.

Return type:

bool

syssimx.viz.system_graph_visualizer._build_loop_index(system)[source]#

Build a component-to-loop index mapping.

Parameters:

system (System) – System containing detected algebraic loops.

Returns:

Mapping from component name to algebraic loop index.

Return type:

dict[str, int]

syssimx.viz.system_graph_visualizer._legend_label()[source]#

Return the HTML label used for the legend node.

Returns:

Graphviz HTML-like label string.

Return type:

str

class syssimx.viz.system_graph_visualizer.SystemGraphVisualizer[source]#

Bases: object

Render a System as a Graphviz directed graph.

__init__(system)[source]#

Initialize the visualizer.

Parameters:

system (System) – System instance to visualize.

visualize(filename='system_graph', format='svg')[source]#

Build and render a Graphviz system graph.

This method constructs a new Graphviz Digraph, adds component nodes, connection edges, and renders to disk without opening a viewer.

Parameters:

  • filename (str) – Output filename; an extension is optional and will be stripped.

  • format (str) – Graphviz output format (e.g., “svg”, “png”).

Return type:

None

save(filepath)[source]#

Save the current graph to a file.

Parameters:

filepath (str) – Output path with extension (e.g., “graph.svg”).

Raises:

RuntimeError – If visualize() was not called before saving.

Return type:

None

_add_legend()[source]#

Add a legend subgraph to the current Graphviz graph.

Return type:

None

_add_grouped_components(palette)[source]#

Add grouped components as clustered subgraphs.

Parameters:

palette (dict[str, str]) – Group name to color mapping.

Return type:

None

_add_ungrouped_components()[source]#

Add any components that were not placed in a group cluster.

Return type:

None

_add_data_edges(active_outputs, loop_index)[source]#

Add standard data connection edges.

Parameters:

  • active_outputs (dict[str, set[str]]) – Mapping of component names to active output ports.

  • loop_index (dict[str, int]) – Mapping of component names to algebraic loop index.

Return type:

None

_add_event_edges()[source]#

Add event connection edges with a distinct style.

Return type:

None