netlist-carpentry 0.1.0__tar.gz

netlist_carpentry-0.1.0/.gitattributes

@@ -0,0 +1,3 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+*.lock -text

netlist_carpentry-0.1.0/.github/workflows/deploy-pages.yml

@@ -0,0 +1,37 @@
+name: Build and deploy pages
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build-and-deploy:
+    name: Build and deploy pages
+    runs-on: ubuntu-latest
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - uses: actions/checkout@v4
+      - run: sudo apt-get -y update
+      - run: sudo apt-get -y install curl git build-essential yosys yosys-dev
+      - run: curl -LsSf https://astral.sh/uv/install.sh | sh
+      - run: echo PATH=${GITHUB_WORKSPACE}/.local/bin:$PATH >> $GITHUB_ENV
+      - run: uv run mkdocs build --site-dir site
+      - name: Upload to GitHub Pages
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

netlist_carpentry-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+# Refer to https://docs.astral.sh/uv/guides/integration/github/#publishing-to-pypi for setup
+
+name: Publish
+
+on:
+  workflow_run:
+    workflows:
+      - "Run Tests"
+    branches:
+      - main
+    types:
+      - completed
+    tags:
+      - v*
+
+jobs:
+  Publish:
+    name: Publish on Pypi
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+      contents: read
+
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Build Project
+        run: uv build
+      - name: Publish on Pypi
+        run: uv publish

netlist_carpentry-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,16 @@
+name: Run Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - run: sudo apt-get -y update
+      - run: sudo apt-get -y install curl git build-essential yosys yosys-dev
+      - run: curl -LsSf https://astral.sh/uv/install.sh | sh
+      - run: echo PATH=${GITHUB_WORKSPACE}/.local/bin:$PATH >> $GITHUB_ENV
+      - run: uv run tox

