Metadata-Version: 2.4
Name: netlist-carpentry
Version: 0.1.0
Summary: A library for netlist modification and analysis
Project-URL: Homepage, https://github.com/IMMS-Ilmenau/netlist-carpentry
Project-URL: Documentation, https://IMMS-Ilmenau.github.io/netlist-carpentry
Author: Manuel Jirsak
Maintainer-email: Georg Gläser <georg.glaeser@imms.de>
License-File: LICENSE
Requires-Python: >=3.9
Requires-Dist: click>=8.1.8
Requires-Dist: ipykernel>=6.29.5
Requires-Dist: mako>=1.3.10
Requires-Dist: matplotlib>=3.9.4
Requires-Dist: mkdocs-jupyter>=0.25.1
Requires-Dist: networkx>=3.2.1
Requires-Dist: pydantic>=2.10.6
Requires-Dist: rich>=13.9.4
Requires-Dist: scipy>=1.13.1
Requires-Dist: tqdm>=4.67.1
Requires-Dist: types-tqdm>=4.67.0.20250516
Requires-Dist: z3-solver>=4.15.0.0
Requires-Dist: z3>=0.2.0
Provides-Extra: type-stubs
Requires-Dist: pytest-stub; extra == 'type-stubs'
Requires-Dist: types-networkx; extra == 'type-stubs'
Description-Content-Type: text/markdown

# Netlist Carpentry

Netlist Carpentry is a Python library that allows you to access and modify a digital circuit in an accessible way. It covers the following use cases:

* Navigate through your circuit and introduce custom checks
* Create a new algorithm that does some new optimization with your circuit
* ...

It uses Yosys (https://github.com/YosysHQ/yosys) to get the circuit from a behavioral code and converts it into a pythonic structure along with a networkx graph (https://networkx.org). This allows for using standard graph algorithms on the circuit as well as pretty-printing facilities.

Once in Python, the structure can be examined and modified. Netlist carpentry internally tracks all the changes and lets you write out your modified circuit to Verilog.
Back in verilog, the most simulation or synthesis tools can be used.

Example:
```python
import netlist_carpentry

# Load your Circuit
circuit = netlist_carpentry.read("simpleAdder.v")
# Define your top module
circuit.set_top('simpleAdder')

print(f"The top module '{top_module.name}' has the following items:")
for instance_name, instance_object in top_module.instances.items():
    print(f"\tInstance '{instance_name}'.")

for port_name, port_object in top_module.ports.items():
    print(f"\tPort '{port_name}', which is an {port_object.direction} port and {port_object.width} bit wide!")

for wire_name, wire_object in top_module.wires.items():
    print(f"\tWire '{wire_name}', which is {wire_object.width} bit wide!")
```

Netlist carpentry is designed for making the access to the circuit as easy as possible. The runtime-performance was not always in focus -- so don't expect it to work as fast as a custom-knitted C++ software. If you want to propose changes, please submit an issue or even a pull request.


## Installation

Install the package via...

```bash
pip install netlist-carpentry
```

... and have fun!

The package requires at least Python 3.9.

Alternatively, you can clone this repository and install the package in editable mode.


## Examples
The examples are located in `docs/src/user_guide` along with the documentation.


## Acknowledgement

The DI-Meta-X project where this software has been developed is funded by the German Federal Ministry of Research, Technology and Space under the reference 16ME0976. Responsibility for the content of this publication lies with the author.
