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

siliconcompiler/report/dashboard/web/state.py

@@ -1,3 +1,18 @@
+"""
+Manages the session state for the SiliconCompiler web dashboard.
+
+This module defines the keys used in Streamlit's session state and provides
+a set of utility functions to initialize, access, and modify that state.
+It is the central point for managing UI state, loaded data (chip manifests),
+and application configuration throughout the user's session.
+
+The main functions are:
+- init(): Parses command-line arguments and sets up the initial session state.
+- setup(): Performs per-rerun setup, like capturing UI dimensions.
+- update_manifest(): Checks for changes in the manifest file and reloads data.
+- A set of getters and setters (get_key, set_key, etc.) for safe access
+  to the session state.
+"""
 import argparse
 import json
 import os
@@ -7,43 +22,70 @@ import fasteners
 
 from siliconcompiler import Chip
 
+# --- State Keys ---
+# These constants define the keys used to store and access data in
+# streamlit.session_state, ensuring consistency across the application.
 
+# UI Component State
 DISPLAY_FLOWGRAPH = "show_flowgraph"
 SELECTED_JOB = "selected_job"
 SELECTED_NODE = "selected_node"
-# This is needed until the graph supports setting a selected node
+# The following keys differentiate the source of a node selection, as multiple
+# UI components (the graph, a dropdown) can select a node.
 SELECTED_FLOWGRAPH_NODE = "selected_flowgraph_node"
 SELECTED_SELECTOR_NODE = "selected_selector_node"
 NODE_SOURCE = "node_source"
 SELECTED_FILE = "selected_file"
 SELECTED_FILE_PAGE = "selected_file_page"
-LOADED_CHIPS = "loaded_chips"
 UI_WIDTH = "ui_width"
+SELECT_TAB = "select_tab"
+TAB_INDEX = "tab-index"
+TAB_STATE = "tab-state"
+
+# Data State
+LOADED_CHIPS = "loaded_chips"
 MANIFEST_FILE = "manifest_file"
 MANIFEST_LOCK = "manifest_lock"
 MANIFEST_TIME = "manifest_time"
 IS_RUNNING = "is_flow_running"
 GRAPH_JOBS = "graph_jobs"
+
+# Application Configuration & Control
 APP_LAYOUT = "app_layout"
 APP_RERUN = "app_rerun"
 APP_RUNNING_REFRESH = "app_running_refresh"
 APP_STOPPED_REFRESH = "app_stopped_refresh"
 MAX_DICT_ITEMS_TO_SHOW = "max_dict_items"
 MAX_FILE_LINES_TO_SHOW = "max_file_lines"
-SELECT_TAB = "select_tab"
-TAB_INDEX = "tab-index"
-TAB_STATE = "tab-state"
 
+# --- Debugging ---
 _DEBUG = False
 DEVELOPER = False
 
 
 def _add_default(key, value):
+    """
+    Initializes a key in the session state if it doesn't already exist.
+
+    Args:
+        key (str): The key to add to the session state.
+        value: The default value to assign if the key is not present.
+    """
     if key not in streamlit.session_state:
         streamlit.session_state[key] = value
 
 
 def update_manifest():
+    """
+    Checks for updates to the main manifest file and reloads it if necessary.
+
+    Compares the current file modification time with the stored time. If they
+    differ, it re-reads the manifest, re-populates the chip objects (including
+    history), and updates the timestamp in the session state.
+
+    Returns:
+        bool: True if the manifest was updated, False otherwise.
+    """
     file_time = os.stat(get_key(MANIFEST_FILE)).st_mtime
 
     if get_key(MANIFEST_TIME) != file_time:
@@ -56,6 +98,7 @@ def update_manifest():
 
         add_chip("default", chip)
 
+        # Load historical runs from the manifest
         for history in chip.getkeys('history'):
             history_chip = Chip(design='')
             history_chip.schema = chip.schema.history(history).copy()
@@ -67,6 +110,14 @@ def update_manifest():
 
 
 def init():
