siliconcompiler 0.35.1__py3-none-any.whl → 0.35.3__py3-none-any.whl

siliconcompiler/checklist.py

@@ -1,21 +1,247 @@
 import re
-
 import os.path
+from pathlib import Path
+from typing import Tuple, List, Optional, Union, Dict, Iterable
 
-from typing import Tuple, Optional
-
-from siliconcompiler.schema import NamedSchema
-from siliconcompiler.schema import EditableSchema, Parameter, Scope, BaseSchema
+from siliconcompiler.schema import NamedSchema, EditableSchema, Parameter, Scope, BaseSchema
 from siliconcompiler.schema.utils import trim
-
 from siliconcompiler import NodeStatus, utils
 
 
+class Criteria(NamedSchema):
+    """
+    Schema for defining a single checklist item's criteria.
+
+    This class holds all the configurable parameters for a specific checklist
+    item, such as its description, requirements, validation criteria,
+    and associated reports or waivers.
+    """
+
+    def __init__(self, name: Optional[str] = None):
+        super().__init__()
+        self.set_name(name)
+        schema_checklist(self)
+
+    def get_description(self) -> Optional[str]:
+        """
+        Retrieves the short, one-line description of the checklist item.
+
+        Returns:
+            Optional[str]: The description string, or None if not set.
+        """
+        return self.get('description')
+
+    def set_description(self, value: Optional[str]) -> None:
+        """
+        Sets the short, one-line description for the checklist item.
+
+        Args:
+            value (Optional[str]): The description string to set.
+        """
+        self.set('description', value)
+
+    def get_requirement(self) -> Optional[str]:
+        """
+        Retrieves the detailed requirement description for the checklist item.
+
+        Returns:
+            Optional[str]: The requirement description, which can be a
+            multi-line string, or None if not set.
+        """
+        return self.get('requirement')
+
+    def set_requirement(self, value: Optional[str]) -> None:
+        """
+        Sets the detailed requirement description for the checklist item.
+
+        Args:
+            value (Optional[str]): The requirement description to set.
+        """
+        self.set('requirement', value)
+
+    def get_dataformat(self) -> Optional[str]:
+        """
+        Retrieves the description of acceptable data file formats.
+
+        Returns:
+            Optional[str]: A free-text description of the data format,
+            or None if not set.
+        """
+        return self.get('dataformat')
+
+    def set_dataformat(self, value: Optional[str]):
+        """
+        Sets the description of acceptable data file formats for signoff.
+
+        Args:
+            value (Optional[str]): A free-text description of the data format.
+        """
+        self.set('dataformat', value)
+
+    def get_rationale(self) -> List[str]:
+        """
+        Retrieves the rationale codes or descriptions for the checklist item.
+
+        Returns:
+            List[str]: A list of rationale strings.
+        """
+        return self.get('rationale')
+
+    def add_rationale(self, value: Union[List[str], str], clobber: bool = False) -> None:
+        """
+        Adds one or more rationale codes or descriptions to the checklist item.
+
+        Args:
+            value (Union[List[str], str]): A single rationale string or a list of strings.
+            clobber (bool): If True, replaces the existing list with the new value.
+                If False, appends to the existing list. Defaults to False.
+        """
+        if clobber:
+            self.set('rationale', value)
+        else:
+            self.add('rationale', value)
+
+    def get_criteria(self) -> List[str]:
+        """
+        Retrieves the list of signoff criteria.
+
+        Each criterion is a string in the format 'metric op value'
+        (e.g., 'errors == 0').
+
+        Returns:
+            List[str]: A list of criteria strings.
+        """
+        return self.get('criteria')
+
+    def add_criteria(self, value: Union[List[str], str], clobber: bool = False) -> None:
+        """
+        Adds one or more signoff criteria to the checklist item.
+
+        Args:
+            value (Union[List[str], str]): A single criterion string or a list of strings.
+            clobber (bool): If True, replaces the existing list with the new value.
+                If False, appends to the existing list. Defaults to False.
+        """
+        if clobber:
+            self.set('criteria', value)
+        else:
+            self.add('criteria', value)
+
+    def get_task(self) -> List[Tuple[str, str, str]]:
+        """
+        Retrieves the flowgraph tasks used to verify this checklist item.
+
+        Each task is represented as a tuple of (job, step, index).
+
+        Returns:
+            List[Tuple[str, str, str]]: A list of task tuples.
+        """
+        return self.get('task')
+
+    def add_task(self, value: Union[List[Tuple[str, str, str]], Tuple[str, str, str]],
+                 clobber: bool = False) -> None:
+        """
+        Adds one or more flowgraph tasks to verify the checklist item.
+
+        Args:
+            value (Union[List[Tuple], Tuple]): A single task tuple or a list of tuples.
+            clobber (bool): If True, replaces the existing list with the new value.
+                If False, appends to the existing list. Defaults to False.
+        """
+        if clobber:
+            self.set('task', value)
+        else:
+            self.add('task', value)
+
+    def get_report(self) -> List[str]:
+        """
+        Retrieves the list of report filepaths documenting validation.
+
+        Returns:
+            List[str]: A list of filepaths.
+        """
+        return self.get('report')
+
+    def add_report(self, value: Union[List[str], str], clobber: bool = False) -> None:
+        """
+        Adds one or more report filepaths to the checklist item.
+
+        Args:
+            value (Union[List[str], str]): A single filepath string or a list of strings.
+            clobber (bool): If True, replaces the existing list with the new value.
+                If False, appends to the existing list. Defaults to False.
+        """
+        if clobber:
+            self.set('report', value)
+        else:
+            self.add('report', value)
+
+    def get_waiver(self, metric: str) -> List[Union[Path, str]]:
+        """
+        Retrieves waiver report files for a specific metric.
+
+        Args:
+            metric (str): The metric for which to retrieve waivers.
+
+        Returns:
+            List[Union[Path, str]]: A list of filepaths for the specified metric's waivers.
+        """
+        return self.get('waiver', metric)
+
+    def add_waiver(self, metric: str, value: Union[List[Union[Path, str]], Union[Path, str]],
+                   clobber: bool = False) -> None:
+        """
+        Adds one or more waiver reports for a specific metric.
+
+        Args:
+            metric (str): The metric to which the waiver applies.
+            value (Union[List, Path, str]): A single filepath or a list of filepaths.
+            clobber (bool): If True, replaces the existing list with the new value.
+                If False, appends to the existing list. Defaults to False.
+        """
+        if clobber:
+            self.set('waiver', metric, value)
+        else:
+            self.add('waiver', metric, value)
+
+    def get_ok(self) -> bool:
+        """
+        Retrieves the manual 'ok' status of the checklist item.
+
+        A value of True indicates a human has reviewed and approved the item.
+
+        Returns:
+            bool: The boolean status, or False if not set.
+        """
+        return self.get('ok')
+
+    def set_ok(self, value: bool) -> None:
+        """
+        Sets the manual 'ok' status of the checklist item.
+
+        Args:
+            value (bool): The boolean status to set. True indicates approval.
+        """
+        self.set('ok', value)
+
+    @classmethod
+    def _getdict_type(cls) -> str:
+        """
+        Internal method to return the type name for dictionary representation.
+        """
+        return Criteria.__name__
+
+
 class Checklist(NamedSchema):
     """
-    A class for managing design checklists and their verification.
+    A class for managing a collection of design checklist items and their verification.
+
+    This class acts as a container for multiple `Criteria` objects, each
+    representing an item in a design checklist (e.g., 'ISO D000'). It provides
+    methods to define, access, and automatically verify these items against
+    flow results.
     """
