najaeda 0.1.8__cp310-cp310-macosx_11_0_arm64.whl → 0.1.11__cp310-cp310-macosx_11_0_arm64.whl

najaeda/docs/.readthedocs.yaml

@@ -16,16 +16,11 @@ build:
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
-   configuration: src/najaeda/najaeda/docs/source/conf.py
-
-# Optionally build your docs in additional formats such as PDF and ePub
-# formats:
-#    - pdf
-#    - epub
+  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:
+  install:
     - requirements: src/najaeda/najaeda/docs/requirements.txt

najaeda/docs/source/api.rst

@@ -1,5 +1,5 @@
-najaeda Complete API Documentation
-==================================
+Complete najaeda API Reference
+==============================
 
 .. automodule:: najaeda.netlist
     :members:

najaeda/docs/source/conf.py

@@ -15,7 +15,7 @@ sys.path.insert(0, os.path.abspath('../../../'))
 project = 'najaeda'
 copyright = '2024, Naja authors'
 author = 'Naja authors'
-release = '0.1.8'
+release = '0.1.9'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -31,10 +31,27 @@ autodoc_mock_imports = ["najaeda.snl"]
 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'
-html_static_path = ['_static']
+
+# 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

@@ -1,11 +1,6 @@
 Equipotential Class
 ===================
 
-.. automodule:: najaeda.equipotential
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 Equipotential Overview
 ----------------------
 

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

@@ -10,8 +10,10 @@ najaeda documentation
    :maxdepth: 2
    :caption: Contents:
 
+   introduction
    instance
    term
    net
    equipotential
-   api
+   examples
+   api

najaeda/docs/source/instance.rst

@@ -1,18 +1,14 @@
 Instance Class
 ==============
 
-.. automodule:: najaeda.instance
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 Instance Overview
 -----------------
 
-In `najaeda`, an `Instance` encapsulates the concept of an instance in its hierarchical context.
+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.
+When an **Instance** is modified through editing methods,
+**najaeda** will automatically manage the necessary uniquification.
 
 Instance Attributes
 -------------------

najaeda/docs/source/introduction.rst

@@ -0,0 +1,53 @@
+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 .
+
+Installation
+------------
+**najaeda** can be easily installed using pip:
+
+.. code-block:: bash
+    
+    pip install najaeda
+
+Bug Reports
+-----------
+Please report any bugs to the `najaeda` issue tracker at
+https://github.com/najaeda/naja/issues .
+
+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

@@ -1,15 +1,15 @@
 Net Class
 =========
 
-.. automodule:: najaeda.net
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 Net Overview
 ------------
 
-The `Net` class is responsible for managing nets in the `najaeda` system.
+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
 --------------

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

@@ -1,15 +1,15 @@
 Term Class
 ==========
 
-.. automodule:: najaeda.term
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 Term Overview
 -------------
 
-The `Term` class is responsible for managing terms in the `najaeda` system.
+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
 ---------------

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

@@ -17,7 +17,7 @@ class VisitorConfig:
     ):
         """
         :param enter_condition: A callable that takes a node (dict)
-        and returns True if the visitor should enter.
+            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.
@@ -28,24 +28,16 @@ class VisitorConfig:
         self.kwargs = kwargs or {}
 
 
-class Visitor:
-    def __init__(self, instance: netlist.Instance):
-        """
-        :param netlist: The hierarchical netlist to be traversed.
-        """
-        self.instance = instance
+def visit(instance: netlist.Instance, config: VisitorConfig):
+    """Recursively visits nodes in the netlist hierarchy.
 
-    def visit(self, 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)
+    :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():
-                self.visit(child, config)
+    # Check if we should proceed to children
+    if config.enter_condition(instance):
+        for child in instance.get_child_instances():
+            visit(child, config)