najaeda 0.3.3__cp314-cp314-win_amd64.whl

najaeda/__init__.py

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2025 The Naja authors
+# <https://github.com/najaeda/naja/blob/main/AUTHORS>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+# start delvewheel patch
+def _delvewheel_patch_1_11_2():
+    import os
+    if os.path.isdir(libs_dir := os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir, 'najaeda.libs'))):
+        os.add_dll_directory(libs_dir)
+
+
+_delvewheel_patch_1_11_2()
+del _delvewheel_patch_1_11_2
+# end delvewheel patch
+
+from ._version import version, git_hash
+
+__all__ = ["version", "git_hash"]

najaeda/_version.py

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: 2025 The Naja authors
+# <https://github.com/najaeda/naja/blob/main/AUTHORS>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from najaeda import naja
+
+
+def version():
+    """Get the version of Naja."""
+    return naja.getVersion()
+
+
+def git_hash():
+    """Get the git hash of Naja."""
+    return naja.getGitHash()

najaeda/docs/.readthedocs.yaml

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: 2024 The Naja authors <https://github.com/najaeda/naja/blob/main/AUTHORS>
+#
+# SPDX-License-Identifier: Apache-2.0
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: src/najaeda/najaeda/docs/source/conf.py
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: src/najaeda/najaeda/docs/requirements.txt

najaeda/docs/requirements.txt

@@ -0,0 +1,7 @@
+docutils>=0.12
+Jinja2>=2.7.3
+MarkupSafe>=0.23
+Pygments>=1.6
+Sphinx>=4.0,!=5.0.0
+Breathe>=v4.35.0
+sphinx_rtd_theme>=1.3.0

najaeda/docs/source/api.rst

@@ -0,0 +1,7 @@
+Complete najaeda API Reference
+==============================
+
+.. automodule:: najaeda.netlist
+    :members:
+    :undoc-members:
+    :show-inheritance:

najaeda/docs/source/common_classes.rst

@@ -0,0 +1,11 @@
+Common Classes
+==============
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+.. autoclass:: najaeda.netlist.Attribute
+    :members:
+    :undoc-members:
+    :show-inheritance:

najaeda/docs/source/conf.py

@@ -0,0 +1,57 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import sys
+import os
+
+# Add the src directory to sys.path
+sys.path.insert(0, os.path.abspath('../../../'))
+
+project = 'najaeda'
+copyright = '2024, Naja authors'
+author = 'Naja authors'
+release = '0.1.22'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',       # Enables the automodule directive
+    'sphinx.ext.napoleon',      # (Optional) Supports Google and NumPy-style docstrings
+    'sphinx.ext.viewcode',      # (Optional) Links to source code in docs
+    'sphinx.ext.todo',          # (Optional) For TODOs in the documentation
+]
+
+autodoc_mock_imports = ["najaeda.naja"]
+templates_path = ['_templates']
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+
+# Run preprocessing step if building in a specific environment
+import os
+print("Running preprocessing script for Sphinx documentation...")
+preprocessor_script = os.path.abspath('./preprocessor.py')
+source_dir = os.path.abspath('../../../examples')
+source_rst = os.path.abspath('./examples.rst.in')
+dest_rst = os.path.abspath('./examples.rst')
+
+try:
+    import subprocess
+    subprocess.call([
+        'python', preprocessor_script, 
+        '--source_dir', source_dir, 
+        '--source_rst', source_rst, 
+        '--dest_rst', dest_rst
+    ])
+    print("Preprocessing completed successfully.")
+except Exception as e:
+    print(f"Error during preprocessing: {e}")

najaeda/docs/source/equipotential.rst

@@ -0,0 +1,15 @@
+Equipotential Class
+===================
+
+Equipotential Overview
+----------------------
+
+The `Equipotential` class is responsible for managing equipotentials in the `najaeda` system.
+
+Equipotential Attributes
+------------------------
+
+.. autoclass:: najaeda.netlist.Equipotential
+    :members:
+    :undoc-members:
+    :show-inheritance:

najaeda/docs/source/examples.rst.in