-    def __init__(self, name=None):
+    def __init__(self, name: Optional[str] = None):
         """
         Initializes the Checklist object.
 
@@ -24,41 +250,80 @@ class Checklist(NamedSchema):
         """
         super().__init__()
         self.set_name(name)
+        EditableSchema(self).insert("default", Criteria())
 
-        schema_checklist(self)
+    def make_criteria(self, name: str) -> Criteria:
+        """
+        Creates a new, named `Criteria` item within this checklist.
 
-    def check(self, items=None, check_ok=False, require_reports=True):
-        '''
-        Check items in a checklist.
+        Args:
+            name (str): The unique name for the new checklist item.
 
-        Checks the status of items in a checklist for the standard provided. If
-        a specific list of items is unspecified, all items are checked.
+        Returns:
+            Criteria: The newly created `Criteria` object.
 
-        All items have an associated 'task' parameter, which indicates which
-        tasks can be used to automatically validate the item. For an item to be
-        checked, all tasks must satisfy the item's criteria, unless waivers are
-        provided. In addition, that task must have generated EDA report files
-        for each metric in the criteria.
+        Raises:
+            ValueError: If a criteria item with the same name already exists.
+        """
+        if name in self.getkeys():
+            raise ValueError(f"{name} has already been defined")
+        return self.get(name, field="schema")
 