+    """
+    Initializes the application's session state on first run.
+
+    This function sets default values for all state keys, parses command-line
+    arguments to find the dashboard configuration file, and loads the initial
+    set of chip manifests.
+    """
+    # Set default values for all session state keys.
     _add_default(DISPLAY_FLOWGRAPH, True)
     _add_default(SELECTED_JOB, None)
     _add_default(SELECTED_NODE, None)
@@ -84,23 +135,23 @@ def init():
     _add_default(UI_WIDTH, None)
     _add_default(APP_LAYOUT, "vertical_flowgraph_sac_tabs")
     _add_default(APP_RERUN, None)
-    _add_default(APP_RUNNING_REFRESH, 2 * 1000)
-    _add_default(APP_STOPPED_REFRESH, 30 * 1000)
+    _add_default(APP_RUNNING_REFRESH, 2 * 1000)  # 2 seconds
+    _add_default(APP_STOPPED_REFRESH, 30 * 1000)  # 30 seconds
     _add_default(MAX_DICT_ITEMS_TO_SHOW, 100)
     _add_default(MAX_FILE_LINES_TO_SHOW, 100)
     _add_default(SELECT_TAB, None)
     _add_default(TAB_INDEX, 0)
 
+    # Parse command-line arguments to get the config file path.
     parser = argparse.ArgumentParser('dashboard')
     parser.add_argument('cfg', nargs='?')
     args = parser.parse_args()
 
     if not args.cfg:
-        raise ValueError('configuration not provided')
+        raise ValueError('Dashboard configuration not provided via command line.')
 
+    # On the very first run, load the configuration and initial data.
     if not get_key(LOADED_CHIPS):
-        # First time through
-
         with open(args.cfg, 'r') as f:
             config = json.load(f)
 
@@ -109,6 +160,8 @@ def init():
 
         update_manifest()
         chip = get_chip("default")
+
+        # Load any additional graph-related chips specified in the config.
         for graph_info in config['graph_chips']:
             file_path = graph_info['path']
             graph_chip = Chip(design='')
@@ -121,41 +174,70 @@ def init():
 
             add_chip(os.path.basename(file_path), graph_chip)
 
+        # Pre-select a node if specified in the chip's arguments.
         chip_step = chip.get('arg', 'step')
         chip_index = chip.get('arg', 'index')
-
         if chip_step and chip_index:
             set_key(SELECTED_NODE, f'{chip_step}/{chip_index}')
 
+    # Clean up args for subsequent runs.
     chip = get_chip("default")
     chip.unset('arg', 'step')
     chip.unset('arg', 'index')
 
+    # Ensure a job is selected.
     if not get_key(SELECTED_JOB):
         set_key(SELECTED_JOB, "default")
 
 
 def setup():
+    """
+    Performs setup tasks required on every page rerun.
+    """
+    # Use a javascript call to get the browser window's current width.
     with streamlit.empty():
-        # get width
         set_key(UI_WIDTH, streamlit_javascript.st_javascript("window.innerWidth"))
-        # replace with a empty container to avoid adding a gap at the top
+        # Replace with an empty container to avoid adding a visual gap at the top.
         streamlit.empty()
 
+    # Reset the node source on each rerun.
     set_key(NODE_SOURCE, None)
 
 
 def get_chip(job=None):
+    """
+    Retrieves a loaded Chip object from the session state.
+
+    Args:
+        job (str, optional): The name of the job/chip to retrieve.
+                             Defaults to the currently selected job.
+
+    Returns:
+        Chip: The requested Chip object.
+    """
     if not job:
         job = get_key(SELECTED_JOB)
     return get_key(LOADED_CHIPS)[job]
 
 
 def add_chip(name, chip):
+    """
+    Adds a Chip object to the session state.
+
+    Args:
+        name (str): The name to associate with the chip (e.g., 'default' or a history ID).
+        chip (Chip): The Chip object to store.
+    """
     streamlit.session_state[LOADED_CHIPS][name] = chip
 
 
 def get_chips():