@@ -0,0 +1,66 @@
+najaeda code examples
+=====================
+
+Load a design from liberty and Verilog
+--------------------------------------
+
+Following snippet shows how to load primitive cells from a liberty file
+and a netlist from a Verilog file.
+
+.. snippet:: load_design_liberty
+
+Load a design with pre-existing libraries
+-----------------------------------------
+
+In FPGA design environments, Liberty files are often unavailable.
+
+To address this, the following example demonstrates how to load primitives
+without relying on Liberty files.
+
+Naja EDA comes with pre-configured libraries to simplify this process.
+Currently, it includes support for partial Xilinx primitives, but this can be
+easily extended in the future. Don't hesitate to reach out if you need help.
+
+.. snippet:: load_xilinx_design
+
+Print all the instances in the netlist
+--------------------------------------
+
+Next example shows how to browse all the netlist and print all its content recursively.
+
+.. snippet:: print_design_recursive
+
+Similar to the previous example, but utilizing an instance visitor.
+This approach allows you to perform operations on each instance while
+also defining conditions for stopping or continuing exploration.
+
+.. snippet:: print_design_visitor
+
+Counting the number of leaves in a netlist
+------------------------------------------
+
+The instance visitor provides a tool for collecting various types of information
+about a netlist.
+
+The following example demonstrates how to use the visitor’s callback
+function to transmit user-defined arguments, allowing for flexible data processing.
+
+This specific use case shows how to count the number of leaf instances in a netlist.
+
+.. snippet:: count_leaves
+
+Design Statistics
+-----------------
+
+This example demonstrates how to use **najaeda** stats.
+The code below generates a text report file, `design.stats`,
+containing detailed statistics for each module in the design.
+
+.. snippet:: design_stats
+
+DLE (Dead Logic Elimination)
+----------------------------
+
+This example demonstrates how to perform Dead Logic Elimination (DLE) on a netlist.
+
+.. snippet:: dle

najaeda/docs/source/index.rst

@@ -0,0 +1,17 @@
+.. najaeda documentation master file, created by
+   sphinx-quickstart on Mon Dec 16 16:39:26 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+najaeda documentation
+=====================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   introduction
+   netlist_classes
+   common_classes
+   examples
+   api

najaeda/docs/source/instance.rst

@@ -0,0 +1,34 @@
+Instance Class
+==============
+
+Instance Overview
+-----------------
+
+In **najaeda**, an :py:class:`najaeda.netlist.Instance` encapsulates the concept
+of an instance in its hierarchical context.
+
+When an **Instance** is modified through editing methods,
+**najaeda** will automatically manage the necessary uniquification.
+
+Generic Gates (and, or, etc.)
+-----------------------------
+
+**najaeda** supports **generic gates** as defined in Verilog, specifically:
+
+- **n-input gates**: `and`, `nand`, `or`, `nor`, `xor`, `xnor`
+- **n-output gates**: `buf`, `not`
+
+In this model:
+
+- **n-input gates** have a **single scalar output** and a **bus input terminal** (of size *n*).
+- **n-output gates** have a **scalar input** and a **bus output terminal** (of size *n*).
+
+All terminals in these generic instances are **unnamed** (see :py:attr:`najaeda.netlist.Instance.is_unnamed`).
+
+Instance Attributes
+-------------------
+
+.. autoclass:: najaeda.netlist.Instance
+    :members:
+    :undoc-members:
+    :show-inheritance:

najaeda/docs/source/introduction.rst