netlist_carpentry-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+.cache
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.tox
+.venv
+__pycache__
+build
+dist
+reports
+wheels
+docs/site
+.coverage*
+*.py[ocd]
+*.egg-info
+
+*.log
+tests/files/gen*
+.VSCodeCounter
+*txt
+xrun
+*.il
+*.ys
+*.ids
+cov_dir
+xcelium.d
+xrun.history
+*.json
+output
+public
+local_files
+*.zip
+
+# ignore all files/dirs under any "eqy/out" chain
+**/eqy/out/**

netlist_carpentry-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

netlist_carpentry-0.1.0/LICENSE

@@ -0,0 +1,11 @@
+Copyright 2025 Institut für Mikroelektronik- und Mechatronik-Systeme gemeinnützige GmbH (IMMS GmbH)
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

netlist_carpentry-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+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.

netlist_carpentry-0.1.0/README.md

@@ -0,0 +1,58 @@
+# 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.

netlist_carpentry-0.1.0/docs/scripts/gen_ref_pages.py

@@ -0,0 +1,70 @@
+"""Generate the code reference pages."""
+
+from pathlib import Path
+from typing import Sequence
+
+import mkdocs_gen_files
+
+INIT_TEMPLATE = """
+::: {identifier}
+    options:
+        members: [{members}]
+        members_order: alphabetical
+"""
+
+
+def find_submodules(dir: Path) -> Sequence[str]:
+    """Find submodules within a directory."""
+    submodules = []
+    for path in dir.iterdir():
+        if path.is_dir():
+            if (path / '__init__.py').exists():
+                submodules.append(path.name)
+        elif path.suffix == '.py' and path.stem != '__init__':
+            submodules.append(path.stem)
+    return sorted(submodules)
+
+
+def gen_ref_pages():
+    nav = mkdocs_gen_files.Nav()
+    mod_symbol = '<code class="doc-symbol doc-symbol-nav doc-symbol-module"></code>'
+
+    root = Path(__file__).parent.parent.parent
+    src = root / 'src'
+
+    for path in sorted(src.rglob('*.py')):
+        # Skip Python files that are not in a module
+        if not (path.parent / '__init__.py').exists():
+            continue
+
+        module_path = path.relative_to(src).with_suffix('')
+        doc_path = path.relative_to(src).with_suffix('.md')
+        full_doc_path = Path('reference', doc_path)
+
+        parts = tuple(module_path.parts)
+
+        if isInit := parts[-1] == '__init__':
+            parts = parts[:-1]
+            doc_path = doc_path.with_name('index.md')
+            full_doc_path = full_doc_path.with_name('index.md')
+        elif parts[-1] == '__main__':
+            continue
+
+        nav_parts = [f'{mod_symbol} {part}' for part in parts]
+        nav[tuple(nav_parts)] = doc_path.as_posix()
+
+        with mkdocs_gen_files.open(full_doc_path, 'w') as fd:
+            identifier = '.'.join(parts)
+            if isInit:
+                text = INIT_TEMPLATE.format(identifier=identifier, members=','.join(find_submodules(path.parent)))
+            else:
+                text = f'::: {identifier}\n'
+            print(text, file=fd)
+
+        mkdocs_gen_files.set_edit_path(full_doc_path, Path('../../') / path.relative_to(root))
+
+    with mkdocs_gen_files.open('reference/summary.nav', 'w') as nav_file:
+        nav_file.writelines(nav.build_literate_nav())
+
+
+gen_ref_pages()

netlist_carpentry-0.1.0/docs/src/assets/logo.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="500" height="500">
+    <g fill="#FFF">
+        <path
+            d="M190.53736355 137.3035038c-29.49302134.07918817-52.97070987 24.2345129-53.03816607 53.04727519-.02346302 11.03061878 0 290.5237982 0 290.5237982h20.46855569s-.0146644-274.85333924-.0146644-291.45059308c.07918771-16.78789203 14.40629683-31.68406667 32.0475581-31.67820088 8.93061357.02932895 296.91283897.00586579 296.91283897.00586579V137.3005709h-296.3761223z" />
+        <path
+            d="M363.45691858 365.2862451c-.0791877-29.49612686-24.23730394-52.9739528-53.0469647-53.0384765-11.03055423-.02639605-290.52503065 0-290.52503065 0v20.46867549s274.8546634-.01759737 291.4518201-.01759737c16.78779377.07918817 31.68094835 14.40638114 31.67801547 32.04774567-.03226166 8.93359873-.00879864 114.52662402-.00879864 114.52662402h20.45095842v-113.9869713z" />
+        <path
+            d="M144.97217067 78.93888965c-36.30023122 0-65.77272242 29.49026107-65.81084983 65.61766394-.01173151 11.03941747-.00879864 330.61354246-.00879864 330.61354246l20.46855569 5.848193s.01466439-319.92607242.01466439-336.52919205c.04985892-24.38702345 21.1196546-44.92608842 44.89063093-44.90849105 8.94234508.03226185 341.0438545-.15837634 341.0438545-.15837634V78.97115149l-340.59805704-.03226184z" />
+        <path
+            d="M235.46905478 195.91448115s-15.49439457-.73908959-27.80075073 11.5673386c-12.31222192 12.30936109-11.55260651 27.59267789-11.55260651 27.59267789v242.99916464h20.46855568s-.27569053-226.41070948-.27569053-242.99916464c.0410603-10.35312 8.390964-18.76466339 18.82027824-18.82625418 8.9511437.02932895 246.06553278.13198028 246.06553278.13198028v-20.46867549H235.46905478z" />
+        <path
+            d="M421.81825825 319.72078553c0-36.30337658-29.49302135-65.77604028-65.61727989-65.81123502-11.03935285-.01173158-330.60867451-.00879869-330.60867451-.00879869l-5.85109165 20.46867549s319.92713278.01759737 336.53015524.01759737c24.38981359.04692632 44.92582547 21.11684532 44.9082282 44.89089368-.03226166 8.94239741.15544253 160.0891507.15544253 160.0891507h20.45095842l.03226166-159.64628353z" />
+        <path
+            d="M304.5911239 410.32671644s.74201813-15.49155236-11.56727091-27.80091345c-12.30928904-12.31229398-27.58958351-11.55560702-27.58958351-11.55560702H22.43359422v20.46867549s226.40645144-.27569215 242.99774238-.27569215c10.35012653.04106053 18.76162068 8.39101312 18.82321112 18.8203884-.02932878 8.9482632-.13197951 68.95236576-.13197951 68.95236576h20.4656228v-68.60921703z" />
+        <path
+            d="M98.55057741.00001578C43.79081195-.02638028-.01172124 44.31312911.00001027 98.5188979c.00293288 14.8609799 0 401.48108879 0 401.48108879h499.99997729V.00001578H98.5505774zm360.73519751 459.29431864H41.16295324s.01173152-347.31051474 0-359.6374732C41.1306916 66.8494957 66.98987707 41.2218576 99.64160804 41.17786416h359.64416688v418.11647026z" />
+    </g>
+</svg>

netlist_carpentry-0.1.0/docs/src/index.md

@@ -0,0 +1 @@
+# Netlist Carpentry

netlist_carpentry-0.1.0/docs/src/stylesheets/extra.css

@@ -0,0 +1,11 @@
+.md-grid {
+    max-width: 1440px;
+}
+
+.red {
+    color: #f44336;
+}
+
+.green {
+    color: #8bc34a;
+}

netlist_carpentry-0.1.0/docs/src/stylesheets/mkdocstrings.css

@@ -0,0 +1,91 @@
+/* Custom Symbols */
+code.doc-symbol-parameter::after {
+    content: "param";
+}
+
+code.doc-symbol-attribute::after {
+    content: "attr";
+}
+
+code.doc-symbol-function::after {
+    content: "def";
+}
+
+code.doc-symbol-method::after {
+    content: "def";
+}
+
+code.doc-symbol-class::after {
+    content: "class";
+}
+
+code.doc-symbol-module::after {
+    content: "module";
+}
+
+/* Additional symbols for YAML models */
+code.doc-symbol-model {
+    color: var(--doc-symbol-class-fg-color);
+    background-color: var(--doc-symbol-class-bg-color);
+}
+
+code.doc-symbol-model::after {
+    content: "model";
+}
+
+code.doc-symbol-abstract-model {
+    color: var(--doc-symbol-method-fg-color);
+    background-color: var(--doc-symbol-method-bg-color);
+}
+
+code.doc-symbol-abstract-model::after {
+    content: "*model";
+}
+code.doc-symbol-field {
+    color: var(--doc-symbol-attribute-fg-color);
+    background-color: var(--doc-symbol-attribute-bg-color);
+}
+
+code.doc-symbol-field::after {
+    content: "field";
+}
+
+/* Abbreviate module symbol on full-width navigation */
+@media screen and (min-width: 76.25em) {
+    .md-nav code.doc-symbol-nav.doc-symbol-module::after {
+        content: "M";
+    }
+}
+
+/* Indentation. */
+div.doc-contents:not(.first) {
+    padding-left: 25px;
+    border-left: .05rem solid var(--md-typeset-table-color);
+}
+
+/* Allow module name to wrap */
+doc-module-name {
+    overflow-wrap: break-word;
+}
+
+/* Mark external links as such. */
+a.external::after,
+a.autorefs-external::after {
+    /* https://primer.style/octicons/arrow-up-right-24 */
+    mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+    -webkit-mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+    content: ' ';
+
+    display: inline-block;
+    vertical-align: middle;
+    position: relative;
+
+    height: 1em;
+    width: 1em;
+    background-color: currentColor;
+}
+
+a.external:hover::after,
+a.autorefs-external:hover::after {
+    background-color: var(--md-accent-fg-color);
+}