+    """
+    Gets a list of all loaded chip names.
+
+    Returns:
+        list: A list of strings, with 'default' guaranteed to be the first element.
+    """
     chips = list(get_key(LOADED_CHIPS).keys())
     chips.remove('default')
     chips.insert(0, 'default')
@@ -163,6 +245,12 @@ def get_chips():
 
 
 def get_selected_node():
+    """
+    Gets the currently selected node, accounting for the selection source.
+
+    Returns:
+        str or None: The identifier of the selected node (e.g., 'import/0').
+    """
     if get_key(NODE_SOURCE) == "flowgraph":
         return get_key(SELECTED_FLOWGRAPH_NODE)
 
@@ -173,10 +261,32 @@ def get_selected_node():
 
 
 def get_key(key):
+    """
+    Generic getter for a value from the session state.
+
+    Args:
+        key (str): The key of the value to retrieve.
+
+    Returns:
+        The value associated with the key.
+    """
     return streamlit.session_state[key]
 
 
 def set_key(key, value):
+    """
+    Generic setter for a value in the session state.
+
+    This function checks if the new value is different from the old one
+    before setting it, which helps in preventing unnecessary reruns.
+
+    Args:
+        key (str): The key of the value to set.
+        value: The new value to assign.
+
+    Returns:
+        bool: True if the value was changed, False otherwise.
+    """
     changed = value != streamlit.session_state[key]
     if changed:
         debug_print("set_key()", key, "changed", streamlit.session_state[key], "->", value)
@@ -186,12 +296,28 @@ def set_key(key, value):
 
 
 def del_key(key):
+    """
+    Deletes a key from the session state if it exists.
+
+    Args:
+        key (str): The key to delete.
+    """
     debug_print("del_key()", key)
     if key in streamlit.session_state:
         del streamlit.session_state[key]
 
 
 def compute_component_size(minimum, requested_px):
+    """
+    Utility to calculate component sizes based on UI width.
+
+    Args:
+        minimum (float): The minimum size as a fraction of the width.
+        requested_px (int): The desired size in pixels.
+
+    Returns:
+        float: The calculated size as a fraction of the width.
+    """
     ui_width = get_key(UI_WIDTH)
 
     if ui_width > 0:
@@ -201,13 +327,14 @@ def compute_component_size(minimum, requested_px):
 
 
 def debug_print(*args):
+    """Prints messages to the console only if the _DEBUG flag is True."""
     if not _DEBUG:
         return
-
     print(*args)
 
 
 def debug_print_state():
+    """Prints the entire Streamlit session state to the console for debugging."""
     if not _DEBUG:
         return
 

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

@@ -1,9 +1,31 @@
+"""
+Utility functions for the SiliconCompiler web dashboard.
+
+This module provides helper functions for processing chip data, formatting it
+for display, and checking the status of a run. These functions are used by
+the main dashboard application to interact with the chip object and prepare
+data for UI components.
+"""
 from siliconcompiler import NodeStatus
-
 from pathlib import Path
 
 
 def get_chip_cwd(chip, manifest):
+    """
+    Determines the original chip working directory from a manifest path.
+
+    This function is useful for resolving relative paths when the dashboard
+    is run from a different location than the original compilation. It traverses
+    up from the manifest's location to find the parent of the build directory.
+
+    Args:
+        chip (Chip): The chip object.
+        manifest (str): The absolute path to the chip's manifest file.
+
+    Returns:
+        str or None: The absolute path to the chip's original working
+                     directory, or None if it cannot be determined.
+    """
     build_dir = Path(chip.get('option', 'builddir'))
 
     manifest_path = Path(manifest)
@@ -15,48 +37,74 @@ def get_chip_cwd(chip, manifest):
 
 
 def make_node_to_step_index_map(chip, metric_dataframe):
