siliconcompiler 0.34.2__py3-none-any.whl → 0.34.3__py3-none-any.whl

siliconcompiler/report/dashboard/web/components/flowgraph.py

@@ -1,3 +1,7 @@
+"""
+Utility functions for generating and configuring the interactive flowgraph
+display for the web dashboard using the `streamlit-agraph` library.
+"""
 from siliconcompiler.report import report
 from siliconcompiler.tools._common import get_tool_task
 from siliconcompiler import NodeStatus
@@ -5,30 +9,36 @@ from siliconcompiler import NodeStatus
 from streamlit_agraph import Node, Edge, Config
 
 
-# for flowgraph
+# --- Constants ---
+# Defines the color scheme for nodes based on their execution status.
 NODE_COLORS = {
     NodeStatus.SUCCESS: '#70db70',  # green
-
     NodeStatus.SKIPPED: '#ffc299',  # orange
-
     NodeStatus.PENDING: '#6699ff',  # blue
-    NodeStatus.QUEUED: '#6699ff',  # blue
-
+    NodeStatus.QUEUED: '#6699ff',   # blue
     NodeStatus.RUNNING: '#ffff4d',  # yellow
-
-    NodeStatus.ERROR: '#ff1a1a',  # red
+    NodeStatus.ERROR: '#ff1a1a',    # red
     NodeStatus.TIMEOUT: '#ff1a1a',  # red
-
-    "Unknown": '#6699ff',  # blue
+    "Unknown": '#6699ff',           # blue
 }
 
 
 def get_nodes_and_edges(chip):
     """
-    Returns the nodes and edges required to make a streamlit_agraph.
+    Constructs the nodes and edges for the flowgraph from a chip object.
+
+    This function traverses the chip's flowgraph, creating styled `Node` and
+    `Edge` objects for `streamlit-agraph`. Node colors are based on status,
+    and edge styles (width, color, dashes) indicate the execution path and
+    dependencies.
 
     Args:
-        chip (Chip) : The chip object that contains the schema read from.
+        chip (Chip): The chip object containing the flowgraph data.
+
+    Returns:
+        tuple: A tuple containing two lists:
+            - list[Node]: A list of `streamlit_agraph.Node` objects.
+            - list[Edge]: A list of `streamlit_agraph.Edge` objects.
     """
     nodes = []
     edges = []
@@ -36,61 +46,66 @@ def get_nodes_and_edges(chip):
     if not chip.get('option', 'flow'):
         return nodes, edges
 
+    # --- Style Configuration ---
     default_node_border_width = 1
     successful_path_node_width = 3
     default_edge_width = 3
     successful_path_edge_width = 5
 
+    # --- Data Extraction ---
     node_dependencies = report.get_flowgraph_edges(chip)
     successful_path = report.get_flowgraph_path(chip)
-
     flow = chip.get('option', 'flow')
-    entry_exit_nodes = chip.get("flowgraph", flow, field="schema").get_entry_nodes() + \
-        chip.get("flowgraph", flow, field="schema").get_exit_nodes()
+    flowgraph_schema = chip.get("flowgraph", flow, field="schema")
+    entry_exit_nodes = flowgraph_schema.get_entry_nodes() + flowgraph_schema.get_exit_nodes()
 
+    # --- Node and Edge Creation ---
     for step, index in node_dependencies:
-        # Build node
+        # 1. Build the Node
         node_border_width = default_node_border_width
         if (step, index) in entry_exit_nodes:
             node_border_width = successful_path_node_width
 
         node_status = chip.get('record', 'status', step=step, index=index)
-        if node_status not in NODE_COLORS:
-            node_status = "Unknown"
-        node_color = NODE_COLORS[node_status]
+        node_color = NODE_COLORS.get(node_status, NODE_COLORS["Unknown"])
 
         tool, task = get_tool_task(chip, step, index)
         node_name = f'{step}/{index}'