-        For items without an associated task, the only requirement is that at
-        least one report has been added to that item.
+    def get_criteria(self, name: Optional[str] = None) -> Union[Dict[str, Criteria], Criteria]:
+        """
+        Retrieves one or all `Criteria` items from the checklist.
 
-        When 'check_ok' is True, every item must also have its 'ok' parameter
-        set to True, indicating that a human has reviewed the item.
+        If a name is provided, it returns the specific `Criteria` object.
+        If no name is provided, it returns a dictionary of all `Criteria` objects.
 
         Args:
-            items (list of str): Items to check from standard.
-            check_ok (bool): Whether to check item 'ok' parameter.
-            verbose (bool): Whether to print passing criteria.
-            require_reports (bool): Whether to assert the presence of reports.
+            name (Optional[str], optional): The name of the item to retrieve.
+                Defaults to None.
 
         Returns:
-            Status of item check.
+            Union[Dict[str, Criteria], Criteria]: A single `Criteria` object
+            or a dictionary mapping names to `Criteria` objects.
+
+        Raises:
+            ValueError: If a name is provided but is not found in the checklist.
+        """
+        if name is None:
+            criteria: Dict[str, Criteria] = {}
+            for item in self.getkeys():
+                criteria[item] = self.get_criteria(item)
+            return criteria
+        if name not in self.getkeys():
+            raise ValueError(f"{name} is not defined")
+        return self.get(name, field="schema")
+
+    def check(self, items: Optional[Iterable[str]] = None,
+              check_ok: bool = False,
+              require_reports: bool = True) -> bool:
+        """
+        Checks the status of items in a checklist against flow results.
+
+        This method validates checklist items by comparing their defined
+        criteria against metrics recorded in the chip's history. For an item
+        to pass, all its criteria must be met by the associated tasks,
+        considering any waivers.
+
+        For items with automated checks (linked to a task), this method verifies
+        that metric values from the flow run satisfy the criteria (e.g., 'errors == 0').
+        It also ensures that corresponding EDA reports were generated.
+
+        For items without a task, it only checks that a report has been manually added.
 
-        Examples:
-            >>> status = check.check_checklist('d000')
-            Returns status.
-        '''
+        Args:
+            items (Optional[Iterable[str]]): A list of item names to check. If None,
+                all items in the checklist are checked. Defaults to None.
+            check_ok (bool): If True, all checked items must also have their 'ok'
+                parameter set to True, indicating manual review. Defaults to False.
+            require_reports (bool): If True, asserts that report files exist for
+                all automated checks. Defaults to True.
+
+        Returns:
+            bool: True if all specified checks pass, False otherwise.
+        """
         error = False
 
         schema_root = self._parent(root=True)
@@ -73,7 +338,7 @@ class Checklist(NamedSchema):
         if items is None:
             items = self.getkeys()
 
