Metadata-Version: 2.4
Name: pysynthutils
Version: 0.0.0
Summary: Utilities to collect synthesis results
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: bigtree
Requires-Dist: pandas
Requires-Dist: pytest>=9.0.1

# 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:
```shell
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:
```python
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](https://bigtree.readthedocs.io/) library. Please refer to its documentation for further information on how to manipulate these structures.

### Linting

> [!WARNING]
> At the moment we only support Spyglass linting flows.

The following example illustrates the API to process linting reports:
```python
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:
```python
# Standard report
ts = results['route_detail']['timing']['timestamp']

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

## Setup

> [!WARNING]
> At the moment we only support Fusion Compiler flows.

`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:
```shell
write_qor_data -label <Stage N> ...
```