-        label = node_name + "\n" + tool + "/" + task
+        label = f"{node_name}\n{tool}/{task}"
         if tool == 'builtin':
-            label = node_name + "\n" + tool
+            label = f"{node_name}\n{tool}"
 
         nodes.append(Node(
             id=node_name,
             label=label,
             color=node_color,
-            opacity=1,
             borderWidth=node_border_width,
             shape='oval',
             fixed=True))
 
-        # Build edges
-        path_taken = chip.get('record', 'inputnode', step=step, index=index)
-        all_edges = set([*node_dependencies[step, index], *path_taken])
+        # 2. Build Edges to this Node
+        path_taken = set(chip.get('record', 'inputnode', step=step, index=index) or [])
+        all_possible_inputs = set(node_dependencies.get((step, index), []))
+        all_edges = all_possible_inputs.union(path_taken)
+
         for source_step, source_index in all_edges:
+            # Determine edge style based on whether it was part of the
+            # actual execution path and the critical path.
             edge_width = default_edge_width
-            if (step, index) in successful_path and \
-               (source_step, source_index) in successful_path:
+            if (step, index) in successful_path and (source_step, source_index) in successful_path:
                 edge_width = successful_path_edge_width
 
             dashes = False
             color = 'black'
             if (source_step, source_index) not in path_taken:
+                # Potential but unused dependency
                 color = 'gray'
                 dashes = True
             elif node_status != NodeStatus.SUCCESS:
+                # Executed path, but not part of a successful flow
                 color = 'gray'
             elif NodeStatus.is_waiting(node_status) or NodeStatus.is_running(node_status):
+                # Path leading to a currently active node
                 color = 'blue'
                 dashes = True
 
@@ -106,12 +121,20 @@ def get_nodes_and_edges(chip):
 
 
 def get_graph_config():
+    """
+    Returns a `streamlit_agraph.Config` object with predefined settings
+    for a hierarchical, top-down flowgraph layout.
+
+    Returns:
+        Config: The configuration object for the agraph component.
+    """
     return Config(
         width='100%',
         height=1000,
         directed=True,
         physics=False,
         hierarchical=True,
+        # Hierarchical layout settings
         nodeSpacing=150,
         levelSeparation=100,
         sortMethod='directed')

siliconcompiler/report/dashboard/web/components/graph.py

@@ -1,5 +1,8 @@
+"""
+A collection of functions for creating and managing interactive metric graphs
+in the web dashboard using Streamlit and Altair.
+"""
 import altair
-import math
 import streamlit
 
 from siliconcompiler.report import report
@@ -8,6 +11,13 @@ from siliconcompiler.report.dashboard.web import state
 
 
 def _get_report_chips():
+    """
+    Gathers all loaded chip objects and their names for reporting.
+
+    Returns:
+        list[dict]: A list of dictionaries, where each dictionary contains
+                    'chip_object' and 'chip_name'.
+    """
     chips = []
     for job in state.get_chips():
         chips.append({'chip_object': state.get_chip(job), 'chip_name': job})
@@ -16,16 +26,18 @@ def _get_report_chips():
 
 def job_selector():
     """
-    Displays a dataframe that can be edited to select specific jobs to include
-    in the analysis.
+    Displays a data editor in a popover for selecting which jobs to include
+    in the graphs.
+
+    The selection is stored in the session state.
     """
     from pandas import DataFrame
 
     jobs = state.get_chips()
 