-    '''
-    Returns a map from the name of a node to the associated step, index pair.
+    """
+    Creates a mapping from a node's string representation to its (step, index) tuple.
+
+    It also renames the columns of the metric dataframe to the 'step/index' format.
 
     Args:
-        metric_dataframe (pandas.DataFrame) : A dataframe full of all metrics and all
-            nodes of the selected chip
-    '''
+        chip (Chip): The chip object.
+        metric_dataframe (pandas.DataFrame): The dataframe of metrics, with
+            multi-level columns of (step, index).
+
+    Returns:
+        tuple: A tuple containing:
+            - dict: A dictionary mapping 'step/index' strings to (step, index) tuples.
+            - pandas.DataFrame: The modified metric dataframe.
+    """
     node_to_step_index_map = {}
     if chip.get('option', 'flow'):
         for step, index in chip.get("flowgraph", chip.get('option', 'flow'),
                                     field="schema").get_nodes():
             node_to_step_index_map[f'{step}/{index}'] = (step, index)
 
-    # concatenate step and index
-    metric_dataframe.columns = metric_dataframe.columns.map(lambda x: f'{x[0]}{x[1]}')
+    # Concatenate step and index in the DataFrame columns
+    metric_dataframe.columns = metric_dataframe.columns.map(lambda x: f'{x[0]}/{x[1]}')
     return node_to_step_index_map, metric_dataframe
 
 
 def make_metric_to_metric_unit_map(metric_dataframe):
-    '''
-    Returns a map from the name of a metric to the associated metric and unit in
-    the form f'{x[0]} ({x[1]})'
+    """
+    Creates a mapping from a formatted metric string to the raw metric name.
+
+    It also renames the index of the metric dataframe to include units,
+    e.g., 'cells (count)'.
 
     Args:
