pysynthutils — Python utilities to manipulate synthesis results

pysynthutils provides a simple, class-based, Pythonic interface for working with the artifacts of physical design tools.

Installation

Since the repository is private, make sure you have SSH access to the iis-git servers.

Then you can simply install this package through pip:

pip install git+ssh://git@iis-git.ee.ethz.ch/colluca/pysynthutils.git@main

Usage

Physical implementation

The API to process artifacts of physical implementation runs is very simple:

from pysynthutils import SynthResults

# Instantiate a SynthResults object providing access to all results
results = SynthResults(run_dir)

# Access any result by:
# - stage name as defined in your backend flow, see Setup section below
# - report, e.g. timing
# - metric, e.g. WNS
wns = results['route_detail']['timing']['WNS']

Report and metric names follow the nomenclature used by Fusion Compiler. For example, the metric above can be found as WNS in the tables/timing.json report.

Hierarchical data

Most reports have a tabular format, and are easily manipulated as shown above. However, several reports have a hierarchical structure, and are better represented using a tree structure.

For example, we can easily visualize the area of all modules in the design hierarchy (as reported in tables/hierarchy_details.json):

results['route_detail']['hierarchy_details'].tree.show(all_attrs=True)

Hierarchical reports are parsed using the bigtree library. Please refer to its documentation for further information on how to manipulate these structures.

Linting

The following example illustrates the API to process linting reports:

from pysynthutils import LintViolations

# Instantiate a LintViolations object providing access to the violations in the linting report
violations = LintViolations('path/to/moresimple.rpt')

# violations.df is a pandas DataFrame with columns: rule, severity, file, line, message
errors = violations.df[violations.df['severity'] == 'SynthesisError']
count = len(violations.df[~violations.df['file'].str.contains('.bender', na=False)])

Timestamps

Every report exposes the last-modified time of the underlying file as a datetime object. For standard reports it is a dictionary entry; for hierarchical reports it is an attribute:

# Standard report
ts = results['route_detail']['timing']['timestamp']

# Hierarchical report
ts = results['route_detail']['hierarchy_details'].timestamp

Setup

pysynthutils requires your physical design flow to follow a conventional directory structure:

<Run directory>
└───qor_data
    ├───<Stage 1>
    │   ├───reports
    │   └───tables
    ├───<Stage 2>
    ...
    └───<Stage N>

The run directory can have an arbitrary name, and is simply the directory from which the Fusion Compiler flow is launched. Similarly, the stage directories can also have arbitrary names, but their contents are assumed to follow the structure produced by Fusion Compiler's write_qor_data command.

To produce this structure, simply add the following command to your physical design flow to generate artifacts for each stage in your flow:

write_qor_data -label <Stage N> ...