-        # these tasks are recorded by SC so there are no reports
+        # These metrics are recorded by SC internally, so they don't have reports.
         metrics_without_reports = (
             'tasktime',
             'totaltime',
@@ -88,11 +353,10 @@ class Checklist(NamedSchema):
                 continue
 
             allow_missing_reports = True
-
             has_check = False
+            item_criteria: Criteria = self.get_criteria(item)
 
-            all_criteria = self.get(item, 'criteria')
-            for criteria in all_criteria:
+            for criteria in item_criteria.get_criteria():
                 m = re.match(r'^(\w+)\s*([\>\=\<]+)\s*([+\-]?\d+(\.\d+)?(e[+\-]?\d+)?)$',
                              criteria.strip())
                 if not m:
@@ -104,10 +368,8 @@ class Checklist(NamedSchema):
                 if metric not in metrics_without_reports:
                     allow_missing_reports = False
 
-                tasks = self.get(item, 'task')
-                for job, step, index in tasks:
+                for job, step, index in item_criteria.get_task():
                     job_data = schema_root.history(job)
-
                     flow = job_data.get("flowgraph", job_data.get('option', 'flow'), field="schema")
 
                     if (step, index) not in flow.get_nodes():
@@ -131,15 +393,14 @@ class Checklist(NamedSchema):
                     if metric not in job_data.getkeys("metric"):
                         if logger:
                             logger.error(f"Criteria must use legal metrics only: {criteria}")
-                            error = True
-                            continue
+                        error = True
+                        continue
 
                     if job_data.get("metric", metric, field='type') == 'int':
                         goal = int(m.group(3))
                         number_format = 'd'
                     else:
                         goal = float(m.group(3))
-
                         if goal == 0.0 or (abs(goal) > 1e-3 and abs(goal) < 1e5):
                             number_format = '.3f'
                         else:
@@ -147,10 +408,8 @@ class Checklist(NamedSchema):
 
                     value = job_data.get('metric', metric, step=step, index=index)
                     criteria_ok = utils.safecompare(value, op, goal)
-                    if metric in self.getkeys(item, 'waiver'):
-                        waivers = self.get(item, 'waiver', metric)
-                    else:
-                        waivers = []
+                    waivers = item_criteria.get_waiver(metric) \
+                        if metric in item_criteria.getkeys("waiver") else []
 
                     criteria_str = f'{metric}{op}{goal:{number_format}}'
                     compare_str = f'{value:{number_format}}{op}{goal:{number_format}}'
@@ -164,17 +423,16 @@ class Checklist(NamedSchema):
                             logger.error(f'{item} criteria {criteria_str} ({compare_str}) unmet '
                                          f'by {step_desc}.')
                         error = True
-                    elif criteria_ok:
-                        if logger:
-                            logger.info(f'{item} criteria {criteria_str} met by {step_desc}.')
+                    elif criteria_ok and logger:
+                        logger.info(f'{item} criteria {criteria_str} met by {step_desc}.')
 
-                    has_reports = \
-                        job_data.valid('tool', tool, 'task', task, 'report', metric) and \
+                    has_reports = (
+                        job_data.valid('tool', tool, 'task', task, 'report', metric) and
                         job_data.get('tool', tool, 'task', task, 'report', metric,
                                      step=step, index=index)
+                    )
 
                     if allow_missing_reports and not has_reports:
-                        # No reports available and it is allowed
                         continue
 
                     reports = []
@@ -190,28 +448,23 @@ class Checklist(NamedSchema):
 
                     if require_reports and not reports:
                         if logger:
-                            logger.error(f'No reports generated for metric {metric} in '
-                                         f'{step_desc}')
+                            logger.error(f'No reports generated for metric {metric} in {step_desc}')
                         error = True
 
                     for report in reports:
                         if not report:
                             continue
-
-                        report = os.path.relpath(report, cwd)
-                        if report not in self.get(item, 'report'):
-                            self.add(item, 'report', report)
+                        report_path = os.path.relpath(report, cwd)
+                        if report_path not in item_criteria.get_report():
+                            item_criteria.add_report(report_path)
 
             if has_check:
-                if require_reports and \
-                        not allow_missing_reports and \
-                        not self.get(item, 'report'):
-                    # TODO: validate that report exists?
+                if require_reports and not allow_missing_reports and not item_criteria.get_report():
                     if logger:
                         logger.error(f'No report documenting item {item}')
                     error = True
 
-                if check_ok and not self.get(item, 'ok'):
+                if check_ok and not item_criteria.get_ok():
                     if logger:
                         logger.error(f"Item {item} 'ok' field not checked")
                     error = True
@@ -224,15 +477,17 @@ class Checklist(NamedSchema):
     @classmethod
     def _getdict_type(cls) -> str:
         """
-        Returns the meta data for getdict
+        Internal method to return the type name for dictionary representation.
         """
-
         return Checklist.__name__
 
     def _generate_doc(self, doc,
                       ref_root: str = "",
                       key_offset: Optional[Tuple[str, ...]] = None,
                       detailed: bool = True):
+        """
+        Internal method to generate documentation for the checklist schema.
+        """
         from .schema.docs.utils import build_section
         settings = build_section('Configuration', f"{ref_root}-config")
 
@@ -254,22 +509,25 @@ class Checklist(NamedSchema):
 
 
 ############################################
-# Design Checklist
+# Design Checklist Schema Definition
 ############################################
-def schema_checklist(schema):
+def schema_checklist(schema: Criteria):
     """
-    Adds checklist schema parameters to the given schema.
+    Adds standard checklist parameters to a Criteria schema object.
+
+    This function defines the common set of parameters that make up a checklist
+    item, such as 'description', 'criteria', 'report', etc., and adds them to
+    the provided schema.
 
     Args:
-        schema (EditableSchema): The schema to modify.
+        schema (Criteria): The Criteria schema object to modify.
     """
-    schema = EditableSchema(schema)
+    edit = EditableSchema(schema)
 
-    item = 'default'
     metric = 'default'
 
-    schema.insert(
-        item, 'description',
+    edit.insert(
+        'description',
         Parameter(
             'str',
             scope=Scope.GLOBAL,
@@ -281,8 +539,8 @@ def schema_checklist(schema):
             help=trim("""
             A short one line description of the checklist item.""")))
 
-    schema.insert(
-        item, 'requirement',
+    edit.insert(
+        'requirement',
         Parameter(
             'str',
             scope=Scope.GLOBAL,
@@ -295,8 +553,8 @@ def schema_checklist(schema):
             A complete requirement description of the checklist item
             entered as a multi-line string.""")))
 
-    schema.insert(
-        item, 'dataformat',
+    edit.insert(
+        'dataformat',
         Parameter(
             'str',
             scope=Scope.GLOBAL,
@@ -309,8 +567,8 @@ def schema_checklist(schema):
             Free text description of the type of data files acceptable as
             checklist signoff validation.""")))
 
-    schema.insert(
-        item, 'rationale',
+    edit.insert(
+        'rationale',
         Parameter(
             '[str]',
             scope=Scope.GLOBAL,
@@ -324,8 +582,8 @@ def schema_checklist(schema):
             unique alphanumeric code used by the standard or a short one line
             or single word description.""")))
 
-    schema.insert(
-        item, 'criteria',
+    edit.insert(
+        'criteria',
         Parameter(
             '[str]',
             scope=Scope.GLOBAL,
@@ -337,11 +595,11 @@ def schema_checklist(schema):
             help=trim("""
             Simple list of signoff criteria for checklist item which
             must all be met for signoff. Each signoff criteria consists of
-            a metric, a relational operator, and a value in the form.
+            a metric, a relational operator, and a value in the form
             'metric op value'.""")))
 
-    schema.insert(
-        item, 'task',
+    edit.insert(
+        'task',
         Parameter(
             '[(str,str,str)]',
             scope=Scope.GLOBAL,
@@ -355,8 +613,8 @@ def schema_checklist(schema):
             The parameter should be left empty for manual and for tool
             flows that bypass the SC infrastructure.""")))
 
-    schema.insert(
-        item, 'report',
+    edit.insert(
+        'report',
         Parameter(
             '[file]',
             scope=Scope.GLOBAL,
@@ -369,8 +627,8 @@ def schema_checklist(schema):
             Filepath to report(s) of specified type documenting the successful
             validation of the checklist item.""")))
 
-    schema.insert(
-        item, 'waiver', metric,
+    edit.insert(
+        'waiver', metric,
         Parameter(
             '[file]',
             scope=Scope.GLOBAL,
@@ -383,8 +641,8 @@ def schema_checklist(schema):
             Filepath to report(s) documenting waivers for the checklist
             item specified on a per metric basis.""")))
 
-    schema.insert(
-        item, 'ok',
+    edit.insert(
+        'ok',
         Parameter(
             'bool',
             scope=Scope.GLOBAL,
@@ -396,4 +654,4 @@ def schema_checklist(schema):
             help=trim("""
             Boolean check mark for the checklist item. A value of
             True indicates a human has inspected the all item dictionary
-            parameters check out.""")))
+            parameters and verified they check out.""")))

siliconcompiler/design.py

@@ -16,7 +16,7 @@ from siliconcompiler.schema.utils import trim
 
 
 ###########################################################################
-class Design(LibrarySchema, DependencySchema):
+class Design(DependencySchema, LibrarySchema):
     '''
     Schema for a 'design'.
 
@@ -34,6 +34,11 @@ class Design(LibrarySchema, DependencySchema):
             name (str, optional): The name of the design. Defaults to None.
         '''
         super().__init__()
+
+        # Mark for copy to ensure proper remote processing
+        fs_file: Parameter = self.get("fileset", "default", "file", "default", field=None)
+        fs_file.set(True, field="copy")
+
         self.set_name(name)
 
         schema_design(self)
@@ -860,6 +865,7 @@ def schema_design(schema: Design):
         Parameter(
             ['dir'],
             scope=Scope.GLOBAL,
+            copy=True,
             shorthelp="Include file search paths",
             example=[
                 "api: design.set('fileset', 'rtl', 'idir', './rtl')",
@@ -899,6 +905,7 @@ def schema_design(schema: Design):
         Parameter(
             ['dir'],
             scope=Scope.GLOBAL,
+            copy=True,
             shorthelp="Library search paths",
             example=[
                 "api: design.set('fileset', 'rtl', 'libdir', '/usr/lib')"],