-        metric_dataframe (pandas.DataFrame) : A dataframe full of all metrics and all
-            nodes of the selected chip.
-    '''
+        metric_dataframe (pandas.DataFrame): The dataframe of metrics, with
+            a multi-level index of (metric, unit).
+
+    Returns:
+        tuple: A tuple containing:
+            - dict: A dictionary mapping formatted metric strings to raw metric names.
+            - pandas.DataFrame: The modified metric dataframe.
+    """
     metric_to_metric_unit_map = {}
     for metric, unit in metric_dataframe.index.tolist():
-        if unit != '':
+        if unit:
             metric_to_metric_unit_map[f'{metric} ({unit})'] = metric
         else:
             metric_to_metric_unit_map[metric] = metric
-    # concatenate metric and unit
+
+    # Concatenate metric and unit in the DataFrame index
     metric_dataframe.index = metric_dataframe.index.map(lambda x: f'{x[0]} ({x[1]})'
                                                         if x[1] else x[0])
     return metric_to_metric_unit_map, metric_dataframe
 
 
 def is_running(chip):
+    """
+    Checks if any node in the chip's flowgraph is still running.
+
+    Args:
+        chip (Chip): The chip object to check.
+
+    Returns:
+        bool: True if any node is not in a 'done' state, False otherwise.
+    """
     if not chip.get('option', 'flow'):
         return False
+
     for step, index in chip.get("flowgraph", chip.get('option', 'flow'),
                                 field="schema").get_nodes():
         state = chip.get('record', 'status', step=step, index=index)
@@ -66,6 +114,21 @@ def is_running(chip):
 
 
 def generate_metric_dataframe(chip):
+    """
+    Generates a fully processed metric dataframe and associated mappings.
+
+    This function orchestrates the creation of the metric dataframe and the
+    helper dictionaries needed to easily look up nodes and metrics in the UI.
+
+    Args:
+        chip (Chip): The chip object from which to generate the report.
+
+    Returns:
+        tuple: A tuple containing:
+            - pandas.DataFrame: The processed metric dataframe.
+            - dict: The node-to-(step, index) mapping.
+            - dict: The formatted-metric-to-raw-metric mapping.
+    """
     from siliconcompiler.report import report
 
     metric_dataframe = report.make_metric_dataframe(chip)

siliconcompiler/report/dashboard/web/utils/file_utils.py

@@ -1,16 +1,34 @@
+"""
+Utility functions for handling and displaying files in the web dashboard.
+
+This module provides helpers for reading files (including compressed ones),
+determining file types for syntax highlighting, selecting appropriate icons,
+and structuring file lists into a hierarchical tree for UI components.
+"""
 import gzip
 import os
 from siliconcompiler import utils, sc_open
 
 
 def is_file_is_binary(path, compressed):
-    # Read first chunk and check for non characters
+    """
+    Checks if a file is binary by attempting to read it as text.
+
+    Args:
+        path (str): The path to the file.
+        compressed (bool): True if the file is gzip compressed.
+
+    Returns:
+        bool: True if a UnicodeDecodeError occurs (indicating binary content),
+              False otherwise.
+    """
+    # Read the first chunk and check for non-text characters.
     try:
         if compressed:
-            with gzip.open(path, 'rt') as f:
+            with gzip.open(path, 'rt', errors='strict') as f:
                 f.read(8196)
         else:
-            with open(path, "r") as f:
+            with open(path, "r", errors='strict') as f:
                 f.read(8196)
     except UnicodeDecodeError:
         return True
@@ -18,11 +36,27 @@ def is_file_is_binary(path, compressed):
 
 
 def read_file(path, max_lines):
+    """
+    Reads the contents of a text file, with support for gzip compression.
+
+    If the file is determined to be binary, it returns a placeholder string.
+    If `max_lines` is specified, the file content will be truncated.
+
+    Args:
+        path (str): The path to the file to read.
+        max_lines (int or None): The maximum number of lines to read. If None,
+                                 the entire file is read.
+
+    Returns:
+        str: The content of the file as a single string, or a placeholder
+             if the file is binary.
+    """
     _, compressed_file_extension = os.path.splitext(path.lower())
     file_info = []
     honor_max_file = max_lines is not None
 
-    def read_file(fid):
+    def _read_lines(fid):
+        """Helper to read lines from a file object and handle truncation."""
         for line in fid:
             file_info.append(line.rstrip())
             if honor_max_file and len(file_info) >= max_lines:
@@ -35,14 +69,23 @@ def read_file(path, max_lines):
 
     if is_compressed:
         with gzip.open(path, 'rt') as fid:
-            read_file(fid)
+            _read_lines(fid)
     else:
         with sc_open(path) as fid:
-            read_file(fid)
+            _read_lines(fid)
     return "\n".join(file_info)
 
 
 def get_file_type(ext):
+    """
+    Maps a file extension to a language identifier for syntax highlighting.
+
+    Args:
+        ext (str): The file extension (without the dot).
+
+    Returns:
+        str: The language identifier (e.g., 'verilog', 'tcl'). Defaults to 'log'.
+    """
     if ext in ("v", "vh", "sv", "svh", "vg"):
         return "verilog"
     if ext in ("vhdl", "vhd"):
@@ -61,6 +104,17 @@ def get_file_type(ext):
 
 
 def get_file_icon(file):
+    """
+    Determines an appropriate icon name for a given file path.
+
+    The icon name is based on the file's extension and type.
+
+    Args:
+        file (str): The path to the file.
+
+    Returns:
+        str: A string identifier for the icon (e.g., 'file-code', 'file-image').
+    """
     if not file:
         return 'file'
     ext = utils.get_file_ext(file)
@@ -80,17 +134,22 @@ def get_file_icon(file):
 
 def convert_filepaths_to_select_tree(logs_and_reports):
     """
-    Converts the logs_and_reports found to the structure
-    required by streamlit_tree_select. Success is predicated on the order of
-    logs_and_reports outlined in report.get_files.
+    Converts a flat list of file paths into a hierarchical tree structure.
+
+    This structure is suitable for UI components like `streamlit_tree_select`.
+    The function recursively builds the tree based on the directory structure.
 
     Args:
-        logs_and_reports (list) : A list of 3-tuples with order of a path name,
-            folder in the..., and files in the....
+        logs_and_reports (list): A list of 3-tuples, where each tuple contains
+            (path_name, list_of_folders, list_of_files).
+
+    Returns:
+        list: A list of dictionaries representing the root nodes of the tree.
     """
     if not logs_and_reports:
         return []
 
+    # Create a dictionary for quick lookup of folder contents.
     all_files = {}
     for path_name, folders, files in logs_and_reports:
         all_files[path_name] = {
@@ -99,8 +158,10 @@ def convert_filepaths_to_select_tree(logs_and_reports):
         }
 
     def organize_node(base_folder):
+        """Recursively builds the node structure for a given folder."""
         nodes = []
 
+        # Add sub-folders as expandable nodes.
         for folder in all_files[base_folder]['folders']:
             path = os.path.join(base_folder, folder)
             nodes.append({
@@ -108,6 +169,7 @@ def convert_filepaths_to_select_tree(logs_and_reports):
                 'label': folder,
                 'children': organize_node(path)
             })
+        # Add files as leaf nodes.
         for file in all_files[base_folder]['files']:
             nodes.append({
                 'value': os.path.join(base_folder, file),
@@ -116,5 +178,6 @@ def convert_filepaths_to_select_tree(logs_and_reports):
 
         return nodes
 
+    # Start the recursion from the root path.
     starting_path_name = logs_and_reports[0][0]
     return organize_node(starting_path_name)

siliconcompiler/report/dashboard/web/viewer.py

@@ -1,3 +1,13 @@
+"""
+Main entry point for the SiliconCompiler web-based dashboard using Streamlit.
+
+This script initializes and runs the Streamlit application. It is responsible for:
+- Initializing the application and session state.
+- Setting up the page configuration (title, icon).
+- Dynamically selecting and rendering the appropriate layout.
+- Handling the auto-refresh mechanism to provide live updates.
+- Triggering reruns when the underlying data changes.
+"""
 import streamlit
 
 from siliconcompiler.report.dashboard.web import components
@@ -9,28 +19,42 @@ import streamlit_autorefresh
 
 
 if __name__ == "__main__":
-    # opened by running command in siliconcompiler/apps/sc_dashboard.py
+    # This script is executed by the `sc-dashboard` command.
+    # Initialize the Streamlit session state. This must be the first
+    # Streamlit command used in the app.
     state.init()
 
+    # Configure the page's title, icon, and other basic properties.
     components.setup_page()
+    # Set up the application state, loading data from the chip object.
     state.setup()
 
+    # Dynamically select the layout function based on the current state
+    # and then execute it to render the UI components for the page.
     layout = layouts.get_layout(state.get_key(state.APP_LAYOUT))
     layout()
 
+    # Determine if a full page reload is needed.
     reload = False
     if state.get_key(state.SELECTED_JOB) == 'default':
+        # Check if the underlying chip process is running and update the state.
         reload = state.set_key(state.IS_RUNNING, utils.is_running(state.get_chip()))
 
+    # Set the refresh interval based on the run status.
+    # Use a faster refresh rate when a job is running, and a slower one when stopped.
     if state.get_key(state.IS_RUNNING):
         update_interval = state.get_key(state.APP_RUNNING_REFRESH)
     else:
         update_interval = state.get_key(state.APP_STOPPED_REFRESH)
 
+    # Add the auto-refresh component to the page.
     streamlit_autorefresh.st_autorefresh(interval=update_interval)
 
+    # For debugging: print the current session state to the console.
     state.debug_print_state()
 
+    # Check if a full re-render of the application is required. This can be
+    # triggered by a data update, a manual rerun request, or a change in run status.
     if reload or state.update_manifest() or state.get_key(state.APP_RERUN):
         state.set_key(state.APP_RERUN, None)
         streamlit.rerun()