@@ -0,0 +1,68 @@
+Introduction
+============
+**najaeda** is a an Electronic Design Automation (EDA) Python package
+that provides open source data structures and APIs for the development
+of post logic synthesis EDA algorithms
+such as: netlist simplification (constant and dead logic propagation),
+logic replication, netlist partitioning, ASIC and FPGA place and route, ...
+
+**najaeda** provides a powerful yet simple framework designed
+to help software **AND** hardware developers efficiently navigate and
+manipulate electronic design automation (EDA) workflows.
+
+With **najaeda**, it is possible to:
+
+* **Explore Netlists with Ease**:
+    * Navigate netlist hierarchy and connectivity effortlessly.
+    * Browse at multiple levels of detail:
+        * Bit-level or bus-level granularity.
+        * Instance-by-instance exploration or flattened views at the primitives level.
+        * Localized per-instance connections or comprehensive equipotential views.
+* **Perform ECO (Engineering Change Order) Transformations**:
+    * Seamlessly apply and manage changes to your designs.
+* **Prototype EDA Ideas Quickly**:
+    * Use an intuitive API to experiment with new EDA concepts and workflows.
+* **Develop Custom EDA Tools**:
+    * Build fast, tailored tools for solving specific challenges without relying on costly, proprietary EDA software.
+
+**najaeda** empowers developers to innovate, adapt, and accelerate
+their EDA processes with minimal overhead.
+
+Information about the **najaeda** PyPI package is available at https://pypi.org/project/najaeda .
+
+If you want more details about the underlying **naja** C++ library,
+please visit the **naja** GitHub repository at https://github.com/najaeda/naja .
+
+Quick Start
+===========
+
+To get started with **najaeda**, try out the interactive notebook in Google Colab:
+
+.. image:: https://colab.research.google.com/assets/colab-badge.svg
+   :target: https://colab.research.google.com/github/najaeda/najaeda-tutorials/blob/main/notebooks/01_getting_started.ipynb
+   :alt: Open in Colab
+
+Installation
+------------
+**najaeda** can be easily installed using pip:
+
+.. code-block:: bash
+    
+    pip install najaeda
+
+Bug Reports
+-----------
+
+If you encounter any bugs, please report them on the `najaeda` issue tracker:
+https://github.com/najaeda/naja/issues
+
+You’re also welcome to join the discussion on Matrix:
+
+.. image:: https://img.shields.io/badge/Matrix-Join%20Chat-success?logo=matrix
+   :target: https://matrix.to/#/#naja:fossi-chat.org
+   :alt: Join the Matrix chat
+
+License
+-------
+This project is licensed under the Apache License 2.0.
+See the `LICENSE <https://github.com/najaeda/naja/blob/main/LICENSE>`_ file for details.

najaeda/docs/source/net.rst

@@ -0,0 +1,20 @@
+Net Class
+=========
+
+Net Overview
+------------
+
+In **najaeda**, a :py:class:`najaeda.netlist.Net` can represent the following scenarios:
+
+1. **Simple Scalar Net**: A net that represents a single scalar signal. See :py:meth:`najaeda.netlist.Net.is_scalar`.
+2. **Full Bus Net**: A net that encompasses an entire bus. See :py:meth:`najaeda.netlist.Net.is_bus`.
+3. **Single Bit of a Bus**: A net that corresponds to an individual bit within a bus. See :py:meth:`najaeda.netlist.Net.is_bus_bit`.
+4. **Concatenation of Bits**: A net created by combining multiple bits. See :py:meth:`najaeda.netlist.Net.is_concat`.
+
+Net Attributes
+--------------
+
+.. autoclass:: najaeda.netlist.Net
+    :members:
+    :undoc-members:
+    :show-inheritance:

najaeda/docs/source/netlist_classes.rst

@@ -0,0 +1,11 @@
+Netlist Classes
+===============
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+   
+   instance
+   term
+   net
+   equipotential

najaeda/docs/source/preprocessor.py