-    all_jobs = DataFrame({
+    all_jobs_df = DataFrame({
         'job names': jobs,
-        'selected jobs': [True] * len(jobs)
+        'selected jobs': [job in state.get_key(state.GRAPH_JOBS) for job in jobs]
     })
 
     configuration = {
@@ -35,41 +47,51 @@ def job_selector():
     }
 
     with streamlit.popover('Select Jobs', use_container_width=True):
-        selected_jobs = streamlit.data_editor(
-            all_jobs,
+        selected_jobs_df = streamlit.data_editor(
+            all_jobs_df,
             disabled=['job names'],
             use_container_width=True,
             hide_index=True,
             column_config=configuration)
 
-        jobs = []
-        for is_selected, job_name in zip(selected_jobs['selected jobs'].tolist(),
-                                         selected_jobs['job names'].tolist()):
-            if is_selected:
-                jobs.append(job_name)
+        selected_jobs_list = [
+            job_name for is_selected, job_name in zip(
+                selected_jobs_df['selected jobs'], selected_jobs_df['job names']
+            ) if is_selected
+        ]
 
-        state.set_key(state.GRAPH_JOBS, jobs)
+        state.set_key(state.GRAPH_JOBS, selected_jobs_list)
 
 
 def graph_count_selector():
+    """
+    Displays a slider to control the number of graphs shown on the page.
+
+    Returns:
+        int: The number of graphs selected by the user.
+    """
     return streamlit.slider(
         'pick the number of graphs you want',
-        1,
-        10,
-        1,
+        1, 10, 1,
         label_visibility='collapsed')
 
 
 def settings(metrics, nodes, graph_number):
     """
-    Displays selectbox for metrics and nodes which informs the graph on what
-    to display.
+    Displays settings controls for a single graph instance.
+
+    This includes popovers for selecting a metric, nodes, and other graph
+    options like log scale, transpose, and chart type.
 
     Args:
-        metrics (list) : A list of metrics that are set for all chips given in chips.
-        nodes (list) : A list of nodes given in the form f'{step}/{index}'
-        graph_number (int) : The number of graphs there are. Used to create
-            keys to distinguish selectboxes from each other.
+        metrics (list): A list of available metric names.
+        nodes (list): A list of available node names in 'step/index' format.
+        graph_number (int): The unique identifier for the graph, used to create
+            distinct keys for the UI widgets.
+
+    Returns:
+        tuple: A tuple containing the selected metric, nodes, log_scale flag,
+               transpose flag, and chart type.
     """
     metric_selector_col, node_selector_col, settings_col = \
         streamlit.columns(3, gap='small')
@@ -77,16 +99,14 @@ def settings(metrics, nodes, graph_number):
     with metric_selector_col:
         with streamlit.popover('Select a Metric', use_container_width=True):
             selected_metric = streamlit.selectbox(
-                'Select a Metric',
-                metrics,
+                'Select a Metric', metrics,
                 label_visibility='collapsed',
                 key=f'graph-{graph_number}-metric-selection')
 
     with node_selector_col:
         with streamlit.popover('Select Nodes', use_container_width=True):
             selected_nodes = streamlit.multiselect(
-                'Select a Node',
-                nodes,
+                'Select a Node', nodes,
                 label_visibility='collapsed',
                 key=f'graph-{graph_number}-node-selection',
                 default=nodes)
@@ -94,20 +114,17 @@ def settings(metrics, nodes, graph_number):
     with settings_col:
         with streamlit.popover('Settings', use_container_width=True):
             log_scale = streamlit.checkbox(
-                "Log scale",
-                False,
+                "Log scale", False,
                 help="Make the y-axis log scale",
                 key=f'graph-{graph_number}-log-scale')
 
             transpose = streamlit.checkbox(
-                "Transpose",
-                False,
+                "Transpose", False,
                 help="Use nodes instead of jobs as the x-axis",
                 key=f'graph-{graph_number}-transpose')
 
             chart_type = streamlit.selectbox(
-                'Chart type',
-                ['line', 'bar', 'point', 'tick'],
+                'Chart type', ['line', 'bar', 'point', 'tick'],
                 label_visibility='collapsed',
                 key=f'graph-{graph_number}-chart-selection')
 
@@ -115,86 +132,108 @@ def settings(metrics, nodes, graph_number):
 
 
 def graph(metrics, nodes, node_to_step_index_map, graph_number):
+    """
+    Renders a single, configurable metric graph using Altair.
+
+    This function gets the user's settings, fetches the corresponding data,
+    and constructs and displays an Altair chart.
+
+    Args:
+        metrics (list): A list of all available metrics.
+        nodes (list): A list of all available nodes.
+        node_to_step_index_map (dict): A mapping from node names to
+            (step, index) tuples.
+        graph_number (int): The unique identifier for this graph instance.
+    """
     from pandas import DataFrame
 
     metric, selected_nodes, log_scale, transpose, chart_type = \
         settings(metrics, nodes, graph_number)
 
-    nodes_as_step_and_index = []
-    for selected_node in selected_nodes:
-        step, index = node_to_step_index_map[selected_node]
-        nodes_as_step_and_index.append((step, index))
+    nodes_as_step_and_index = [
+        node_to_step_index_map[node] for node in selected_nodes
+    ]
 
+    # --- Data Fetching and Preparation ---
     if transpose:
-        x_axis_label = 'nodes'
-        color_label = 'runs'
+        x_axis_label, color_label = 'nodes', 'runs'
     else:
-        x_axis_label = 'runs'
-        color_label = 'nodes'
+        x_axis_label, color_label = 'runs', 'nodes'
 
     y_axis_label = metric
-
-    data, metric_unit = report.get_chart_data(_get_report_chips(), metric, nodes_as_step_and_index)
+    data, metric_unit = report.get_chart_data(
+        _get_report_chips(), metric, nodes_as_step_and_index)
     if metric_unit:
         y_axis_label = f'{metric} ({metric_unit})'
 
-    # Prepare plot data
-    filtered_data = {
-        x_axis_label: [],
-        y_axis_label: [],
-        color_label: []
-    }
-
-    labels = {
-        "runs": state.get_key(state.GRAPH_JOBS),
-        "nodes": [f'{step}/{index}' for step, index in data]
-    }
-
-    if nodes:
-        # filtering through data
-        for job_name in state.get_key(state.GRAPH_JOBS):
-            for step, index in data:
-                filtered_data['runs'].append(job_name)
-                filtered_data['nodes'].append(step + index)
-                if job_name not in data[(step, index)].keys():
-                    filtered_data[y_axis_label].append(None)
-                else:
-                    filtered_data[y_axis_label].append(data[(step, index)][job_name])
-
-    # Setup chart
-    x_axis = altair.X(x_axis_label, axis=altair.Axis(labelAngle=-75), sort=labels[x_axis_label])
-
-    y_axis = y_axis_label
-    if log_scale and chart_type != 'bar':
-        y_axis = altair.Y(y_axis_label, scale=altair.Scale(type="log"))
-
-    color = color_label
-
-    alt_chart = altair.Chart(DataFrame(filtered_data).dropna(), height=500)
-
-    if chart_type == 'line':
-        chart_mark = alt_chart.mark_line(point=True)
-    elif chart_type == 'bar':
-        chart_mark = alt_chart.mark_bar(point=True)
-    elif chart_type == 'point':
-        chart_mark = alt_chart.mark_circle(point=True)
-    elif chart_type == 'tick':
-        chart_mark = alt_chart.mark_tick(point=True)
+    # Reshape data into a long-form DataFrame suitable for Altair
+    plot_data = []
+    if data:
+        for (step, index), job_data in data.items():
+            for job_name, value in job_data.items():
+                if job_name in state.get_key(state.GRAPH_JOBS):
+                    plot_data.append({
+                        'runs': job_name,
+                        'nodes': f'{step}/{index}',
+                        y_axis_label: value
+                    })
+    filtered_df = DataFrame(plot_data).dropna()
+
+    # --- Chart Configuration and Rendering ---
+    if not filtered_df.empty:
+        sort_order = {
+            "runs": state.get_key(state.GRAPH_JOBS),
+            "nodes": selected_nodes
+        }
+
+        x_axis = altair.X(x_axis_label,
+                          axis=altair.Axis(labelAngle=-75),
+                          sort=sort_order[x_axis_label])
+
+        y_axis = altair.Y(y_axis_label)
+        if log_scale and chart_type != 'bar':
+            y_axis = altair.Y(y_axis_label, scale=altair.Scale(type="log"))
+
+        color = color_label
+
+        alt_chart = altair.Chart(filtered_df, height=500)
+
+        if chart_type == 'line':
+            chart_mark = alt_chart.mark_line(point=True)
+        elif chart_type == 'bar':
+            chart_mark = alt_chart.mark_bar()
+        elif chart_type == 'point':
+            chart_mark = alt_chart.mark_circle()
+        elif chart_type == 'tick':
+            chart_mark = alt_chart.mark_tick()
+        else:
+            raise ValueError(f'{chart_type} not supported')
+
+        chart = chart_mark.encode(x=x_axis, y=y_axis, color=color)
+        streamlit.altair_chart(chart, use_container_width=True, theme='streamlit')
     else:
-        raise ValueError(f'{chart_type} not supported')
+        streamlit.warning("No data available for the selected metric and nodes.")
 
-    chart = chart_mark.encode(
-        x=x_axis,
-        y=y_axis,
-        color=color)
 
-    streamlit.altair_chart(chart, use_container_width=True, theme='streamlit')
+def viewer(node_to_step_index_map):
+    """
+    The main container component for the graphing page.
 
+    It lays out the job selector, the graph count selector, and the
+    individual graph components in a grid.
 
-def viewer(node_to_step_index_map):
+    Args:
+        node_to_step_index_map (dict): A mapping from node names to
+            (step, index) tuples, passed down to the graph components.
+    """
     nodes, metrics = report.get_chart_selection_options(_get_report_chips())
     metrics = sorted(metrics)
 
+    # Initialize selected jobs if not already set
+    if state.get_key(state.GRAPH_JOBS) is None:
+        state.set_key(state.GRAPH_JOBS, state.get_chips())
+
+    # --- UI Layout ---
     job_selector_col, graph_adder_col = streamlit.columns(2, gap='large')
     with job_selector_col:
         job_selector()
@@ -203,14 +242,14 @@ def viewer(node_to_step_index_map):
 
     streamlit.divider()
 
+    # Create a responsive grid for the graphs
     columns = 1 if graphs <= 1 else 2
-    last_row_num = int(math.floor((graphs - 1) / columns)) * columns
-
-    graph_number = 0
-    graph_cols = streamlit.columns(columns, gap='large')
-    while graph_number < graphs:
-        with graph_cols[graph_number % columns]:
-            graph(metrics, nodes, node_to_step_index_map, graph_number)
-            if graph_number < last_row_num:
+    for i in range(graphs):
+        if i % columns == 0:
+            # Start a new row of columns
+            graph_cols = streamlit.columns(columns, gap='large')
+        with graph_cols[i % columns]:
+            graph(metrics, nodes, node_to_step_index_map, i)
+            # Add a divider between rows
+            if i < graphs - columns:
                 streamlit.divider()
-        graph_number += 1

siliconcompiler/report/dashboard/web/layouts/__init__.py

@@ -1,7 +1,15 @@
+"""
+A registry for different dashboard layouts.
+
+This module imports layout functions from other files and provides a centralized
+way to access them by name. This allows the main application to dynamically
+switch between different UI arrangements.
+"""
 from siliconcompiler.report.dashboard.web.layouts import vertical_flowgraph
 from siliconcompiler.report.dashboard.web.layouts import vertical_flowgraph_sac_tabs
 from siliconcompiler.report.dashboard.web.layouts import vertical_flowgraph_node_tab
 
+# A dictionary mapping layout names to their corresponding layout functions.
 __LAYOUTS = {
     "vertical_flowgraph": vertical_flowgraph.layout,
     "vertical_flowgraph_sac_tabs": vertical_flowgraph_sac_tabs.layout,
@@ -10,11 +18,31 @@ __LAYOUTS = {
 
 
 def get_all_layouts():
+    """
+    Retrieves a list of all available layout names.
+
+    Returns:
+        list[str]: A list of strings, where each string is the name of a
+                   registered layout.
+    """
     return list(__LAYOUTS.keys())
 
 
 def get_layout(name):
+    """
+    Retrieves a layout function by its registered name.
+
+    Args:
+        name (str): The name of the layout to retrieve.
+
+    Returns:
+        function: The corresponding layout function.
+
+    Raises:
+        ValueError: If the provided name does not match any registered layout.
+    """
     if name not in __LAYOUTS:
-        raise ValueError(f"{name} is not a layout")
+        raise ValueError(f"'{name}' is not a valid layout. "
+                         f"Available layouts: {', '.join(get_all_layouts())}")
 
     return __LAYOUTS[name]

siliconcompiler/report/dashboard/web/layouts/_common.py

@@ -1,43 +1,79 @@
+"""
+Utility functions for managing the state of tab components in the web dashboard.
+
+This module provides helpers for controlling which tab is active, especially
+when a user action (like selecting a node or a file) should automatically
+switch the view to a different tab.
+"""
 import streamlit_antd_components as sac
 
 from siliconcompiler.report.dashboard.web import state
 
 
 def check_rerun():
-    # Determine if node was modified
+    """
+    Checks if the selected node or file has changed and updates the active tab accordingly.
+
+    This function is called on each rerun to ensure that if a user selects a
+    node in the flowgraph, the UI automatically switches to the "Node Information"
+    tab. Similarly, if a file is selected, it switches to the "File Viewer" tab.
+    """
+    # If the globally selected node changes, flag a rerun to switch tabs.
     if state.set_key(state.SELECTED_NODE, state.get_selected_node()):
         state.set_key(state.APP_RERUN, "Node")
 
+    # Based on the rerun flag, force a specific tab to be selected.
     if state.get_key(state.APP_RERUN) == "Node":
         state.set_key(state.SELECT_TAB, "Node Information")
+        # Reset the component's internal state to ensure the change takes effect.
         state.del_key(state.TAB_STATE)
     elif state.get_key(state.APP_RERUN) == "File":
         state.set_key(state.SELECT_TAB, "File Viewer")
         state.del_key(state.TAB_STATE)
     else:
+        # Clear the forced selection if no specific action was taken.
         state.set_key(state.SELECT_TAB, None)
 
 
 def sac_tabs(tab_headings):
+    """
+    Renders a tab group using streamlit-antd-components and manages its state.
+
+    This function determines which tab should be initially selected based on
+    the application state and saves the user's new selection back to the state.
+
+    Args:
+        tab_headings (list[sac.Tabs.Item]): A list of tab items to display.
+
+    Returns:
+        str: The label of the currently selected tab.
+    """
     index = 0
 
+    # Determine the initial tab index based on a forced selection or the last known state.
     if state.get_key(state.SELECT_TAB):
+        # A specific tab is being forced by an action (e.g., node selection).
         for n, tab in enumerate(tab_headings):
             if state.get_key(state.SELECT_TAB) == tab.label:
                 index = n
+                break
     elif state.get_key(state.TAB_INDEX) is not None:
+        # Default to the last tab the user had open.
         index = state.get_key(state.TAB_INDEX)
 
+    # Render the tabs component.
     tab_selected = sac.tabs(
         tab_headings,
         align='center',
         variant='outline',
         use_container_width=True,
         index=index,
-        key=state.TAB_STATE)
+        key=state.TAB_STATE)  # The key links to the component's internal state.
 
+    # Save the index of the selected tab for the next rerun.
     for n, tab in enumerate(tab_headings):
         if tab_selected == tab.label:
             state.set_key(state.TAB_INDEX, n)
+            break
 
     return tab_selected