@@ -0,0 +1,73 @@
+import argparse
+import re
+from pathlib import Path
+
+class RSTSnippetInserter:
+    def __init__(self, source_dir, source_rst, dest_rst):
+        self.source_dir = Path(source_dir)
+        self.source_rst = Path(source_rst)
+        self.dest_rst = Path(dest_rst)
+        self.snippet_pattern = re.compile(r"# snippet-start: (.+?)\n(.*?)# snippet-end: \1", re.DOTALL)
+        self.placeholder_pattern = re.compile(r"\.\. snippet:: (.+)")
+
+    def extract_snippets(self):
+        snippets = {}
+        for file in self.source_dir.rglob("*.py"):
+            with file.open("r") as f:
+                print(f"Extracting snippets from {file}")
+                content = f.read()
+                for match in self.snippet_pattern.finditer(content):
+                    snippet_name = match.group(1)
+                    snippet_code = match.group(2).strip()
+                    print(f"Extracted snippet {snippet_name} from {file}")
+                    snippets[snippet_name] = snippet_code
+        return snippets
+
+    def replace_placeholders(self, snippets):
+        if not self.source_rst.exists():
+            print(f"Source RST {self.source_rst} does not exist.")
+            return
+
+        target_rst = open(self.dest_rst, "w")
+
+        content = self.source_rst.read_text()
+        for match in self.placeholder_pattern.finditer(content):
+            snippet_name = match.group(1)
+            if snippet_name in snippets:
+                code_block = f"\n.. code-block:: python\n\n    {snippets[snippet_name].replace('\n', '\n    ')}"
+                content = content.replace(f".. snippet:: {snippet_name}", code_block)
+            else:
+                raise ValueError(f"Snippet {snippet_name} not found in source files. Available snippets: {snippets.keys()}")
+
+        target_rst.write(content)
+        print(f"Created {target_rst} with code snippets.")
+
+    def run(self):
+        snippets = self.extract_snippets()
+        self.replace_placeholders(snippets)
+
+def main():
+    parser = argparse.ArgumentParser(description="Insert code snippets into RST files.")
+    parser.add_argument(
+        "--source_dir",
+        required=True,
+        help="Directory containing source files with snippets.",
+    )
+    parser.add_argument(
+        "--source_rst",
+        required=True,
+        help="source RST file to update with snippets.",
+    )
+    parser.add_argument(
+        "--dest_rst",
+        required=True,
+        help="dest RST file.",
+    )
+    args = parser.parse_args()
+
+    inserter = RSTSnippetInserter(args.source_dir, args.source_rst, args.dest_rst)
+    inserter.run()
+
+
+if __name__ == "__main__":
+    main()

najaeda/docs/source/term.rst

@@ -0,0 +1,20 @@
+Term Class
+==========
+
+Term Overview
+-------------
+
+In **najaeda**, a :py:class:`najaeda.netlist.Term` (also referred to as a Port in Verilog terminology)
+can represent the following scenarios:
+
+1. **Single Bit Scalar Terminal**: A terminal representing a single scalar signal. See :py:meth:`najaeda.netlist.Term.is_scalar` .
+2. **Full Bus Terminal**: A terminal representing an entire bus. See :py:meth:`najaeda.netlist.Term.is_bus` .
+3. **Single Bus Bit Terminal**: A terminal representing a single bit of a bus. See :py:meth:`najaeda.netlist.Term.is_bus_bit` .
+
+Term Attributes
+---------------
+
+.. autoclass:: najaeda.netlist.Term
+    :members:
+    :undoc-members:
+    :show-inheritance:

najaeda/docs/source/visitors.rst

@@ -0,0 +1,13 @@
+najaeda visitors
+================
+
+Instance Visitor
+----------------
+
+Instance Visitor Overview
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: najaeda.instance_visitor.Visitor
+    :members:
+    :undoc-members:
+    :show-inheritance:

najaeda/instance_visitor.py

@@ -0,0 +1,43 @@
+# SPDX-FileCopyrightText: 2024 The Naja authors
+# <https://github.com/najaeda/naja/blob/main/AUTHORS>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Callable
+from najaeda import netlist
+
+
+class VisitorConfig:
+    def __init__(
+        self,
+        enter_condition: Callable[[netlist.Instance], bool] = lambda node: True,
+        callback: Callable[..., None] = lambda node, *args, **kwargs: None,
+        args: tuple = (),
+        kwargs: dict = None,
+    ):
+        """
+        :param enter_condition: A callable that takes a node (dict)
+            and returns True if the visitor should enter.
+        :param callback: A callable that takes a node (dict) and performs an operation on it.
+        :param args: Positional arguments to pass to the callback.
+        :param kwargs: Keyword arguments to pass to the callback.
+        """
+        self.enter_condition = enter_condition
+        self.callback = callback
+        self.args = args
+        self.kwargs = kwargs or {}
+
+
+def visit(instance: netlist.Instance, config: VisitorConfig):
+    """Recursively visits nodes in the netlist hierarchy.
+
+    :param instance: The current node in the netlist instance hierarchy.
+    :param config: VisitorConfig object defining conditions and callbacks.
+    """
+    # Execute the callback
+    config.callback(instance, *config.args, **config.kwargs)
+
+    # Check if we should proceed to children
+    if config.enter_condition(instance):
+        for child in instance.get_child_instances():
+            visit(child, config)